The Okta Sign-In Widget is a Javascript widget that provides a fully featured and customizable login experience which can be used to authenticate users on any website.
You can learn more on the Okta + JavaScript page in our documentation.
Table of Contents
- Getting started
- Usage guide
- API Reference
- Configuration
- Events
- Building the Widget
- Browser support
- Contributing
Installing the Okta Sign-In Widget into your project is simple. You can include the Sign-In Widget in your project either directly from the Okta CDN, or by packaging it with your app via our npm package, @okta/okta-signin-widget.
You'll also need:
- An Okta account, called an organization (sign up for a free developer organization if you need one)
Loading our assets directly from the CDN is a good choice if you want an easy way to get started with the widget, 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:
<!-- Latest CDN production Javascript and CSS -->
<script src="https://global.oktacdn.com/okta-signin-widget/3.8.2/js/okta-sign-in.min.js" type="text/javascript"></script>
<link href="https://global.oktacdn.com/okta-signin-widget/3.8.2/css/okta-sign-in.min.css" type="text/css" rel="stylesheet"/>
The standard JS asset served from our CDN includes polyfills via babel-polyfill
to ensure compatibility with older browsers. This may cause conflicts if your app already includes polyfills. For this case, we provide an alternate JS asset which does not include any polyfills.
<!-- Latest CDN production Javascript without polyfills -->
<script src="https://global.oktacdn.com/okta-signin-widget/3.8.2/js/okta-sign-in.no-polyfill.min.js" type="text/javascript"></script>
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 3rd party sites
To install @okta/okta-signin-widget:
# Run this command in your project root folder
# yarn
yarn add @okta/okta-signin-widget
# npm
npm install @okta/okta-signin-widget --save
The widget source files and assets will be installed to node_modules/@okta/okta-signin-widget/dist
, and will have this directory structure:
node_modules/@okta/okta-signin-widget/dist/
├── css/
│ │ # Main CSS file for widget styles. Try not to override the classes in this
│ │ # file when creating a custom theme - the classes/elements are subject to
│ │ # change between releases
│ └── okta-sign-in.min.css
│
│ # Base font and image files that are used in rendering the widget
├── font/
│
├── img/
│
├── js/
│ │ # CDN JS file that exports the OktaSignIn object in UMD format. This is
│ │ # packaged with everything needed to run the widget, including 3rd party
│ │ # vendor files and polyfills.
│ ├── okta-sign-in.min.js
| |
│ │ # CDN JS file bundled without polyfills.
│ ├── okta-sign-in.no-polyfill.min.js
│ │
│ │ # Main entry file that is used in the npm require(@okta/okta-signin-widget)
│ │ # flow. This does not package 3rd party dependencies - these are pulled
│ │ # down through `npm install` (which allows you to use your own version of
│ │ # jquery, etc).
│ ├── okta-sign-in.entry.js
│ │
│ │ # Development version of okta-sign-in.min.js. Equipped with helpful
│ │ # console warning messages for common configuration errors.
│ └── okta-sign-in.js
│
│ # Localized strings that are used to display all text and labels in the
│ # widget. Three output formats are included - json, jsonp, and properties
├── labels/
│
│ # Sass files that are used to generate the widget css. If you are already
│ # using Sass in your project, you can include these helper files to make
│ # generating your custom theme easier
└── sass/
After installing:
-
Copy the assets to a folder that will be distributed to your publicly hosted site. The folders you'll need to copy are
css
,font
,img
,js
andlabels
. -
Instead of copying the
js
directory and including it in your page as a global, you can require the Sign-In Widget in your build if you are using Webpack, Browserify, or another module bundling system that understands thenode_modules
format.// Load the Sign-In Widget module var OktaSignIn = require('@okta/okta-signin-widget'); // Use OktaSignIn var signIn = new OktaSignIn(/* configOptions */);
Source maps are provided as an external .map file. If you are using Webpack, these can be loaded using the source-map-loader plugin.
Note: If you use Browserify to bundle your app, you'll need to use the
--noparse
option:browserify main.js \ --noparse=$PWD/node_modules/@okta/okta-signin-widget/dist/js-okta-sign-in.entry.js \ --outfile=bundle.js
-
Make sure you include ES6 polyfills with your bundler if you need the broadest browser support. We recommend
babel-polyfill
.
For an overview of the Widget's features and authentication flows, check out our developer docs. There, you will learn how to use the Widget to:
- Sign In to Okta with the Default Dashboard
- Sign In to Okta with a Custom Dashboard
- Sign In to Your Application
You can also browse the full API reference documentation.
-
Configure your Single-page application in the Okta Admin UI to allow the
Authorization code
grant type. -
To complete the flow, your client application must handle the code passed to
redirectUri
. This is most easily accomplished using okta-auth-js or with one of our Javascript OIDC SDKs
var signIn = new OktaSignIn(
{
baseUrl: 'https://{yourOktaDomain}',
redirectUri: '{{redirectUri configured in OIDC app}}',
authParams: {
display: 'page',
pkce: true
}
}
);
Creates a new instance of the Sign-In Widget with the provided options. The widget has many config options. The only required option to get started is baseUrl
, the base url for your Okta domain.
config
- Options that are used to configure the widget
var signIn = new OktaSignIn(
{
baseUrl: 'https://{yourOktaDomain}'
}
);
Note:
https://{yourOktaDomain}
can be any Okta organization. See Basic config options for more information.
Renders the widget to the DOM, and passes control back to your app through success and error callback functions when the user has entered a success or error state.
options
el
- CSS selector which identifies the container element that the widget attaches to.
success
(optional) - Function that is called when the user has completed an authentication flow. If an OpenID Connect redirect flow is used, this function can be omitted.error
(optional) - Function that is called when the widget has been initialized with invalid config options, or has entered a state it cannot recover from. If omitted, a default function is used to output errors to the console.
signIn.renderEl(
// Assumes there is an empty element on the page with an id of 'osw-container'
{el: '#osw-container'},
function success(res) {
// The properties in the response object depend on two factors:
// 1. The type of authentication flow that has just completed, determined by res.status
// 2. What type of token the widget is returning
// The user has started the password recovery flow, and is on the confirmation
// screen letting them know that an email is on the way.
if (res.status === 'FORGOT_PASSWORD_EMAIL_SENT') {
// Any followup action you want to take
return;
}
// The user has started the unlock account flow, and is on the confirmation
// screen letting them know that an email is on the way.
if (res.status === 'UNLOCK_ACCOUNT_EMAIL_SENT') {
// Any followup action you want to take
return;
}
// The user has successfully completed the authentication flow
if (res.status === 'SUCCESS') {
// Handle success when the widget is not configured for OIDC
if (res.type === 'SESSION_STEP_UP') {
// Session step up response
// If the widget is not configured for OIDC and the authentication type is SESSION_STEP_UP,
// the response will contain user metadata and a stepUp object with the url of the resource
// and a 'finish' function to navigate to that url
console.log(res.user);
console.log('Target resource url: ' + res.stepUp.url);
res.stepUp.finish();
return;
} else {
// If the widget is not configured for OIDC, the response will contain
// user metadata and a sessionToken that can be converted to an Okta
// session cookie:
console.log(res.user);
res.session.setCookieAndRedirect('https://acme.com/app');
return;
}
// OIDC response
// If the widget is configured for OIDC with a single responseType, the
// response will be the token.
// i.e. authParams.responseType = 'id_token':
console.log(res.claims);
signIn.tokenManager.add('my_id_token', res);
// If the widget is configured for OIDC with multiple responseTypes, the
// response will be an array of tokens:
// i.e. authParams.responseType = ['id_token', 'token']
signIn.tokenManager.add('my_id_token', res[0]);
signIn.tokenManager.add('my_access_token', res[1]);
return;
}
},
function error(err) {
// This function is invoked with errors the widget cannot recover from:
// Known errors: CONFIG_ERROR, UNSUPPORTED_BROWSER_ERROR
}
);
Renders the widget to the DOM to prompt the user to sign in. On successful authentication, users are redirected back to the application via the redirectUri
with an Okta SSO session in the browser, and access and/or identity tokens in the fragment identifier.
options
authorizationServerId
(optional) - Specify a custom authorization server to perform the OIDC flow. Defaults todefault
.clientId
(optional) - Client Id pre-registered with Okta for the OIDC authentication flow. If omitted, defaults to the value passed in during the construction of the Widget.redirectUri
(optional) - The url that is redirected to after authentication. This must be pre-registered as part of client registration. Defaults to the current origin.getAccessToken
(optional) - Return an access token from the authorization server. Defaults tofalse
.getIdToken
(optional) - Return an ID token from the authorization server. Defaults totrue
.scope
(optional) - Specify what information to make available in the returned access or ID token. If omitted, defaults to the value passed in during construction of the Widget.
var signIn = new OktaSignIn({
baseUrl: 'https://{yourOktaDomain}',
// Assumes there is an empty element on the page with an id of 'osw-container'
el: '#osw-container'
});
signIn.showSignInToGetTokens({
clientId: '{{myClientId}}',
redirectUri: '{{redirectUri configured in OIDC app}}',
// Return an access token from the authorization server
getAccessToken: true,
// Return an ID token from the authorization server
getIdToken: true,
scope: 'openid profile'
});
Hide the widget, but keep the widget in the DOM.
signIn.hide();
Show the widget if hidden.
signIn.show();
Remove the widget from the DOM entirely.
signIn.remove();
Subscribe to an event published by the widget.
event
- Event to subscribe tocallback
- Function to call when the event is triggered
// Handle a 'ready' event using an onReady callback
signIn.on('ready', onReady);
Unsubscribe from widget events. If no callback is provided, unsubscribes all listeners from the event.
event
- Optional event to unsubscribe fromcallback
- Optional callback that was used to subscribe to the event
// Unsubscribe all listeners from all events
signIn.off();
// Unsubscribe all listeners that have been registered to the 'ready' event
signIn.off('ready');
// Unsubscribe the onReady listener from the 'ready' event
signIn.off('ready', onReady);
Returns the underlying @okta/okta-auth-js
object used by the Sign-in Widget.
Before version 3.0, the Sign-in Widget contained session
and tokenManager
properties, and methods like tokenManager.get
. These were just proxies to identical objects and methods in the AuthJS base library. These proxies have been removed in favor of direct access to the authClient object which allows you to call any of these methods. All the methods are documented in the AuthJS base library.
// Check for an existing authClient transaction
signIn.authClient.tx.exists();
if (exists) {
console.log('A session exists!');
} else {
console.log('A session does not exist.');
};
Synchronous method to check for access or ID Tokens in the url. This is used when authParams.display = 'page'
. Returns true
if there are tokens, and false
if the redirect flow has not taken place yet.
if (signIn.hasTokensInUrl()) {
// The user has just successfully completed a redirect
}
else {
// There are no tokens in the URL, render the Sign-In Widget.
}
The only required configuration option is baseUrl
. All others are optional.
// Basic example
var config = {
baseUrl: 'https://{yourOktaDomain}',
logo: '/path/to/logo.png',
logoText: 'logo text',
helpSupportNumber: '(123) 456-7890',
language: 'en',
i18n: {
en: {
'primaryauth.title': 'Sign in to Acme'
}
},
helpLinks: {
help: 'https://acme.com/help'
}
};
var signIn = new OktaSignIn(config);
-
baseUrl: The base URL for your Okta organization
// Production org with subdomain "acme" baseUrl: 'https://acme.okta.com' // Can also target oktapreview and okta-emea, i.e. baseUrl: 'https://acme.oktapreview.com'
-
logo: Local path or URL to a logo image that is displayed at the top of the Sign-In Widget
// Hosted on the same origin logo: '/img/logo.png' // Can also be a full url logo: 'https://acme.com/img/logo.png'
-
logoText: Text for
alt
attribute of the logo image, logo text will only show up when logo image is not avaiable// Text to describe the logo logoText: 'logo text'
-
helpSupportNumber: Support phone number that is displayed in the Password Reset and Unlock Account flows. If no number is provided, no support screen is shown to the user.
// Can be any format - there are no formatting checks helpSupportNumber: '(123) 456-7890'
-
brandName: The brand or company name that is displayed in messages rendered by the Sign-in Widget (for example, "Reset your {
brandName
} password"). If nobrandName
is provided, a generic message is rendered instead (for example, "Reset your password"). You can further customize the text that is displayed with language and text settings.brandName: 'Spaghetti Inc.'
-
username: Prefills the username input with the provided username
username: '[email protected]'
-
transformUsername: Transforms the username before sending requests with the username to Okta. This is useful when you have an internal mapping between what the user enters and their Okta username.
// The callback function is passed two arguments: // 1) username: The name entered by the user // 2) operation: The type of operation the user is trying to perform: // - PRIMARY_AUTH // - FORGOT_PASSWORD // - UNLOCK_ACCOUNT transformUsername: function (username, operation) { // This example will append the '@acme.com' domain if the user has // not entered it return username.indexOf('@acme.com') > -1 ? username : username + '@acme.com'; }
-
processCreds: Hook to handle the credentials before they are sent to Okta in the Primary Auth, Password Expiration, and Password Reset flows.
If processCreds takes a single argument it will be executed as a synchronous hook:
// Passed a creds object {username, password} processCreds: function (creds) { // This example demonstrates a partial integration with ChromeOS google.principal.add({ token: creds.username, user: creds.username, passwordBytes: creds.password, keyType: 'KEY_TYPE_PASSWORD_PLAIN' }); }
If processCreds takes two arguments it will be executed as an asynchronous hook:
// Passed a creds object {username, password} and a callback for further processing processCreds: function (creds, callback) { // This example demonstrates optional legacy form-based login $.ajax({ method: "POST", url: "/logintype", data: { username : creds.username }, success: function (logintype) { if (logintype == "LEGACY") { $('#legacyUser').val(creds.username); $('#legacyPassword').val(creds.password); $('#legacyLogonForm').submit(); } else { callback(); } } }); }
-
language: Set the language of the widget. If no language is specified, the widget will choose a language based on the user's browser preferences if it is supported, or defaults to
en
.// You can simply pass the languageCode as a string: language: 'ja' // Or, if you need to determine it dynamically, you can pass a // callback function: language: function (supportedLanguages, userLanguages) { // supportedLanguages is an array of languageCodes, i.e.: // ['cs', 'da', ...] // // userLanguages is an array of languageCodes that come from the user's // browser preferences return supportedLanguages[0]; }
Supported languages:
cs
- Czechda
- Danishde
- Germanel
- Greeken
- Englishes
- Spanishfi
- Finnishfr
- Frenchhu
- Hungarianid
- Indonesianit
- Italianja
- Japaneseko
- Koreanms
- Malaysiannb
- Norwegiannl-NL
- Dutchpl
- Polishpt-BR
- Portuguese (Brazil)ro
- Romanianru
- Russiansv
- Swedishth
- Thaitr
- Turkishuk
- Ukrainianzh-CN
- Chinese (PRC)zh-TW
- Chinese (Taiwan)
-
i18n: Override the text in the widget. The full list of properties can be found in the login.properties and country.properties files.
// The i18n object maps language codes to a hash of property keys -> // property values. i18n: { // Overriding English properties 'en': { 'primaryauth.title': 'Sign in to Acme', 'primaryauth.username.placeholder': 'Your Acme Username' }, // Overriding Japanese properties 'ja': { 'primaryauth.title': 'ACMEにサインイン', 'primaryauth.username.placeholder': 'ACMEのユーザー名' } } // If you want to override any properties in the country.properties file, // you will need to prefix the name with "country.": i18n: { 'en': { // login.properties keys do not have a special prefix 'primaryAuth.title': 'Sign in to Acme', // country.properties keys are prefixed with 'country.' 'country.AF': 'Afghanistan, edited', 'country.AL': 'Albania, edited' } }
-
assets.baseUrl: Override the base url the widget pulls its language files from. The widget is only packaged with english text by default, and loads other languages on demand from the Okta CDN. If you want to serve the language files from your own servers, update this setting.
// Loading the assets from a path on the current domain assets: { baseUrl: '/path/to/dist' }, // Full urls work as well assets: { baseUrl: 'https://acme.com/assets/dist' }
Note: The jsonp files can be accessed from the
dist/labels/jsonp
folder that is published in the npm module. -
assets.rewrite: You can use this function to rewrite the asset path and filename. Use this function if you will host the asset files on your own host, and plan to change the path or filename of the assets. This is useful, for example, if you want to cachebust the files.
assets: { // Note: baseUrl is still needed to set the base path baseUrl: '/path/to/dist', rewrite: function (assetPath) { // assetPath is relative to baseUrl // Example assetPath to load login for 'ja': "/labels/jsonp/login_ja.jsonp" return someCacheBustFunction(assetPath); } }
These options let you customize the appearance of the Sign-in Widget.
If you want even more customization, you can modify the Sass source files and build the Widget.
-
colors.brand: Sets the brand (primary) color. Colors must be in hex format, like
#008000
.colors: { brand: '#008000' }
You can override a link URL by setting the following config options. If you'd like to change the link text, use the i18n
config option.
Set the following config options to override the help link URLs on the Primary Auth page.
// An example that overrides all help links, and sets two custom links
helpLinks: {
help: 'https://acme.com/help',
forgotPassword: 'https://acme.com/forgot-password',
unlock: 'https://acme.com/unlock-account',
custom: [
{
text: 'What is Okta?',
href: 'https://acme.com/what-is-okta'
},
{
text: 'Acme Portal',
href: 'https://acme.com',
target: '_blank'
}
]
}
-
helpLinks.help - Custom link href for the "Help" link
-
helpLinks.forgotPassword - Custom link href for the "Forgot Password" link
-
helpLinks.unlock - Custom link href for the "Unlock Account" link. For this link to display,
features.selfServiceUnlock
must be set totrue
, and the self service unlock feature must be enabled in your admin settings. -
helpLinks.custom - Array of custom link objects
{text, href, target}
that will be added to the "Need help signing in?" section. Thetarget
of the link is optional.
Set the following config option to override the sign out link URL. If not provided, the widget will navigate to Primary Auth.
signOutLink: 'https://www.signmeout.com'
You can add buttons to the Primary Auth page by setting the following config options.
You can add custom buttons underneath the login form on the primary auth page by setting the following config options. If you'd like to change the divider text, use the i18n
config option.
// An example that adds a custom button underneath the login form on the primary auth page
customButtons: [{
title: 'Click Me',
className: 'btn-customAuth',
click: function() {
// clicking on the button navigates to another page
window.location.href = 'http://www.example.com';
}
}]
-
customButtons.title - String that is set as the button text
-
customButtons.className - Optional class that can be added to the button
-
customButtons.click - Function that is called when the button is clicked
You can add a registration link to the primary auth page by setting features.registration
to true
and by adding the following config options.
// An example that adds a registration button underneath the login form on the primary auth page
registration: {
click: function() {
window.location.href = 'https://acme.com/sign-up';
}
}
- registration.click - Function that is called when the registration button is clicked
⚠️ Beta feature: The registration feature is currently a Beta feature. This widget functionality won't work unless your Okta organization is part of the Beta program. For help, contact [email protected].
To add registration into your application, configure your Okta admin settings to allow users to self register into your app. Then, set features.registration
in the widget. You can add additional configs under the registration key on the OktaSignIn
object.
var signIn = new OktaSignIn({
baseUrl: 'https://{yourOktaDomain}',
// If you are using version 2.8 or higher of the widget, clientId is not required while configuring
// registration. Instead the widget relies on policy setup with Self Service Registration. For help
// with setting up Self Service Registration contact [email protected]. Registration should continue
// to work with a clientId set and version 2.7 or lower of the widget.
clientId: '{{myClientId}}', // REQUIRED (with version 2.7.0 or lower)
registration: {
parseSchema: function(schema, onSuccess, onFailure) {
// handle parseSchema callback
onSuccess(schema);
},
preSubmit: function (postData, onSuccess, onFailure) {
// handle preSubmit callback
onSuccess(postData);
},
postSubmit: function (response, onSuccess, onFailure) {
// handle postsubmit callback
onSuccess(response);
}
},
features: {
// Used to enable registration feature on the widget.
// https://github.com/okta/okta-signin-widget#feature-flags
registration: true // REQUIRED
}
});
Optional configuration:
-
parseSchema: Callback used to mold the JSON schema that comes back from the Okta API.
// The callback function is passed 3 arguments: schema, onSuccess, onFailure // 1) schema: json schema returned from the API. // 2) onSuccess: success callback. // 3) onFailure: failure callback. Note: accepts an errorObject that can be used to show form level or field level errors. parseSchema: function (schema, onSuccess, onFailure) { // This example will add an additional field to the registration form schema.profileSchema.properties.address = { 'type': 'string', 'description': 'Street Address', 'default': 'Enter your street address', 'maxLength': 255 }; schema.profileSchema.fieldOrder.push('address'); onSuccess(schema); }
-
preSubmit: Callback used primarily to modify the request parameters sent to the Okta API.
// The callback function is passed 3 arguments: postData, onSuccess, onFailure // 1) postData: form data that will be posted to the registration API. // 2) onSuccess: success callback. // 3) onFailure: failure callback. Note: accepts a errorObject that can be used to show form level or field level errors. preSubmit: function (postData, onSuccess, onFailure) { // This example will add @companyname.com to the email if user fails to add it during registration if (postData.username.indexOf('@acme.com') > 1) { return postData.username; } else { return postData.username + '@acme.com'; } }
-
postSubmit: Callback used to primarily get control and to modify the behavior post submission to registration API .
// The callback function is passed 3 arguments: response, onSuccess, onFailure // 1) response: response returned from the API post registration. // 2) onSuccess: success callback. // 3) onFailure: failure callback. Note: accepts an errorObject that can be used to show form level // or field level errors. postSubmit: function (response, onSuccess, onFailure) { // In this example postSubmit callback is used to log the server response to the browser console before completing registration flow console.log(response); // call onSuccess to finish registration flow onSuccess(response); }
-
onFailure and ErrorObject: The onFailure callback accepts an error object that can be used to show a form level vs field level error on the registration form.
preSubmit: function (postData, onSuccess, onFailure) { // A Default form level error is shown if no error object is provided onFailure(); }
preSubmit: function (postData, onSuccess, onFailure) { var error = { "errorSummary": "Custom form level error" }; onFailure(error); }
preSubmit: function (postData, onSuccess, onFailure) { var error = { "errorSummary": "API Error", "errorCauses": [ { "errorSummary": "Custom field level error", "reason": "registration.error.address", "resource": "User", "property": "address", //should match field name "arguments": [] } ] }; onFailure(error); }
ℹ️ EA feature: The Identity Provider (IdP) Discovery feature is currently an EA feature.
IdP Discovery enables you to route users to different 3rd Party IdPs that are connected to your Okta Org. Users can federate back into the primary org after authenticating at the IdP.
To use IdP Discovery in your application, first ensure that the IDP_DISCOVERY
feature flag is enabled for your Org and configure an identity provider routing policy in the Okta admin panel.
Then, in the widget configuration, set features.idpDiscovery
to true
.
var signIn = new OktaSignIn({
baseUrl: 'https://{yourOktaDomain}',
... ...
features: {
idpDiscovery: true
}
});
The IdP Discovery authentication flow in widget will be
- If a routing policy with a username/domain condition is configured, the widget will enter identifier first flow
- Otherwise, the widget will enter primary authentication flow.
For the identifier first flow,
- The widget will display an identifier first page for the user to enter an Okta userName to determine the IdP to be used for authentication.
- If the IdP is your Okta org, the widget will transition to the primary authentication flow.
- If the IdP is a 3rd party IdP or a different Okta org, the widget will automatically redirect to path of the 3rd party IdP.
Options for the OpenID Connect authentication flow. This flow is required for social authentication, and requires OAuth 2.0 client registration with Okta. For instructions, see Social Authentication.
-
clientId: Client Id pre-registered with Okta for the OIDC authentication flow
clientId: 'GHtf9iJdr60A9IYrR0jw'
-
redirectUri: The url that is redirected to when using
authParams.display:page
. This must be pre-registered as part of client registration. If noredirectUri
is provided, defaults to the current origin.redirectUri: 'https://acme.com/oauth2/callback/home'
-
idps: External Identity Providers to use in OIDC authentication. Supported IDPs (
GOOGLE
,FACEBOOK
, andLINKEDIN
) are declared with atype
and will get distinct styling and default i18n text, while any other entry will receive a general styling and require text to be provided. Each IDP can have additional CSS classes added via an optionalclassName
property.idps: [ {type: 'GOOGLE', id: '0oaaix1twko0jyKik0g4'}, {type: 'FACEBOOK', id: '0oar25ZnMM5LrpY1O0g3'}, {type: 'LINKEDIN', id: '0oaaix1twko0jyKik0g4'}, {id: '0oabds23xM3ssMjosl0g5', text: 'Login with Joe', className: 'with-joe' } ]
-
idpDisplay: Display order for External Identity Providers relative to the Okta login form. Defaults to
SECONDARY
.PRIMARY
- Display External IDP buttons above the Okta login formSECONDARY
- Display External IDP buttons below the Okta login form
idpDisplay: 'PRIMARY'
-
oAuthTimeout: Timeout for OIDC authentication flow requests, in milliseconds. If the authentication flow takes longer than this timeout value, an error will be thrown and the flow will be cancelled. Defaults to
12000
.oAuthTimeout: 300000 // 5 minutes
-
authParams.pkce: Set to
true
to enable PKCE flow -
authParams.display: Specify how to display the authentication UI for External Identity Providers. Defaults to
popup
.-
popup
- Opens a popup to the authorization server when an External Identity Provider button is clicked.responseMode
will be set tookta_post_message
and cannot be overridden. -
page
- Redirect to the authorization server when an External Identity Provider button is clicked. IfresponseMode
is not specified, it will default toquery
ifresponseType = 'code'
, andfragment
for other values ofresponseType
.
// Redirects to authorization server when the IDP button is clicked, and // returns an access_token in the url hash authParams: { display: 'page', responseType: 'token' }
-
-
authParams.responseMode: Specify how the authorization response should be returned. You will generally not need to set this unless you want to override the default values for your
authParams.display
andauthParams.responseType
settings.-
okta_post_message
- Used whenauthParams.display = 'popup'
. Uses postMessage to send the response from the popup to the origin window. -
fragment
- Used whenauthParams.display = 'page'
. Returns the authorization response in the hash fragment of the URL after the authorization redirect.fragment
is the default for Single-page applications and for standard web applications whereresponseType != 'code'
. -
query
- Used whenauthParams.display = 'page'
. Returns the authorization response in the query string of the URL after the authorization redirect.query
is the default value for standard web applications whereauthParams.responseType = 'code'
. -
form_post
- Returns the authorization response as a form POST after the authorization redirect. Use this whenauthParams.display = page
and you do not want the response returned in the URL.
// Use form_post instead of query in the Authorization Code flow authParams: { display: 'page', responseType: 'code', responseMode: 'form_post' }
-
-
authParams.responseType: Specify the response type for OIDC authentication. Defaults to
id_token
.Valid response types are
id_token
,access_token
, andcode
. Note thatcode
goes through the Authorization Code flow, which requires the server to exchange the Authorization Code for tokens.// Specifying a single responseType authParams: { responseType: 'token' } // Use an array if specifying multiple response types - in this case, // the response will contain both an ID Token and an Access Token. authParams: { responseType: ['id_token', 'token'] }
-
authParams.scopes: Specify what information to make available in the returned
id_token
oraccess_token
. For OIDC, you must includeopenid
as one of the scopes. Defaults to['openid', 'email']
.Valid OIDC scopes:
openid
,email
,profile
,address
,phone
authParams: { scopes: ['openid', 'email', 'profile', 'address', 'phone'] }
-
authParams.state: Specify a state that will be validated in an OAuth response. This is usually only provided during redirect flows to obtain an authorization code. Defaults to a random string.
authParams: { state: '8rFzn3MH5q' }
-
authParams.nonce: Specify a nonce that will be validated in an id_token. This is usually only provided during redirect flows to obtain an authorization code that will be exchanged for an id_token. Defaults to a random string.
authParams: { nonce: '51GePTswrm' }
-
authParams.issuer: Specify a custom issuer to perform the OIDC flow. Defaults to the baseUrl.
authParams: { issuer: 'https://{yourOktaDomain}/oauth2/default' }
-
authParams.authorizeUrl: Specify a custom authorizeUrl to perform the OIDC flow. Defaults to the issuer plus "/v1/authorize".
authParams: { issuer: 'https://{yourOktaDomain}/oauth2/default', authorizeUrl: 'https://{yourOktaDomain}/oauth2/default/v1/authorize' }
-
authScheme: Authentication scheme for OIDC authentication. You will normally not need to override this value. Defaults to
OAUTH2
.authParams: { authScheme: 'OAUTH2' }
-
recoveryToken: Bootstrap the widget into continuing either the Forgot Password or Unlock Account flow after the recovery email has been sent to the user with the
recoveryToken
.recoveryToken: 'x0whAcR02i0leKtWMZVc'
Enable or disable widget functionality with the following options. Some of these features require additional configuration in your Okta admin settings.
// An example that enables the autoPush and multiOptionalFactorEnroll features
features: {
autoPush: true,
multiOptionalFactorEnroll: true
}
-
features.router - Set to
true
if you want the widget to update the navigation bar when it transitions between pages. This is useful if you want the user to maintain their current state when refreshing the page, but requires that your server can handle the widget url paths. Defaults tofalse
. -
features.rememberMe - Display a checkbox to enable "Remember me" functionality at login. Defaults to
true
. -
features.autoPush - Display a checkbox to enable "Send push automatically" functionality in the MFA challenge flow. Defaults to
false
. -
features.smsRecovery - Allow users with a configured mobile phone number to recover their password using an SMS message. Defaults to
false
. -
features.callRecovery - Allow users with a configured mobile phone number to recover their password using a voice call. Defaults to
false
. -
features.webauthn - Display and use factors supported by the FIDO 2.0 (Web Authentication) security standard. Enabling this feature will prevent the widget from invoking the legacy Windows Hello factor. Defaults to
false
. -
features.selfServiceUnlock - Display the "Unlock Account" link to allow users to unlock their accounts. Defaults to
false
. -
features.multiOptionalFactorEnroll - Allow users to enroll in multiple optional factors before finishing the authentication flow. Default behavior is to force enrollment of all required factors and skip optional factors. Defaults to
false
. -
features.hideSignOutLinkInMFA - Hides the sign out link for MFA challenge. Defaults to
false
. -
features.registration - Display the registration section in the primary auth page. Defaults to
false
. -
features.idpDiscovery - Enable IdP Discovery. Defaults to
false
. -
features.showPasswordToggleOnSignInPage - End users can now toggle visibility of their password on the Okta Sign-In page, allowing end users to check their password before they click Sign In. This helps prevent account lock outs caused by end users exceeding your org's permitted number of failed sign-in attempts. Note that passwords are visible for 30 seconds and then hidden automatically. Defaults to
false
.
Events published by the widget. Subscribe to these events using on.
Triggered when the widget is ready to accept user input for the first time. Returns a context
object containing the following properties:
- controller - Current controller name
signIn.on('ready', function (context) {
// The Widget is ready for user input
});
The widget will handle most types of errors - for example, if the user enters an invalid password or there are issues authenticating. To capture an authentication state change error after it is handled and rendered by the Widget, listen to the afterError
event. You can also capture OAuth and registration errors. For other error types, it is encouraged to handle them using the renderEl
error handler.
Returns context
and error
objects containing the following properties:
context
:- controller - Current controller name
error
:- name - Name of the error triggered
- message - Error message
- statusCode - HTTP status code (if available)
- xhr - HTTP response (if available)
signIn.on('afterError', function (context, error) {
console.log(context.controller);
// reset-password
console.log(error.name);
// AuthApiError
console.log(error.message);
// The password does not meet the complexity requirements
// of the current password policy.
console.log(error.statusCode);
// 403
});
Triggered when the widget transitions to a new page and animations have finished. Returns a context
object containing the following properties:
- controller - Current controller name
// Overriding the "Back to Sign In" click action on the Forgot Password page
signIn.on('afterRender', function (context) {
if (context.controller !== 'forgot-password') {
return;
}
var backLink = document.getElementsByClassName('js-back')[0];
backLink.addEventListener('click', function (e) {
e.preventDefault();
e.stopPropagation();
// Custom link behavior
});
});
Triggered when the widget transitions to a new page and animations have finished.
signIn.on('pageRendered', function (data) {
console.log(data);
// { page: 'forgot-password' }
});
Triggered when the show password button is clicked.
signIn.on('passwordRevealed', function () {
// Handle the event
})
We use Yarn as our node package manager. To install Yarn, check out their install documentation.
-
Clone this repo and navigate to the new
okta-signin-widget
folder.git clone https://github.com/okta/okta-signin-widget.git cd okta-signin-widget
-
Install our Node dependencies.
yarn install
-
Create a
.widgetrc
file in theokta-signin-widget
directory with an entry forbaseUrl
.{ "widgetOptions": { "baseUrl": "https://{yourOktaDomain}" } }
-
Build the widget, start a local connect server that hosts it, and launch a browser window with the widget running.
yarn start
or start local connect server in watch mode, changes in
src/
andassets/sass/
folders will trigger browser auto reload.yarn start:playground
-
Finally, enable CORS support for our new server by following these instructions. You can now authenticate to Okta using your very own, customizable widget!
The .widgetrc
file is a configuration file that saves your local widget settings.
Property | Description |
---|---|
widgetOptions | Config options that are passed to the widget on initialization. |
serverPort | The port the local server runs on. Defaults to 3000 |
Command | Description |
---|---|
yarn start |
Build the widget, start the server, and open a browser window with the widget loaded |
yarn start:playground |
Build the widget, start the server, and open a browser window with the widget loaded and watch on widget js and sass changes |
yarn build:dev |
Build an unminified version of the widget |
yarn build:release |
Build a minified, uglified version of the widget (okta-sign-in.min.js ) and a non-minified development version of the widget (okta-sign-in.js ). |
yarn test |
Run unit tests |
yarn test --test OAuth2Util_spec |
Run a single unit test |
yarn test:testcafe <browser> |
Run testcafe tests on selected browser (example: yarn test:testcafe chrome ) |
yarn lint |
Run eslint and scss linting tests |
Need to know if the Sign-In Widget supports your browser requirements? Please see Platforms, Browser, and OS Support.
We're happy to accept contributions and PRs! Please see the contribution guide to understand how to structure a contribution.