Skip to main content

Authentication

Nexus Repository integrations with several external authentication sources. Configure the available authentication methods using Realms.

User access is managed through roles assigned privileges as explained in the Access Controls.

See Access Control

Authentication Methods

Description

External Realms

Nexus Repository Cloud deployments integrate their Identity provider using the my.sonatype.com portal.

See Using my.sonatype.com

Nexus Repository self-hosted deployments may manually configure an external realm for authentication.

See Realms

Anonymous Access

Anonymous or unauthenticated access is managed through an anonymous user and role profile.

See Anonymous Access

Local Authentication

We strongly recommend a centralized authentication provider such as LDAP or SSO. Nexus Repository includes support for managing users through both the user interface and REST API.

See Local Authentication

User Tokens

For improved security, enabling user token support allows users to generate a random token pair to use with client tools and avoids storing credentials in local files.

See User Tokens

Remote User Token (RUT) Authentication

With Remote User Token (RUT) authentication, a reverse proxy placed in front of Nexus Repository supplies the identification for the user as a header.

See Authentication via Remote User Token

SCIM Not Supported

Direct System for Cross-domain Identity Management (SCIM) is not supported.

User provisioning and deprovisioning data (e.g., user creation, deletion, group membership changes) are not automatically synchronized between your identity provider and Nexus Repository. While SSO handles authentication flow, changes to user identity data within your identity provider are not automatically reflect within Nexus Repository.

Manual user management or custom API integrations are required for comprehensive user lifecycle management.

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.

OIDC authentication is a feature available Nexus Repository Cloud and Professional editions.

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).

  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 Professional license.

  • 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.

  • 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-part process: first setting up the application in your OP, then configuring the OIDC realm in Nexus Repository.

  1. 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.

    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/service/rest/v1/security/openid-connect/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.

  2. Configure Nexus Repository

    In the Nexus Repository administration interface, configure the OIDC realm.

    1. Sign in as an administrator and navigate to Administration → Security → OpenID Connect.

    2. On the OpenID Connect configuration screen, enter the required details:

    3. Scroll down to the IdP Field Mappings section. Configure how claims from the ID Token map to Nexus Repository user fields:

      • Username Claim

        The claim used as the unique identifier for the user.

      • First Name Claim

        The claim containing the user's given name.

      • Last Name Claim

        The claim containing the user's family name.

      • Email Claim

        The claim containing the user's email address.

      • Groups Claim

        The claim containing the user's group memberships. This is essential for role mapping.

        groups or roles

    4. Select Save.

    5. Navigate to Administration → Security → Realms.

    6. Select the OpenID Connect Realm and move it from Available to Active.

    7. Ensure the OpenID Connect Realm is placed above the Local Authentication Realm so that external authentication is attempted first.

    8. Select Save.

  • Client ID

    The unique identifier created in your OP.

    nexus-repository-client
  • Client Secret

    The secret generated by your OP.

    aGV5IHNlY3JldA==
  • Authorization URL

    The base URL of your OP.

    https://sso.your.domain/auth/realms/nexus
  • Logout URL

    The Logout URL provided by your OP.

  • Token URL

    The Token URL provided by your OP.

  • JSON Web Key URL

    The Web Key URL provided by your OP.

  • JWT Signature Algorithm

    The algorithm your OP uses to sign the ID Token.

    RS256

External Role Mapping

To grant users appropriate access, you must map the group names provided by your OP to specific Nexus Repository roles.

  1. Navigate to Administration → Security → Roles.

  2. From the Create role dropdown, select External role mapping → OpenID Connect.

  3. Configure the following fields:

    • ID

      A unique identifier for this role mapping. Use the OP group name.

    • Name

      A friendly name for the mapping.

    • Description

      A brief explanation of the group's purpose.

    • Mapped Role

      The exact name of the group claim from your OP (e.g., nexus-developers).

    • Roles

      Select one or more Nexus Repository built-in or custom roles (e.g., nx-developer, nx-admin) to assign to users who are members of the mapped OP group.

  4. Click Create role.

  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 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.

Common Issues

  • 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.