Auth Connect API

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#

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


clearStorage#

clearStorage(): Promise<void>

This method will clear all tokens & data stored in the TokenStorageProvider as well as any metadata relevant to the existing session such as access token expiration time.

Returns: Promise<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

deprecated: Use handleLoginCallback instead

Parameters:

NameTypeDescription
urlstringcallback url to handle

Returns: Promise<AuthResult>


handleLoginCallback#

handleLoginCallback(url?: undefined | string): Promise<AuthResult>

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

Parameters:

NameTypeDescription
Optional urlundefined | stringcallback url to handle @default defaults to `window.location.href`

Returns: Promise<AuthResult>


handleLogoutCallback#

handleLogoutCallback(): Promise<void>

called by the hosting app when logout callbacks happens

Returns: Promise<void>


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>



ISafariWebViewOptions#

ISafariWebViewOptions:

<Optional> dismissButtonStyle#

● dismissButtonStyle: "done" | "close" | "cancel"

Configures the label of the dismiss button ("done", "close", or "cancel"). Defaults to "Done".


<Optional> preferredBarTintColor#

● preferredBarTintColor: undefined | string

The color to tint the background of the navigation bar and the toolbar. Must be in hex (#000000) format.


<Optional> preferredControlTintColor#

● preferredControlTintColor: undefined | string

The color to tint the control buttons on the navigation bar and the toolbar. Must be in hex (#000000) format.



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" | "identity-server" | "keycloak" | "general"

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

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

'general' is deprecated--please use a specific provider.


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"

determines the UI mode to use with web authentication in implicit. "CURRENT" will replace the current window with the authentication provider, and "POPUP" will open the authentication provider in a new window/tab. When this is set to "CURRENT", you will need to use the handleLoginCallback and handleLogoutCallback to complete the auth


<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> safariWebViewOptions#

● safariWebViewOptions: ISafariWebViewOptions

Additional configuration options to pass to the Safari Web View when iosWebView is set to "private".


<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" | "identity-server" | "keycloak" | "general"

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

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

'general' is deprecated--please use a specific provider.


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"

determines the UI mode to use with web authentication in implicit. "CURRENT" will replace the current window with the authentication provider, and "POPUP" will open the authentication provider in a new window/tab. When this is set to "CURRENT", you will need to use the handleLoginCallback and handleLogoutCallback to complete the auth


<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> safariWebViewOptions#

● safariWebViewOptions: ISafariWebViewOptions

Additional configuration options to pass to the Safari Web View when iosWebView is set to "private".


<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



Variables#

<Const> ready#

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