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#
Index#
Interfaces#
Variables#
Interfaces#
IIonicAuth#
IIonicAuth:
additionalLoginParameters#
▸ additionalLoginParameters(parameters: object): 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?: undefined | string, scopes?: undefined | string): Promise<string | undefined>
get the access token, once logged in, for API calls
Parameters:
| Name | Type | Description |
|---|---|---|
Optional tokenName | undefined | string | Optional token name, only used when multiple tokens are required (Azure specific feature). |
Optional scopes | undefined | string | The 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:
| Name | Type | Description |
|---|---|---|
| url | string | callback 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:
| Name | Type | Description |
|---|---|---|
Optional url | undefined | 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?: undefined | string): Promise<boolean>
check to see if the access token is available
Parameters:
| Name | Type | Description |
|---|---|---|
Optional tokenName | undefined | 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?: 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 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?: undefined | string): Promise<void>
refresh the session, throws if refresh token is invalid or missing
Parameters:
| Name | Type | Description |
|---|---|---|
Optional tokenName | undefined | string | Optional 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();
});
})