@idport/oidc-rp-sdk NPM

OIDC RP SDK

The OIDC RP SDK provides a high-level API for authentication to single page applications (SPA) via OpenID Connect protocol with the Hybrid Flow or Authorization Code Flow with PKCE. Under the hood, it handles a lot of the details and implements best practices to secure SPAs.

The SDK is built with ES2015 target in ESM format, which is supported in all modern browsers. It is recommended to use bundler and minification for production use.

The documentation of specific methods and parameters is directly in the code as JSDoc which works well with TypeScript.

Installation via npm

npm install @idport/oidc-rp-sdk

Usage

It's recommended to pull in all you need directly from '@idport/oidc-rp-sdk' as shown below in example with OidcRpClient.

Example

This example assumes you have a http server running where:

/node_modules/@idport/oidc-rp-sdk/index.js serves node_modules/@idport/oidc-rp-sdk/index.js
/, YOUR_REDIRECT_URI, YOUR_POST_LOGOUT_REDIRECT_URI serves the following document:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <base href="/" />
    <title>OIDC RP SDK demo</title>
  </head>
  <body>
    <script type="module">
      import { OidcRpClient } from './node_modules/@idport/oidc-rp-sdk/index.js';

      const currentUri = window.location.origin + window.location.pathname;
      const redirectUri = 'YOUR_REDIRECT_URI';
      const postLogoutRedirectUri = 'YOUR_POST_LOGOUT_REDIRECT_URI';

      const oidcRpClient = OidcRpClient.createClient({
        clientId: 'YOUR_CLIENT_ID',
        issuer: 'YOUR_ISSUER_URL',
        responseType: 'code',
        checkSession: { interval: 1, iframeId: 'op' },
        checkUserInactivity: { type: 'app', timeout: 300, interval: 1 },
        callback: async (event) => {
          switch (event.type) {
            case 'session_changed':
              console.log('Session changed.');
              break;
            case 'session_error':
              console.log('Session error occured.');
              break;
            case 'user_inactivity_timeout':
              console.log('User inactivity timeout.');
              await oidcRpClient
                .revokeToken()
                .then(() => console.log('Token revoked.'))
                .catch((e) => console.error(e));
              break;
            case 'user_inactivity_reset':
              console.log(`User inactivity reset. Timeout: ${event.timeout}s`);
              break;
          }
        },
      });

      if (currentUri === redirectUri) {
        handleRedirectUri();
      } else if (currentUri === postLogoutRedirectUri) {
        handlePostLogoutRedirectUri();
      } else {
        login();
      }

      function handleRedirectUri() {
        oidcRpClient
          .handleLoginWithRedirectCallback()
          .then((x) => {
            if (x.type === 'success') {
              console.log('Successfully logged in.', x);
              console.log('Type logout() to console to log out');
              console.log('Type revokeToken() to console to revoke token.');
            } else {
              console.log(x);
            }
            window.history.pushState('', '', '.');
          })
          .catch((e) => console.error(e));
      }

      function handlePostLogoutRedirectUri() {
        oidcRpClient
          .handleLogoutCallback()
          .then((x) => {
            if (x.type === 'success') {
              console.log('Successfully logged out.', x);
              console.log('Type login() to console to log in.');
            } else {
              console.log(x);
            }
          })
          .catch((e) => console.error(e));
      }

      function login() {
        console.log('Login initiated.');
        oidcRpClient
          .loginWithRedirect({
            redirectUri,
            scope: '',
            state: 'this string will be available as OidcRpLoginSuccess.state in redirectUri handler',
          })
          .catch((e) => console.error(e));
      }

      function revokeToken() {
        console.log('Token revocation initiated.');
        oidcRpClient
          .revokeToken()
          .then(() => console.log('Token revoked.'))
          .catch((e) => console.error(e));
      }

      function logout() {
        console.log('Logout initiated.');
        oidcRpClient
          .logout({
            postLogoutRedirectUri,
            state: 'this string will be available as OidcRpLogoutSuccess.state in postLogoutRedirectUri handler',
          })
          .catch((e) => console.error(e));
      }

      window.login = login;
      window.logout = logout;
      window.revokeToken = revokeToken;
    </script>
  </body>
</html>

Changelog

2.5.1

(2025-03-21)

Prefer fragment over query in URL response from OIDC provider.

2.5.0

(2024-08-15)

Resolves promise from loginWithRedirect and logout functions when page is restored from bfcache after redirect to login/logout.

2.4.0

(2024-06-20)

Set default end session request method to POST
Add endSessionHttpMethod option to config.

2.3.0

(2024-01-09)

Add user inactivity check
Parse expires_in from url (Implicit Flow)
Add target option to login request.

2.2.0

(2023-02-28)

Add support for claims attribute in authorization request.

2.1.3

(2023-01-03)

Default url for handleLoginWithRedirectCallback and handleLogoutCallback functions is captured during library loading.

2.1.2

(2022-11-02)

Add session state to login response.

2.1.1

(2022-10-13)

Fix docs.
Optional callback parameter in config.
Remove OidcRpEventType type.

2.1.0

(2022-09-27)

Add support for refresh token.
Add options to revokeToken function

2.0.5

(2022-09-14)

If session_state is not specified in the URL, use session_state from id_token.
Change types of claims and headers in OidcRpLoginSuccess from any to unknown.