Configuring Service Accounts and User Tokens - Nexus Repository Cloud

Configuring Service Accounts and User Tokens - Nexus Repository Cloud

This page describes the recommended process for creating and managing user tokens for service accounts on Nexus Repository Cloud.

Internal and External Role Management

The Nexus Repository Cloud user role management API manages Nexus-internal role mappings only.

The API can return external roles for visibility, but external roles are read-only and must be managed through the identity provider.

Prerequisites

Step 1: Add a User for the Service Account

Service accounts on Nexus Repository Cloud are provisioned by inviting a user through the Nexus Repository Cloud UI or the invite user API.

Add a User via the UI

  1. In Nexus Repository Cloud, navigate to Settings → Security → Users.
  2. Select Invite Users.
  3. Enter the service account email address and name.
  4. Click Invite User. A confirmation email is sent to the service account email address.

Add a User via the API

For API-based provisioning in Nexus Repository Cloud, use the invite user API. This sends an invitation email to the service account email address.

curl -u <admin-user>:<admin-password-or-token> -X POST \
  -H 'Content-Type: application/json' \
  'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/invite' \
  -d '{ "firstName": "Service", "lastName": "Account", "email": "svc-nexus-ci@example.com" }'

The API caller must have the nexus:users:create permission.

Example response:

{ "firstName": "Service", "lastName": "Account", "email": "svc-nexus-ci@example.com" }

External Users

If the service account is managed through an external identity provider, create the account in the identity provider first. Then ensure the user is available to Nexus Repository Cloud before assigning Nexus-internal roles.

Step 2: Initial Login and 2FA Enrollment

A human must complete this step on behalf of the service account:

  1. Access the invitation email and follow the link to verify the email address.
  2. Enter a password for the service account.
  3. Complete 2FA enrollment using the required authenticator for your organization.
  4. Log in to the Nexus Repository Cloud tenant at least once to confirm the account is active.

2FA Recovery Planning

Before using a service account in automation, document how your team will recover access if the person who enrolled 2FA is unavailable. Follow your organization's credential management policy.

Step 3: Assign the Appropriate Role

Before generating and using a service account token, ensure the service account has the correct Nexus-internal roles for its intended purpose. Apply the principle of least privilege.

For service accounts used in repository automation, assign only the repository permissions required by the automation. For example, a read-only automation account may need repository browse and read privileges, while a publishing account may also need add or edit privileges for the target repositories.

Assign a Role via the UI

  1. In Nexus Repository Cloud, navigate to Settings → Security → Users.
  2. Search for and select the service account user.
  3. Update the user's assigned roles.
  4. Save the user.

See Roles for more information.

Role Assignments

In Nexus Repository Cloud, users authenticate through Auth0. You can assign Nexus-internal roles to users from the Users view.

External group-based access is managed through your identity provider and the configured role mappings.

Assign a Role via the API

For automation or bulk provisioning, use the Nexus Repository Cloud user role management API. See Security Management API for the complete API reference.

To review the user's current Nexus-internal and external roles:

curl -u <admin-user>:<admin-password-or-token> -X GET \
 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/svc-nexus-ci%40example.com/roles'

To replace the user's complete set of Nexus-internal roles:

curl -u <admin-user>:<admin-password-or-token> -X PUT \
 -H 'Content-Type: application/json' \
 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/svc-nexus-ci%40example.com/roles' \
 -d '{ "roles": ["nx-repository-view-*-*-browse", "nx-repository-view-*-*-read"] }'

To add roles without replacing existing Nexus-internal role assignments:

curl -u <admin-user>:<admin-password-or-token> -X PUT \
 -H 'Content-Type: application/json' \
 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/svc-nexus-ci%40example.com/roles/add' \
 -d '{ "roles": ["nx-repository-view-*-*-add"] }'

To remove roles without replacing existing Nexus-internal role assignments:

curl -u <admin-user>:<admin-password-or-token> -X PUT \
 -H 'Content-Type: application/json' \
 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/svc-nexus-ci%40example.com/roles/remove' \
 -d '{ "roles": ["nx-admin"] }'

URL Encode User IDs

If the userId contains special characters, such as @ in an email address, URL encode the value before sending the request. For example, use svc-nexus-ci%40example.com for `svc-nexus-ci@example.com.

Replacement Behavior

PUT /v1/security/users/{userId}/roles replaces the user's complete Nexus-internal role set. Use PUT /v1/security/users/{userId}/roles/add or PUT /v1/security/users/{userId}/roles/remove when you want to preserve existing Nexus-internal role assignments.

Step 4: Generate a User Token

Once the service account has logged in and has the appropriate role assignments, generate a user token for use in automation.

User Token Expiration

For improved security, enable user token expiration if it is not already enabled. User token expiration applies to existing and newly generated tokens. See User Tokens for configuration details.

Generate User Token via the UI
Nexus One UI Classic UI
  1. Log in to Nexus Repository Cloud as the service account user.
  2. Select the profile icon at the top right.
  3. Select User Token.
  4. Select the Generate Token button (if you’re using the Classic UI, select the Access User Token button instead).
  5. Save the token credentials immediately and store them securely.

Generate User Token via the API

Use the Nexus Repository user token API to generate a token programmatically after the service account has completed initial login and 2FA enrollment.

curl -u svc-nexus-ci@example.com:<service-account-password> -X POST \
 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/user-tokens/current'

Token Storage

Store generated token credentials in an approved secrets manager. Do not commit service account passwords or generated token credentials to source control.

Step 5: Use the Token for Repository Automation

Use the generated user token credentials in build tools, package managers, CI/CD jobs, or scripts that need to authenticate to Nexus Repository Cloud.

Example API call using token credentials:

curl -u <user-token-code>:<user-token-passcode> \
 'https://<your-nexus-repository-cloud-url>/service/rest/v1/status'

Confirm that the service account can perform only the actions required by its automation.

Step 6: Verify and Maintain Role Assignments

After the service account is configured, periodically verify that the assigned roles still match the automation requirements.

Verify Roles via the UI

  1. In Nexus Repository Cloud, navigate to Settings → Security → Users.
  2. Search for and select the service account user.
  3. Review the assigned roles.
  4. Remove roles that are no longer required.

Verify Roles via the API

Use the Get User Roles endpoint to review Nexus-internal and external roles. See Security Management API for response details and error handling.

Example response:

{ "userId": "svc-nexus-ci@example.com", "roles": ["nx-repository-view-*-*-browse", "nx-repository-view-*-*-read"], "externalRoles": ["Sonatype Platform - Repository Users"] }

The roles field contains Nexus-internal role assignments managed by Nexus Repository Cloud. The externalRoles field contains external or IdP-managed roles and is read-only through this API.

Related API Reference

For complete request and response schemas, supported error responses, and endpoint behavior, see the API Reference.

This flow uses the following role-management endpoints: