Introduction

The Okta Auth SDK builds on top of our Authentication API and OAuth 2.0 API to enable you to create a fully branded sign-in experience using JavaScript.

For an overview of the client's features and authentication flows, check out our developer docs.

Read our contributing guidelines if you wish to contribute.

Table of Contents

• Install
• Using the Okta CDN
• Using the npm module
• API
• OktaAuth
• signIn
• signOut
• forgotPassword
• unlockAccount
• verifyRecoveryToken
• tx.resume
• tx.exists
• transaction.status
  • LOCKED_OUT
  • PASSWORD_EXPIRED
  • PASSWORD_RESET
  • PASSWORD_WARN
  • RECOVERY
  • RECOVERY_CHALLENGE
  • MFA_ENROLL
  • Enroll Factor
  • MFA_ENROLL_ACTIVATE
  • MFA_REQUIRED
  • MFA_CHALLENGE
  • SUCCESS
• session.setCookieAndRedirect
• session.exists
• session.get
• session.refresh
• token.getWithoutPrompt
• token.getWithPopup
• token.getWithRedirect
• token.parseFromUrl
• token.decode
• token.refresh
• token.getUserInfo
• token.verify
• tokenManager.add
• tokenManager.get
• tokenManager.remove
• tokenManager.clear
• tokenManager.refresh
• tokenManager.on
• tokenManager.off
• OpenId Connect Options
• Client Configuration
• Developing the Okta Auth Client
• Building the Client
• Build and Test Commands

Install

You can include Okta Auth JS in your project either directly from the Okta CDN, or by packaging it with your app via our npm package, @okta/okta-auth-js.

Using the Okta CDN

Loading our assets directly from the CDN is a good choice if you want an easy way to get started with okta-auth-js, and don't already have an existing build process that leverages npm for external dependencies.

To use the CDN, include links to the JS and CSS files in your HTML:

<script
  src="https://ok1static.oktacdn.com/assets/js/sdk/okta-auth-js/1.6.0/okta-auth-js.min.js"
  type="text/javascript"></script>

The okta-auth-js.min.js file will expose a global OktaAuth object. Use it to bootstrap the client:

var authClient = new OktaAuth({/* configOptions */});

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.
[project-root-folder]$ npm install @okta/okta-auth-js --save

After running npm install:

The minified auth client will be installed to node_modules/@okta/okta-auth-js/dist. You can copy the dist contents to a publicly hosted directory. However, if you're using a bundler like Webpack or Browserify, you can simply import the module using CommonJS.

var OktaAuth = require('@okta/okta-auth-js');
var authClient = new OktaAuth(/* configOptions */);

API

new OktaAuth(config)

Creates a new instance of the Okta Auth Client with the provided options. The client has many config options. The only required option to get started is url, the base url for your Okta domain.

• config - Options that are used to configure the client

var authClient = new OktaAuth({url: 'https://acme.okta.com'});

signIn(options)

The goal of an authentication flow is to set an Okta session cookie on the user's browser or retrieve an id_token or access_token. The flow is started using signIn.

• username - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)
• password - The password of the user

authClient.signIn({
  username: 'some-username',
  password: 'some-password'
})
.then(function(transaction) {
  if (transaction.status === 'SUCCESS') {
    authClient.session.setCookieAndRedirect(transaction.sessionToken); // Sets a cookie on redirect
  } else {
    throw 'We cannot handle the ' + transaction.status + ' status';
  }
})
.fail(function(err) {
  console.error(err);
});

signOut()

Signs the user out of their current Okta session.

authClient.signOut()
.then(function() {
  console.log('successfully logged out');
})
.fail(function(err) {
  console.error(err);
});

forgotPassword(options)

Starts a new password recovery transaction for a given user and issues a recovery token that can be used to reset a user’s password.

• username - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)
• factorType - Recovery factor to use for primary authentication. Supported options are SMS, EMAIL, or CALL
• relayState - Optional state value that is persisted for the lifetime of the recovery transaction

authClient.forgotPassword({
  username: 'dade.murphy@example.com',
  factorType: 'SMS',
})
.then(function(transaction) {
  return transaction.verify({
    passCode: '123456' // The passCode from the SMS or CALL
  });
})
.then(function(transaction) {
  if (transaction.status === 'SUCCESS') {
    authClient.session.setCookieAndRedirect(transaction.sessionToken);
  } else {
    throw 'We cannot handle the ' + transaction.status + ' status';
  }
})
.fail(function(err) {
  console.error(err);
});

unlockAccount(options)

Starts a new unlock recovery transaction for a given user and issues a recovery token that can be used to unlock a user’s account.

• username - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)
• factorType - Recovery factor to use for primary authentication. Supported options are SMS, EMAIL, or CALL
• relayState - Optional state value that is persisted for the lifetime of the recovery transaction

authClient.unlockAccount({
  username: 'dade.murphy@example.com',
  factorType: 'SMS',
})
.then(function(transaction) {
  return transaction.verify({
    passCode: '123456' // The passCode from the SMS
  });
})
.then(function(transaction) {
  if (transaction.status === 'SUCCESS') {
    authClient.session.setCookieAndRedirect(transaction.sessionToken);
  } else {
    throw 'We cannot handle the ' + transaction.status + ' status';
  }
})
.fail(function(err) {
  console.error(err);
});

verifyRecoveryToken(options)

Validates a recovery token that was distributed to the end-user to continue the recovery transaction.

• recoveryToken - Recovery token that was distributed to end-user via an out-of-band mechanism such as email

authClient.verifyRecoveryToken({
  recoveryToken: '00xdqXOE5qDZX8-PBR1bYv8AESqIFinDy3yul01tyh'
})
.then(function(transaction) {
  if (transaction.status === 'SUCCESS') {
    authClient.session.setCookieAndRedirect(transaction.sessionToken);
  } else {
    throw 'We cannot handle the ' + transaction.status + ' status';
  }
})
.fail(function(err) {
  console.error(err);
});

tx.resume()

Resumes an in-progress transaction. This is useful if a user navigates away from the login page before authentication is complete.

authClient.tx.exists()
.then(function(exists) {
  if (exists) {
    return authClient.tx.resume();
  }
  throw new Error('a session does not exist');
})
.then(function(transaction) {
  console.log('current status:', transaction.status);
})
.fail(function(err) {
  console.error(err);
});

tx.exists()

Check for a transaction to be resumed. This is synchronous and returns true or false.

var exists = authClient.tx.exists()
if (exists) {
  console.log('a session exists');
} else {
  console.log('a session does not exist');
}

transaction.status

When Auth Client methods resolve, they return a transaction object that encapsulates the new state in the authentication flow. This transaction contains metadata about the current state, and methods that can be used to progress to the next state.

Sample transactions and their methods:

Common methods

cancel()

Terminates the current auth flow.

transaction.cancel()
.then(function() {
  // transaction canceled. You can now start another with authClient.signIn
});

LOCKED_OUT

The user account is locked; self-service unlock or admin unlock is required.

{
  status: 'LOCKED_OUT',
  unlock: function(options) { /* returns another transaction */ },
  cancel: function() { /* terminates the auth flow */ },
  data: { /* the parsed json response */ }
}

unlock(options)

• username - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)
• factorType - Recovery factor to use for primary authentication. Supported options are SMS, EMAIL, or CALL
• relayState - Optional state value that is persisted for the lifetime of the recovery transaction

transaction.unlock({
  username: 'dade.murphy@example.com',
  factorType: 'EMAIL'
});

cancel()

PASSWORD_EXPIRED

The user’s password was successfully validated but is expired.

{
  status: 'PASSWORD_EXPIRED',
  expiresAt: '2014-11-02T23:39:03.319Z',
  user: {
    id: '00ub0oNGTSWTBKOLGLNR',
    profile: {
      login: 'isaac@example.org',
      firstName: 'Isaac',
      lastName: 'Brock',
      locale: 'en_US',
      timeZone: 'America/Los_Angeles'
    }
  },
  changePassword: function(options) { /* returns another transaction */ },
  cancel: function() { /* terminates the auth flow */ },
  data: { /* the parsed json response */ }
}

changePassword(options)

• oldPassword - User’s current password that is expired
• newPassword - New password for user

transaction.changePassword({
  oldPassword: '0ldP4ssw0rd',
  newPassword: 'N3wP4ssw0rd'
});

cancel()

PASSWORD_RESET

The user successfully answered their recovery question and can set a new password.

{
  status: 'PASSWORD_EXPIRED',
  expiresAt: '2014-11-02T23:39:03.319Z',
  user: {
    id: '00ub0oNGTSWTBKOLGLNR',
    profile: {
      login: 'isaac@example.org',
      firstName: 'Isaac',
      lastName: 'Brock',
      locale: 'en_US',
      timeZone: 'America/Los_Angeles'
    }
  },
  resetPassword: function(options) { /* returns another transaction */ },
  cancel: function() { /* terminates the auth flow */ },
  data: { /* the parsed json response */ }
}

resetPassword(options)

• newPassword - New password for user

transaction.resetPassword({
  newPassword: 'N3wP4ssw0rd'
});

cancel()

PASSWORD_WARN

The user’s password was successfully validated but is about to expire and should be changed.

```javascript { status: 'PASSWORD_WARN', expiresAt: '2014-11-02T23:39:03.319Z', user: { id: '00ub0oNGTSWTBKOLGLNR', profile: { login: 'isaac@example.org', firstName: 'Isaac', lastName: 'Brock',