Anvil Connect client for Node.js / camfou fork
Anvil Connect is a modern authorization server built to authenticate your users and protect your APIs. It's based on OAuth 2.0 and OpenID Connect.
This library is a low level OpenID Connect and Anvil Connect API client. Previous versions included Express-specific functions and middleware. These higher-level functions are being split out into a [separate library][connect-express].
Install
$ npm install camfou-connect-nodejs --save
Configure
Before performing any other operations (such as verifying or refreshing OIDC tokens, or accessing the AnvilConnect-specific API (such as creating users), an OIDC client needs to be configured and registered with the server (OIDC Provider, OP for short).
new Connect(config)
var ConnectClient = ; // If the client has been pre-registered, pass the credentials to constructorvar client = issuer: 'https://connect.example.com' client_id: 'CLIENT_ID' client_secret: 'CLIENT_SECRET' redirect_uri: 'REDIRECT_URI' scope: 'realm'client // If the client has not been registered, use OIDC dynamic registrationvar client = issuer: 'https://connect.example.com' client
options
issuer
– REQUIRED uri of your OpenID Connect providerclient_id
– OPTIONAL client identifier issued by OIDC provider during registrationclient_secret
– OPTIONAL confidential value issued by OIDC provider during registrationredirect_uri
– OPTIONAL uri users will be redirected back to after authenticating with the issuerscope
– OPTIONAL array of strings, or space delimited string value containing scopes to be included in authorization requests. Defaults toopenid profile
OpenID Connect
client.discover()
Returns a promise providing OpenID Metadata retrieved from the
.well-known/openid-configuration
endpoint for the configured issuer. Sets the
response data as client.configuration
.
example
client
client.getJWKs()
Returns a promise providing the JWK set published by the configured issuer.
Depends on a prior call to client.discover()
.
example
client
client.register(registration)
Dynamically registers a new client with the configured issuer and returns a
promise for the new client registration. You can learn more about dynamic
registration for Anvil Connect in the docs. Depends on a
prior call to client.discover()
.
example
var options = client_name: 'Antisocial Network' client_uri: 'https://app.example.com' logo_uri: 'https://app.example.com/assets/logo.png' response_types: 'code' grant_types: 'authorization_code' 'refresh_token' default_max_age: 86400 // one day in seconds redirect_uris: 'https://app.example.com/callback.html' 'https://app.example.com/other.html' post_logout_redirect_uris: 'https://app.example.com'client
client.authorizationUri([endpoint|options])
Accepts a string specifying a non-default endpoint or an options object and
returns an authorization URI. Depends on a prior call to client.discover()
and
client_id
being configured.
options
- All options accepted by
client.authorizationParams()
. endpoint
– This value is used for the path in the returned URI. Defaults toauthorize
.
example
client// 'https://connect.example.com/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile%20more' client// 'https://connect.example.com/signin?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile%20more' client// 'https://connect.example.com/connect/google?response_type=code%20id_token%20token&client_id=CLIENT_ID&redirect_uri=OTHER_REDIRECT_URI&scope=openid%20profile%20extra'
client.authorizationParams(options)
Accepts an options object and returns an object containing authorization params
including default values. Depends on client_id
being configured.
Note: This is a low-level function used by authorizationUri()
,
documented to list its parameters (which are passed through to
authorizationParams()
). It's unlikely that your code will be invoking it
directly.
options
response_type
– defaults tocode
redirect_uri
– defaults to theredirect_uri
configured for this clientscope
– defaults to the scope configured for this clientstate
response_mode
nonce
display
prompt
max_age
ui_locales
id_token_hint
login_hint
acr_values
email
password
provider
client.token(options)
Given an authorization code is provided as the code
option, this method will
exchange the auth code for a set of token credentials, then verify the
signatures and decode the payloads. Depends on client_id
and client_secret
being configured, and prior calls to client.discover()
and client.getJWKs()
.
options
code
– value obtained from a successful authorization request withcode
in theresponse_types
request param
example
client
client.refresh(options)
Given an refresh_token is provided as the refresh_token
option, this method
will exchange the refresh_token for a set of token credentials, then verify the
signatures. Depends on client_id
and client_secret
being configured, and
prior calls to client.discover()
and client.getJWKs()
.
options
refresh_token
– value obtained from a successful authorization request withtoken
in theresponse_types
request param
example
client
client.userInfo(options)
Get user info from the issuer.
options
token
– access token
example
client
client.verify(token, options)
Anvil Connect Admin API
Anvil Connect provides a backend admin-only API (outside of the OIDC specs), for managing clients, users and so on.
Note: All of these operations require an access token passed in options.token
.
You can get this token either via an admin user (with an authority
role
assigned to them) login, OR via a Client Credentials Grant request
(see client.getClientAccessToken()
docs in ../index.js
).
Example Usage:
client.getClientAccessToken()
.then(function (accessToken) {
var options = { token: accessToken }
// Once you have the access token you can
// call client.users.update(), create(), delete(), etc
return client.users.create(userData, options)
})
Clients
client.clients.list()
client.clients.get(id)
client.clients.create(data)
client.clients.update(id, data)
client.clients.delete(id)
Roles
client.roles.list()
client.roles.get(id)
client.roles.create(data)
client.roles.update(id, data)
client.roles.delete(id)
Scopes
client.scopes.list()
client.scopes.get(id)
client.scopes.create(data)
client.scopes.update(id, data)
client.scopes.delete(id)
Users
client.users.list()
client.users.get(id)
client.users.create(data)
client.users.update(id, data)
client.users.delete(id)
Example
var AnvilConnectClient = ; // Assumes a preregistered client (if not, call register() after initProvider())var client = issuer: 'https://connect.example.com' client_id: 'CLIENT_ID' client_secret: 'CLIENT_SECRET' redirect_uri: 'REDIRECT_URI' // Initialize the provider config (endpoints and public keys)client