# 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)](https://help.sonatype.com/en/configure-identity-provider.html "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](https://help.sonatype.com/en/configuring-ssl.html "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.

```bash
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.
   
   ```bash
   nexus-repository-client
   ```

2. **Client Secret**  
   A secret generated by the OP to secure communication. Keep this confidential.
   
   ```bash
   aGV5IHNlY3JldA==
   ```

3. **Redirect URI (Callback URL)**  
   The URL in Nexus Repository that the OP sends the authentication response to.
   
   ```bash
   https://your.nexus.domain/oidc/callback
   ```

For Keycloak when extra params are provided,
   
   ```bash
   https://your.nexus.domain/oidc/callback*
   ```

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

5. **Scopes**  
   Must include openid (required) and often profile, email, and groups for user details and role mapping.
   
   ```bash
   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](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_.