@sailfin/oidc

Overview

@sailfin/oidc is a fully-featured OpenID Connect (OIDC) client library designed for seamless integration with OIDC providers, including Sailfin's OIDC provider. It enables user authentication, token management, and secure interaction with APIs that support the OIDC standard.

This library is built for enterprise-grade TypeScript and Node.js applications, adhering to modern TypeScript practices. It supports multiple grant types, token validation, user information retrieval, and more.

This package it under active development and is not yet ready for production use. Please use with caution and report any issues or bugs you encounter.

Table of Contents

• Design Philosophy
• Features
• Installation
• Usage
  • Basic Setup
  • Token Management
  • Device Authorization Flow
  • Token Introspection and Revocation
  • Logging
• Configuration Options
• API Reference
  • Methods
• Error Handling
• Testing
  • Unit Tests
• Contributing
• Support
• License

Design Philosophy

To ensure a lightweight and dependency-free experience, @sailfin/oidc incorporates several internally built utility functions. These utilities handle complex operations such as DER encoding, key conversions, and asynchronous control flows without relying on external packages, providing a seamless and efficient integration for your applications. These utilities are designed to be modular and can be used independently in other projects, although they are primarily intended for internal use within the library and are not exposed as part of the public API. Feel free to explore the src/utils directory to learn more about these utilities.

Features

• Authorization URL Generation: Supports PKCE and state validation.
• Token Management: Access, refresh, and ID tokens handling.
• User Info Retrieval: Fetch user details securely using the userinfo endpoint.
• Device Authorization Flow: Simplified device code handling and polling.
• Token Introspection and Revocation: Validate and manage tokens efficiently.
• Discovery Endpoint Support: Dynamically fetches and caches OIDC configuration.
• Flexible Configuration: Works with any OIDC-compliant provider.

Installation

Install the package using npm:

npm install @sailfin/oidc

or with Yarn:

yarn add @sailfin/oidc

Usage

Basic Setup

Here's an example of initializing and using the @sailfin/oidc client:

import { Client, Scopes, GrantType, SameSite, Storage } from '@sailfin/oidc';

const oidcClient = new Client({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  redirectUri: 'https://your-app/callback',
  discoveryUrl: 'https://issuer.com/.well-known/openid-configuration',
  scopes: [Scopes.OpenId, Scopes.Profile, Scopes.Email],
  grantType: GrantType.AuthorizationCode,
  logging: {
    logLevel: 'info',
  },
  session: {
    cookie: {
      name: 'oidc-session',
      secure: true,
      httpOnly: true,
      sameSite: SameSite.STRICT,
      maxAge: 3600,
    },
    useSilentRenew: true,
  },
  storage: {
    mechanism: Storage.MEMORY,
    options: {
      storage: { ttl: 3600 },
    },
  },
});

(async () => {
  // Initialize the client
  await oidcClient.getAuthorizationUrl();

  // Generate the authorization URL
  const { url, state } = await oidcClient.getAuthorizationUrl();
  console.log(`Visit this URL to authenticate: ${url}`);

  // Handle the redirect with the authorization code
  await oidcClient.handleRedirect('auth-code', state, {
    request: mockRequest,
    response: mockResponse,
  });

  // Fetch user info
  const userInfo = await oidcClient.getUserInfo();
  console.log('User Info:', userInfo);
})();

Token Management

Retrieve, introspect, or revoke tokens with ease:

// Get the access token
const accessToken = await oidcClient.getAccessToken();
console.log('Access Token:', accessToken);

// Introspect a token
const tokenInfo = await oidcClient.introspectToken(accessToken);
console.log('Token Introspection:', tokenInfo);

// Revoke a refresh token
await oidcClient.revokeToken('refresh-token', 'refresh_token');
console.log('Refresh token revoked.');

Device Authorization Flow

Supports device code authentication:

const { device_code, user_code, verification_uri } =
  await oidcClient.startDeviceAuthorization();

console.log(`Visit ${verification_uri} and enter the code: ${user_code}`);

// Poll for tokens
await oidcClient.pollDeviceToken(device_code);
console.log('Device successfully authorized.');

Token Introspection and Revocation

// Introspect a token
const introspection = await oidcClient.introspectToken('your-token');
console.log('Token introspection:', introspection);

// Revoke a token
await oidcClient.revokeToken('your-refresh-token', 'refresh_token');
console.log('Token revoked.');

Logging

Customize the logging level:

oidcClient.setLogLevel('debug');

Configuration Options

Below are the required and optional parameters for initializing the Client:

Scopes, GrantType, and LogLevel are enums provided by the library. This is a non-exhaustive list of available values:

enum Scopes {
  OpenId = 'openid',
  Profile = 'profile',
  Email = 'email',
}

enum GrantType {
  AuthorizationCode = 'authorization_code',
  ClientCredentials = 'client_credentials',
  DeviceCode = 'urn:ietf:params:oauth:grant-type:device_code',
}

enum LogLevel {
  Info = 'info',
  Debug = 'debug',
  Warn = 'warn',
  Error = 'error',
}

note - The client accepts additonal options for customizing the OIDC flow, such as responseType, responseMode, prompt, nonce, and state etc. These options can be configured by adhereing to the `ICl

API Reference

Methods

• getAuthorizationUrl() - Generates an authorization URL for user login.
• handleRedirect(code, state) - Processes the authorization code callback.
• handleRedirectForImplicitFlow(fragment) - Processes the implicit flow callback.
• getUserInfo() - Fetches user info from the userinfo endpoint.
• getAccessToken() - Retrieves the current access token, refreshing it if necessary.
• clearTokens() - Clears all stored tokens.
• startDeviceAuthorization() - Initiates device authorization flow.
• pollDeviceToken(device_code, interval, timeout) - Polls for tokens in device authorization flow.
• introspectToken(token) - Introspects a token.
• revokeToken(token, tokenTypeHint) - Revokes a token.
• setLogLevel(level) - Sets the log level.

Error Handling

The library throws ClientError for all error scenarios, ensuring consistent error handling. Each error includes a message, code, and optional details field.

Example:

try {
  await oidcClient.getUserInfo();
} catch (error) {
  if (error instanceof ClientError) {
    console.error(`Error Code: ${error.code}`);
    console.error(`Error Message: ${error.message}`);
  } else {
    console.error('An unexpected error occurred:', error);
  }
}

Testing

Unit Tests

To run the unit tests, use the following command:

npm run test

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for guidelines.

Support

For issues and feature requests, please open an issue.

License

This project is licensed under the MIT License. See the LICENSE file for details.