-
Notifications
You must be signed in to change notification settings - Fork 320
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added MIGRATING.md with instructions to migrate from v2.x to v3.x
- Loading branch information
1 parent
c76c354
commit 3c96637
Showing
1 changed file
with
76 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,76 @@ | ||
# Okta Sign-in Widget Migration guide | ||
|
||
This library uses semantic versioning and follows Okta's [library version policy](https://developer.okta.com/code/library-versions/). In short, we don't make breaking changes unless the major version changes! | ||
|
||
## Migrating From 2.x to 3.x | ||
|
||
### Consolidated CSS Files | ||
|
||
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.css` and remove the `okta-theme.css` link. | ||
|
||
Version 2.x configuration: | ||
```html | ||
<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: | ||
```html | ||
<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 single `okta-sign-in.min.css` instead of the previous two files. | ||
|
||
### Renamed Functions | ||
|
||
`tokenManager.refresh` has been renamed to `tokenManager.renew`, so you should update it in your code. | ||
|
||
### Token Retrieval Is Now Asynchronous | ||
|
||
Starting in version 3.0, `tokenManager.get` is an asynchronous function. It returns an object you can handle as a promise: | ||
|
||
```javascript | ||
// ES2016+ | ||
const accessToken = await signIn.tokenManager.get('accessToken'); | ||
|
||
// Handle as a promise | ||
signIn.tokenManager.get('accessToken') | ||
.then(function(accessToken) { | ||
console.log(accessToken); | ||
}); | ||
``` | ||
|
||
### New `afterError` Events | ||
|
||
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: | ||
```javascript | ||
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. | ||
}); | ||
``` | ||
|
||
|
||
## Getting Help | ||
|
||
If you have questions about this library or about the Okta APIs, post a question on our [Developer Forum](https://devforum.okta.com). | ||
|
||
If you find a bug or have a feature request for this library specifically, [post an issue](https://github.com/okta/okta-signin-widget/issues) here on GitHub. |