okta
Okta Auth JavaScript SDK
- Release status
- Need help?
- Getting started
- Usage guide
- Strategies for Obtaining Tokens
- Configuration reference
- API Reference
- Building the SDK
- Node JS and React Native Usage
- Migrating from previous versions
- Contributing
The Okta Auth JavaScript SDK builds on top of our Authentication API and OpenID Connect & OAuth 2.0 API to enable you to create a fully branded sign-in experience using JavaScript.
You can learn more on the Okta + JavaScript page in our documentation.
This library uses semantic versioning and follows Okta's library version policy.
:warning: :warning: :warning: :warning: :warning: :warning: :warning: :warning: :warning:
:warning: Bulletin Board :warning:
- Review Future of autoRenew
- Review End of Third-Party Cookies
:warning: :warning: :warning: :warning: :warning: :warning: :warning: :warning::warning:
Release Status
:heavy_check_mark: The current stable major version series is: 7.x
| Version | Status |
|---|---|
7.x |
:heavy_check_mark: Stable |
6.x |
:x: Retired |
5.x |
:x: Retired |
4.x |
:x: Retired |
3.x |
:x: Retired |
2.x |
:x: Retired |
1.x |
:x: Retired |
0.x |
:x: Retired |
The latest release can always be found on the releases page.
Need help?
If you run into problems using the SDK, you can:
- Ask questions on the Okta Developer Forums
- Post issues here on GitHub (for code errors)
Users migrating from previous versions of this SDK should see Migrating Guide to learn what changes are necessary.
Browser compatibility / polyfill
This SDK is known to work with current versions of Chrome, Firefox, and Safari on desktop and mobile.
Compatibility with IE 11 / Edge can be accomplished by adding polyfill/shims for the following objects:
- ES Promise
- Array.from
- TextEncoder
- Object.assign
- UInt8 typed array
- webcrypto (crypto.subtle)
:warning: crypto polyfills are unable to use the operating system as a source of good quality entropy used to generate pseudo-random numbers that are the key to good cryptography. As such we take the posture that crypto polyfills are less secure and we advise against using them.
This module provides an entrypoint that implements all required polyfills.
If you are using the JS on a web page from the browser, you can copy the node_modules/@okta/okta-auth-js/dist contents to publicly hosted directory, and include a reference to the okta-auth-js.polyfill.js file in a <script> tag. It should be loaded before any other scripts which depend on the polyfill.
If you're using a bundler like Webpack or Browserify, you can simply import import or require @okta/okta-auth-js/polyfill at or near the beginning of your application's code:
import '@okta/okta-auth-js/polyfill';or
require('@okta/okta-auth-js/polyfill');The built polyfill bundle is also available on our global CDN. Include the following script in your HTML file to load before any other scripts:
<script src="https://global.oktacdn.com/okta-auth-js/7.5.1/okta-auth-js.polyfill.js" type="text/javascript" integrity="sha384-EBFsuVdi4TGp/DwS7b+t+wA8zmWK10omkX05ZjJWQhzWuW31t7FWEGOnHQeIr8+L" crossorigin="anonymous"></script>:warning: The version shown in this sample may be older than the current version. We recommend using the highest version available
Third party cookies
Many browsers have started blocking cross-origin or "third party" cookies by default. Although most of the Okta APIs supported by this SDK do not rely upon cookies, there are a few methods which do. These methods will break if third party cookies are blocked:
- session APIs require access to cookies stored on the Okta domain.
- token
- token.getWithoutPrompt must have access to cookies on the Okta domain via an iFrame running on your application's page.
- token.renew uses token.getWithoutPrompt and is subject to the same limitations.
If your application depends on any of these methods, you should try to either rewrite your application to avoid using these methods or communicate to your users that they must enable third party cookies. Okta engineers are currently working on a better long-term solution to this problem.
Getting started
Installing the Authentication SDK is simple. You can include it in your project via our npm package, @okta/okta-auth-js.
You'll also need:
- An Okta account, called an organization (sign up for a free developer organization if you need one)
- An Okta application, which can be created using the Okta Admin UI
Creating your Okta application
When creating a new Okta application, you can specify the application type. This SDK is designed to work with SPA (Single-page Applications) or Web applications. A SPA application will perform all logic and authorization flows client-side. A Web application will perform authorization flows on the server.
Configuring your Okta application
From the Okta Admin UI, click Applications, then select your application. You can view and edit your Okta application's configuration under the application's General tab.
Client ID
A string which uniquely identifies your Okta application.
Login redirect URIs
To sign users in, your application redirects the browser to an Okta-hosted sign-in page. Okta then redirects back to your application with information about the user. You can learn more about how this works on Okta-hosted flows.
You need to whitelist the login redirect URL in your Okta application settings.
Logout redirect URIs
After you sign users out of your app and out of Okta, you have to redirect users to a specific location in your application. You need to whitelist the post sign-out URL in your Okta application settings.
Using the npm module
Using our npm module is a good choice if:
- You have a build system in place where you manage dependencies with npm.
- You do not want to load scripts directly from third party sites.
To install @okta/okta-auth-js:
# Run this command in your project root folder.
# yarn
yarn add @okta/okta-auth-js
# npm
npm install --save @okta/okta-auth-jsIf you are using the JS on a web page from the browser, you can copy the node_modules/@okta/okta-auth-js/dist contents to publicly hosted directory, and include a reference to the okta-auth-js.min.js file in a <script> tag.
The built library bundle is also available on our global CDN. Include the following script in your HTML file to load before your application script:
<script src="https://global.oktacdn.com/okta-auth-js/7.5.1/okta-auth-js.min.js" type="text/javascript" integrity="sha384-6epSwnIDkI5zFNEVNjEYy3A7aSZ+C7ehmEyG8zDJZfP9Bmnxc51TK8du+2me4pjb" crossorigin="anonymous"></script>:warning: The version shown in this sample may be older than the current version. We recommend using the highest version available
Then you can create an instance of the OktaAuth object, available globally.
const oktaAuth = new OktaAuth({
// config
})However, if you're using a bundler like Webpack or Rollup you can simply import or require the module.
// ES module
import { OktaAuth } from '@okta/okta-auth-js'
const authClient = new OktaAuth(/* configOptions */)// CommonJS
var OktaAuth = require('@okta/okta-auth-js').OktaAuth;
var authClient = new OktaAuth(/* configOptions */);Usage guide
For an overview of the client's features and authentication flows, check out our developer docs. There, you will learn how to use the Auth SDK on a simple static page to:
- Retrieve and store an OpenID Connect (OIDC) token
- Get an Okta session
:warning: The developer docs may be written for an earlier version of this library. See Migrating from previous versions.
You can also browse the full API reference documentation.
:hourglass: Async methods return a promise which will resolve on success. The promise may reject if an error occurs.
Example Client
var config = {
issuer: 'https://{yourOktaDomain}/oauth2/default',
clientId: 'GHtf9iJdr60A9IYrR0jw',
redirectUri: 'https://acme.com/oauth2/callback/home',
};
var authClient = new OktaAuth(config);Running as a service
By default, creating a new instance of OktaAuth will not create any asynchronous side-effects. However, certain features such as token auto renew, token auto remove and cross-tab synchronization require OktaAuth to be running as a service. This means timeouts are set in the background which will continue working until the service is stopped. To start the OktaAuth service, simply call the start method right after creation and before calling other methods like handleRedirect. To terminate all background processes, call stop. See Service Configuration for more info.
var authClient = new OktaAuth(config);
await authClient.start(); // start the service
await authClient.stop(); // stop the serviceNote: Starting the service will also call authStateManager.updateAuthState.
Usage with Typescript
Type definitions are provided implicitly through the types entry in package.json. Types can also be referenced explicitly by importing them.
import {
OktaAuth,
OktaAuthOptions,
TokenManagerInterface,
AccessToken,
IDToken,
UserClaims,
TokenParams
} from '@okta/okta-auth-js';
const config: OktaAuthOptions = {
issuer: 'https://{yourOktaDomain}'
};
const authClient: OktaAuth = new OktaAuth(config);
const tokenManager: TokenManagerInterface = authClient.tokenManager;
const accessToken: AccessToken = await tokenManager.get('accessToken') as AccessToken;
const idToken: IDToken = await tokenManager.get('idToken') as IDToken;
const userInfo: UserClaims = await authClient.token.getUserInfo(accessToken, idToken);
if (!userInfo) {
const tokenParams: TokenParams = {
scopes: ['openid', 'email', 'custom_scope'],
};
authClient.token.getWithRedirect(tokenParams);
}Usage with Typescript < 3.6
Typescript versions prior to 3.6 have no type definitions for WebAuthn.
Support for WebAuthn in IDX API was introduced in @okta/okta-auth-js@6.1.0.
To solve this issue please install package @types/webappsec-credential-management version ^0.5.1.
Strategies for Obtaining Tokens
Authorization Code flow for web and native client types
Web and native clients can obtain tokens using the authorization_code flow which uses a client secret stored in a secure location. (SPA applications should use the PKCE flow which does not use a client secret) To use the authorization_code flow, set responseType to "code" and pkce to false:
var config = {
// Required config
issuer: 'https://{yourOktaDomain}/oauth2/default',
clientId: 'GHtf9iJdr60A9IYrR0jw',
redirectUri: 'https://acme.com/oauth2/callback/home',
// Use authorization_code flow
responseType: 'code',
pkce: false
};
var authClient = new OktaAuth(config);PKCE OAuth 2.0 flow
The PKCE OAuth flow will be used by default. This library supports PKCE for both browser and NodeJS applications. PKCE is widely supported by most modern browsers when running on an HTTPS connection. PKCE requires that the browser implements crypto.subtle (also known as webcrypto). Most modern browsers provide this when running in a secure context (on an HTTPS connection). PKCE also requires the TextEncoder object. This is available on all major browsers except IE 11 and Edge < v79. To add support, we recommend using a polyfill/shim such as text-encoding.
If the user's browser does not support PKCE, an exception will be thrown. You can test if a browser supports PKCE before construction with this static method:
OktaAuth.features.isPKCESupported()
Implicit OAuth 2.0 flow
:warning: We strongly discourage using the implicit flow. Use PKCE and/or client credentials if possible.
Implicit OAuth flow is available as an option if PKCE flow cannot be supported in your deployment. It is widely supported by most browsers, and can work over an insecure HTTP connection. Note that implicit flow is less secure than PKCE flow, even over HTTPS, since raw tokens are exposed in the browser's history. For this reason, we highly recommending using the PKCE flow if possible.
Implicit flow can be enabled by setting the pkce option to false
var config = {
pkce: false,
// other config
issuer: 'https://{yourOktaDomain}/oauth2/default',
};
var authClient = new OktaAuth(config);Redirects and Routing
To sign a user in, your application must redirect the browser to the Okta-hosted sign-in page.
Note: Initial redirect to Okta-hosted sign-in page starts a transaction with a stateToken lifetime set to one hour.
After successful authentication, the browser is redirected back to your application along with information about the user. Depending on your preferences it is possible to use the following callback strategies.
Handling the callback without routing
Most applications will handle an OAuth callback using a special route/page, separate from the signin page. However some SPA applications have no routing logic and will want to handle everything in a single page.
- Create / configure your auth-js instance
- Before starting the OktaAuth service, or making any other API calls with auth-js , call token.isLoginRedirect - if this returns true, call token.parseFromUrl and save tokens using tokenManager.setTokens. It’s important that no other app logic runs until the async parseFromUrl / token manager logic is complete
- After this, continue normal app logic
async function main() {
// create OktaAuth instance
var config = {
issuer: 'https://{yourOktaDomain}/oauth2/default',
clientId: 'GHtf9iJdr60A9IYrR0jw',
redirectUri: 'https://acme.com/oauth2/callback/home',
};
authClient = new OktaAuth(config);
// Subscribe to authState change event.
authClient.authStateManager.subscribe(function(authState) {
// Logic based on authState is done here.
if (!authState.isAuthenticated) {
// render unathenticated view
return;
}
// Render authenticated view
});
// Handle callback
if (authClient.token.isLoginRedirect()) {
const { tokens } = await authClient.token.parseFromUrl(); // remember to "await" this async call
authClient.tokenManager.setTokens(tokens);
}
// normal app startup
authClient.start(); // will update auth state and call event listeners
}Handling the callback with hash routing
According to the OAuth 2.0 spec the redirect URI "MUST NOT contain a fragment component": https://tools.ietf.org/html/rfc6749#section-3.1.2 When using a hash/fragment routing strategy and OAuth 2.0, the redirect callback will be the main / default route. The redirect callback flow will be very similar to handling the callback without routing. We recommend defining the logic that will parse redirect url at the very beginning of your app, before any other authorization checks.
Additionally, if using hash routing, we recommend using PKCE and responseMode "query" (this is the default for PKCE). With implicit flow, tokens in the hash could cause unpredictable results since hash routers may rewrite the fragment.
Handling the callback with path routing (on a dedicated route)
- Define a redirectUri that maps to a dedicated route in your app
- Before redirect, save the current route: setOriginalUri
- Do the redirect to okta: token.getWithRedirect
- After successful authentication, Okta will redirect back to the configured redirectUri, your app should load on the dedicated callback route
- On this callback page:
- call token.parseFromUrl to retrieve tokens
- Add tokens to the
TokenManager: tokenManager.setTokens
- Read saved route and redirect to it: getOriginalUri
Enabling DPoP
Reference: DPoP (Demonstrating Proof-of-Possession) - RFC9449
Requirements
DPoPmust be enabled in your Okta application (Guide: Configure DPoP)- Only supported on web (browser)
httpsis required. A secure context is required forWebCrypto.subtle- Targeted browsers must support
IndexedDB(MDN, caniuse) - :warning: IE11 (and lower) is not supported!
Configuration
const config = {
// other configurations
pkce: true, // required
dpop: true,
dpopOptions: {
// set to `true` to skip the validation to check the resulting token response includes `token_type: DPoP`
allowBearerTokens: false // defaults to `false`, tokens are validated to include `token_type: DPoP`
}
};
const authClient = new OktaAuth(config);Providing DPoP Proof to Resource Requests
Reference: The DPoP Authentication Scheme (RFC9449)
DPoP-Protected Resource Request (link)
GET /protectedresource HTTP/1.1
Host: resource.example.org
Authorization: DPoP Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsIm...Fetching DPoP-Protected Resource
async function dpopAuthenticatedFetch (url, options) {
const { method } = options;
const dpop = await authClient.getDPoPAuthorizationHeaders({ url, method });
// dpop = { Authorization: "DPoP token****", Dpop: "proof****" }
const headers = new Headers({...options.headers, ...dpop});
return fetch(url, {...options, headers });
}Handling use_dpop_nonce
Reference: Resource Server-Provided Nonce (RFC9449)
Resource servers can also choose to provide a nonce value to be included in DPoP proofs sent to them. They provide the nonce using the DPoP-Nonce header in the same way that authorization servers do...
Resource Server Response
HTTP/1.1 401 Unauthorized
WWW-Authenticate: DPoP error="use_dpop_nonce", \
error_description="Resource server requires nonce in DPoP proof"
DPoP-Nonce: eyJ7S_zG.eyJH0-Z.HX4w-7vHandling Response
async function dpopAuthenticatedFetch (url, options) {
// ...previous example...
const resp = await fetch(url, {...options, headers });
// resp = HTTP/1.1 401 Unauthorized...
if (!resp.ok) {
const nonce = authClient.parseUseDPoPNonceError(resp.headers);
if (nonce) {
const retryDpop = await authClient.getDPoPAuthorizationHeaders({ url, method, nonce });
const retryHeaders = new Headers({...options.headers, ...retryDpop});
return fetch(url, {...options, headers: retryHeaders });
}
}
return resp;
}Ensure browser can support DPoP (Recommended)
DPoP requires certain browser features. A user using a browser without the required features will unable to complete a request for tokens. It's recommended to verify browser support during application bootstrapping.
// App.tsx
useEffect(() => {
if (!authClient.features.isDPoPSupported()) {
// user will be unable to request tokens
navigate('/unsupported-error-page');
}
}, []);Clear DPoP Storage (Recommended)
DPoP requires the generation of a CryptoKeyPair which needs to be persisted in storage. Methods like signOut() or revokeAccessToken() will clear the key pair, however users don't always explicitly logout. It's therefore good practice to clear storage before login to flush any orphaned key pairs generated from previously requested tokens.
async function login (options) {
await authClient.clearDPoPStorage(); // clear possibly orphaned key pairs
return authClient.signInWithRedirect(options);
}Configuration reference
Whether you are using this SDK to implement an OIDC flow or for communicating with the Authentication API, the only required configuration option is issuer, which is the URL to an Okta Authorization Server
About the Issuer
You may use the URL for your Okta organization as the issuer. This will apply a default authorization policy and issue tokens scoped at the organization level.
var config = {
issuer: 'https://{yourOktaDomain}'
};
var authClient = new OktaAuth(config);Okta allows you to create multiple custom OAuth 2.0 authorization servers that you can use to protect your own resource servers. Within each authorization server you can define your own OAuth 2.0 scopes, claims, and access policies. Many organizations have a "default" authorization server.
var config = {
issuer: 'https://{yourOktaDomain}/oauth2/default'
};
var authClient = new OktaAuth(config);You may also create and customize additional authorization servers.
var config = {
issuer: 'https://{yourOktaDomain}/oauth2/custom-auth-server-id'
};
var authClient = new OktaAuth(config);Configuration options
These options can be included when instantiating Okta Auth JS (new OktaAuth(config)).
issuer
:warning: This option is required
The URL for your Okta organization or an Okta authentication server. About the issuer
clientId
Client Id pre-registered with Okta for the OIDC authentication flow. Creating your Okta application
redirectUri
The url that is redirected to when using token.getWithRedirect. This must be listed in your Okta application's Login redirect URIs. If no redirectUri is provided, defaults to the current origin (window.location.origin). Configuring your Okta application
postLogoutRedirectUri
Specify the url where the browser should be redirected after signOut. This url must be listed in your Okta application's Logout redirect URIs. If not specified, your application's origin (window.location.origin) will be used. Configuring your Okta application |
scopes
Specify what information to make available in the returned id_token or access_token. For OIDC, you must include openid as one of the scopes. Defaults to ['openid', 'email']. For a list of available scopes, see Scopes and Claims
state
A client-provided string that will be passed to the server endpoint and returned in the OAuth response. The value can be used to validate the OAuth response and prevent cross-site request forgery (CSRF). Defaults to a random string.
pkce
Default value is true which enables the PKCE OAuth Flow. To use the Implicit Flow or Authorization Code Flow, set pkce to false.
dpop
Default value is false. Set to true to enable DPoP (Demonstrating Proof-of-Possession (RFC9449))
See Guide: Enabling DPoP
dpopOptions
Default value:
dpopOptions: {
allowBearerTokens: false
}See Guide: Enabling DPoP
dpopOptions.allowBearerTokens
When false, dpop-enabled token requests are validated to contain token_type: DPoP and will throw otherwise. Set to true to skip this validation and allow Bearer tokens as a possible token_type. This can be useful during a migration, to avoid needing to update a web application simutaneously with Okta Org configurations. Defaults to false
responseMode
When requesting tokens using token.getWithRedirect values will be returned as parameters appended to the redirectUri.
In most cases you will not need to set a value for responseMode. Defaults are set according to the OpenID Connect 1.0 specification.
For PKCE OAuth Flow), the authorization code will be in search query of the URL. Clients using the PKCE flow can opt to instead receive the authorization code in the hash fragment by setting the responseMode option to "fragment".
For Implicit OAuth Flow), tokens will be in the hash fragment of the URL. This cannot be changed.
responseType
Specify the response type for OIDC authentication when using the Implicit OAuth Flow. The default value is ['token', 'id_token'] which will request both an access token and ID token. If pkce is true, both the access and ID token will be requested and this option will be ignored. For web/native applications using the authorization_code flow, this value should be set to "code" and pkce should be set to false.
authorizeUrl
Specify a custom authorizeUrl to perform the OIDC flow. Defaults to the issuer plus "/v1/authorize".
userinfoUrl
Specify a custom userinfoUrl. Defaults to the issuer plus "/v1/userinfo".
tokenUrl
Specify a custom tokenUrl. Defaults to the issuer plus "/v1/token".
ignoreSignature
:warning: This option should be used only for browser support and testing purposes.
ID token signatures are validated by default when token.getWithoutPrompt, token.getWithPopup, token.getWithRedirect, and token.verify are called. To disable ID token signature validation for these methods, set this value to true.
maxClockSkew
Defaults to 300 (five minutes). This is the maximum difference allowed between a client's clock and Okta's, in seconds, when validating tokens. Setting this to 0 is not recommended, because it increases the likelihood that valid tokens will fail validation.
ignoreLifetime
:warning: This option disables token lifetime validation, which can introduce security vulnerability issues. This option should be used for testing purpose. Please handle the error in your own app for production environment.
Token lifetimes are validated using the maxClockSkew. To override this and disable token lifetime validation, set this value to true.
transformAuthState
Callback function. When updateAuthState is called a new authState object is produced. Providing a transformAuthState function allows you to modify or replace this object before it is stored and emitted. A common use case is to change the meaning of isAuthenticated. By default, updateAuthState will set authState.isAuthenticated to true if unexpired tokens are available from tokenManager. This logic could be customized to also require a valid Okta SSO session:
const config = {
// other config
transformAuthState: async (oktaAuth, authState) => {
if (!authState.isAuthenticated) {
return authState;
}
// extra requirement: user must have valid Okta SSO session
const user = await oktaAuth.token.getUserInfo();
authState.isAuthenticated = !!user; // convert to boolean
authState.users = user; // also store user object on authState
return authState;
}
};
const oktaAuth = new OktaAuth(config);
oktaAuth.authStateManager.subscribe(authState => {
// handle latest authState
});
oktaAuth.authStateManager.updateAuthState();restoreOriginalUri
:link: web browser only
Callback function. When sdk.handleRedirect is called, by default it uses window.location.replace to redirect back to the originalUri. This option overrides the default behavior.
const config = {
// other config
restoreOriginalUri: async (oktaAuth, originalUri) => {
// redirect with custom router
router.replace({
path: toRelativeUrl(originalUri, baseUrl)
});
}
};
const oktaAuth = new OktaAuth(config);
if (oktaAuth.isLoginRedirect()) {
try {
await oktaAuth.handleRedirect();
} catch (e) {
// log or display error details
}
}devMode
Default to false. It enables debugging logs when set to true.
clientSecret
Used in authorization and interaction code flows by server-side web applications to obtain OAuth tokens. In a production application, this value should never be visible on the client side.
setLocation
Used in authorization and interaction code flows by server-side web applications to customize the redirect process.
httpRequestClient
The http request implementation. By default, this is implemented using cross-fetch. To provide your own request library, implement the following interface:
- Must accept:
- method (http method)
- url (target url)
- args (object containing headers and data)
- Must return a Promise that resolves with a raw XMLHttpRequest response
var config = {
url: 'https://{yourOktaDomain}',
httpRequestClient: function(method, url, args) {
// args is in the form:
// {
// headers: {
// headerName: headerValue
// },
// data: postBodyData,
// withCredentials: true|false,
// }
return Promise.resolve(/* a raw XMLHttpRequest response */);
}
}storageManager
The storageManager provides access to client storage for specific purposes. storageManager configuration is divided into named sections. The default configuration is shown below:
var config = {
storageManager: {
token: {
storageTypes: [
'localStorage',
'sessionStorage',
'cookie'
],
},
cache: {
storageTypes: [
'localStorage',
'sessionStorage',
'cookie'
]
},
transaction: {
storageTypes: [
'sessionStorage',
'localStorage',
'cookie'
]
}
}
}Important: If neither localStorage nor sessionStorage are available, the default storage provider may fall back to using cookie storage on some clients, . If your site will always be served over a HTTPS connection, you may want to forcibly enable "secure" cookies. This option will prevent cookies from being stored on an HTTP connection.
var config = {
cookies: {
secure: true
}
}storageType
The following values for storageType are recognized:
memory: values are stored in a closure and will not survive a page reloadsessionStorage: will only be available to the current browser tablocalStorage: available to all browser tabscookie: available to all browser tabs, and server-side code
Note: If the specified storageType is not available, but matches an entry in storageTypes, then default fallback logic will be applied. To disable this behavior, set storageTypes to an empty array:
var config = {
storageManager: {
token: {
storageType: 'sessionStorage',
storageTypes: []
}
}
}or set the storageTypes property with only one entry:
var config = {
storageManager: {
token: {
storageTypes: ['sessionStorage']
}
}
}If fallback logic is disabled, the storageManager may throw an exception if an instance of the given storageType cannot be created.
storageTypes
A list of storageTypes, in order of preference. If a type is not available, the next type in the list will be tried.
storageProvider
This option allows you to pass a custom storage provider instance. If a storageProvider is set, the storageType will be ignored.
Important: A storage provider will receive sensitive data, such as the user's raw tokens, as a readable string. Any custom storage provider should take care to save this string in a secure location which is not accessible to unauthorized users.
A storageProvider must provide a simple but specific API to access client storage. An example of a storageProvider is the built-in localStorage. It has a method called getItem that returns a string for a key and a method called setItem which accepts a string and key.
A custom storage provider must implement two functions:
getItem(key)setItem(key, value)
Optionally, a storage provider can also implement a removeItem function. If removeItem is not implemented, values will be cleared but keys will persist.
const myMemoryStore = {};
const storageProvider = {
getItem: function(key) {
// custom get
return myMemoryStore[key];
},
setItem: function(key, val) {
// custom set
myMemoryStore[key] = val;
},
// optional
removeItem: function(key) {
delete myMemoryStore[key];
}
}
var config = {
storageManager: {
token: {
storageProvider: storageProvider
}
}
}tokenManager
If cookie storage is specified, it is possible to specify whether or not a session cookie is used by the cookie storage. This will automatically be configured if sessionStorage is specified and you fall back to cookie storage. If sessionCookie is not specified it will create a cookie with an expiry date of 2200-01-01T00:00:00.000Z
var config = {
cookies: {
sessionCookie: true
}
}autoRenew
:warning: Moved to TokenService. For backwards compatibility will set
services.tokenService.autoRenew
expireEarlySeconds
:warning: DEV ONLY
To facilitate a more stable user experience, tokens are considered expired 30 seconds before actual expiration time. You can customize this value by setting the expireEarlySeconds option. The value should be large enough to account for network latency and clock drift between the client and Okta's servers.
NOTE expireEarlySeconds option is only allowed in the DEV environment (localhost). It will be reset to 30 seconds when running in environments other than DEV.
// Emit expired event 2 minutes before expiration
// Tokens accessed with tokenManager.get() will auto-renew within 2 minutes of expiration
tokenManager: {
expireEarlySeconds: 120
}autoRemove
:warning: Moved to TokenService. For backwards compatibility will set
services.tokenService.autoRenew
syncStorage
:warning: Moved to SyncStorageService. For backwards compatibility will set
services.syncStorageService.enable
storageKey
By default all tokens will be stored under the key okta-token-storage. You may want to change this if you have multiple apps running on a single domain which share the same storage type. Giving each app a unique storage key will prevent them from reading or writing each other's token values.
storage
Specify the storage type for tokens. This will override any value set for the token section in the storageManager configuration. By default, localStorage will be used. This will fall back to sessionStorage or cookie if the previous type is not available. You may pass an object or a string. If passing an object, it should meet the requirements of a custom storage provider. Pass a string to specify one of the built-in storage types:
localStorage(default)sessionStoragecookiememory: a simple in-memory storage provider
var config = {
url: 'https://{yourOktaDomain}',
tokenManager: {
storage: 'sessionStorage'
}
};
var authClient = new OktaAuth(config);A custom storage provider instance can also be passed here. (This will override any storageProvider value set under the token section of the storageManager configuration)
var myMemoryStore = {};
const storageProvider = {
getItem: function(key) {
// custom get
return myMemoryStore[key];
},
setItem: function(key, val) {
// custom set
myMemoryStore[key] = val;
},
// optional
removeItem: function(key) {
delete myMemoryStore[key];
}
}
const config = {
url: 'https://{yourOktaDomain}',
tokenManager: {
storage: storageProvider
}
};
const authClient = new OktaAuth(config);
const { tokens } = await authClient.token.getWithoutPrompt();
authClient.tokenManager.setTokens(tokens); // storageProvider.setItem
cookies
An object containing additional properties used when setting cookies
secure
Defaults to true, unless the application origin is http://localhost, in which case it is forced to false. If true, the SDK will set the "Secure" option on all cookies. When this option is true, an exception will be thrown if the application origin is not using the HTTPS protocol. Setting to false will allow setting cookies on an HTTP origin, but is not recommended for production applications.
sameSite
Defaults to none if the secure option is true, or lax if the secure option is false. Allows fine-grained control over the same-site cookie setting. A value of none allows embedding within an iframe. A value of lax will avoid being blocked by user "3rd party" cookie settings. A value of strict will block all cookies when redirecting from Okta and is not recommended.
clearPendingRemoveTokens
Defaults to true, set this option to false if you want to opt-out of the default clearing pendingRemove tokens behaviour when tokenManager.start() is called.
services
:gear: Requires a running service The following configurations require
OktaAuthto be running as a service. See running service for more info.
Default configuration:
services: {
autoRenew: true,
autoRemove: true,
syncStorage: true,
renewOnTabActivation: true,
tabInactivityDuration: 1800 // seconds
}autoRenew
When true, the library will attempt to renew tokens before they expire. If you wish to manually control token renewal, set autoRenew to false to disable this feature. You can listen to expired events to know when the token has expired.
NOTE tokens are considered
expiredslightly before their actual expiration time. For more info, see expireEarlySeconds.
In version 6.X, the autoRenew configuration was set in config.tokenManager. To maintain backwards compatibility, this configuration is still respected but with a slight caveat. tokenManager.autoRenew configures 2 token auto renew strategies, active and passive.
active- Network requests are made in the background in an attempt to refresh tokens before they are truly expired to maintain a seamless UX.:warning: this can cause an unintended side effect where the session never expires because it is constantly being refreshed (extended) before the actual expiration time
passive- Token refresh attempts are only made whenoktaAuth.isAuthenticatedis called and the current tokens are determined to be expired.
When tokenManager.autoRenew is true both renew strategies are enabled. To disable the active strategy, set tokenManager.autoRenew to true and services.autoRenew to false. To disable both renew strategies set either tokenManager.autoRenew or services.autoRenew to false
autoRemove
By default, the library will attempt to remove expired tokens when autoRemove is true. If you wish to disable auto removal of tokens, set autoRemove to false.
syncStorage
Automatically syncs tokens across browser tabs when it's supported in browser (browser supports native broadcastchannel API, IndexDB or localStorage). To disable this behavior, set syncStorage to false.
This is accomplished by selecting a single tab to handle the network requests to refresh the tokens and broadcasting to the other tabs. This is done to avoid all tabs sending refresh requests simultaneously, which can cause rate limiting/throttling issues.
renewOnTabActivation
NOTE: This service requires
autoRenew: true
When enabled ({ autoRenew: true, renewOnTabActivation: true }), this service binds a handler to the Page Visibility API which attempts a token renew (if needed) when the tab becomes active after a (configurable) inactivity period
tabInactivityDuration
The amount of time, in seconds, a tab needs to be inactive for the RenewOnTabActivation service to attempt a token renew. Defaults to 1800 (30 mins)
API Reference
- start
- stop
- signIn
- signInWithCredentials
- signInWithRedirect
- signOut
- closeSession
- revokeAccessToken
- revokeRefreshToken
- forgotPassword
- unlockAccount
- verifyRecoveryToken
- webfinger
- fingerprint
- isAuthenticated
- getUser
- getIdToken
- getAccessToken
- getOrRenewAccessToken
- storeTokensFromRedirect
- setOriginalUri
- getOriginalUri
- removeOriginalUri
- isLoginRedirect
- handleLoginRedirect
- handleRedirect
- setHeaders
- tx.resume
- tx.exists
- transaction.status
- getDPoPAuthorizationHeaders
- parseUseDPoPNonceError
- clearDPoPStorage
- session
- idx
- myaccount
- endpoints
- token
- tokenManager
- authStateManager
- http
start()
:hourglass: async
Starts the OktaAuth service. See running as a service for more details.
stop()
:hourglass: async
Stops the OktaAuth service. See running as a service for more details.
signIn(options)
:warning: Deprecated, this method will be removed in next major release, use signInWithCredentials instead.
signInWithCredentials(options)
See authn API.
signInWithRedirect(options)
:link: web browser only
:hourglass: async
Starts the full-page redirect to Okta with optional request parameters. In this flow, there is a originalUri parameter in options to track the route before the user signIn, and the addtional params are mapped to the Authorize options. You can use storeTokensFromRedirect to store tokens and getOriginalUri to clear the intermediate state (the originalUri) after successful authentication.
if (authClient.isLoginRedirect()) {
try {
await authClient.handleRedirect();
} catch (e) {
// log or display error details
}
} else if (!await authClient.isAuthenticated()) {
// Start the browser based oidc flow, then parse tokens from the redirect callback url
authClient.signInWithRedirect();
} else {
// User is authenticated
}signOut()
:hourglass: async :link: web browser only
Signs the user out of their current Okta session and clears all tokens stored locally in the TokenManager. By default, the refresh token (if any) and access token are revoked so they can no longer be used. Some points to consider:
- Will redirect to an Okta-hosted page before returning to your app.
- If a
postLogoutRedirectUrihas not been specified or configured,window.location.originwill be used as the return URI. This URI must be listed in the Okta application's Login redirect URIs. If the URI is unknown or invalid the redirect will end on a 400 error page from Okta. This error will be visible to the user and cannot be handled by the app. - Requires a valid ID token. If an ID token is not available,
signOutwill fallback to using the XHR-based closeSession method. This method may fail to sign the user out if 3rd-party cookies have been blocked by the browser. - If a fallback to closeSession is used,
signOut()returns a promise that resolves with the result of closeSession (trueif an existing Okta session have been closed orfalseif a session does not exist or has already been closed). Otherwise a promise resolves withtrue. - For more information, see Logout in the OIDC API documentation.
signOut takes the following options:
postLogoutRedirectUri- Setting a value will override thepostLogoutRedirectUriconfigured on the SDK. This will default towindow.location.originif no value is provided. To prevent this explicitly passnullto leverage the default behavior of/logout. IfsignOutfalls back tocloseSessionwindow.location.originwill still be used as the default value, even ifnullis passed.state- An optional value, used along withpostLogoutRedirectUri. If set, this value will be returned as a query parameter during the redirect to thepostLogoutRedirectUriidToken- Specifies the ID token object. By default,signOutwill look for a token object namedidTokenwithin theTokenManager. If you have stored the id token object in a different location, you should retrieve it first and then pass it here.clearTokensBeforeRedirect- Iftrue(default:false) local tokens will be removed before the logout redirect happens. Otherwise a flag (pendingRemove) will be added to each local token instead of clearing them immediately. CallingoktaAuth.start()after logout redirect will clear local tokens if flags are found. Use this option with care: removing local tokens before fully terminating the Okta SSO session can result in logging back in again when using@okta/okta-react'sSecureRoutecomponent.revokeAccessToken- Iffalse(default:true) the access token will not be revoked. Use this option with care: not revoking tokens may pose a security risk if tokens have been leaked outside the application.revokeRefreshToken- Iffalse(default:true) the refresh token will not be revoked. Use this option with care: not revoking tokens may pose a security risk if tokens have been leaked outside the application. Revoking a refresh token will revoke any access tokens minted by it, even ifrevokeAccessTokenisfalse.accessToken- Specifies the access token object. By default,signOutwill look for a token object namedaccessTokenwithin theTokenManager. If you have stored the access token object in a different location, you should retrieve it first and then pass it here. This options is ignored if therevokeAccessTokenoption isfalse.
// Sign out using the default options
authClient.signOut()// Override the post logout URI for this call
authClient.signOut({
postLogoutRedirectUri: `${window.location.origin}/logout/callback`
});// In this case, the ID token is stored under the 'myIdToken' key
var idToken = await authClient.tokenManager.get('myIdToken');
authClient.signOut({
idToken: idToken
});// In this case, the access token is stored under the 'myAccessToken' key
var accessToken = await authClient.tokenManager.get('myAccessToken');
authClient.signOut({
accessToken: accessToken
});closeSession()
:warning: This method requires access to third party cookies
:hourglass: async
Signs the user out of their current Okta session and clears all tokens stored locally in the TokenManager. Returns a promise that resolves with true if an existing Okta session have been closed, or false if a session does not exist or has already been closed. This method is an XHR-based alternative to signOut, which will redirect to Okta before returning to your application. Here are some points to consider when using this method:
- Executes in the background. The user will see not any change to
window.location. - The method will fail to sign the user out if 3rd-party cookies are blocked by the browser.
- Does not revoke the access token. It is strongly recommended to call revokeAccessToken before calling this method
- It is recommended (but not required) for the app to call
window.location.reload()after theXHRmethod completes to ensure your app is properly re-initialized in an unauthenticated state. - For more information, see Close Current Session in the Session API documentation.
await authClient.revokeAccessToken(); // strongly recommended
authClient.closeSession()
.then((sessionClosed) => {
if (sessionClosed) {
window.location.reload(); // optional
} else {
// Session does not exist or has already been closed
}
})
.catch(e => {
if (e.xhr && e.xhr.status === 429) {
// Too many requests
}
})revokeAccessToken(accessToken)
:hourglass: async
Revokes the access token for this application so it can no longer be used to authenticate API requests. The accessToken parameter is optional. By default, revokeAccessToken will look for a token object named accessToken within the TokenManager. If you have stored the access token object in a different location, you should retrieve it first and then pass it here. Returns a promise that resolves when the operation has completed. This method will succeed even if the access token has already been revoked or removed.
revokeRefreshToken(refreshToken)
:hourglass: async
Revokes the refresh token (if any) for this application so it can no longer be used to mint new tokens. The refreshToken parameter is optional. By default, revokeRefreshToken will look for a token object named refreshToken within the TokenManager. If you have stored the refresh token object in a different location, you should retrieve it first and then pass it here. Returns a promise that resolves when the operation has completed. This method will succeed even if the refresh token has already been revoked or removed.
forgotPassword(options)
See authn API.
unlockAccount(options)
See authn API.
verifyRecoveryToken(options)
See authn API.
webfinger(options)
:hourglass: async
Calls the Webfinger API and gets a response.
resource- URI that identifies the entity whose information is sought, currently only acct scheme is supported (e.g acct:dade.murphy@example.com)rel- Optional parameter to request only a subset of the information that would otherwise be returned without the "rel" parameter
authClient.webfinger({
resource: 'acct:john.joe@example.com',
rel: 'okta:idp'
})
.then(function(res) {
// use the webfinger response to select an idp
})
.catch(function(err) {
console.error(err);
});fingerprint(options)
:hourglass: async
Creates a browser fingerprint. See Primary authentication with device fingerprint for more information.
timeout- Time in ms until the operation times out. Defaults to15000.
authClient.fingerprint()
.then(function(fingerprint) {
// Do something with the fingerprint
})
.catch(function(err) {
console.log(err);
})isAuthenticated(options?)
:hourglass: async
Resolves with authState.isAuthenticated from non-pending authState.
options
expiredTokenBehavior:'renew'(default) |'remove'|'none''renew'- attempt to renew token beforePromiseresolves'remove'- removes token'none'- neither renews or removes expired token
NOTE:
tokenManager.autoRenewandtokenManager.autoRemovedetermine the default value forexpiredTokenBehavior
getUser()
:hourglass: async
Alias method of token.getUserInfo.
getIdToken()
Returns the id token string retrieved from authState if it exists.
getAccessToken()
Returns the access token string retrieved from authState if it exists.
getOrRenewAccessToken()
Returns the access token string if it exists. Returns null if the access token doesn't exist or a renewal cannot be completed
storeTokensFromRedirect()
:hourglass: async
Parses tokens from the redirect url and stores them.
setOriginalUri(uri?)
Stores the current URL state before a redirect occurs.
getOriginalUri(state?)
Returns the stored URI string stored by setOriginal. An OAuth state parameter is optional. If no value is passed for state, the URI is retrieved from isolated session storage and will work in a single browser. If a valid OAuth state is passed this method can return the URI stored from another browser tab.
removeOriginalUri()
Removes the stored URI string stored by setOriginal from storage.
isLoginRedirect()
:link: web browser only
Check window.location to verify if the app is in OAuth callback state or not. This function is synchronous and returns true or false.
if (authClient.isLoginRedirect()) {
// callback flow
try {
await authClient.handleRedirect();
} catch (e) {
// log or display error details
}
} else {
// normal app flow
}handleLoginRedirect(tokens?, originalUri?)
:link: web browser only
:hourglass: async
:warning: Deprecated, this method could be removed in next major release, use sdk.handleRedirect instead.
Stores passed in tokens or tokens from redirect url into storage, then redirect users back to the originalUri. When using PKCE authorization code flow, this method also exchanges authorization code for tokens. By default it calls window.location.replace for the redirection. The default behavior can be overrided by providing options.restoreOriginalUri. By default, originalUri will be retrieved from storage, but this can be overridden by passing a value fro originalUri to this function in the 2nd parameter.
Note:
handleLoginRedirectthrowsOAuthErrororAuthSdkErrorin case there are errors during token retrieval.
handleRedirect(originalUri?)
:link: web browser only
:hourglass: async
Handle a redirect to the configured redirectUri that happens on the end of login flow, enroll authenticator flow or on an error.
Stores tokens from redirect url into storage (for login flow), then redirect users back to the originalUri. When using PKCE authorization code flow, this method also exchanges authorization code for tokens. By default it calls window.location.replace for the redirection. The default behavior can be overrided by providing options.restoreOriginalUri. By default, originalUri will be retrieved from storage, but this can be overridden by specifying originalUri in the first parameter to this function.
Note:
handleRedirectthrowsOAuthErrororAuthSdkErrorin case there are errors during token retrieval or authenticator enrollment.
handleIDPPopupRedirect(url?)
:link: web browser only
:hourglass: async
Used in conjunction with token.getWithIDPPopup. Handles the redirect from the Authorization Server back to the web application. This method relays the resulting OAuth2 response from the popup window to the main window.
setHeaders()
Can set (or unset) request headers after construction.
const authClient = new OktaAuth({
issuer: 'https://{yourOktaDomain}',
// headers can be set during construction
headers: {
foo: 'bar'
}
});
// Headers can be set (or modified) after construction
authClient.setHeaders({
foo: 'baz'
});
// Headers can be removed
authClient.setHeaders({
foo: undefined
})tx.resume()
See authn API.
tx.exists()
See authn API.
transaction.status
See authn API.
getDPoPAuthorizationHeaders(params)
:link: web browser only
:hourglass: async
Requires dpop set to true. Returns Authorization and Dpop header values to build a DPoP protected-request.
Params: url and (http) method are required.
accessTokenis optional, but will be read fromtokenStorageif not providednonceis optional, may be provided viause_dpop_noncepattern from Resource Server (more info)
parseUseDPoPNonceError(headers)
:link: web browser only
Utility to extract and parse the WWW-Authenticate and DPoP-Nonce headers from a network response from a DPoP-protected request. Should the response be in the following format, the nonce value will be returned. Otherwise returns null
HTTP/1.1 401 Unauthorized
WWW-Authenticate: DPoP error="use_dpop_nonce", \
error_description="Resource server requires nonce in DPoP proof"
DPoP-Nonce: eyJ7S_zG.eyJH0-Z.HX4w-7vclearDPoPStorage(clearAll=false)
:link: web browser only
:hourglass: async
Clears storage location of CryptoKeyPairs generated and used by DPoP. Pass true to remove all key pairs as it's possible for orphaned key pairs to exist. If clearAll is false, the key pair bound to the current accessToken in tokenStorage will be removed.
It's recommended to call this function during user login. See Example
session
session.setCookieAndRedirect(sessionToken, redirectUri)
See authn API.
session.exists()
:link: web browser only
:warning: This method requires access to third party cookies
:hourglass: async
Returns a promise that reso