npm package: @idport/oidc-rp-sdk
Description: 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 pract
Latest version: 2.6.0

# 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

```sh
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:

```html
<!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.6.0

(2025-04-09)

- Add ability to send additional parameters with a login and logout request.

### 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`.

### 2.0.4

(2022-07-19)

- Add login/logout options.

### 2.0.3

(2022-07-18)

- Fix docs.

### 2.0.2

(2022-07-07)

- Remove UMD build. Set target to ES2015.

### 2.0.1

(2022-06-27)

- Fix revokeToken, empty response.

### 2.0.0

(2022-05-26)

- Release new major version of rewritten SDK.

### 1.3.1

(2021-11-16)

- Add logoutUri parameter to generateLogoutRequest in README docs.

### 1.3.0

(2021-11-16)

- Add logoutUri parameter to generateLogoutRequest.

### 1.2.4

(2021-07-14)

- This version updates dependencies due to security vulnerabilities.

### 1.2.3

(2020-03-17)

- Pass `OP_BASE_FQDN` as parameter to RP iframe.

### 1.2.2

(2020-01-31)

- Set `state` parameter as optional in `generateAuthenticationRequest` function.

### 1.2.1

(2020-01-28)

- Add `additionalRequestParams` optional param to `generateAuthenticationRequest` function.

### 1.2.0

(2019-09-18)

- Update OP iframe configuration.

### 1.1.3

(2019-08-02)

- Fix issue with join OP_FDQN base url with endpoint paths.

### 1.1.2

(2019-08-02)

- Refactor code structure
- Add unit tests
- Fix publish repository config

### 1.0.0

(2019-06-06)

- Initial library version.