OpenID Connect

OpenID Connect (OIDC) is an authentication layer built on top of the OAuth 2.0 framework. It enables Nexus Repository to securely verify the identity of a user via an external OpenID Provider (OP) and obtain basic user profile information.

When OIDC is configured, users are redirected to your organization's OpenID Provider for login, providing a Single Sign-On (SSO) experience.

Note

• OIDC authentication is supported in Nexus Repository Cloud and in Nexus Repository Pro starting from version 3.86 and later. For Nexus Repository Cloud, configure OIDC using the Identity Provider configuration described in Configure Identity Provider (IdP).

• The ability to use a custom certificate imported into SSL for outbound HTTPS communication with the OpenID Provider (OP) is available in Nexus Repository Cloud and in Nexus Repository Pro starting from version 3.92 and later.

How OIDC Authentication Works

The authentication process involves Nexus Repository acting as the Relying Party (RP) and your organization's identity system (e.g., Okta, Keycloak, Azure AD) acting as the OpenID Provider (OP). OIDC works in the following sequence:

1. A user attempts to access a secured resource in Nexus Repository.
2. Nexus Repository redirects the user to the OP's authorization endpoint.
3. The user authenticates with the OP.
4. The OP sends an ID Token (containing user identity claims) and an Access Token back to Nexus Repository.
5. Nexus Repository verifies the tokens, provisions a local user, and maps the user's groups/roles from the tokens to Nexus Repository roles.
6. The user is logged in and granted access based on their mapped Nexus Repository roles.

Prerequisites

Before configuring OIDC in Nexus Repository, ensure you meet the following requirements:

• Nexus Repository Cloud or Nexus Repository Pro.
• An operational OpenID Provider (OP) (e.g., Okta, Keycloak, Azure AD) that supports the OIDC specification.
• Administrator access to both Nexus Repository and your OP.
• The Nexus Repository instance must be accessible via HTTPS with a valid, trusted certificate. OIDC requires a secure connection.
• To use the truststore option, make sure that the custom certificate (self-signed or issued by a private CA) is imported into SSL Certificates before proceeding. For more information, see Configuring SSL. Note that it is available from 3.92 in self-hosted deployments.
• For self-hosted Nexus Repository Pro licenses, set the following configuration in nexus.properties to enable OpenID Connect.

nexus.security.oauth2.enabled=true
nexus.jwt.enabled=true

Configuration

Configuration is a two-step process. First, set up the application in your OP and then configure the OIDC realm in Nexus Repository.

Configure the OpenID Provider (OP)

In your OP's administration console, you must create a new client application (sometimes called a Relying Party) for Nexus Repository. Your client application may have the following fields:

1. Client ID
   A unique identifier for the Nexus Repository client.

   nexus-repository-client
   

2. Client Secret
   A secret generated by the OP to secure communication. Keep this confidential.

   aGV5IHNlY3JldA==
   

3. Redirect URI (Callback URL)
   The URL in Nexus Repository that the OP sends the authentication response to.

   https://your.nexus.domain/oidc/callback
   

For Keycloak when extra params are provided,

https://your.nexus.domain/oidc/callback*

4. Grant Types
   Must include Authorization Code (recommended) or Implicit.

   Authorization Code
   

5. Scopes
   Must include openid (required) and often profile, email, and groups for user details and role mapping.

   openid profile email groups
   

After configuring, note the following values from your OP's discovery document (often located at /.well-known/openid-configuration):

• Issuer URL: The base URL of the OP.
• Authorization Endpoint: The URL for initiating login.
• Token Endpoint: The URL for exchanging the authorization code for tokens.
• User Info Endpoint (Optional): The URL for retrieving additional user claims.

Configure Nexus Repository via UI

The configuration in Nexus Repository has two steps:

1. Configure your OAuth 2.0 settings
2. Add OAuth 2.0 to active realms.

Configure OAuth 2.0

Take the following steps to configure your OAuth 2.0 settings.

1. As an administrator, navigate to Settings→ Security → OAuth 2.0.

2. Under OIDC Settings, enter the required fields.

   • Client ID - The unique identifier created in your OP, for example nexus-repository-client
   • Client Secret - The secret generated by your OP, for example aGV5IHNlY3JldA==
   • Authorization URL - The authorization URL (authorization endpoint) of your OP, for example https://sso.your.domain/auth/realms/nexus
   • Logout URL - The Logout URL provided by your OP
   • Token URL - Token URL provided by your OP
   • JSON Web Key URL - Web Key URL provided by your OP

3. Under Use the Nexus Repository Truststore, check the box if you want to use a certificate that is connected to the Nexus Repository. To add a certificate, see Configuring SSL.

4. Under Claim Mappings, configure how claims from the ID Token map to Nexus Repository user fields. Following are the required fields:

   • Username Claim - Unique identifier for the user
   • First Name Claim - User's first name
   • Last Name Claim - User's last name
   • Email Claim - User's email address
   • Groups Claim - User's group memberships, required for role mapping. For example groups or roles

5. Under JWT Settings, enter the JWT Signature Algorithm, for example RS256.

6. Select Save.

Add to Realms

Take the following steps to add OAuth 2.0 to Active Realms.

1. Navigate to Settings→ Security→ Realms.
2. Click OAuth2 Realm to transfer it from Available to Active.
3. Ensure the OAuth2 Realm is placed above the Local Authenticating Realm so that external authentication is attempted first.
4. Select Save.

External Role Mapping

To grant users appropriate access, map the group names provided by your OP to specific Nexus Repository roles. Take the following steps to perform external role mapping:

1. Navigate to Settings → Security → Roles.
2. From the Create Role dropdown list, select External Role Mapping → OAuth2.
3. Configure the following fields:
   • Mapped Role - Exact name of the group claim from your OP, for example nexus-developers
   • Role Name - Name of the role
   • Role Description (optional) - Brief explanation of its purpose
   • Applied Privileges - Privileges applied
   • Applied Roles - Roles applied
4. Click Save.
5. Repeat this process for all OP groups that require access to Nexus Repository.

Testing and Troubleshooting

• Test the Login

1. Open a new private or incognito browser window.
2. Navigate to the Nexus Repository UI.
3. Click Sign In. You should see an option like "Sign in with SSO" or be automatically redirected to your OP's login page.
4. Log in using a user account from your OP.
5. Upon successful authentication, you should be redirected back to Nexus Repository and logged in.

• Confirm User Details and Roles

• User Details: As an administrator, navigate to Administration → Security → Users. The newly authenticated user should appear with the Source listed as OpenID Connect. Verify that the First Name, Last Name, and Email fields populated correctly based on your attribute mapping.

• Role Assignment: Check the user's assigned roles to confirm that the External Role Mappings are working as expected.

• Redirection error to OP.

Incorrect Issuer URL or Redirect URI configured in the OP or Nexus Repository. Double-check that the Nexus Redirect URI is correctly registered with your OP.

• Error after OP login (e.g., "Invalid Token").

Incorrect Client Secret or Signature Algorithm. Verify the Client Secret and Signature Algorithm (RS256 is common) are correct in the Nexus OIDC configuration.

• User logged in but missing roles/groups.

Incorrect Groups claim mapping or missing external role mapping. Check the IdP Field Mappings to ensure the Groups claim name (e.g., groups) is correct. Verify that External Role Mappings have been created for the user's groups.

• PKIX Path Building Failed

This error can occur when Nexus Repository does not trust the OpenID Provider certificate. To resolve this issue, verify that the certificate or issuing CA certificate is imported in Settings → Security → SSL Certificates. Then verify that Use Truststore is selected in Settings → Security → OAuth 2.0.