Quarks IAM client for Node.js

[Quarks IAM] 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 Quarks IAM 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 @quarks/quarks-iam-nodejs-client --save

Configure

Before performing any other operations (such as verifying or refreshing OIDC tokens, or accessing the QuarksIAM-specific API (such as creating users), an OIDC client needs to be configured and registered with the server (OIDC Provider, OP for short).

new QuarksIAM(config)

var QuarksIAMClient = require('@quarks/quarks-iam-nodejs-client');

// If the client has been pre-registered, pass the credentials to constructor
var client = new QuarksIAMClient({
  issuer: 'https://iam.quarks-ecosystem.io',
  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 QuarksIAMClient({ issuer: 'https://iam.quarks-ecosystem.io' })
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 Metadata 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 Quarks IAM][dynamic-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://iam.quarks-ecosystem.io/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile%20more'

client.authorizationUri('signin')
// 'https://iam.quarks-ecosystem.io/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://iam.quarks-ecosystem.io/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 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 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)

Quarks IAM Admin API

Quarks IAM 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 QuarksIAMClient = require('@quarks/quarks-iam-nodejs-client');

// Assumes a preregistered client (if not, call register() after initProvider())
var client = new QuarksIAMClient({
  issuer: 'https://iam.quarks-ecosystem.io',
  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' })
  })