⚠️ Okta recommends against integrating directly with this module. Developers wishing to use IDX APIs in an end-to-end flow should use the Okta AuthJS SDK instead. See the guide: Using IDX with AuthJS.
❕ The use of this SDK requires usage of the Okta Identity Engine. If you want to request to gain access to the Okta Identity Engine, please reach out to your account manager. If you do not have an account manager, please reach out to oie@okta.com for more information.
okta-idx-js is a low-level protocol library used internally by Okta AuthJS and the Okta Signin Widget to parse responses from the IDX API. This library does not contain any OAuth/PKCE code and cannot retrieve tokens.
This library is intended to ease JS-based integration with the Okta Identity Engine (OIE) making use if the Okta Identity Experience (IDX) API. This library wraps the sequence of calls to the Okta IDX endpoints so that the consumer doesn't have to parse the entirety of each response, nor manage XHR calls.
Though this library exposes the metadata needed to generate a UI to gather needed data and select between available options, the consumer is responsible for interpeting and acting on that metadata - idx-js is focused on sending passed data to the appropriate endpoint for the selected actions only.
This library uses semantic versioning and follows Okta's Library Version Policy.
| Version | Status |
|---|---|
| 0.x.x |
The latest release can always be found on the releases page.
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)
You will need:
- An Okta account, called an organization (sign up for a free developer organization if you need one)
# npm
npm install @okta/okta-idx-js
# yarn
yarn install @okta/okta-idx-jsidx-js is compatible with node 12+
idx-js uses ES module syntax:
import idx from `@okta/okta-idx-js`;idx.start() is passed a config object and returns a promise that resolves to an idxState object.
Configuration params:
- clientId: (required) Client Id pre-registered with Okta for the OIDC authentication flow.
- issuer: (required) The protocol+domain+path of the Okta issuer domain (Authorization Server).
- redirectUri: (required) The url that is redirected to after authentication. This must be pre-registered as part of client registration in the okta application console.
- version: (required) The server version of the IDX api. (Example: "1.0.0") You must specify a specific version as any change in the parsed output can have drastic impact on anything relying on this library.
- codeChallenge: (required) A PKCE code challenge (base64UrlEncoded hash of code verifier, which is maintained outside of the idx-js library
- codeChallengeMethod: (required) The method used to generate the hash of the PKCE code challenge. Per PKCE spec, this is currently 'S256'
- scopes: (optional) Specify what information to make available in the returned tokens by providing an array of strings with known meaning as an OIDC scope. Defaults to ['openid', 'email'].
- interactionHandle: (optional) The current interactionHandle of a customer-hosted flow in-progress. New flows will not have an existing handle and should not try to pass this value.
idx.start() is called anytime you don't have an idxState object (such as after a browser full-page redirect) and will resume any OIE flow in-progress based on the passed interactionHandle (customer-hosted)
let idxState;
try {
idxState = await idx.start({ issuer, clientId, redirectUri, version, codeChallenge, codeChallengeMethod });
// idxState has properties and methods
} catch (err) {
// err.error has an error message
}The happy path for idx-js is:
- Calling
idx.start()initially to get anidxState - Inspecting the
idxState.neededToProceedarray to see what data to send- use the
idxState.contextobject for any additional information to display
- use the
- Collect the data from the user (generating a UI is outside the scope of idx-js)
- Pass the collected data to
idxState.proceed('name of remediation', dataObject) - The returned promise resolves to a new
idxStateobject - Continue this loop until
idxState.hasInteractionCode()returns true - Get an
interactionCodefromidxState.interactionCode - Exchange the
interactionCodeto obtain tokens. This is outside idx-js, but can be done with (for example) okta-auth-jstoken.exchangeCodeForTokens(...)
The less-than-happy paths include these options:
- Canceling the flow: Actions that don't result in a new (usable) idxState are collected into an object of functions,
idxState.actions - Something complicated:
idxState.rawIdxResponsegives you access to the uninterpreted response
To read, modify, or perform additional logic before a HTTP request is performed, add a custom interceptor:
idx.client.interceptors.request.use(requestConfig => {
// Add a custom header to the request
requestConfig.headers['X-Custom-Header'] = 'my-custom-header';
return requestConfig;
});Clear all attached interceptors.
idx.client.interceptors.request.clear();proceed() is called to move forward to the next step of authentication.
proceed() returns a promise that resolves to a new idxState.
remediationChoiceis the name of the corresponding entry inneededToProceed(note that any actions that can't be called withproceed, such as full-page redirects, are not valid remediationChoices)paramsis an object of key/value pairs for data (matching the list inneededToProceedIon entry)
neededToProceed is an array of objects, with each object having:
- a
.nameproperty that will be used as aremediationChoicefor callingproceed() - a
.valueproperty that is an array of Ion-based descriptions of the values to pass toproceed() - Other properties may be internal or dropped in later iterations (TODO: Confirm and implement)
context is an object of any metadata values about the current state of the IDX request and/or potential remediations. Possible properties within this object include:
expiresAt- When the current stateHandle expiresintent- The intent (e.g. "LOGIN") of the IDX flowuser- Information about the user currently in the flowstateHandle- The current stateHandle valueversion- What version of the IDX API in usefactor- Information about the current factor being used for authenticationterminal- Any terminal errorsmessages- Any message information. Note that messages that pertain to particular fields will be in the remediation structures describing those fields.success- The result information for a successful flow
actions is an object of functions that do not return a new idxState, but can still be called as background (XHR) requests. Potential actions include:
actions.cancel()- Cancels the current authentication flow- actions involving factor resets (e.g. forgotten passwords)
- actions involving WebAuthN interactions (TODO: Confirm flows)
hasInteractionCode() returns true if the flow has resulted in a final success and the idxState contains an interactionCode that can be exchanged for tokens. Not used in the Okta-hosted flow.
interactionCode is the value returned at the end of a successful IDX flow. This value can be sent to the Okta v1/token endpoint to be exchanged for the tokens matching the requesting scope. The PKCE code_verifier used to produce the codeChallenge sent to idx.start(...) must be sent to the token endpoint as well.
rawIdxResponse is an object containing the raw Ion response. It is included to cover the uncommon cases that idx-js doesn't serve well, but the goal is to minimize the need and use of it, as any useful information should be more easily obtained in .neededToProceed, .actions, or .context.
We are happy to accept contributions and PRs! Please see the contribution guide to understand how to structure a contribution.
Create a .env file with the below or set the same environment variables:
ISSUER_URL=https://{yourOktaDomain}
CLIENT_ID={clientId}
REDIRECT_URI=http://localhost:8080/implicit/callback
USER_IDENTIFIER={userEmailAddress}