Skip to content

Latest commit

 

History

History
160 lines (112 loc) · 8.64 KB

migrate-from-authn-to-idx.md

File metadata and controls

160 lines (112 loc) · 8.64 KB
Raw

Migrating from authn to IDX

The IDX API is built on the Okta Identity Engine. The API allows applications to implement features which were not possible with the older authn API, such as multi-factor authentication without redirection to Okta. We recommend that all new application deployments use the IDX API. Existing applications using authn can migrate to IDX by following this guide.

Introduction to IDX

The IDX API is designed to enable dynamic login experiences, like the Okta SignIn Widget. IDX is a brand new protocol and enables more authentication flows than the traditional authn API. IDX pairs very well with dynamic-rendered or templated UI frameworks like React, Angular or even JSPs. Each IDX response describes a form, prompting the user for the inputs needed to proceed to the next step in the authentication flow. For example:

const { nextStep } = await idx.start();
// nextStep.inputs = [{ name: 'username', ... }, { name: 'password', ... }]
const { status } = await idx.proceed({username: 'foo', password: 'bar'});
// status = IdxStatus.SUCCESS

The authn API is still supported. IDX is not a drop-in replacement for authn. It's a more sophisticated protocol. Either API can be used to build authencation flows. However if you're looking to ultitize features of OIE, like passwordless authentication, you'll have to build on top of IDX

Getting Started

The first step is to enable the Okta Identity Engine on your Okta organization. If your organization does not have the Okta Identity Engine enabled, 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.

The IDX API can be accessed using the @okta/okta-auth-js module. We recommend upgrading to the latest available version. See detail in Using the npm module.

Configuration

IDX applications must use the PKCE OAuth 2.0 flow. In addition to issuer, you must specify a clientId and redirectUri in your config. (pkce is enabled by default). A minimal config for a SPA application looks like:

var config = {
  issuer: 'https://{yourOktaDomain}/oauth2/default',
  clientId: 'GHtf9iJdr60A9IYrR0jw',
  redirectUri: 'https://{yourAppDomain}/login/callback',
};

var authClient = new OktaAuth(config);

Server-side web applications must also provide a clientSecret.

Transaction Models

Authn

Entrypoint methods in the authn API, such as signInWithCredentials and forgotPassword return a Transaction object which has a status field and various methods to proceed or cancel the transaction.

Basic authentication using authn API:

const transaction = await authClient.signInWithCredentials({
  username: 'some-username',
  password: 'some-password'
});

if (transaction.status === 'SUCCESS') {
  authClient.session.setCookieAndRedirect(transaction.sessionToken); // Sets a cookie on redirect
}

// App will receive tokens on redirect

IDX

Methods in the IDX API return an IdxTransaction object which also includes a status field. If the transaction was successful and no further action is required, this value will be IdxStatus.SUCCESS. If the value is IdxStatus.PENDING, then some further action is required. Unlike the authn Transaction object, the IdxTransaction object does not include methods to proceed or cancel the transaction, these methods are exposed via the idx namespace (authClient.idx.proceed and authClient.idx.cancel).

Basic authentication using IDX API:

const { 
  status, // IdxStatus.PENDING
  nextStep: { 
    inputs // [{ name: 'username', ... }, { name: 'password', ... }]
  }
} = await authClient.idx.start();

const { 
  status // IdxStatus.SUCCESS
} = await authClient.idx.proceed({ username: 'xxx',  password: 'xxx' });

Optionally, form values can be passed "up front". This may result in multiple network calls to the IDX API

Basic authentication using IDX API (up-front approach):

const { status } = await authClient.idx.start({ 
  username: 'some-username',
  password: 'some-password',
});
// status = IdxStatus.SUCCESS

IDX Transaction

For more details, check the type

The primary goal of any IDX transaction is to authenticated a user. The nextStep field will contain the form necessary to continue on the current "path".

start();                                  // nextStep.inputs: [username]
proceed({username: 'user@foo.com'});      // nextStep.inputs: [password]
proceed({password: '12345});

Sometimes users need to complete an additonal step before authenticating, like signing up (registration) or unlocking their account. The availableSteps field contains all available "paths" a user can proceed down as of their current step. The value of availableSteps is largely dictated by your Okta Org (OIE) Policies. For example: for Self-service registration to be an avaiable path, it will need to be enabled in your Org settings

{
  status,           // ENUM [PENDING, SUCCESS, FAILURE, TERMINAL, CANCELED]

  nextStep,         // { inputs: [], ... }

  availableSteps    // [{ inputs: [], ... }, { inputs: [], ... }, ...]

  messages,         // describes errors, if any have occured

Implementing IDK

Standard IDX flows should use idx.start and idx.proceed. However these methods will allow the user to step into all available paths. This makes sense if you're developing something similar to the Okta SignIn Widget, but may not make sense in all cases. For example, if you're building a dedicated registration page, you may not want to the user to step into the account unlock path. To solve this, all idx methods accept a flow parameter. Setting flow restricts the paths the SDK will step into, preventing the user from entering an unexpected path.

For more details, see IDX Flow

For convenience, idx has a few entry point methods which will set the flow param (listed below)

Authn to IDX Conversion Chart

Note: These are not a 1-1 mapping. These IDX entry points are used to enter a specific flow

authn IDX
signInWithCredentials idx.authenticate
forgotPassword idx.recoverPassword
unlockAccount idx.unlockAccount
verifyRecoveryToken idx.start({ recoveryToken })
session.setCookieAndRedirect N/A
transaction.cancel idx.cancel

Handling Errors

Errors will be returned on the IdxTransaction object.

If the status field has a value of IdxStatus.FAILURE, this indicates an SDK-level error, such as application mis-configuration. In this case, check the error field on the transaction for more details.

If the status field has a value of IdxStatus.TERMINAL, this indicates the flow has run into a terminal state, check the messages field to handle it.

Helpful Information and Resources