Overview

This article outlines how to integrate Keycloak with Nexus Repository 3 Pro and/or Sonatpye IQ Server.

The given setup will authenticate against a user created directly within Keycloak, however for real-world/production usage it is expected that you have integrated Keycloak with your existing LDAP directory or user database for backend authentication similar to the following:

The configuration of backend authentication is beyond the scope of this article and we advise you to consult the Keycloak documentation available at https://www.keycloak.org/docs/latest/server_admin/ for further guidance.

For reference, the Keycloak version used was v24.0.4 (May 2024).

Configure Keycloak - Metadata Download and User/Group Creation

Download Keycloak IdP Metadata 

[Top]

1. Login to the Keycloak Admin Console

2. From the left-side menu, click on Realm Settings.

3. From the General tab, right-click on SAML 2.0 Identity Provider Metadata under the Endpoints field and save the link/file locally. This is the Keycloak IdP metadata that will be needed.

Configure Users and Groups

[Top]

4. To add groups, via the left-side menu, under Manage, select Groups and then 'Create Group'.

5. In the "create a group" pop-up, enter a group name and select 'Create'. This will create a group that will be used for role mapping.

6. To add users, via the left-side menu, under Manage, select Users and then 'Add user'.

7. In the next screen:

• From the "required user actions" field, select "Update Password"
• Enter a username, First Name, Last Name and Email.
• Click on "Join Groups", select the group created in 5 and click "Join"

• Finally click "Create", to create the user.

8. Once saved, the user will be created but will not have a default password set or be assigned to any groups. To set the password, click on the Credentials tab, set a password and click 'Reset Password'.

9. To add the user to a group, click on the Groups tab and from the 'Available Groups' field enter the name of the group created in Step 5 and click 'Join'.

At this stage, the Keycloak IdP metadata has been saved locally, a group and user has been created, and the user has been assigned to the group.

10. The next set of actions are to configure the Sonatype Platform. Please refer to the Configure Nexus Repository 3 Pro and/or Configure Sonatype IQ Server sections below. Once configured, proceed to the Configure Keycloak - Client Config and Attribute Mapping section to continue with the remaining Keycloak configuration.

Configure Sonatype Platform

Configure Nexus Repository 3 Pro

[Top]

Full SAML configuration documentation for Nexus Repository 3 Pro is available at https://help.sonatype.com/en/saml.html

1. Log in to the Nexus Repository 3 Pro UI.

2. Go to the Administration → Security → SAML page and enter the XML from the URL in Step 3 of the Download Keycloak IdP Metadata section above into the 'SAML Identity Provider Metadata XML' field.

3. Ensure the 'Entity ID URI' field is set to <NXRMBaseURL>/service/rest/v1/security/saml/metadata

4. Select the appropriate setting for the 'Validate Response Signature' and 'Validate Assertion Signature' fields. For production setups, these should be both set to either "Default" or "True".

5. The IdP Field Mappings section will be used to map the attributes sent in the SAML response, when provisioning the SAML user. The values set for each field will be needed when following the Configure Keycloak - Client Config and Attribute Mapping section. For this example, the field mapping is set as follows:

• Username: username
• First Name: firstName
• Last Name: lastName
• Email: email
• Roles/Groups: groups

6. Scroll to the bottom of the configuration page and click Save.

7. Go to the Administration → Security → Realms page and activate the "SAML Realm" and click Save.

8. To configure external role mapping, go to Administration → Security → Roles, and from the 'Create role' dropdown select 'External role mapping' → 'SAML'.

9. In the 'Mapped Role' field, enter the exact name of the group that was configured in Step 5 of the Configure Keycloak - Metadata Download and User/Group Creation section. The remaining fields can be configured per requirements.

10. Scroll to the bottom and click 'Create role'.

Nexus Repository 3 Pro is now configured for SAML authentication. Obtain a copy of the Nexus Repository 3 Pro SAML Metadata by opening the Entity ID URI i.e. <NXRMBaseURL>/service/rest/v1/security/saml/metadata and saving the XML to file. This will be needed for the remaining Keycloak configuration documented in the Configure Keycloak - Client Config and Attribute Mapping section.

Configure Sonatype IQ Server

[Top]

Full SAML configuration documentation for Sonatype IQ Server is available at 

https://help.sonatype.com/en/saml-integration.html

1. Log in to the Sonatype IQ Server UI.

2. Via the System Preferences drop down (cog icon in the top-right of the UI), select SAML.

3. Paste or load the XML from the URL in Step 3 of the Configure Keycloak - Metadata Download and User/Group Creation section above into the 'Identity Provider Metadata XML' field.

4. Select the appropriate setting for the 'Validate Response Signature' and 'Validate Assertion Signature' fields. For production setups, these should be both set to either "Default" or "True".

5. Ensure the 'Entity ID' field is set to <IQBaseURL>/api/v2/config/saml/metadata

6. The *Attribute section will be used to map the attributes sent in the SAML response, when provisioning the SAML user. The values set for each field will be needed when following the  Keycloak - Client Config and Attribute Mapping section. For this example, the field mapping is set as follows:

• Username: username
• First Name: firstName
• Last Name: lastName
• Email: email
• Roles/Groups: groups

7. Scroll to the bottom of the configuration page and click Save.

8. To map SAML groups to roles in Sonatype IQ Server, you will need to use the Authorization Configuration (aka Role Membership) REST API. In this example, we will assign the group that was configured in Step 5 of the Configure Keycloak - Metadata Download and User/Group Creation section to the built-in 'System Administrator' IQ role. The API call will take the form of:

PUT /api/v2/roleMemberships/global/role/{roleId}/group/{groupName}

Where:

• {roleId} is the ID of the 'System Administrator' role. This ID can be obtained using the Role REST APIe.g

  curl -u admin:admin123 'http://localhost:8070/api/v2/roles'

• {groupName} is the exact name/string of the group configured in Step 5 of the Configure Keycloak - Metadata Download and User/Group Creation section.

So if the roleId returned is 1b92fae3e55a411793a091fb821c422d and the groupName is samltestgroup, the actual API call will look similar to:

curl -u admin:admin123 -X PUT 'http://localhost:8070/api/v2/roleMemberships/global/role/1b92fae3e55a411793a091fb821c422d/group/samltestgroup'

To confirm the group has been successfully mapped to the role, you can use the following REST call:

GET /api/v2/roleMemberships/global

Sonatype IQ Server is now configured for SAML authentication. Obtain a copy of the Sonatype IQ Server SAML Metadata by opening the Entity ID URI i.e. <IQServerURL>/api/v2/config/saml/metadata and saving the XML to file - this will be needed for the remaining Keycloak configuration documented in the Configure Keycloak - Client Config and Attribute Mapping section.

Configure Keycloak - Client Config and Attribute Mapping

Configure Client Settings

[Top]

Note: If you are configuring SAML for both products, you will need to configure a separate Keycloak Client for each.

1. To import the Nexus Repository 3 Pro or Sonatype IQ Server SAML metadata into Keycloak, via the Keycloak Admin Console select Clients from the left-side menu, then click 'Create'.

2. In the Add Client screen, click 'Select file' from the Import field, upload the Nexus Repository 3 Pro or Sonatype IQ Server SAML metadata obtained when configuring the Nexus Repository and/or Sonatype IQ Server and click 'Save'.

3. After saving, in the next screen, for the Client SAML Endpoint field, enter the Nexus instance's Assertion Consumer Service (ACS) URL i.e. <NXRMBaseURL>/saml for Nexus Repository 3 Pro or <IQBaseURL>/saml for Sonatype IQ Server and click 'Save'.

4. If in the Configure Nexus Applications section, the 'Validate Response Signature' and 'Validate Assertion Signature' fields are set to "Default" or "True", then in the Clients → Settings tab ensure that the 'Sign Documents' and 'Sign Assertions' fields are enabled.

Note: Any changes made on the Settings tab will modify the Keycloak IdP metadata. As such, further to any changes you will need to download a fresh copy of the Keycloak Metadata and import it again into the Nexus side(s).

Configure Attribute Mapping

[Top]

Once the client has been created and the Client SAML Endpoint has been set, an attribute for each of the mappable fields that were configured in the Configure Sonatype Platform section i.e. username, firstName, lastName, email and groups, will need to be created.

5. To map an attribute, select the Mappers tab and then click on 'Create'. In new version of Keycloak, mappers have moved to Client Scope.

6. Create a mapper for each of the mappable attributes with the values shown here:

Username:

First Name:

Last Name:

Email:

Groups:

This completes the required Keycloak configuration. The next action is to Verify SAML Login.

Verify SAML Login

Nexus Repository 3 Pro SAML Log in

[Top]

1. To test the log in, open a private/incognito browser window and go to the Nexus Repository 3 Pro UI, click on Sign in and in the login modal, select 'Sign in with SSO'.  

2. You will be directed to the Keycloak login UI. Enter the credentials of the user created in the Configure Keycloak - Metadata Download and User/Group Creation section.

3. On successful authentication, you will be directed back to Nexus Repository 3 Pro and will be logged in to the UI. 

4. To confirm the user has been provisioned with the correct attributes, click on the username in the top-right of the Nexus Repository 3 Pro UI.

5. This will open a page that will list the user details similar to the following. 

The values listed here should match the user attributes configured on the Keycloak side.

Note: If the SAML attribute mapping is incorrect or updated, the SAML user provisioned on the Nexus Repository 3 Pro will need to be deleted via the Users REST API and re-login in order for the new/updated attributes to be picked up.

Sonatype IQ Server SAML Login

[Top]

1. To test login, open a private/incognito browser window, go to the Sonatype IQ Server UI and from the User Login modal click on 'Single Sign-On'.

2. You will be directed to the Keycloak login UI. Enter the credentials of the user created in the Configure Keycloak - Metadata Download and User/Group Creation section.

3. On successful authentication, you will be directed back to Sonatype IQ Server and will be logged in to the UI. 

4. To confirm the user has been provisioned with the correct attributes, from the User dropdown in top-right of the IQ Server UI, select 'Details'.

5. This will open a small modal that will list the user details similar to the following. 

The values listed here should match the user attributes configured on the Keycloak side.