@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.

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 OIDCClient:

import { OIDCClient } from '@sailfin/oidc';

const oidcClient = new OIDCClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  discoveryUrl:
    'https://your-oidc-provider.com/.well-known/openid-configuration',
  redirectUri: 'https://your-redirect-uri.com',
  scopes: ['openid', 'profile', 'email'],
  grantType: 'authorization_code',
});

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

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

  // Handle redirect after authentication (use your framework's routing to get the code and state)
  await oidcClient.handleRedirect(
    'your-authorization-code',
    'your-returned-state',
  );

  // Retrieve user information
  const userInfo = await oidcClient.getUserInfo();
  console.log(userInfo);
})();

Token Management

Refresh and retrieve tokens with ease:

const accessToken = await oidcClient.getAccessToken();
console.log(`Access Token: ${accessToken}`);

const tokens = oidcClient.getTokens();
console.log('Tokens:', tokens);

// Clear stored tokens
oidcClient.clearTokens();

Device Authorization Flow

Supports device code authentication:

const deviceAuthorization = await oidcClient.startDeviceAuthorization();
console.log(
  'Enter the code on this page:',
  deviceAuthorization.verification_uri,
);
console.log('Your user code:', deviceAuthorization.user_code);

// Poll for tokens
await oidcClient.pollDeviceToken(deviceAuthorization.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 OIDCClient:

API Reference

Methods

• initialize() - Fetches discovery configuration and initializes the client.
• getAuthorizationUrl() - Generates an authorization URL for user login.
• handleRedirect(code, state) - Handles redirect after login for authorization code flow.
• 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);
  }
}

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.

Happy coding! 🎉