Skip to main content
Version: 2.2

Auth Connect

Ionic Auth Connect handles logging in and/or registering a user with an authentication provider (such as Auth0, Azure AD, or AWS Cognito) using industry standard OAuth/OpenId Connect on iOS, Android, or on the web.

When used with Ionic Identity Vault, it provides a complete security solution for authentication and storage of logged-in credentials.

Auth Connect also allows your app to support multiple authentication providers. Should you need to change providers, easily switch between them without having to develop a new solution. Learn more.

Installation​

If you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.

Next, install the plugin:

npm install @ionic-enterprise/auth 
npx cap sync

Update the native project config files:


_20
// Android - AndroidManifest.xml
_20
<intent-filter>
_20
<data android:scheme="$AUTH_URL_SCHEME"/>
_20
<action android:name="android.intent.action.VIEW"/>
_20
<category android:name="android.intent.category.DEFAULT"/>
_20
<category android:name="android.intent.category.BROWSABLE"/>
_20
</intent-filter>
_20
<intent-filter>
_20
<action android:name="android.intent.action.SEND"/>
_20
<category android:name="android.intent.category.DEFAULT"/>
_20
<data android:mimeType="text/*"/>
_20
</intent-filter>
_20
_20
// iOS - Info.plist (inside existing CFBundleURLTypes)
_20
<dict>
_20
<key>CFBundleURLSchemes</key>
_20
<array>
_20
<string>$AUTH_URL_SCHEME</string>
_20
</array>
_20
</dict>

Reference App​

A complete login/logout experience using Auth0. Simply swap the Auth0 configuration in the IonicAuthOptions object to switch to a different auth provider.

Configuring Auth Connect​

The hosting app configures Auth Connect with settings specific to each authentication provider. This is done by passing in an instance of IonicAuthOptions to the IIonicAuth class. The IIonicAuth class is the main interface exposed by the Auth Connect plugin, and is expected to be subclassed for specific behaviors and/or events.

The default behavior for caching tokens in the plugin is not secure and should be replaced with something more robust, such as integrating it with the Ionic Identity Vault.

To access callbacks, and override behavior as needed, it is recommended to subclass the IIonicAuth interface.

Supported Providers​

Leveraging the OAuth/OpenId Connect protocols, Auth Connect supports:

Workflow​

The typical Auth Connect workflow consists of:

  1. The hosting app instantiates the Auth Connect Plugin, passing in the IonicAuthOptions object. Configure it based on the chosen auth provider.
  2. On app load, the hosting app calls IsAuthenticated to check if the user is logged in already.
  3. If the user isn't logged in, redirect the app to a Login page and call the Login method. Auth Connect loads the chosen auth provider's login page.
  4. The app user enters their username and password and taps the provider's login button.
  5. On success, Auth Connect automatically retrieves and stores the user's access token. The onLoginSuccess method is fired, and the app can redirect to the desired protected homepage.
  6. The IsAuthenticated method can be called at any point to refresh the access token.
  7. Use GetAccessToken to retrieve the access token if making any API requests to the auth provider.

Edge Support​

It is common to create a class that extends IonicAuth like this:


_12
@Injectable({
_12
providedIn: 'root'
_12
})
_12
export class AuthenticationService extends IonicAuth {
_12
private vaultService: VaultService;
_12
...
_12
async isAuthenticated(): Promise<boolean> {
_12
const isVaultLocked = await this.vaultService.isLocked();
_12
return !isVaultLocked && (await super.isAuthenticated());
_12
}
_12
...
_12
}

However, due to a bug in the pre-Chromium version of Edge, you cannot overide a method like that in the subclass. If you need to support the pre-Chromium version of Edge, you will need to write that code as follows:


_12
@Injectable({
_12
providedIn: 'root'
_12
})
_12
export class AuthenticationService extends IonicAuth {
_12
private vaultService: VaultService;
_12
...
_12
async myAppIsAuthenticated(): Promise<boolean> {
_12
const isVaultLocked = await this.vaultService.isLocked();
_12
return !isVaultLocked && (await super.isAuthenticated());
_12
}
_12
...
_12
}

You will then need to change external references from this.authentication.isAuthenticated() to this.authentication.myAppIsAuthenticated() (the name is not important so much as the fact that you are not overriding the base class method, pick a name that makes sense to you). You will also need to use the CURRENT behavior for implicitLogin on Edge.

Note: this is only required if you need to support pre-Chromium Edge browsers. If you are creating a pure hybrid-native app or otherwise have no reason to support pre-Chromium Edge, then you can override methods like isAuthenticated() in the usual manner.

Web Configuration Options​

Login UX Options​

Login can occur either within the current tab/window or a separate pop-up window (the default). Here's a visual comparison:

 

The current tab option is great for developers supporting IE11. Within the IonicAuthOptions configuration, set implicit_login to "CURRENT". Next, in the login page (or whichever page is navigated to after login - the redirectUri in the config options) implement:


_10
async ngOnInit() {
_10
// If coming back after logging into the auth provider,
_10
// grab the token from the URL and pass it to Auth Connect
_10
if (window.location.hash) {
_10
// Pass it to Auth Connect
_10
await this.authentication.handleCallback(window.location.href);
_10
// Navigate to another page
_10
this.navController.navigateRoot('/tabs/home');
_10
}
_10
}

Testing Locally​

To test an Ionic app using Auth Connect locally, configure IonicAuthOptions to use http://localhost:8100/ as the base URL for properties such as redirectUri and logoutUrl. Then, run the ionic serve command.

Upgrading to v2.0.0​

  • Upgrade your app to use cordova-android 9.x (see the 9.0.0 milestone for progress) or Capacitor 2.x.
    • For Capacitor, please see the upgrade guide for Android and iOS.
  • Install the new plugin version.

API Documentation​

You can find the API and interface documentation for everything below. The main classes to pay attention to are:

Auth Connect

Index​

Interfaces​

Variables​

Interfaces​

IHandlers​

IHandlers:

onLoginSuccess​

▸ onLoginSuccess(result: AuthResult): void

Parameters:

NameType
resultAuthResult

Returns: void

onLogout​

▸ onLogout(): void

Returns: void

IIonicAuth​

IIonicAuth:

additionalLoginParameters​

▸ additionalLoginParameters(parameters: object): void

Parameters:

NameTypeDescription
parametersobjectany additional parameters that should be added to the login request examples: `login_hint`, `domain_hint`

Returns: void

expire​

▸ expire(): Promise<void>

expire the current access token, but keep the refresh token, useful for testing

Returns: Promise<void>

getAccessToken​

▸ getAccessToken(tokenName?: undefined | string, scopes?: undefined | string): Promise<string | undefined>

get the access token, once logged in, for API calls

Parameters:

NameTypeDescription
Optional tokenNameundefined | stringOptional token name, only used when multiple tokens are required (Azure specific feature).
Optional scopesundefined | stringThe scopes for the access token.

Returns: Promise<string | undefined>

getAuthResponse​

▸ getAuthResponse(): Promise<any | undefined>

get the full original auth response

Returns: Promise<any | undefined>

getIdToken​

▸ getIdToken(): Promise<IDTokenType | undefined>

get the parsed id token, includes requested scope values

Returns: Promise<IDTokenType | undefined>

getRefreshToken​

▸ getRefreshToken(): Promise<string | undefined>

get the refresh token if available

Returns: Promise<string | undefined>

handleCallback​

▸ handleCallback(url: string): Promise<AuthResult>

called by the hosting app when callbacks happen, these will be to the URL specified in the options for LogoutUrl and RedirectUri

Parameters:

NameTypeDescription
urlstringcallback url to handle

Returns: Promise<AuthResult>

isAccessTokenAvailable​

▸ isAccessTokenAvailable(tokenName?: undefined | string): Promise<boolean>

check to see if the access token is available

Parameters:

NameTypeDescription
Optional tokenNameundefined | stringOptional token name, only used when multiple tokens are required (Azure specific feature).

Returns: Promise<boolean>

isAccessTokenExpired​

▸ isAccessTokenExpired(): Promise<boolean>

check to see if the access token is expired

Returns: Promise<boolean>

isAuthenticated​

▸ isAuthenticated(): Promise<boolean>

check to see if the user is logged in, and refresh the token if needed

Returns: Promise<boolean>

isRefreshTokenAvailable​

▸ isRefreshTokenAvailable(): Promise<boolean>

check to see if the refresh token is available

Returns: Promise<boolean>

login​

▸ login(overrideUrl?: undefined | string): Promise<void>

Using configuration display the auth provider's login UI.

The overrideUrl parameter should only be used when the default discovery url needs to be overrode. (The known use case is with Azure AD custom user flows/policies.)

Parameters:

NameType
Optional overrideUrlundefined | string

Returns: Promise<void>

logout​

▸ logout(): Promise<void>

log the user out

Returns: Promise<void>

onLoginSuccess​

▸ onLoginSuccess(response: any): void

Event handler which can be overridden to handle successful login events

Parameters:

NameType
responseany

Returns: void

onLogout​

▸ onLogout(): void

Event handler which can be overridden to handle successful logout events

Returns: void

refreshSession​

▸ refreshSession(tokenName?: undefined | string): Promise<void>

refresh the session, throws if refresh token is invalid or missing

Parameters:

NameTypeDescription
Optional tokenNameundefined | stringOptional token name, only used when multiple tokens are required (Azure specific feature).

Returns: Promise<void>

IVConfig​

IVConfig:

isPasscodeSetupNeeded​

● isPasscodeSetupNeeded: boolean

IVUserInterface​

IVUserInterface:

getVault​

▸ getVault(): Promise<VaultInterface>

Returns: Promise<VaultInterface>

setPasscode​

▸ setPasscode(): Promise<void>

Returns: Promise<void>

IonicAuthOptions​

IonicAuthOptions:

Provided by the hosting app, this interface allows the hosting app to configure, and provide information needed to login, logout.

<Optional> androidToolbarColor​

● androidToolbarColor: undefined | string

setting to allow the toolbar color of the android webview control to be set. Takes a string that can be parsed as a color by android.graphics.Color.parseColor

<Optional> audience​

● audience: undefined | string

Provided audience (aud) value

<Optional> authConfig​

● authConfig: "auth0" | "azure" | "cognito" | "salesforce" | "okta" | "ping" | "general"

The type of the Auth Server, currently only the following are supported:

  • Auth0
  • Azure Active Directory
  • Cognito (AWS)
  • Salesforce
  • Okta
  • Ping

clientID​

● clientID: string

Provided Application ID

<Optional> clientSecret​

● clientSecret: undefined | string

The client secret, optional

<Optional> discoveryUrl​

● discoveryUrl: undefined | string

Location of the Auth Server's discovery endpoint, can be null for Azure

<Optional> implicitLogin​

● implicitLogin: "CURRENT" | "POPUP"

for implicit login (aka web) should the auth window be opened in a new popup window/tab or the current windwow/tab defaults to: POPUP for CURRENT to work the app will need to call IIonicAuth::handleCallback when the auth service navigates to the url set in redirect_url

<Optional> iosWebView​

● iosWebView: "private" | "shared"

setting the option to shared allows for sharing a session between Safari and other applications for a true SSO experience between apps but on iOS 11 and higher it will prompt the user for permission to share the website data with the application. Using private avoids the prompt but the session will only be shared with Safari on iOS 10 or lower.

<Optional> logLevel​

● logLevel: "DEBUG" | "ERROR" | "NONE"

The log level for the module

logoutUrl​

● logoutUrl: string

Location that the hosting app expects logout callbacks to navigate to.

<Optional> platform​

● platform: "web" | "cordova" | "capacitor"

Are we hosted in cordova, web, capacitor

<Optional> redirectUri​

● redirectUri: undefined | string

Location that the hosting app expects callbacks to navigate to.

<Optional> scope​

● scope: undefined | string

User details requested from the Authentication provider, each provider may support standard {e.g. openid, profile, email, etc.}, or custom scopes.

<Optional> tokenStorageProvider​

● tokenStorageProvider: "localStorage" | TokenStorageProvider | IVUserInterface

The type of storage to use for the tokens

<Optional> webAuthFlow​

● webAuthFlow: "implicit" | "PKCE"

Authentication flow to use on web defaults to: implicit PKCE is not supported by Azure, if authConfig is set to azure the plugin will use implicit despite webAuthFlow value

IonicGeneralAuthOptions​

IonicGeneralAuthOptions:

<Optional> alwaysSendClientSecretOnLogin​

● alwaysSendClientSecretOnLogin: undefined | false | true

should the 'client_secret' value always be passed in for login calls, regardless of implict(web) or not defaults to: true

<Optional> androidToolbarColor​

● androidToolbarColor: undefined | string

setting to allow the toolbar color of the android webview control to be set. Takes a string that can be parsed as a color by android.graphics.Color.parseColor

<Optional> audience​

● audience: undefined | string

Provided audience (aud) value

<Optional> authConfig​

● authConfig: "auth0" | "azure" | "cognito" | "salesforce" | "okta" | "ping" | "general"

The type of the Auth Server, currently only the following are supported:

  • Auth0
  • Azure Active Directory
  • Cognito (AWS)
  • Salesforce
  • Okta
  • Ping

clientID​

● clientID: string

Provided Application ID

<Optional> clientSecret​

● clientSecret: undefined | string

The client secret, optional

<Optional> discoveryUrl​

● discoveryUrl: undefined | string

Location of the Auth Server's discovery endpoint, can be null for Azure

<Optional> implicitLogin​

● implicitLogin: "CURRENT" | "POPUP"

for implicit login (aka web) should the auth window be opened in a new popup window/tab or the current windwow/tab defaults to: POPUP for CURRENT to work the app will need to call IIonicAuth::handleCallback when the auth service navigates to the url set in redirect_url

<Optional> iosWebView​

● iosWebView: "private" | "shared"

setting the option to shared allows for sharing a session between Safari and other applications for a true SSO experience between apps but on iOS 11 and higher it will prompt the user for permission to share the website data with the application. Using private avoids the prompt but the session will only be shared with Safari on iOS 10 or lower.

<Optional> logLevel​

● logLevel: "DEBUG" | "ERROR" | "NONE"

The log level for the module

logoutUrl​

● logoutUrl: string

Location that the hosting app expects logout callbacks to navigate to.

<Optional> platform​

● platform: "web" | "cordova" | "capacitor"

Are we hosted in cordova, web, capacitor

<Optional> redirectUri​

● redirectUri: undefined | string

Location that the hosting app expects callbacks to navigate to.

<Optional> scope​

● scope: undefined | string

User details requested from the Authentication provider, each provider may support standard {e.g. openid, profile, email, etc.}, or custom scopes.

<Optional> tokenStorageProvider​

● tokenStorageProvider: "localStorage" | TokenStorageProvider | IVUserInterface

The type of storage to use for the tokens

<Optional> webAuthFlow​

● webAuthFlow: "implicit" | "PKCE"

Authentication flow to use on web defaults to: implicit PKCE is not supported by Azure, if authConfig is set to azure the plugin will use implicit despite webAuthFlow value

TokenStorageProvider​

TokenStorageProvider:

This interface can be implemented by the hosting app, and set in the options it should be a wrapper around access to a secure storage solution if Ionic Identity Vault is not being used.

<Optional> clear​

● clear: undefined | function

clear storage

<Optional> getAccessToken​

● getAccessToken: undefined | function

get the saved access token

param: Optional token name, only used when multiple tokens are required (Azure specific feature).

<Optional> getAuthResponse​

● getAuthResponse: undefined | function

get the full auth result

<Optional> getIdToken​

● getIdToken: undefined | function

get the id token

<Optional> getRefreshToken​

● getRefreshToken: undefined | function

get the saved refresh token

<Optional> setAccessToken​

● setAccessToken: undefined | function

save the access token

param: Optional token name, only used when multiple tokens are required (Azure specific feature).

<Optional> setAuthResponse​

● setAuthResponse: undefined | function

save the full auth response

<Optional> setIdToken​

● setIdToken: undefined | function

save the id token

<Optional> setRefreshToken​

● setRefreshToken: undefined | function

save the refresh token

VaultInterface​

VaultInterface:

clear​

▸ clear(): Promise<void>

Returns: Promise<void>

getConfig​

▸ getConfig(): Promise<IVConfig>

Returns: Promise<IVConfig>

getValue​

▸ getValue(name: string): Promise<any>

Parameters:

NameType
namestring

Returns: Promise<any>

storeValue​

▸ storeValue(name: string, value: any): Promise<any>

Parameters:

NameType
namestring
valueany

Returns: Promise<any>

Variables​

<Const> ready​

● ready:


_10
*`Promise`&lt;`unknown`>* = new Promise(resolve => {
_10
document.addEventListener('deviceready', () => {
_10
resolve();
_10
});
_10
})

Changelog

[2.2.1] (2020-05-29)​

Bug Fixes​

  • okta: fix logout configuration

[2.2.0] (2020-05-27)​

Features​

  • Okta integration

Bug Fixes​

  • android: make source-file target-dir lowercase
  • web: add client secret to postToken body if required

[2.1.0] (2020-04-23)​

Features​

  • add support for Ping

Bug Fixes​

  • web: add client secret to postToken body if required

[2.0.1] (2020-04-17)​

Bug Fixes​

  • make client_secret optional for Cognito

[2.0.0] (2020-04-17)​

⚠ BREAKING CHANGES​

  • AndroidX is now required in projects with auth v2.

Features​

  • add isAccessTokenExpired, isRefreshTokenAvailable, getRefreshToken, refreshSession
  • Add support for Saleforce
  • isAccessTokenAvailable
  • android: AndroidX upgrade

Bug Fixes​

  • Android: Fix an issue where Auth Connect didn't work on Android 10.

  • await the access token from storage

  • Fix a bug where if a provider doesn't return when the access token expires it defaults to be immediately expired.

  • Fix an issue where if refresh failed isAuthenticated still returned true

  • ios: move AuthenticationServices import from .m to .h for Capacitor compat

  • web: catch error on refresh frame creation

  • web, cognito: fix for SE-150. Added logout_uri to list of valid params.

  • Add upgrading to v2 instructions

[1.8.1] (2020-04-01)​

Bug Fixes​

  • await the access token from storage

[1.8.0] (2020-04-01)​

Features​

  • isAccessTokenAvailable

[1.7.0] (2020-03-27)​

Features​

  • add isAccessTokenExpired, isRefreshTokenAvailable, getRefreshToken, refreshSession

[1.6.2] (2020-03-17)​

Bug Fixes​

  • Android: Fix an issue where Auth Connect didn't work on Android 10.

[1.6.1] (2020-03-16)​

Bug Fixes​

  • Fix an issue where if refresh failed isAuthenticated still returned true

[1.6.0] (2020-03-13)​

Features​

  • Add support for Saleforce

Bug Fixes​

  • Fix a bug where if a provider doesn't return when the access token expires it defaults to be immediately expired.

[1.5.4] (2020-03-10)​

Bug Fixes​

  • web: catch error on refresh frame creation

[1.5.3] (2020-03-09)​

Bug Fixes​

  • web, cognito: fix for SE-150. Added logout_uri to list of valid params.

[1.5.2] (2020-02-24)​

Bug Fixes​

  • web: throw error if POST to token endpoint failed

[1.5.1] (2020-02-21)​

Bug Fixes​

  • web: properly refresh token when using PKCE

[1.5.0] (2020-02-17)​

Features​

  • web: add PKCE auth flow option

[1.4.0] (2020-02-13)​

Features​

  • reject if user closed the auth browser

Bug Fixes​

  • ios, android, web: SE-132: allow client_secret to be passed into authorization calls.
  • propagate network errors on login
  • update to general to send client secret in payload of token call

[1.3.5] (2019-12-17)​

Bug Fixes​

  • ios: prevent blank screen on SFSafariViewController presentation

[1.3.4] (2019-12-04)​

Bug Fixes​

  • android: implement IonicSecureWebView.hide() to avoid invalid action
  • ios: add in new interface for ios 13 when using ASWebAuthenticationPresentationContextProviding

[1.3.3] (2019-11-08)​

Bug Fixes​

  • ios: rename AFNetworking symbols that conflic with advanced-http plugin

[1.3.2] (2019-11-01)​

[1.3.1] (2019-10-29)​

[1.3.0] (2019-10-09)​

Bug Fixes​

  • make sure interfaces are not snake cased, move some parameters off to method to make them more dynmaic, clean up some parameter checking to be more clear, make some dictionary combines clearer.

Features​

  • ios,android,web: changes for supporting implicit path (aka web) in window rather than in tabs. allow pass through of login_hint value for azure/auth0 and domain_hint for azure. fixes for param handling

[1.2.0] (2019-09-16)​

Bug Fixes​

  • all: remove unneeded plugin deps
  • ios, web, android: make sure the access token is valid before returning it
  • web: password reset error was being ignored and needed to check (hash) not (query params) for value
  • Web: Fix issue with IE 11 not working.

Features​

  • ios,android,web: support acquiring multiple tokens from an oauth source (especially azure ad), also fix some issues with refresh for the web path. The major change is that getToken now has two optional paramters, they both must be passed in or neither. The parameters are an id for the token being acquired and the specific scope for the token being acquired.

[1.1.4] (2019-08-28)​

[1.1.3] (2019-08-21)​

[1.1.2] (2019-08-14)​

[1.1.1] (2019-07-29)​

Bug Fixes​

  • Android, iOS: fix incorrect package.json dependency

[1.1.0] (2019-07-29)​

Features​

  • iOS, Android: Remove extra plugin dependencies and unify flow across Android and all iOS webviews.

Contents