Integrating Keycloak with Sonatype Platform using OpenID Connect (OIDC)

Overview

This article describes how to integrate Keycloak with the Sonatype Platform (Nexus Repository and Lifecycle) using OpenID Connect (OIDC) for authentication.

The configuration steps are similar to other OIDC providers (such as Microsoft Entra ID). This article focuses specifically on Keycloak-specific configuration and behavior.

Note
This setup is intended for testing purposes only. Additional configuration and security hardening may be required for a production environmen

Steps

1. Configure Keycloak

1.1 Create a New Realm

A Realm in Keycloak is an isolated security domain that manages users, roles, and clients. Sonatype recommends using a dedicated Realm for Sonatype Platform integration.

1. Log in to the Keycloak Admin Console
2. From the top-left dropdown, click Manage realms, then click Create realm
3. Provide the following values:

4. Click Create  

You will use the Realm name in all OIDC endpoints later.
For example:

https://<keycloak-host>/realms/sonatype

⚠️ Important

Realm names are case-sensitive and must match exactly in all Sonatype OIDC configuration fields.

For all the steps below, verify that the current Realm is the Realm created in this step. 

1.2 Create a Client

1. Navigate to Clients → Create client

Client settings:

Configure Redirect URIs

Add the following redirect URI(s):

Nexus Repository

https://<nexus-host>/oidc/callback*

Lifecycle:

https://<lifecycle_host>/oidc/callback*

Configure Logout (Optional)

Keycloak supports POST-based logout, which is compatible with Nexus. If you enable IdP logout in Nexus, ensure the following endpoint is used:

https://<keycloak-host>/realms/<realm>/protocol/openid-connect/logout

Note: IdP logout is optional. Nexus logout will still function locally if this is disabled.

1.3 Configure Client Credentials

1. Go to Clients → sonatype → Credentials
2. Copy the Client Secret

This value will be required in the Sonatype configuration.

1.4 Create a Group

1. Navigate to Groups
2. Click Create group
3. Enter a group name, example: nexus-admin
4. Click Create

📌 Note

Group names are case-sensitive and should match the values you plan to use in Lifecycle role mappings.

1.5 Create a User

1. Navigate to Users
2. Click Add user
3. Fill in required fields: 

• Username: johnwick 
• Email: johnwick@example.com
• First Name / Last Name: John Wick 
• Groups: the groups created in 1.4

4. Click Create
5. Go to the Credentials tab
6. Click Set password
7. Enter a password
8. Disable Temporary (unless you want the user to reset password on first login)
9. Click Save

1.6 Create or verify client scopes

In Keycloak, client scopes define which claims (attributes) are included in tokens for a client. They are essentially a set of mappers that control what data the client receives. For each scope, please verify that Include in token scope is ON. 

1. Navigate to Client scopes.
2. Verify that the email and profile scope exist.
3. Click the profile scope-> Mappers, verify that the family name, given name, and username mappers exist 
4. Click Add mapper -> By Configuration -> Group Membership

📌 Important

• Token Claim Name must match what you configure in Sonatype Platform (Nexus Repository and Lifecycle)
• If you enable “Full group path”, groups will appear as /parent/child.

1.7 Evaluate the Generated Access Token 

1.8 Collect the OpenID Metadata

Click Realm settings -> General -> Endpoints (OpenID Endpoint Configuration)

Or use the URL:

 https://<keycloak-host>/realms/<realm-name>/.well-known/openid-configuration

2. Configure Nexus Repository

Log in to Nexus Repository as an administrator.

2.1 Configure OpenID Connect

Refer to the official for additional details: https://help.sonatype.com/en/openid-connect.html

2.2 Configure External Role Mapping

1. Navigate to Settings → Security → Roles.
2. Click Create an external role mapping.
3. Set the Mapped Role to the Group name created in 1.4 

2.3 Test the Configuration

2.3.1 Log In

1. Click Log in.
   • NXRM 3.86: Select Sign in with OAuth2.
   • NXRM 3.87+: Select Continue with SSO.

You will be redirected to the Keycloak sign-in page.

2.3.2 Verify User Access

Confirm that:

• The user is successfully authenticated.
• The expected roles and permissions are applied.
• User profile information (name, email, groups) is populated correctly.

3. Configure Sonatype Lifecycle

Log in to Sonatype Lifecycle as an administrator.

3.1 Configure OIDC

Refer to the official for additional details: https://help.sonatype.com/en/oidc-oauth2-configuration.html

and 2.1 

3.2 Mapping Entra ID Groups to Lifecycle Roles

After OIDC authentication is configured, authorization in Lifecycle is handled separately. Lifecycle does not automatically map IdP groups to roles; instead, group-to-role assignments must be configured using the Authorization Configuration (Role Membership) REST API.

In this example, a group (created during the Keycloak setup) is mapped to the built-in System Administrator role in Lifecycle.

3.2.1 Identify the Lifecycle Role ID

Each Lifecycle role has a unique internal ID. To locate the role ID for System Administrator, query the Roles REST API:

curl -u <username>:<password> 'http://<lifecycle-host>:<port>/api/v2/roles'

From the response, note the id value associated with the System Administrator role.

Example:

"id": "1b92fae3e55a411793a091fb821c422d"

3.2.2 Map the Group to the Lifecycle Role

Use the Role Membership REST API to associate the Entra ID group with the desired Lifecycle role:

curl -u <username>:<password> -X PUT \
  'http://<Lifecycle_host>:<port>/api/v2/roleMemberships/global/role/{roleId}/group/{groupId}'

Where:

• {roleId} is the Lifecycle Server role ID (for example, System Administrator)
• {groupId} is the group name in 1.4

Example

curl -u admin:admin123 -X PUT \
  'http://localhost:8070/api/v2/roleMemberships/global/role/1b92fae3e55a411793a091fb821c422d/group/nexus-admin'

3.2.3 Verify Role Membership

To confirm that the group has been successfully mapped to the role, query the role memberships endpoint:

curl -u <username>:<password> 'http://<Lifecycle_host>:<port>//api/v2/roleMemberships/global'

Verify that the group name appears under the expected role.

3.3 Test the Configuration

3.3.1 Log In

Sign in with "Single Sign-On (SSO)". You will be redirected to the Keycloak sign-in page.

3.3.2 Verify User Access

Confirm that:

• The user is successfully authenticated.
• The expected roles and permissions are applied.
• User profile information (name, email, groups) is populated correctly.