Integrating Keycloak with Sonatype Platform using OpenID Connect (OIDC) – Sonatype Support

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.

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

Setting	Value (Example)
Realm name	sonatype
Enabled	ON

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

Navigate to Clients → Create client

Client settings:

Setting	Value
Client type	OpenID Connect
Client ID	sonatype (example)
Client authentication	ON
Authorization	OFF
Standard flow	ON
Direct access grants	OFF

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

Go to Clients → sonatype → Credentials
Copy the Client Secret

This value will be required in the Sonatype configuration.

1.4 Create a Group

Navigate to Groups
Click Create group
Enter a group name, example: nexus-admin
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

Navigate to Users
Click Add user
Fill in required fields:
- Username: johnwick
- Email: johnwick@example.com
- First Name / Last Name: John Wick
- Groups: the groups created in 1.4
Click Create
Go to the Credentials tab
Click Set password
Enter a password
Disable Temporary (unless you want the user to reset password on first login)
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.

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

Setting	Value
Name	groups
Token Claim Name	groups
Full group path	❌ Disabled (recommended)
Add to ID token	✅ Enabled
Add to access token	❌ Optional
Add to userinfo	✅ Enabled

📌 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

2.1 Configure OpenID Connect

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

Field	Value	OIDC Metadata / Reference
Client ID	Application (client) ID from Step 1.2
Client Secret	Client secret in 1.3
Authorization URL	https:///realms//protocol/openid-connect/auth	authorization_endpoint
Logout URL	https:///realms//protocol/openid-connect/logout	end_session_endpoint
Token URL	https:///realms//protocol/openid-connect/token	token_endpoint
JSON Web Key URL	https:///realms//protocol/openid-connect/certs	jwks_uri
Username Claim	`preferred_username`	Token Claim Name
First Name Claim	`given_name`	Token Claim Name
Last Name Claim	`family_name`	Token Claim Name
Email Claim	`email`	Token Claim Name
Groups Claim	`groups`	Token Claim Name
JWT Signature Algorithm	`RS256`	Keycloak console->Realm settings -> Tokens -> Default Signature Algorithm

2.2 Configure External Role Mapping

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

2.3 Test the Configuration

2.3.1 Log In

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

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'