Security Management API

The Nexus Repository Security Management API allows administrators to programmatically manage access control, users, roles, privileges, and content selectors within Nexus Repository. It also provides endpoints to configure external authentication mechanisms and sources, including LDAP, SAML, OpenID Connect, and security realms.

This page provides only a basic overview of the endpoints available for this API. Detailed API documentation is available in the Nexus Repository user interface as well as in our API Reference.

Content Selectors

The content selectors REST API endpoints can be used to create and manage content selectors:

list the content selectors
create or modify content selectors

LDAP

The LDAP endpoints can be used to accomplish the following:

List all LDAP servers
Create LDAP server
Retrieve the details of a single LDAP server
Update LDAP server
Delete LDAP server
Change LDAP server ordering

SAML

When onboarding users to Nexus Repository, Administrators use this API to pre-provision SAML users, assign roles before first login, and reconcile roles with IdP groups upon login.

The SAML endpoints can be used to accomplish the following:

Lists users with pagination, filtering, and sorting.
```
GET /v1/security/saml/users
```
Requires nexus:users:read permission
Returns the user by identifier.
```
GET /v1/security/saml/users/{id}
```
Requires nexus:users:read permission
Creates a SAML user.
```
POST /v1/security/saml/users
```
Requires nexus:users:create permission
Replaces mutable fields.
```
PUT /v1/security/saml/users/{id}
```
Requires nexus:users:update permission
Deletes the user per current capabilities.
```
DELETE /v1/security/saml/users/{id}
```
Requires nexus:users:delete permission

Example Json Payload for Users

The following payload is returned by the GET requests. This structure is used when setting new users.

 {
  "userId": "jsmith",
  "firstName": "John",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "status": "active",
  "roles": [
    "Nexus Developer"
  ]
}

OpenID Connect

The OpenID Connect is an authentication layer built on top of the OAuth 2.0 framework. The following REST API endpoints can be used to configure OpenID connect in self hosted Nexus Repository Pro editions:

Retrieves the current OIDC configuration.
```
GET/service/rest/v1/security/oauth2
```
Creates or updates the OIDC configuration.
```
PUT/service/rest/v1/security/oauth2
```
Removes the OIDC configuration.
```
DELETE/service/rest/v1/security/oauth2
```

Privileges

The privileges REST API endpoints can be used to create and manage privileges:

list the privileges
create or modify privileges

Roles

The roles REST API endpoints can be used to create and manage roles and their permissions within Nexus Repository:

list the roles from any configured user source (internal or external)
create or modify local roles and external role mappings

Users

The users REST API endpoints can be used to create and manage users and their permissions within Nexus Repository:

search for users available to NXRM whether they were defined locally or from a configured authentication source such as LDAP
create or modify local users (self-hosted only)
manage Nexus-internal roles assigned to a user in Nexus Repository Cloud
reset an individual user token
reset all user tokens in the system

User Role Management

Note

This API is available in Nexus Repository Cloud only.

For external users, these endpoints update Nexus-internal role mappings only. External group-based roles are not changed.

The user role management endpoints can be used to accomplish the following:

List the roles assigned to a user.
```
GET /v1/security/users/{userId}/roles
```
Requires nexus:users:read permission.
Set all Nexus-internal roles assigned to a user. This replaces the user's complete set of Nexus-internal roles.
```
PUT /v1/security/users/{userId}/roles
```
Requires nexus:users:update permission.
Add one or more Nexus-internal roles to a user without replacing existing role assignments.
```
PUT /v1/security/users/{userId}/roles/add
```
Requires nexus:users:update permission.
Remove one or more Nexus-internal roles from a user.
```
PUT /v1/security/users/{userId}/roles/remove
```
Requires nexus:users:update permission.

Role update requests use the following payload:

{
  "roles": ["nx-admin", "nx-repository-view-*-*-browse"]
}

Responses include the user ID, Nexus-internal roles, and external roles when applicable:

{
  "userId": "[email protected]",
  "roles": ["nx-admin", "nx-repository-view-*-*-browse"],
  "externalRoles": ["Sonatype Platform - Administrator"]
}

The user role management endpoints can return the following errors:

Endpoint type	Status	Condition
Role update requests (PUT)	400	The `roles` value is missing, or contains a role ID that does not exist. For add and remove requests, an empty `roles` value also returns this status.
All role management endpoints	403	The caller lacks the required permission.
All role management endpoints	404	The user was not found.