Auth Connect API

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

Auth Connect#

Table of contents#

Interfaces#

Interfaces#

Interface: IIonicAuth<IDTokenType>#

Type parameters#

NameTypeDefault
IDTokenTypeobjectany

Table of contents#

Methods#

Methods#

additionalLoginParameters#

additionalLoginParameters(parameters: { [id: string]: string; }): 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?: string, scopes?: string): Promise<undefined | string>

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

Parameters:#
NameTypeDescription
tokenName?stringOptional token name, only used when multiple tokens are required (Azure specific feature).
scopes?stringThe scopes for the access token.

Returns: Promise<undefined | string>


getAuthResponse#

getAuthResponse(): Promise<any>

get the full original auth response

Returns: Promise<any>


getIdToken#

getIdToken(): Promise<undefined | IDTokenType>

get the parsed id token, includes requested scope values

Returns: Promise<undefined | IDTokenType>


getRefreshToken#

getRefreshToken(): Promise<undefined | string>

get the refresh token if available

Returns: Promise<undefined | string>


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?: 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
url?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?: string): Promise<boolean>

check to see if the access token is available

Parameters:#
NameTypeDescription
tokenName?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?: 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
overrideUrl?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?: string): Promise<void>

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

Parameters:#
NameTypeDescription
tokenName?stringOptional token name, only used when multiple tokens are required (Azure specific feature).

Returns: Promise<void>

Interface: IonicAuthOptions#

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

Hierarchy#

Table of contents#

Properties#

Properties#

androidToolbarColor#

Optional androidToolbarColor: 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


audience#

Optional audience: string

Provided audience (aud) value


authConfig#

Optional 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


clientSecret#

Optional clientSecret: string

The client secret, optional


discoveryUrl#

Optional discoveryUrl: string

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


implicitLogin#

Optional 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


iosWebView#

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


logLevel#

Optional logLevel: DEBUG | ERROR | NONE

The log level for the module


logoutUrl#

logoutUrl: string

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


platform#

Optional platform: web | cordova | capacitor

Are we hosted in cordova, web, capacitor


redirectUri#

Optional redirectUri: string

Location that the hosting app expects callbacks to navigate to.


safariWebViewOptions#

Optional safariWebViewOptions: ISafariWebViewOptions

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


scope#

Optional scope: string

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


tokenStorageProvider#

Optional tokenStorageProvider: IVUserInterface | localStorage | TokenStorageProvider

The type of storage to use for the tokens


webAuthFlow#

Optional 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

Interface: IonicGeneralAuthOptions#

Hierarchy#

Table of contents#

Properties#

Properties#

alwaysSendClientSecretOnLogin#

Optional alwaysSendClientSecretOnLogin: boolean

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


androidToolbarColor#

Optional androidToolbarColor: 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

Inherited from: IonicAuthOptions.androidToolbarColor


audience#

Optional audience: string

Provided audience (aud) value

Inherited from: IonicAuthOptions.audience


authConfig#

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

Inherited from: IonicAuthOptions.authConfig


clientID#

clientID: string

Provided Application ID

Inherited from: IonicAuthOptions.clientID


clientSecret#

Optional clientSecret: string

The client secret, optional

Inherited from: IonicAuthOptions.clientSecret


discoveryUrl#

Optional discoveryUrl: string

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

Inherited from: IonicAuthOptions.discoveryUrl


implicitLogin#

Optional 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

Inherited from: IonicAuthOptions.implicitLogin


iosWebView#

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

Inherited from: IonicAuthOptions.iosWebView


logLevel#

Optional logLevel: DEBUG | ERROR | NONE

The log level for the module

Inherited from: IonicAuthOptions.logLevel


logoutUrl#

logoutUrl: string

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

Inherited from: IonicAuthOptions.logoutUrl


platform#

Optional platform: web | cordova | capacitor

Are we hosted in cordova, web, capacitor

Inherited from: IonicAuthOptions.platform


redirectUri#

Optional redirectUri: string

Location that the hosting app expects callbacks to navigate to.

Inherited from: IonicAuthOptions.redirectUri


safariWebViewOptions#

Optional safariWebViewOptions: ISafariWebViewOptions

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

Inherited from: IonicAuthOptions.safariWebViewOptions


scope#

Optional scope: string

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

Inherited from: IonicAuthOptions.scope


tokenStorageProvider#

Optional tokenStorageProvider: IVUserInterface | localStorage | TokenStorageProvider

The type of storage to use for the tokens

Inherited from: IonicAuthOptions.tokenStorageProvider


webAuthFlow#

Optional 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

Inherited from: IonicAuthOptions.webAuthFlow

Interface: ISafariWebViewOptions#

Table of contents#

Properties#

Properties#

dismissButtonStyle#

Optional dismissButtonStyle: done | close | cancel

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


preferredBarTintColor#

Optional preferredBarTintColor: string

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


preferredControlTintColor#

Optional preferredControlTintColor: string

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

Interface: 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.

Table of contents#

Properties#

Properties#

clear#

Optional clear: () => Promise<void>

clear storage

Type declaration:#

▸ (): Promise<void>

Returns: Promise<void>


getAccessToken#

Optional getAccessToken: (tokenName?: string) => Promise<undefined | string>

get the saved access token

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

Type declaration:#

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

Parameters:#
NameType
tokenName?string

Returns: Promise<undefined | string>


getAuthResponse#

Optional getAuthResponse: () => Promise<any>

get the full auth result

Type declaration:#

▸ (): Promise<any>

Returns: Promise<any>


getIdToken#

Optional getIdToken: () => Promise<undefined | string>

get the id token

Type declaration:#

▸ (): Promise<undefined | string>

Returns: Promise<undefined | string>


getRefreshToken#

Optional getRefreshToken: () => Promise<undefined | string>

get the saved refresh token

Type declaration:#

▸ (): Promise<undefined | string>

Returns: Promise<undefined | string>


setAccessToken#

Optional setAccessToken: (accessToken: string, tokenName?: string) => Promise<void>

save the access token

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

Type declaration:#

▸ (accessToken: string, tokenName?: string): Promise<void>

Parameters:#
NameType
accessTokenstring
tokenName?string

Returns: Promise<void>


setAuthResponse#

Optional setAuthResponse: (response: any) => Promise<void>

save the full auth response

Type declaration:#

▸ (response: any): Promise<void>

Parameters:#
NameType
responseany

Returns: Promise<void>


setIdToken#

Optional setIdToken: (idToken: string) => Promise<void>

save the id token

Type declaration:#

▸ (idToken: string): Promise<void>

Parameters:#
NameType
idTokenstring

Returns: Promise<void>


setRefreshToken#

Optional setRefreshToken: (refreshToken: string) => Promise<void>

save the refresh token

Type declaration:#

▸ (refreshToken: string): Promise<void>

Parameters:#
NameType
refreshTokenstring

Returns: Promise<void>