Tutorial

# Setup DOAP (Domino OAuth2 Provider) into your IBM Domino server

Edition

* 2018-06-29 - Kazunori Tatsuki; Translated readme.md in English.
* 2018-06-02 - Takahide Kondoh; Wrote about "Client request", "Access to Domino resource". Updated entire content. Added "Register license file".
* 2018-06-01 - Takahide Kondoh; Created README

## How to install

* Enabling Domino HTTPS is highly recommended.

  1.  Stop Domino server and install DOAP from the installer. After installation is completed, start Domino server.
    * DOAP 32-bit and 64-bit for Windows are availabe. Please choose the appropriate version according to Domino architecture.
  2. Create DOAP application (nsf) from the doap.ntf which is installed into the notes data folder.
    * Please set ACL for DOAP application accordingly.
  3. Create notes license document and attach license file.
  4. Create Private key, Public key for use in token generation.* Details on how to create private and public key are described at the bottom of this readme file.
  5. Create two “RSA Key” documents, then attach key file (PEM format) issued in the previous step.* In the private key documents, specify “private” in the “Key Type” field.
    * In the public key document, specify “public” in “Key Type” field.
  6. Insert a new line in notes.ini of the Domino server as described below:
    (i.e.) if the DOAP application is created as “doap.nsf” in step 2, then specify the following:
    DOAP_App_Path=doap.nsf
  7. Add “ndoap” into “DSAPI filter file names” field in the Domino Server document under “Internet Protocols – HTTP” tab. If you use Internet Site Document, follow the same steps to add the DSAPI information.
    * Allow at least GET, POST HTTP method.
  8. Restart HTTP task of the Domino server.

## Register the Client (Web site) which uses DOAP (OAuth2)

In OAuth2 environment, a “client” refers to a web service/web site that wants to use OAuth2 authorization, whereas the “Resource Owner” is describing the end-user.

Firstly, you need to register the “client” that wants to use OAuth2. In DOAP, you can manage multiple clients by creating “OAuth Client” documents.

Create “OAuth Client” document, then fill in the fields below:

  • Client Name: Any name of your Web site.
  • Callback URL: full path of the callback URL that the Web site receives. 
    i.e.) http://localhost:3000/authorize
  • Client ID: Unique authentication ID of the client, used when issuing token.
  • Client Secret: Authentication password used when issuing token.
  • Scope to allow: Range of actions accepted by DOAP (So far only “domino”)

## Client request

To connect to Domino via DOAP, observe that your “client” conforms to the following rules:

  • DOAP conforms to RFC6749 (The OAuth 2.0 Authorization Framework). (https://tools.ietf.org/html/rfc6749)
  • Currently, only authorization cod is available as authorization grants. (https://tools.ietf.org/html/rfc6749#section-1.3)
  • During the client authentication process, HTTP basic authentication is under the control of the Domino server and cannot be used. The client credential (client ID and client secret) must be included in the request body. (https://tools.ietf.org/html/rfc6749#section-2.3.1)

## DOAP OAuth2 specification

### Request for authorization code

URL format:

http(s)://(domino_host)/doap/auth?response_type=code&client_id=(Client ID)&scope=domino&state=xyz
  • Method: GET
  • response_type: (Required) Always specify “code”.
  • client_id: (Required) Client ID which has been registered in “OAuth Client” document inside DOAP application.
  • scope: (Required) (Currently) Always specify “domino”
  • state: (Optional) Random number prepared by Web site. It is recommended to set it as CSRF countermeasure, DOAP operates without it.
  • Response
    If End-User(Resource Owner) succeeded to login (authorized to use OAuth), then authorization code is returned to the callback URL specified in “OAuth Client” document. (return “state” if provided).
i.e.) http://localhost:3000/authorize?code=pQun7G5・・・・・Rsx&state=xyz

### Request of Access Token

URL format:

http(s)://(domino_host)/doap/token

Request Body:

grant_type=authorization_code&code=pQun7G5・・・・・Rsx&client_id=(Client ID)&client_secret=(Client Secret)
  • Method: POST
  • grant_type: (Required) Always specify “authorization_code”
  • code: (Required) authorization code value you got from request of authorization code in previous step
  • client_id: (Required) Client ID which is specified in “OAuth Client” document of DOAP application.
  • client_secret: (Required) Client Secret which is specified in “OAuth Client” document of DOAP application.
  • Response
    When the authorization code is found to be valid and within the due date, the access token is issued and added as JSON format.

* Example of response

{ "access_token":"qWeRtYuI・・・・・NbVcXz",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"PoIuYtRe・・・・・CvBnM" }
  • access_token: Access Token
  • token_type: bearer
  • expires_in: Number of expiration (seconds)
  • refresh_token: Refresh Token

### Update request of Access token

URL format:

http(s)://(domino_host)/doap/token

Request Body:

grant_type=refresh_token&refresh_token=PoIuYtRe・・・・・CvBnM&client_id=(Client ID)&client_secret=(Client Secret)
  • Method: POST
  • grant_type: (Required) Always specify “refresh_token”
  • refresh_token: (Required) value of refresh Token
  • client_id: (Required) Client ID which is specified in “OAuth Client” document of DOAP application.
  • client_secret: (Required) Client Secret which is specified in “OAuth Client” document of DOAP application.
  • Response
    When refresh token is found to be valid and within the due date, a new access token is issued and added in the JSON format. Response contents are the same as when access token is requested.

### Access to Domino resources

To access Domino resources through OAuth2, use the Bearer token type. Since it does not affect URI and request body, it can access any resources.

For example, if you want to retrieve all the documents in database.nsf using Domino Access Services, send the following HTTP request:

> GET /database.nsf/api/data/documents
> Host: domino1.example.com
> Authorization: Bearer pOiUyTrE...

Following “Bearer” is the access token.

#### When DOAP returns 401 (Unauthorized)

When authentication expires, DOAP returns 401. In this case, please request “update token of access token” with refresh token.

## Appendix

### OpenSSL for Windows

OpenSSL is mostly standard on UNIX (Linux, Mac OSX), but not on Windows. Only source code can be downloaded on the original site. There is no compilation trouble, the binary installer is recommended.

### Issue secret key, public key in OpenSSL

  • Command to create a secret key as private-key.pem with 2048 bits 
    > openssl genrsa 2048 > private-key.pem
  • Command to create a public key as public-key.pem from this secret key 
    > openssl rsa -in private-key.pem -pubout -out public-key.pem

### Other option from OpenSSL for Windows

Sometimes tools for generating keys may be attached to secure communication with the Linux tool package for Windows, terminal application (Tera Term), Git application, etc. Any tools can be used as long as the key can be created (or converted) into PEM format with an RSA key of 2048 bit or more.