Auth Connect API
You can find the API and interface documentation for everything below. The main classes to pay attention to are:
- IonicAuth
- IonicAuthOptions
- TokenStorageProvider (if Ionic Identity Vault is not being used.)
Auth Connect#
Table of contents#
Interfaces#
Interfaces#
Interface: IIonicAuth<IDTokenType>#
Type parameters#
| Name | Type | Default |
|---|---|---|
IDTokenType | object | any |
Table of contents#
Methods#
- additionalLoginParameters
- clearStorage
- expire
- getAccessToken
- getAuthResponse
- getIdToken
- getRefreshToken
- handleCallback
- handleLoginCallback
- handleLogoutCallback
- isAccessTokenAvailable
- isAccessTokenExpired
- isAuthenticated
- isRefreshTokenAvailable
- login
- logout
- onLoginSuccess
- onLogout
- refreshSession
Methods#
additionalLoginParameters#
▸ additionalLoginParameters(parameters: { [id: string]: string; }): void
Parameters:#
| Name | Type | Description |
|---|---|---|
parameters | object | any 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:#
| Name | Type | Description |
|---|---|---|
tokenName? | string | Optional token name, only used when multiple tokens are required (Azure specific feature). |
scopes? | string | The 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:#
| Name | Type | Description |
|---|---|---|
url | string | callback 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:#
| Name | Type | Description |
|---|---|---|
url? | string | callback 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:#
| Name | Type | Description |
|---|---|---|
tokenName? | string | Optional 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:#
| Name | Type |
|---|---|
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:#
| Name | Type |
|---|---|
response | any |
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:#
| Name | Type | Description |
|---|---|---|
tokenName? | string | Optional 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#
IonicAuthOptions
Table of contents#
Properties#
- androidToolbarColor
- audience
- authConfig
- clientID
- clientSecret
- discoveryUrl
- implicitLogin
- iosWebView
- logLevel
- logoutUrl
- platform
- redirectUri
- safariWebViewOptions
- scope
- tokenStorageProvider
- webAuthFlow
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#
↳ IonicGeneralAuthOptions
Table of contents#
Properties#
- alwaysSendClientSecretOnLogin
- androidToolbarColor
- audience
- authConfig
- clientID
- clientSecret
- discoveryUrl
- implicitLogin
- iosWebView
- logLevel
- logoutUrl
- platform
- redirectUri
- safariWebViewOptions
- scope
- tokenStorageProvider
- webAuthFlow
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#
- clear
- getAccessToken
- getAuthResponse
- getIdToken
- getRefreshToken
- setAccessToken
- setAuthResponse
- setIdToken
- setRefreshToken
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:#
| Name | Type |
|---|---|
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:#
| Name | Type |
|---|---|
accessToken | string |
tokenName? | string |
Returns: Promise<void>
setAuthResponse#
• Optional setAuthResponse: (response: any) => Promise<void>
save the full auth response
Type declaration:#
▸ (response: any): Promise<void>
Parameters:#
| Name | Type |
|---|---|
response | any |
Returns: Promise<void>
setIdToken#
• Optional setIdToken: (idToken: string) => Promise<void>
save the id token
Type declaration:#
▸ (idToken: string): Promise<void>
Parameters:#
| Name | Type |
|---|---|
idToken | string |
Returns: Promise<void>
setRefreshToken#
• Optional setRefreshToken: (refreshToken: string) => Promise<void>
save the refresh token
Type declaration:#
▸ (refreshToken: string): Promise<void>
Parameters:#
| Name | Type |
|---|---|
refreshToken | string |
Returns: Promise<void>