anvil-connect-nodejs

Anvil Connect JavaScript client for Node.js

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
anvil-connect-nodejs
1750.4.36 years ago8 years agoMinified + gzip package size for anvil-connect-nodejs in KB

Readme

Anvil Connect client for Node.js
NPM Version Build Status
Anvil Connectconnect is a modern authorization server built to authenticate your users and protect your APIs. It's based on OAuth 2.0oauth2 and OpenID Connectoidc.
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 libraryconnect-express.

Install

$ npm install anvil-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 AnvilConnect(config)

var AnvilConnectClient = require('anvil-connect-nodejs');

// If the client has been pre-registered, pass the credentials to constructor
var client = new AnvilConnectClient({
  issuer: 'https://connect.example.com',
  client_id: 'CLIENT_ID',
  client_secret: 'CLIENT_SECRET',
  redirect_uri: 'REDIRECT_URI',
  scope: 'realm'
})
client.initProvider()
  .then(function () {
    // Ready to verify() tokens, refresh(), etc
  })

// If the client has not been registered, use OIDC dynamic registration
var client = new AnvilConnectClient({ issuer: 'https://connect.example.com' })
client.initProvider()
  .then(function () {
    // Provider config loaded (.discover() and .getJWKs() called)
    
    // Ready to register()
    return client.register({
      // ... see below for registration options
    })
  })
  .then(function () {
    // Client is now registered. Ready to verify() tokens, refresh(), etc
  })
  .catch(function (err) {
    // as always, don't forget error handling
  })

options
  • issuer – REQUIRED uri of your OpenID Connect provider
  • client_id – OPTIONAL client identifier issued by OIDC provider during
registration
  • client_secret – OPTIONAL confidential value issued by OIDC provider during
registration
  • redirect_uri – OPTIONAL uri users will be redirected back to after
authenticating with the issuer
  • scope – OPTIONAL array of strings, or space delimited string value
containing scopes to be included in authorization requests. Defaults to openid profile

OpenID Connect

client.discover()

Returns a promise providing OpenID Metadataoidc-meta retrieved from the .well-known/openid-configuration endpoint for the configured issuer. Sets the response data as client.configuration.
example
client.discover()
  .then(function (openidMetadata) {
    // client.configuration === openidMetadata
  })
  .catch(function (error) {
    // ...
  })

client.getJWKs()

Returns a promise providing the JWK set published by the configured issuer. Depends on a prior call to client.discover().
example
client.getJWKs()
  .then(function (jwks) {
    // client.jwks === jwks
  })
  .catch(function (error) {
    // ...
  })

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 Connectdynamic-registration 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.register(options)
  .then(function (data) {
    // After the register request resolves
    // client.client_id and .client_secret are initialized
    // and the rest of the returned data is set to client.registration
  })

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 to authorize.

example
client.authorizationUri()
// 'https://connect.example.com/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile%20more'

client.authorizationUri('signin')
// 'https://connect.example.com/signin?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile%20more'

client.authorizationUri({
  endpoint: 'connect/google',
  response_type: 'code id_token token',
  redirect_uri: 'OTHER_REDIRECT_URI',
  scope: 'openid profile extra'
})
// '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 to code
  • redirect_uri – defaults to the redirect_uri configured for this client
  • scope – defaults to the scope configured for this client
  • state
  • 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 with code
in the `response_types` request param
example
client.token({ code: 'AUTHORIZATION_CODE' })

client.refresh(options)

Given an refreshtoken is provided as the refresh_token option, this method will exchange the refreshtoken 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 with
token in the response_types request param
example
client.refresh({ refresh_token: 'REFRESH_TOKEN' })

client.userInfo(options)

Get user info from the issuer.
options
  • token – access token

example
client.userInfo({ token: 'ACCESS_TOKEN' })

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 = require('anvil-connect-nodejs');

// Assumes a preregistered client (if not, call register() after initProvider())
var client = new AnvilConnectClient({
  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.initProvider()
  .then(function () {
    // At this point, provider config and public keys are loaded and cached
    console.log(client.configuration)
    console.log(jwks)
    
    // Now, build an authorization url
    return client.authorizationUri()
  })
  .then(function (url) {
    console.log(url)

    // handle an authorization response
    // this verifies the signatures on tokens received from the authorization server
    return client.token({ code: 'AUTHORIZATION_CODE' })
  })
  .then(function (tokens) {
    // a successful call to tokens() gives us id_token, access_token, 
    // refresh_token, expiration, and the decoded payloads of the JWTs
    console.log(tokens)

    // get userinfo
    return client.userInfo({ token: tokens.access_token })
  })
  .then(function (userInfo) {
    console.log(userInfo)

    // verify an access token received by an API service
    return client.verify(JWT, { scope: 'research' })
  })