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 parametersName | 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: IonicAuthOptionsProvided by the hosting app, this interface allows the hosting app to configure, and provide information needed to login, logout.
#
HierarchyIonicAuthOptions
#
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: TokenStorageProviderThis 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>