Client Library

If you have a Node.js application which wants to access Domino resources with OAuth authorization securely, you can use node-iam-client library to handle your application's OAuth 2.0 flow. The library helps your application to interact with IAM server.

Installation

To use IAM Client library, install node-iam-client library as a npm dependency of your Node.js application.

Let's assume you are developing a Node.js client application. The package.json file of the client application is in /my-client-application folder.

Then you can use the following command to install node-iam-client from the downloaded package: domino-node-iam-client-2.2.5.tgz

cd /my-client-application
npm install /path/to/domino-node-iam-client-2.2.5.tgz --save

Run Examples

IAM client library includes several examples to demonstrate the usage. Uncompress domino-node-iam-client-2.2.5.tgz, then you can find all the examples under the examples sub-folder.

To run the examples, see Run examples

OAuth 2.0 Authorization Code Flow

If your Node.js application wants to access Domino resources on behalf of user. It is appropriate to use the OAuth 2.0 Authorization code flow.

For example, a typical use case is: your application wants to use OAuth 2.0 to obtain user's permission to access user's calendar data with Domino Calendar API.

Let's describe a typical OAuth 2.0 authorization code flow in short.

Your application wants to access Domino Calendar API on behalf of user, so it redirects user to a login page in IAM to obtain the user's consent. User log in with his credential in IAM and decides whether to proceed or not. With user's consent, IAM will redirect the user back to a callback url of your application with a set of "Tokens". Then, your application can use the access_token in the token set to access Domino Calendar API.

Let's see how Client application library helps your application to interact with IAM server in this scenario.

Obtain OAuth2 Access Tokens

Step 0: Register client application

Before you start implementing OAuth flow, Use IAM Admin Server to register a client.

To use OAuth 2.0 authorization code flow, the Node.js application must be registered as Server-Side Application in IAM Admin Server, which means your application must have the ability to keep information private. e.g. The client secret.

copy the client_id and client_secret from the registration result page.

Step 1: Create IAM client

Your first step should be create a IAMClient instance with the information you got from Step 0 section.

The following metadata should be provided to initiate an client instance.

The createInstance API accepts an options object. The options object can have the following fields:

Field	Description
iam_server	[required]The IAM server url
client_id	[required]The client ID of the client application
client_secret	[required]The client secret of the client application
redirect_uri	[required]The callback uri in client application. IAM server redirects user back to redirect_uri in client application.
httpOptions	[optional]The additional http options used by IAM

clientOption example:

  const clientOptions = {
    iam_server: 'https://iamserver.com',
    client_id: '6a609abd-53e9-4777-ad46-c882e3324820',
    client_secret: 'R/kJYb2ByzXbztHu4+9qSCW2n/JPw5qb8XTzw0THVEjSPECbjQFkAKbJ/pILxxLB',
    redirect_uri: 'https://myclient.com/cb',
    httpOptions: {
      // for a list of available httpOptions, please refer to:
      // https://nodejs.org/api/http.html#http_http_request_url_options_callback
      timeout: 50000,
    }
  };

  const iamClient = await IAMClient.createInstance(clientOptions);

Step 2: Redirect to IAM server

Client application should redirect the user to IAM server to obtain user's consent to access user's data. In this step, client application calls createAuthorizationCtx API to get the redirection url.

The createAuthorizationCtx API accepts an options object. The options object can have the following fields:

Field	Description
scopes	[required]Array of scopes.
grantType	OAuth2 grant types: AUTHORIZATION_CODE

  const options = {
    scopes: ['openid','offline_access','das.calendar.read.with.shared','das.freebusy'],
    grantType: GRANT_TYPES.AUTHORIZATION_CODE,
  };

  // get IAM authentication url and redirect to it.
  const { authorizationUrl, secureCtx } = iamClient.createAuthorizationCtx(options);

The result of createAuthorizationCtx contains a secureCtx object and the authorization Url.

• Authorization Url is a Url in IAM server where user can go to authenticate and give his consent to the requested scopes.
• SecureCtx object contains some security nonce to prevent CSRF attack and replay attach. Save the secureCtx in your server (e.g. user session) for later validation.

Then your client application can redirect the user to the authorization Url you got from the previous step.

Step 3: IAM prompts user for consent

In this step, IAM server displays a consent page to the user to let him decide whether to proceed or not. Then IAM server will redirect the user to the redirect_uri, which is a callback in your Client application to handle IAM response.

Step 4: Handle IAM response in callback and obtain Access token

In client registration process, we registered a redirect_uri. This is the callback which handles IAM response from consent page.

If user denials access in step 3, the callback will receive a error response and should handle it accordingly.

If user decides to proceed in step 3, we can extract access token (and other tokens) from IAM response.

The getToken API accepts an options object. The options object can have the following fields:

Field	Description
request	[required]The koa/express/node request object or a url string
secureCtx	[required]The secureCtx object

  // get IDToken, refreshTokan, and AccessToken
  const tokenSet = await iamClient.getToken(ctx.request, secureCtx);

The tokenSet contains all the tokens got from IAM server.

An Example tokenSet result:

{
  access_token:"uIjlc1syV0VwqAjnFIai2iOTQYdeKpU3ESIVrEccwAO"
  id_token:"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZC..."
  refresh_token:"UczNEBSVuDD6Sr4Mo2JDH5pvzIY"
  scope:"openid offline_access das.calendar.read.with.shared das.freebusy"
  token_type:"Bearer"
}

Request Data with Access token

To access domino data, the client application should send the access_token in the Authorization request header when access Domino data APIs.

Authorization: Bearer { access token value}

Example:

Authorization: Bearer kJYb2ByzXbztHu4+9qSCW2n/JPw5qb8XTzw0THVEjSPECbjQ

Refresh Access token

If client application requests for offline_access scope, a refresh token will be sent back along with access token.

Client application can use the refresh token to obtain a new access token without prompt to the user. Typically client application refreshes token set when access token is expired.

Field	Description
token	[required]refresh token

 const newTokenSet = await this.iamClient.refreshToken(tokenSet.refresh_token);

The refreshToken API returns a new token set including a new access token. Note that the new token set also contains a new refresh token, the original refresh token will be obsoleted.

The refreshToken API may throw an error if the refresh token itself is expired. In this case, the client application should obtain new tokenset with user consent. See Obtain OAuth2 Access Tokens section.

Token introspection

The introspection APIs return detail information about a token.

Introspect access token:

Field	Description
token	[required]access token

  const introspectionResponse = await iamClient.introspectAccessToken(tokenSet.access_token);

Introspection Result example:

{
  "active" : true,
  "sub" : "cn=Test User",
  "client_id" :"05e4279a-30ad-4d90-960c-4ad6cb46d2a1",
  "exp" : 1541559370,
  "iat" : 1541555770,
  "sid" : "38882033-7d70-4370-957f-5fb6a7e076e9",
  "iss" : "https://iam.com:3000",
  "jti" : "LbS6bQYxcVrf~_ihknkMXsnMvctRdvuvA724qppVBn2",
  "scope" : "openid offline_access das.calendar.read.with.shared das.freebusy",
  "notes_dn" : "cn=Test User",
  "email" : "testuser@iam.com"
}

Introspect refresh token:

Field	Description
token	[required]refresh token

  const introspectionResponse = await iamClient.introspectRefreshToken(tokenSet.refresh_token);

OAuth 2.0 Client Credential Flow

If your Node.js application want to access Domino resources on behalf of application itself, it is appropriate to use the client credential flow.

The client credential flow is relatively simple. Node.js application asks for an access token from IAM server with its client ID and client secret. Then it can use the access token to access Domino resource on behalf of the application itself.

NOTE: Client credential flow is not an appropriate way to acquire an access token to be used with domino-db and Proton. If it's configured correctly, Proton already uses a client certificate to authenticate your application. Therefore, if you want to make a domino-db request on behalf of the application itself, you should simply omit the accessToken property from the request.

Let's see how client libraries work in this scenario.

Obtain Access token for client credential flow

Step 0: Register client application for client credential flow

For client credential flow, your client application should also be registered as Server-Side application in IAM Admin server.

Step 1: Create IAM client for client credential flow

Use createInstance API to create an IAM client.

Example:

  const clientOptions = {
    iam_server: 'https://iamserver.com',
    client_id: '6a609abd-53e9-4777-ad46-c882e3324820',
    client_secret: 'R/kJYb2ByzXbztHu4+9qSCW2n/JPw5qb8XTzw0THVEjSPECbjQFkAKbJ/pILxxLB',
  };

Obtain Access Token

Field	Description
scopes	[required]Array of scopes.

 const clientTokenSet = await iamClient.getClientToken(scopes);

Request Data with Access Token

To access domino data, the client application should send the access_token in the Authorization request header when access Domino data APIs.

Authorization: Bearer { access token value}