@csmtools/openid
v1.1.0
Published
OpenID 1.1/2.0 library for Node.js
Downloads
9
Maintainers
Readme
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
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.