Socket
Socket
Sign inDemoInstall

openid-client

Package Overview
Dependencies
5
Maintainers
1
Versions
180
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

openid-client

OpenID Connect Relying Party (RP, Client) implementation for Node.js runtime, supports passportjs


Version published
Maintainers
1
Weekly downloads
2,085,307
decreased by-4.03%

Weekly downloads

Package description

What is openid-client?

The openid-client package is a server-side library that allows Node.js applications to act as a Relying Party (RP) for any OpenID Connect (OIDC) compliant Identity Provider (IP). It provides functionality to discover OIDC providers, authenticate users, validate ID tokens, and securely perform token operations.

What are openid-client's main functionalities?

Discovery of OpenID Provider configuration

This feature allows the client to automatically discover the OpenID Provider's configuration using the issuer's URL. It simplifies the process of setting up the client by fetching the necessary endpoints and public keys.

const { Issuer } = require('openid-client');

(async () => {
  const googleIssuer = await Issuer.discover('https://accounts.google.com');
  console.log('Discovered issuer %s', googleIssuer.issuer);
})();

Client authentication with an OpenID Provider

This code sample demonstrates how to authenticate with an OpenID Provider by creating a client instance with the necessary credentials and generating an authorization URL for user redirection.

const { Issuer } = require('openid-client');

(async () => {
  const issuer = await Issuer.discover('https://example.com');
  const client = new issuer.Client({
    client_id: 'your-client-id',
    client_secret: 'your-client-secret',
    redirect_uris: ['https://your-callback-url/callback'],
    response_types: ['code']
  });

  const authorizationUrl = client.authorizationUrl({
    scope: 'openid email profile',
  });

  console.log('Authorization URL:', authorizationUrl);
})();

Handling authentication responses

This feature is used to handle the callback from the OpenID Provider after user authentication. It involves parsing the callback parameters, exchanging the authorization code for tokens, and validating the ID token.

const { Issuer, generators } = require('openid-client');

(async () => {
  const issuer = await Issuer.discover('https://example.com');
  const client = new issuer.Client({
    client_id: 'your-client-id',
    client_secret: 'your-client-secret',
    redirect_uris: ['https://your-callback-url/callback'],
    response_types: ['code']
  });

  const code_verifier = generators.codeVerifier();
  const code_challenge = generators.codeChallenge(code_verifier);

  const params = client.callbackParams('https://your-callback-url/callback?code=AUTH_CODE&state=STATE');
  const tokenSet = await client.callback('https://your-callback-url/callback', params, { code_verifier });

  console.log('Received and validated tokens %j', tokenSet);
  console.log('ID Token claims %j', tokenSet.claims());
})();

Token management

This code sample shows how to manage tokens, including how to exchange an authorization code for tokens and how to refresh tokens using a refresh token.

const { Issuer } = require('openid-client');

(async () => {
  const issuer = await Issuer.discover('https://example.com');
  const client = new issuer.Client({
    client_id: 'your-client-id',
    client_secret: 'your-client-secret'
  });

  const tokenSet = await client.grant({
    grant_type: 'authorization_code',
    code: 'AUTH_CODE',
    redirect_uri: 'https://your-callback-url/callback'
  });

  const refreshedTokenSet = await client.refresh(tokenSet.refresh_token);
  console.log('Refreshed tokens %j', refreshedTokenSet);
})();

Other packages similar to openid-client

Readme

Source

openid-client

openid-client is a server side OpenID Relying Party (RP, Client) implementation for Node.js runtime, supports passport.

Implemented specs & features

The following client/RP features from OpenID Connect/OAuth2.0 specifications are implemented by openid-client.

Updates to draft specifications are released as MINOR library versions, if you utilize these specification implementations consider using the tilde ~ operator in your package.json since breaking changes may be introduced as part of these version updates.

Certification

OpenID Certification
Filip Skokan has certified that openid-client conforms to the following profiles of the OpenID Connect™ protocol

  • Basic, Implicit, Hybrid, Config, Dynamic, and Form Post RP
  • FAPI 1.0 Advanced RP

Sponsor

auth0-logo If you want to quickly add OpenID Connect authentication to Node.js apps, feel free to check out Auth0's Node.js SDK and free plan. Create an Auth0 account; it's free!

Support

If you or your business use openid-client, please consider becoming a sponsor so I can continue maintaining it and adding new features carefree.

Documentation

The library exposes what are essentially steps necessary to be done by a relying party consuming OpenID Connect Authorization Server responses or wrappers around requests to its endpoints. Aside from a generic OpenID Connect passport strategy it does not expose any framework specific middlewares. Those can however be built using the exposed API, one such example is express-openid-connect

Install

Node.js LTS releases Codename Erbium and newer LTS releases are supported.

npm install openid-client

Note: Other javascript runtimes are not supported. I recommend panva/oauth4webapi, or a derivate thereof, if you're looking for a similarly compliant and certified client software that's not dependent on the Node.js runtime builtins.

Quick start

Discover an Issuer configuration using its published .well-known endpoints

import { Issuer } from 'openid-client';

const googleIssuer = await Issuer.discover('https://accounts.google.com');
console.log('Discovered issuer %s %O', googleIssuer.issuer, googleIssuer.metadata);

Authorization Code Flow

Authorization Code flow is for obtaining Access Tokens (and optionally Refresh Tokens) to use with third party APIs securely as well as Refresh Tokens. In this quick start your application also uses PKCE instead of state parameter for CSRF protection.

Create a Client instance for that issuer's authorization server intended for Authorization Code flow.

See the documentation for full API details.

const client = new googleIssuer.Client({
  client_id: 'zELcpfANLqY7Oqas',
  client_secret: 'TQV5U29k1gHibH5bx1layBo0OSAvAbRT3UYW3EWrSYBB5swxjVfWUa1BS8lqzxG/0v9wruMcrGadany3',
  redirect_uris: ['http://localhost:3000/cb'],
  response_types: ['code'],
  // id_token_signed_response_alg (default "RS256")
  // token_endpoint_auth_method (default "client_secret_basic")
}); // => Client

When you want to have your end-users authorize you need to send them to the issuer's authorization_endpoint. Consult the web framework of your choice on how to redirect but here's how to get the authorization endpoint's URL with parameters already encoded in the query to redirect to.

import { generators } from 'openid-client';
const code_verifier = generators.codeVerifier();
// store the code_verifier in your framework's session mechanism, if it is a cookie based solution
// it should be httpOnly (not readable by javascript) and encrypted.

const code_challenge = generators.codeChallenge(code_verifier);

client.authorizationUrl({
  scope: 'openid email profile',
  resource: 'https://my.api.example.com/resource/32178',
  code_challenge,
  code_challenge_method: 'S256',
});

When end-users are redirected back to your redirect_uri your application consumes the callback and passes in the code_verifier to include it in the authorization code grant token exchange.

const params = client.callbackParams(req);
const tokenSet = await client.callback('https://client.example.com/callback', params, { code_verifier });
console.log('received and validated tokens %j', tokenSet);
console.log('validated ID Token claims %j', tokenSet.claims());

You can then call the userinfo_endpoint.

const userinfo = await client.userinfo(access_token);
console.log('userinfo %j', userinfo);

And later refresh the tokenSet if it had a refresh_token.

const tokenSet = await client.refresh(refresh_token);
console.log('refreshed and validated tokens %j', tokenSet);
console.log('refreshed ID Token claims %j', tokenSet.claims());

Implicit ID Token Flow

Implicit response_type=id_token flow is perfect for simply authenticating your end-users, assuming the only job you want done is authenticating the user and then relying on your own session mechanism with no need for accessing any third party APIs with an Access Token from the Authorization Server.

Create a Client instance for that issuer's authorization server intended for ID Token implicit flow.

See the documentation for full API details.

const client = new googleIssuer.Client({
  client_id: 'zELcpfANLqY7Oqas',
  redirect_uris: ['http://localhost:3000/cb'],
  response_types: ['id_token'],
  // id_token_signed_response_alg (default "RS256")
}); // => Client

When you want to have your end-users authorize you need to send them to the issuer's authorization_endpoint. Consult the web framework of your choice on how to redirect but here's how to get the authorization endpoint's URL with parameters already encoded in the query to redirect to.

import { generators } from 'openid-client';
const nonce = generators.nonce();
// store the nonce in your framework's session mechanism, if it is a cookie based solution
// it should be httpOnly (not readable by javascript) and encrypted.

client.authorizationUrl({
  scope: 'openid email profile',
  response_mode: 'form_post',
  nonce,
});

When end-users hit back your redirect_uri with a POST (authorization request included form_post response mode) your application consumes the callback and passes the nonce in to include it in the ID Token verification steps.

// assumes req.body is populated from your web framework's body parser
const params = client.callbackParams(req);
const tokenSet = await client.callback('https://client.example.com/callback', params, { nonce });
console.log('received and validated tokens %j', tokenSet);
console.log('validated ID Token claims %j', tokenSet.claims());

Device Authorization Grant (Device Flow)

RFC8628 - OAuth 2.0 Device Authorization Grant (Device Flow) is started by starting a Device Authorization Request.

const handle = await client.deviceAuthorization();
console.log('User Code: ', handle.user_code);
console.log('Verification URI: ', handle.verification_uri);
console.log('Verification URI (complete): ', handle.verification_uri_complete);

The handle represents a Device Authorization Response with the verification_uri, user_code and other defined response properties.

You will display the instructions to the end-user and have him directed at verification_uri or verification_uri_complete, afterwards you can start polling for the Device Access Token Response.

const tokenSet = await handle.poll();
console.log('received tokens %j', tokenSet);

This will poll in the defined interval and only resolve with a TokenSet once one is received. This will handle the defined authorization_pending and slow_down "soft" errors and continue polling but upon any other error it will reject. With tokenSet received you can throw away the handle.

Client Credentials Grant Flow

Client Credentials flow is for obtaining Access Tokens to use with third party APIs on behalf of your application, rather than an end-user which was the case in previous examples.

See the documentation for full API details.

const client = new issuer.Client({
  client_id: 'zELcpfANLqY7Oqas',
  client_secret: 'TQV5U29k1gHibH5bx1layBo0OSAvAbRT3UYW3EWrSYBB5swxjVfWUa1BS8lqzxG/0v9wruMcrGadany3',
});

const tokenSet = await client.grant({
  resource: 'urn:example:third-party-api',
  grant_type: 'client_credentials'
});

FAQ

Semver?

Yes. Everything that's either exported in the TypeScript definitions file or documented is subject to Semantic Versioning 2.0.0. The rest is to be considered private API and is subject to change between any versions.

How do I use it outside of Node.js

It is only built for Node.js. Other javascript runtimes are not supported. I recommend panva/oauth4webapi, or a derivate thereof, if you're looking for a similarly compliant and certified client software that's not dependent on the Node.js runtime builtins.

How to make the client send client_id and client_secret in the body?

See Client Authentication Methods (docs).

Can I adjust the HTTP timeout?

See Customizing (docs).

Keywords

FAQs

Last updated on 07 Mar 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc