@csmtools/openid

OpenID for Node.js

OpenID for Node.js is (yes, you guessed it) an OpenID implementation for Node.js.

Highlights and features include:

• Full OpenID 1.0/1.1/2.0 compliant Relying Party (client) implementation
• Easy to use API
• Simple extension points for association state
• Safety checks for which providers to use

Table of content

• Download
• Installation
• Examples
• API
  • RelyingParty
    • Methods
      • authenticate()
      • verifyAssertion()
  • Extension
  • Store
  • extensions
• Types
  • ValidityChecks
  • AssertionResponse
  • ErrorMessage
• Supported Extensions
• License

Download

The library can be reviewed and retrieved from GitHub.

Installation

If you use npm:

npm i openid

If you use yarn:

yarn add openid

If you use bun:

bun add openid

The package can then be imported using both commonjs (require) and es6 modules (import).

Examples

Examples including extensions can be found in the samples folder in the GitHub repository.

API

RelyingParty

const rp = new RelyingParty(returnUrl, realm, stateless, strict, extensions, validityChecks?, associationStore?, discoveryStore?, nonceStore?)

• returnUrl: string
  • The URL to which openid authentication should return to.
• realm: string | null
  • Can be either null or the url of the service that is requesting the user to identify themselves (your website most likely).
• stateless: boolean
  • Whether or not to use stateless authentication.
• strict: boolean
  • Whether or not to use strict mode.
• extensions: Extension[]
  • Array of extensions, can be empty.
• validityChecks: ValidityChecks
  • Refer to ValidityChecks
• associationStore: Store
  • Refer to Store
• discoveryStore: Store
  • Refer to Store
• nonceStore: Store
  • Refer to Store

Methods

authenticate()

const authUrl = await rp.authenticate(identifier)

• identifier: string
  • String identifier in the form of an URL from which the RelyingParty can find an openid provider.
• returns: Promise<string>
  • URL that can be used to authenticate a user.
• throws: ErrorMessage
  • Refer to ErrorMessage

verifyAssertion()

const result = await rp.verifyAssertion(url)

• url: string | URL
  • The url the user was redirected to by the openid provider, including query/search. Can be given as string or URL object.
• returns: Promise<AssertionResponse>
  • Refer to AssertionResponse
• throws: ErrorMessage
  • Refer to ErrorMessage

Extension

class MyExtension extends Extension {
  fillResult(params, result) {
    // Add implementation here
  }
}

Abstract class that can be implemented to create your own extensions. The only required method is fillResult, but you can also implement your own constructor.

The following properties and methods are available on Extension:

requestParams: Record<string, string>;

getHeader(header: string): string;

static getExtensionAlias(params: URLSearchParams, ns: string): string;

Store

abstract class Store<Key extends string | number | symbol, Value> {
    abstract getItem(key: Key): (Value | undefined) | Promise<Value | undefined>;
    abstract setItem(key: Key, value: Value): this | Promise<this>;
    abstract removeItem(key: Key): this | Promise<this>;
    abstract getAll(): Record<Key, Value> | Promise<Record<Key, Value>>;
}

Abstract class that is used for storing data, can be extended and supplied to the RelyingParty class to have custom data stores, like redis or other solutions.

This can be especially handy if you have a multi-server solution.

extensions

{
    AttributeExchange,
    OAuthHybrid,
    PAPE,
    SimpleRegistration,
    UserInterface
}

An object containing all built-in extensions.

Types

ValidityChecks

{
    /**
     * Checks if ns is in this array
     */
    ns: string[],
    /**
     * Checks if claimed_id starts with any of these
     */
    claimed_id: string[],
    /**
     * Checks if identity starts with any of these
     */
    identity: string[],
    /**
     * Checks if op_endpoint is in this array
     */
    op_endpoint: string[]
}

AssertionResponse

{
  authenticated: boolean,
  claimedIdentifier: string | null

  + VALUES ADDED BY EXTENSIONS
}

ErrorMessage

{
  message: string
}

Supported Extensions

This library comes with built-in support for the following OpenID extensions:

• The Simple Registration (SREG) 1.1 extension is implemented as extensions.SimpleRegistration.
• The Attribute Exchange (AX) 1.0 extension is implemented as extensions.AttributeExchange.
• The OAuth 1.0 extension is implemented as extensions.OAuthHybrid.
• The User Interface 1.0 extension is implemented as extensions.UserInterface.
• The Provider Authentication Policy Extension 1.0 (PAPE) is implemented as extensions.pape.

License

OpenID for Node.js is licensed under the MIT license. See LICENSE for further details.