This library uses semantic versioning and follows Okta's library version policy. In short, we don't make breaking changes unless the major version changes!
useInteractionCodeFlowoption is removeduseClassicEngineoption is added
The widget will run against the Identity Engine by default, using the interaction code flow for OIDC applications. Support for the Classic Engine is still available by setting the useClassicEngine option to true. This option, along with support for the Classic Engine, will be removed in a future widget version. All customers are encouraged to migrate from the Classic Engine to the Identity Engine. Visit Migrating to OIE for more details on migrating to Identity Engine.
Documentation for configuring the Okta Sign-in Widget using the interaction code flow is in the main README.
Custom montserrat font is renamed to monteserrat-okta. Styles referencing it should be updated.
To install the NPM module, Node version 14.18 or greater is required
If you are creating an instance of @okta/okta-auth-js and passing it to the widget using the authClient option, the instance must be version 6.0.0 or higher.
The existing .widgetrc file used to configure the Widget has been removed. Simply rename the existing file to .widgetrc.js export the contents:
- {
- widgetOptions: {
+ module.exports = {
baseUrl: 'http://localhost:3000',
logo: '/img/logo_widgico.png',
logoText: 'Windico',
features: {
router: true,
rememberMe: true,
},
// Host the assets (i.e. json files) locally
assets: {
baseUrl: '/'
}
};
- }If you're using TypeScript, you'll need to enable synthetic imports in your tsconfig.json.
{
...
"compilerOptions": {
"allowSyntheticDefaultImports": true,
...
}
}Angular (TypeScript) projects require a simliar configuration, also in your tsconfig.json
{
...
"angularCompilerOptions": {
"allowSyntheticDefaultImports": true,
...
}
}If you are creating an instance of @okta/okta-auth-js and passing it to the widget using the authClient option, the instance must be version 6.0.0 or higher.
showSignInToGetTokens now returns a Promise that resolves to an object containing tokens. This avoids a round-trip redirect to Okta and provides a faster, simpler, and more seamless experience for both developers and end-users. A redirectUri must still be configured, but it is no longer necessary to provide any callback logic when using this method. If your application requires a redirect for some reason, such as server-side processing of an authorization code, you should use showSignInAndRedirect instead.
If a redirect is needed, you should use showSignInAndRedirect, otherwise use showSignInToGetTokens to obtain tokens without a redirect.
We recommend setting the clientId and redirectUri options in the config object passed to the widget constructor. We also recommend using the OIDC flow by calling either showSignInAndRedirect (if redirect is needed) or showSignInToGetTokens if no redirect is required. If you must call setCookieAndRedirect, we strongly recommend calling it with no parameters, to provide better compatibility with new features. It will redirect to the configured redirectUri. In developer mode, a warning message will be printed to the console if a URL is passed to this function.
The widget no longer contains any logic to handle a redirect callback. If your app needs to handle a redirect callback, we recommend using @okta/okta-auth-js or one of our other client SDKs:
This option has been deprecated with a warning since version 3 and has now been removed. You should use scopes (array) instead.
If a redirect is needed, use showSignInAndRedirect, otherwise use showSignInToGetTokens to obtain tokens without a redirect.
Hosting the widget over the insecure HTTP protocol is not recommended. By default, an error will be thrown if the widget is loaded on a HTTP connection (there is an exception for http://localhost). In order to use HTTP, you must disable PKCE and secure cookies:
var signIn = new OktaSignIn(
{
baseUrl: 'https://{yourOktaDomain}',
authParams: {
pkce: false,
cookies: {
secure: false
}
}
}
);For SPA OIDC applications, PKCE flow will now be used by default. Implicit flow can still be used by setting pkce: false in the authParams:
var signIn = new OktaSignIn(
{
baseUrl: 'https://{yourOktaDomain}',
authParams: {
pkce: false
}
}
);The default responseMode for PKCE flow is query. By default, the authorization code will be returned as a query parameter, not a hash fragment. The code can be returned in a fragment by setting responseMode to fragment:
var signIn = new OktaSignIn(
{
baseUrl: 'https://{yourOktaDomain}',
authParams: {
responseMode: 'fragment'
}
}
);See showSignInToGetTokens for updated documentation on this method.
- getAccessToken is now
trueby default authorizationServerIdoption has been removed to specify a custom authorization server, useauthParams.issuer. The issuer should be specified as a full URI, not just the server ID.
See the okta-auth-js CHANGELOG for details on all the changes.
- authClient.token.parseFromUrl() now returns tokens in an object hash, not an array.
authParams.grantTypehas been removed
In version 2.x there were two CSS files to import, okta-sign-in.min.css and okta-theme.css. In version 3.x, there is a single file named okta-sign-in.min.css.
- If you were using CDN links for the CSS, you will need to update the version path for
okta-sign-in.min.cssand remove theokta-theme.csslink.
Version 2.x configuration:
<link
href="https://ok1static.oktacdn.com/assets/js/sdk/okta-signin-widget/2.14.0/css/okta-sign-in.min.css"
type="text/css"
rel="stylesheet"/>
<link
href="https://ok1static.oktacdn.com/assets/js/sdk/okta-signin-widget/2.14.0/css/okta-theme.css"
type="text/css"
rel="stylesheet"/>Version 3.x configuration:
<link
href="https://ok1static.oktacdn.com/assets/js/sdk/okta-signin-widget/3.0.0/css/okta-sign-in.min.css"
type="text/css"
rel="stylesheet"/>- If you were building your CSS files through
sass, you will need to build them again. The build will produce a singleokta-sign-in.min.cssinstead of the previous two files.
tokenManager.refresh has been renamed to tokenManager.renew, so you should update it in your code.
Starting in version 3.0, tokenManager.get is an asynchronous function. It returns an object you can handle as a promise:
// ES2016+
const accessToken = await signIn.tokenManager.get('accessToken');
// Handle as a promise
signIn.tokenManager.get('accessToken')
.then(function(accessToken) {
console.log(accessToken);
});We've replaced the global error handler for OAUTH_ERROR and REGISTRATION_FAILED in favor of afterError events. For these two types of errors, instead of passing a error handler to signIn.renderEl, you should add a listener on afterError to your application and act accordingly.
Example:
signIn.on('afterError', function (context, error) {
console.log(context.controller);
// primary-auth
console.log(error.name);
// OAUTH_ERROR
console.log(error.message);
// Invalid value for client_id parameter.
});If you have questions about this library or about the Okta APIs, post a question on our Developer Forum.
If you find a bug or have a feature request for this library specifically, post an issue here on GitHub.