Search docs/

Auth Connect

v1.1.2

Contents

インストール

Ionic Enterprise Editionのプラグインを利用する場合は、 通常のバージョンでスコープ指定されたプラグインに問題がある可能性があるため、 Ionic Enterprise Cordova CLIを使用していることを確認する必要があります。

npm uninstall -g cordovanpm install -g @ionic-enterprise/cordova

Ionic Enterprise Cordova CLIをインストールしたら、プラグインをインストールできます。

ionic enterprise register --key=YOURPRODUCTKEYionic cordova plugin add @ionic-enterprise/auth --variable AUTH_URL_SCHEME =mycustomscheme

Overview

The Auth Plugin 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 and Android, or on the web.

When used with the Ionic Identity Vault plugin it provides a complete secure solution for authentication and storage of logged in credentials.

Auth Plugin also allows you app to support multiple authentication providers, or allow you to switch from one to another without having to develop a new solution.

Configuring Auth Connect

To configure the Auth Connect plugin the hosting app should provide settings specific to how authentication provider is configured. 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.

Note for handling password reset cases from Azure AD with custom user flows/policies

When using custom user flows/policies with Azure AD password reset needs to be handled by a separate endpoint. To handle this:

  1. when Login is called if there is an error
  2. if that error contains a message property that starts with the string AADB2C90118 (this is an error message returned by Azure AD)
  3. the app should call Login with the location of the password reset endpoint

Flow

  1. Hosting app creates the Auth Plugin and passes in the options
  2. Login is called
  3. The hosting app can wait on IsAuthenticated until it succeeds or fails.
  4. On success the access token can be retrieved and used as needed and the onLoginSuccess method will be called.
  5. IsAuthenticated can be called again to refresh the access token as needed.

Implicit/Web Flow Notes

The redirect URL for the auth service needs to be local path that the hosting app can navigate to, as the auth plugin needs to read the tokens from the redirect url. The auth service needs to support returning the authorization and id tokens back to the implicit path (for Azure this is under App registrations/Authentication in the 'Implicit Grants' section).

Supported Providers

OAuth/OpenId Connect from the following providers:

  • Cognito (AWS)
  • Azure Active Directory v.2 (Microsoft)
  • Auth0

API Documentation

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

Index

Interfaces

Variables


Interfaces

IHandlers

IHandlers:

onLoginSuccess

onLoginSuccess(result: AuthResult): void

Parameters:

Name Type
result AuthResult

Returns: void


onLogout

onLogout(): void

Returns: void



IIonicAuth

IIonicAuth:

expire

expire(): Promise<void>

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

Returns: Promise<void>


getAccessToken

getAccessToken(): Promise<string | undefined>

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

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>


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:

Name Type Description
url string callback url to handle

Returns: Promise<AuthResult>


isAuthenticated

isAuthenticated(): Promise<boolean>

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

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:

Name Type
Optional overrideUrl undefined | 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 overriden to handle successful login events

Parameters:

Name Type
response any

Returns: void


onLogout

onLogout(): void

Event handler which can be overriden to handle successful logout events

Returns: 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"*

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

  • Auth0
  • Azure Active Directory v2
  • Cognito (AWS)

clientID

● clientID: string

Provided Application ID


<Optional> clientSecret

● clientSecret: undefined | string

The client secret, optional only required for Cognito/Web


<Optional> discoveryUrl

● discoveryUrl: undefined | string

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


<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 Authintication provider, each provider may support standard {e.g. openid, profile, email, etc.}, or cutom scopes.


<Optional> tokenStorageProvider

● tokenStorageProvider: *"localStorage" | IdentityVaultUser<any> | TokenStorageProvider*

The type of storage to use for the tokens



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


<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


<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



Variables

<Const> ready

● ready: Promise<Object> = new Promise(resolve => { document.addEventListener('deviceready', () => { resolve(); }); })


Change Log

[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.

Other Versions