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/logoutNote: 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-configuration2. 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
| Field | Value | OIDC Metadata / Reference |
|---|---|---|
| Client ID | Application (client) ID from Step 1.2 | |
| Client Secret | Client secret in 1.3 | |
| Authorization URL | https://<keycloak-host>realms/<realm-name>/protocol/openid-connect/auth | authorization_endpoint |
| Logout URL | https://<keycloak-host>realms/<realm-name>/protocol/openid-connect/logout | end_session_endpoint |
| Token URL | https://<keycloak-host>realms/<realm-name>/protocol/openid-connect/token | token_endpoint |
| JSON Web Key URL | https://<keycloak-host>realms/<realm-name>/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
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.