Configuring Service Accounts and User Tokens - IQ Cloud

Configuring Service Accounts and User Tokens - IQ Cloud

This page describes the recommended process for creating and managing user tokens for service accounts on Sonatype IQ Cloud, specifically when using the Sonatype Identity Provider (IdP).

Important
In IQ Server, a user token can only be generated by the user authenticating as themselves. System administrators cannot generate a token on behalf of another user. This is a security constraint that applies to all realm types (Internal, SAML, LDAP) to prevent impersonation and ensure that tokens are only issued to authenticated users. See User Token REST API.

Prerequisites

Step 1: Add a User for the Service Account

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

Add a User via the UI

  1. In Sonatype Lifecycle Cloud, navigate to System Preferences (gear icon at the top right) → Users.
  2. Select Invite User and fill in the user details (email, first name, last name).
  3. Click Save. An email with setup instructions is sent to the provided email address.

Add a User via the API

For large-scale provisioning, the User REST API can create service accounts programmatically:

curl -u admin:admin123 -X POST -H 'Content-Type: application/json' \  'https://<your-tenant>.sonatype.app/platform/api/v2/users' \  -d '{    "username": "svc-account-01",    "password": "secret",    "firstName": "Service",    "lastName": "Account01",    "email": "svc-account-01@example.com"  }'

Note
Users created via the API are created as internal users, not as users from your configured identity provider.

Step 2: Initial Login and MFA Enrollment

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

  1. Access the invitation email and follow the link to set a password.
  2. Complete MFA enrollment using a supported authenticator (e.g., Google Authenticator, Microsoft Authenticator). See Authentication with Sonatype Cloud.
  3. Log in to the Lifecycle Cloud tenant at least once to establish the account session.

Tip
Multiple devices can scan the same QR code during MFA setup, which allows multiple team members to access the service account if needed.

After initial login, assign the appropriate IQ role to the service account through the administrator UI or role management APIs.

Step 3: Assign the Appropriate Role

Before generating a user token, ensure the service account has the correct role for its intended purpose. For service accounts used in CI/CD scanning automation, the principle of least privilege applies.

Recommended role for CI/CD application scans: Application Evaluator. This role grants access to evaluate applications and receive policy violation summary results within the CI workflow. It limits service accounts to evaluation workflows and avoids broad access to application data or policy results. See Role Management.

Assign a Role via the UI

  1. In Sonatype Lifecycle Cloud, navigate to Orgs & Policies and select the target organization or application.
  2. Click Access → Add a Role.
  3. Select the appropriate role and search for the service account username.
  4. Click Create to confirm.

Assign a Role via the REST API

For bulk provisioning, use the Authorization Configuration REST API:

At the application level:

curl -u admin:admin123 -X PUT \  'https://<your-tenant>.sonatype.app/platform/api/v2/roleMemberships/application/{applicationId}/role/{roleId}/user/{userName}'

At the organization level:

curl -u admin:admin123 -X PUT \  'https://<your-tenant>.sonatype.app/platform/api/v2/roleMemberships/organization/{organizationId}/role/{roleId}/user/{userName}'

Step 4: Generate a User Token

Once the service account has logged in at least once, a user token can be generated either via the UI or the REST API.

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

  1. Log in as the service account user.
  2. Click the Profile icon (top-right corner) → Manage User Token.
  3. Click Generate User Token and save the credentials immediately; the userCode and passCode are only shown once and cannot be retrieved afterwards.

See User Tokens.

Generate User Token via the REST API

After the initial UI login, the service account can generate its own token programmatically using basic authentication with its own credentials:

curl -u svc-account-01:my-secret -X POST \  https://<your-tenant>.sonatype.app/platform/api/v2/userTokens/currentUser

Example response:

{  "userCode": "NFWIevo8",  "passCode": "wv5XosXBU5EBv1OfT31POJ0MgGGbHgbtIRYxq9k4GRgg"}

Store this response securely. The passCode cannot be retrieved after this response is returned.

See User Token REST API.

Using the Token for API / CI Calls

curl -u NFWIevo8:wv5XosXBU5EBv1OfT31POJ0MgGGbHgbtIRYxq9k4GRgg \  https://<your-tenant>.sonatype.app/platform/api/v2/organizations

Step 5: Administrator Token Management

While administrators cannot create tokens for other users, they have the following management capabilities:

Query all user tokens (by realm)

curl -u admin:admin123 -X GET \  'https://<your-tenant>.sonatype.app/platform/api/v2/userTokens?realm=Internal'

Query token for a specific username

curl -u admin:admin123 -X GET \  'https://<your-tenant>.sonatype.app/platform/api/v2/userTokens/svc-account-01?realm=Internal'

The response includes only the userCode (not the passCode) and the associated username and realm.

Delete a user token by user code

curl -u admin:admin123 -X DELETE \  'https://<your-tenant>.sonatype.app/platform/api/v2/userTokens/userCode/NFWIevo8'

Returns 204 No Content on success.

Purge obsolete tokens

curl -u admin:admin123 -X DELETE \  'https://<your-tenant>.sonatype.app/platform/api/v2/userTokens/purge'

Configure token expiration (System Administrators only)

# Set expiration to 90 days
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" \  -d '{"userTokenDefaultExpirationDays": 90}' \  https://<your-tenant>.sonatype.app/platform/api/v