Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[SDK-1507] Updated readme with info on refresh tokens #415

Merged
merged 1 commit into from
Apr 15, 2020
Merged

[SDK-1507] Updated readme with info on refresh tokens #415

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 37 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Auth0 SDK for Single Page Applications using [Authorization Code Grant Flow with
From the CDN:

```html
<script src="https://cdn.auth0.com/js/auth0-spa-js/1.7.0-beta.5/auth0-spa-js.production.js"></script>
<script src="https://cdn.auth0.com/js/auth0-spa-js/1.7/auth0-spa-js.production.js"></script>
```

Using [npm](https://npmjs.org):
Expand Down Expand Up @@ -56,25 +56,27 @@ import createAuth0Client from '@auth0/auth0-spa-js';
const auth0 = await createAuth0Client({
domain: '<AUTH0_DOMAIN>',
client_id: '<AUTH0_CLIENT_ID>',
redirect_uri: '<MY_CALLBACK_URL>'
redirect_uri: '<MY_CALLBACK_URL>',
});

//with promises
createAuth0Client({
domain: '<AUTH0_DOMAIN>',
client_id: '<AUTH0_CLIENT_ID>',
redirect_uri: '<MY_CALLBACK_URL>'
}).then(auth0 => {
redirect_uri: '<MY_CALLBACK_URL>',
}).then((auth0) => {
//...
});

//or, you can just instantiate the client on it's own
import { Auth0Client } from '@auth0/auth0-spa-js';

const auth0 = new Auth0Client({
domain: '<AUTH0_DOMAIN>',
client_id: '<AUTH0_CLIENT_ID>',
redirect_uri: '<MY_CALLBACK_URL>'
redirect_uri: '<MY_CALLBACK_URL>',
});

//if you do this, you'll need to check the session yourself
try {
await getTokenSilently();
Expand Down Expand Up @@ -118,9 +120,9 @@ document.getElementById('login').addEventListener('click', () => {

//in your callback route (<MY_CALLBACK_URL>)
window.addEventListener('load', () => {
auth0.handleRedirectCallback().then(redirectResult => {
auth0.handleRedirectCallback().then((redirectResult) => {
//logged in. you can get the user profile like this:
auth0.getUser().then(user => {
auth0.getUser().then((user) => {
console.log(user);
});
});
Expand All @@ -140,8 +142,8 @@ document.getElementById('call-api').addEventListener('click', async () => {
const result = await fetch('https://myapi.com', {
method: 'GET',
headers: {
Authorization: `Bearer ${accessToken}`
}
Authorization: `Bearer ${accessToken}`,
},
});
const data = await result.json();
console.log(data);
Expand All @@ -151,16 +153,16 @@ document.getElementById('call-api').addEventListener('click', async () => {
document.getElementById('call-api').addEventListener('click', () => {
auth0
.getTokenSilently()
.then(accessToken =>
.then((accessToken) =>
fetch('https://myapi.com', {
method: 'GET',
headers: {
Authorization: `Bearer ${accessToken}`
}
Authorization: `Bearer ${accessToken}`,
},
})
)
.then(result => result.json())
.then(data => {
.then((result) => result.json())
.then((data) => {
console.log(data);
});
});
Expand All @@ -180,7 +182,7 @@ document.getElementById('logout').addEventListener('click', () => {
});
```

### Data caching
### Data caching options

The SDK can be configured to cache ID tokens and access tokens either in memory or in local storage. The default is in memory. This setting can be controlled using the `cacheLocation` option when creating the Auth0 client.

Expand All @@ -191,14 +193,31 @@ await createAuth0Client({
domain: '<AUTH0_DOMAIN>',
client_id: '<AUTH0_CLIENT_ID>',
redirect_uri: '<MY_CALLBACK_URL>',
cacheLocation: 'localstorage' // valid values are: 'memory' or 'localstorage'
}).then(auth0 => {
// ...
cacheLocation: 'localstorage', // valid values are: 'memory' or 'localstorage'
});
```

**Important:** This feature will allow the caching of data **such as ID and access tokens** to be stored in local storage. Exercising this option changes the security characteristics of your application and **should not be used lightly**. Extra care should be taken to mitigate against XSS attacks and minimize the risk of tokens being stolen from local storage.

### Refresh Tokens

Refresh tokens can be used to request new access tokens. [Read more about how our refresh tokens work for browser-based applications](https://auth0.com/docs/tokens/concepts/refresh-token-rotation) to help you decide whether or not you need to use them.

To enable the use of refresh tokens, set the `useRefreshTokens` option to `true`:

```js
await createAuth0Client({
domain: '<AUTH0_DOMAIN>',
client_id: '<AUTH0_CLIENT_ID>',
redirect_uri: '<MY_CALLBACK_URL>',
useRefreshTokens: true,
});
```

Using this setting will cause the SDK to automatically send the `offline_access` scope to the authorization server. Refresh tokens will then be used to exchange for new access tokens instead of using a hidden iframe, and calls the `/oauth/token` endpoint directly. This means that the SDK does not rely on third-party cookies when using refresh tokens.

**Note** This configuration option requires Rotating Refresh Tokens to be [enabled for your Auth0 Tenant](https://auth0.com/docs/tokens/guides/configure-refresh-token-rotation).

## Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:
Expand Down