Domino Service Accounts provide a managed and secure way to access the Domino API from outside of the Domino cluster. Domino Service Accounts provide stable, token-based authentication for API calls without compromising the accounts of individual Domino users and the assets they have access to. Service Accounts are especially useful when calling the Domino API as part of an automation pipeline.
Domino Service Accounts are a special type of Domino user. They don’t represent a human being behind a browser, but rather a "technical user", "service account", or "automation principal" — all these terms describe a digital identity used by software programs to communicate with other software.
-
Each Service Account can have one or more long-lived tokens associated with it which are used to authenticate calls to the Domino API. Each token has its own independent lifespan but points to the same Service Account, for which it was created. Each token created for the same Service Account gives the token bearer access to the same Projects.
-
Only Service Accounts can have long-lived credentials for calling Domino APIs. Regular Domino users are not allowed to have long-lived tokens.
-
Service Accounts are not allowed to utilize the web interface, Domino, or Domino CLI.
-
Service Accounts are managed by Domino Administrators and are not accessible to regular Domino users. Admins create and archive the Service Accounts, as well as generate and manage their tokens. If compromised, each token can be invalidated individually, or the whole service account can be deactivated, effectively prohibiting any access using its tokens.
-
Service Accounts can be invited to collaborate on a Project, just like a regular user. This gives the Service Account access to code and data in that particular Project.
Domino Service Accounts can only be managed with the Domino APIs. The calling user must have an Administrator role.
Note
|
The easiest way for an Administrator to communicate with Domino via API is to start a Workspace (e.g. Jupyter) in Domino, start a Terminal inside the Workspace, and take advantage of the API Proxy, which will automatically authenticate the calls to Domino APIs. The following examples assume that they are executed from inside a Workspace and use the API Proxy. To make these calls from outside of Domino, authenticate as described by the documentation for Domino API. |
To create a Service Account, the Administrator makes a call to the /v4/serviceAccounts
endpoint, supplying the desired username for the Service Account and a valid email address. Domino Service Accounts, just like regular Domino users, need a valid and unique email address. Domino uses this email address to send notifications, inform about failed jobs, and for other purposes.
$ curl -X POST -H 'Content-Type: application/json'
-d '{"username": "demo-sa", "email": "demo-sa@customer.com"}'
$DOMINO_API_PROXY/v4/serviceAccounts
Result:
{
"email": "demo-sa@customer.com",
"id": "65cd5ca022e1a963208d7a6d",
"idpId": "ca72dc97-504b-4b3c-98d6-3a306b30bd24",
"userName": "demo-sa"
}
Save the value of the "idpId" property in the IDPID environment variable for future use.
Create multiple Service Accounts emails with "plus addressing"
To manage multiple unique email addresses, you can use "plus addressing" or "subaddressing" to create multiple email addresses for your Service Accounts without requiring you to create new email accounts.
Many email services, like Gmail, Google Workspace, Microsoft Exchange Online, and others support "plus addressing" (or "subaddressing") — an industry-defined way to support dynamic recipient email addresses.
For example, if you have an email like riley@gmail.com
, you can create a Service Account for an Apache Airflow pipeline with the email address riley+airflow@gmail.com
. Domino will send all activity related to the Apache Airflow Service Account to the riley@gmail.com
inbox tagged with the tag airflow
. This way, a single user can manage multiple service accounts from one inbox.
Check with your enterprise email provider to see if subaddressing is supported at your company.
Admins can list all the existing Service Accounts in Domino.
$ curl $DOMINO_API_PROXY/v4/serviceAccounts
Result:
[
{
"email" : "demo-sa@customer.com",
"id" : "65cd5ca022e1a963208d7a6d",
"idpId" : "ca72dc97-504b-4b3c-98d6-3a306b30bd24",
"username" : "demo-sa"
}
]
Admins can create a token for a Service Account using the Service Accounts idpId
.
Each token has a default lifespan of 4 months, which is listed in the response above.
The value of the token
property can be copied and used to authenticate the calls to Domino APIs. The caller will be recognized as the Service Account to which this token belongs. Let’s save the value to the SA_TOKEN
environment variable for the next example.
In this example, IDPID
is an environment variable that contains the idpId of the Service Account.
$ curl -X POST -H 'Content-Type: application/json'
-d '{"name": "token-for-circleci"}'
$DOMINO_API_PROXY/v4/serviceAccounts/$IDPID/tokens
Result:
{
"createdAt" : "2024-02-15T00:39:35.521Z",
"expiresAt" : "2024-06-14T00:39:35.513201660Z",
"isValid" : true,
"name" : "token-for-circleci",
"serviceAccountIdpId" : "ca72dc97-504b-4b3c-98d6-3a306b30bd24",
"token" : "eyJhbGciOiJSUzI1N... redacted for brevity ...kNY_DlWXl8WJPvjTJsPeddd40u9dUhDp-FDg"
}
The following example starts a Domino Job using the token
value from the previous "Create a token" step.
$ curl -H "Authorization: Bearer $SA_TOKEN"
--header 'Content-Type: application/json'
--data '{ "projectId": "12398gg098", "runCommand": "main.py"}'
$DOMINO_API_HOST/api/jobs/v1/jobs
Note
| This call goes to $DOMINO_API_HOST, which does not automatically add authentication. |
List all existing tokens for a Service Account. The "List tokens" response contains the expiration dates of all the tokens. Monitoring this and taking proactive steps helps avoid service interruptions when using the tokens.
$ curl -s $DOMINO_API_PROXY/v4/serviceAccounts/$IDPID/tokens
Result:
[
{
"createdAt" : "2024-02-15T00:39:35.521Z",
"expiresAt" : "2024-06-14T00:39:35.513Z",
"isValid" : true,
"name" : "token-for-circleci",
"serviceAccountIdpId" : "ca72dc97-504b-4b3c-98d6-3a306b30bd24"
}
]
If a token is compromised or is no longer needed, it can be invalidated. This won’t affect other tokens belonging to this or any other Service Account.
$ curl -H 'Accept: application/json' -X POST
$DOMINO_API_PROXY/v4/serviceAccounts/$IDPID/tokens/token-for-circleci/invalidate
If the whole Service Account is no longer necessary, it can be deactivated, making all its tokens invalid.
$ curl -X POST -H 'Content-Type: application/json'
$DOMINO_API_PROXY/v4/serviceAccounts/$IDPID/deactivate
-
To lower the risk of exposing sensitive Project data and code, Domino recommends minimizing the number of Projects on which a single Service Account collaborates.
-
To help the Administrators map Service Accounts to Projects, the username can be crafted to reflect the relationship between the Service Account and the Project.
-
Domino recommends that you use one token for a single purpose (for example, in a single automation pipeline). It’s helpful if the token name reflects where it’s being used. This way, if a token needs to be replaced, it could be done without affecting many scripts or automation pipelines.
-
The "List tokens" API response contains the expiration dates of all the tokens. Monitoring this and taking proactive steps helps avoid service interruptions when using the tokens.
Explore the Domino REST API reference.
See other methods users can authenticate against the Domino API.