Configure Domino Rest API IdP
About this task
Domino REST API implements an OAuth2 provider. The following is a guide for setting up and configuring Domino REST API's OAuth2 provider.
Before you begin
The oauth.nsf
database exists in your Domino data directory. The Domino IdP uses the oauth.nsf
to store content and refresh information.
Note
- If you are using Domino+Domino REST API docker image, the
oauth.nsf
should already be in the image but may not be fully configured. - If for some reason you need to create the
oauth.nsf
, see Set up oauth.nsf, and save it in your Domino data directory.
Client Ids
When configuring an external IdP using OIDC or OIDC-idpcat, you need to provide a clientId. It's recommended to use Domino
, but the admins of your IdP might have other ideas. In any case, that's the clientId for the REST server. It's NOT the one for the AdminUI or the Office Forms Based Authentication (OFBA) for attachment editing. To be fully operational, you need to configure at least three clients on your IdP:
Domino
for the server (client secret might be handeled byidpcat.nsf
)keepadminui
for the Domino REST API admin clientkeepofba
for the Office document round trip experience- One each for your custom client applications (with clientSecret for servers or PKSE for clients)
Use the internal IdP as learning resource
The application configuration provided by the internal IdP makes it easy to configure and retrieve client-specific JWT that have all the required fields. Test your application with that and use the defined proprties, scopes foremost, to requests the external IdP client configurations.
Procedure
-
Configure Domino REST API to access the
oauth.nsf
.- Create an
oauth.json
file using a text editor. -
Copy the following JSON object to the JSON file.
{ "oauth": { "active": true, "database": "oauth.nsf", "url": "https://sample.keep.io:8880", "authCodeExpiresIn": 120, "accessTokenExpiresIn": 3600, "refreshTokenExpiresIn": 525600 } }
For more information, see the following table:
Property Description active
Required
It has a boolean value indicating if the provided token is now active. If the token is issued by this authorization server, it isn't revoked by the user, and it's not yet expired, the value should betrue
.database
The nsf
file where the authorization details are stored.url
Server URL authCodeExpiresIn
The code expiration time in seconds. accessTokenExpiresIn
The access token expiration time in seconds. refreshTokenExpiresIn
The refresh token expiration time in seconds. -
Change the value of the
url
parameter to match your Domino REST API host.The indicated
url
value in the JSON object above is just an example value. -
(Optional) Adjust the expiration time values as needed.
-
Save the JSON file in the
keepconfig.d
directory located in your Domino data directory.You need to create the
keepconfig.d
directory if not yet existing. -
Restart Domino REST API.
- Create an
-
Add the
OAuthAdmin
role for the ACL entry.Be sure to thoroughly examine the ACL.
- By default, the configured access level is
Author
with the capability to create information but unable to remove it. - All servers involved must have at least an
Editor
access level and theOAuthAdmin
role assigned. If you DON'T have this role, you'll only see your documents or records. -
Administrators requiring troubleshooting capabilities should have
Editor
access level and theOAuthAdmin
role assigned. - Ensure the database is copied to all servers involved.
- By default, the configured access level is