OpenID Connect (OIDC) and OAuth2 library for browser based JavaScript applications.

• Silent Authentication
• Automatic Access Token Renewal
• OAuth 2.0 Token Revocation
• Session Management (with logout functionality)
• PKCE
• JWT payload validation
• Can be used with any OAuth 2.0 / OpenID Connect provider
• Cross tab/window login synchronization
• Dispatches single request per tab/window to prevent inconsistency
• Official TypeScript support

• Installation
• Documentation
• Access Token Refreshing
• Use Refresh Token
• Login with Popup
• Additional Methods
• Examples

From the CDN:

<script src="https://unpkg.com/@plusauth/[email protected]/dist/oidc-client.min.js"></script>

Using package managers:

npm install @plusauth/oidc-client-js
yarn add @plusauth/oidc-client-js
pnpm add @plusauth/oidc-client-js

Create the OIDCClient instance before rendering or initializing your application.

import { OIDCClient } from '@plusauth/oidc-client-js';

const oidcClient = new OIDCClient({
  issuer: 'YOUR_OIDC_PROVIDER',
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_CALLBACK_PAGE_URI'
});

oidcClient.initialize().then( function(){
  // client initialized
})

Or with create helper method:

import createOIDCClient from '@plusauth/oidc-client-js';

createOIDCClient({
  issuer: 'YOUR_OIDC_PROVIDER',
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_CALLBACK_PAGE_URI'
}).then(oidcClient => {
  //...
});

Using createOIDCClient does a couple of things automatically:

• It creates an instance of OIDCClient.
• It calls silentLogin to refresh the user session.
• It suppresses all errors from silentLogin.

OpenID Connect / OAuth2 authorization flows require a redirect uri to return the authorization result back. Create a page and register its url to your client's allowed redirect uris. In your page initialize OIDCClient and all you need to do is call loginCallback method.

oidcClient.loginCallback()
.then( function(localState){
  // successful login
  console.log('User successfully logged in')
})
.catch( function(error) {
  console.error('Authorization error:', error)
 })

Create a login button users can click.

<button id="login">Login</button>

In the click event handler of button you created, call login method for redirecting user to provider's login page . Make sure redirect_uri is registered on the provider, and you have created a callback handler as defined in above .

document.getElementById('login').addEventListener('click', function() {
  oidcClient.login({
    redirect_uri: 'http://localhost:8080/'
  });
});

After user is successfully logged in we can use access_token retrieved from authentication response to call the API.

<button id="makeRequest">Make Request</button>

On the event handler you can get access token and use it like this:

document.getElementById('makeRequest').addEventListener('click', function () {
 oidcClient.getAccessToken().then(accessToken =>
       fetch('https://any.exampleapi.com/api', {
         method: 'GET',
         headers: {
           Authorization: 'Bearer ' + accessToken
         }
       })
     )
     .then(result => result.json())
     .then(data => {
       console.log(data);
     });
});

Add a logout button.

<button id="logout">Logout</button>

In event handler, call equivalent method.

document.getElementById('logout').addEventListener('click', function(){
  oidcClient.logout();
});

Generally, access tokens have a short lifetime, so it is common to renew the access token before its expiration. This feature is enabled by default, but you can disable it by passing autoSilentRenew: false to client options.

new OIDCClient({
  autoSilentRenew: false,
  ...// other options
})

In silent renew the library performs the flow in a hidden iframe. When you are developing a single page application, assuming your callback page is handled by the app itself, the iframe will load your whole application after the oauth2 redirection.

You can prevent this overhead by creating a different page which will handle silent renew only. To accomplish this you should pass silent_redirect_uri to client options which should have your silent redirect handler page uri. If you don't use silent_redirect_uri, redirect_uri will be used instead. Don't forget to include it to your providers redirect uri whitelist.

Have a look at following snippets for an example:

// auth.js
import { OIDCClient } from '@plusauth/oidc-client-js';

const oidcClient = new OIDCClient({
  redirect_uri: 'https://YOUR_SITE/callback'
  silent_redirect_uri: 'https://YOUR_SITE/silent-renew.html',
  ...//other options
});

<!-- silent-renew.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://unpkg.com/@plusauth/oidc-client-js/dist/plusauth-oidc-client.umd.js"></script>
</head>
<body>
<script type="application/javascript" >
    new PlusAuthOIDCClient.OIDCClient({
      issuer: 'YOUR_OIDC_PROVIDER'
    }).loginCallback()
</script>
</body>
</html>

Configure the library by passing the setting useRefreshTokens to true on initialization:

const oidcClient = new OIDCClient({
  issuer: 'YOUR_OIDC_ISSUER',
  client_id: 'YOUR_CLIENT-ID',
  useRefreshTokens: true
});

Create a button to trigger login.

<button id="loginWithPopup">Login</button>

Attach event listener and call loginWithPopup method of your initialized oidc client.

document.getElementById('loginWithPopup').click(async () => {
  await oidcClient.loginWithPopup();
});

You can access user, access token, refresh token, id token and scopes with followings. Using getter methods are always the safe bet as they will read from store. Direct access of those variables may result unexpectedly if you modify them in your app. Direct variables are created by listening the user_login and user_logout events.

  const user = await oidcClient.getUser();
  // or
  const user = oidcClient.user

  const accessToken = await oidcClient.getAccessToken();
  // or
  const accessToken = oidcClient.accessToken

  const idToken = await oidcClient.getIdToken();
  // or
  const idToken = oidcClient.idToken

  const refreshToken = await oidcClient.getRefreshToken();
  // or
  const refreshToken = oidcClient.refreshToken

  const scopes = await oidcClient.getScopes();
  // or
  const scopes = oidcClient.scopes

Please visit here

Have a look at examples directory for various examples

Browserlist Coverage

This library uses global fetch api. If your app requires to be working in environment that does not have fetch you must use a polyfill like whatwg-fetch.