SAML integration for Nexus Repository Manager Pro 3 and Nexus IQ Server with Keycloak

Overview

This article will outline through example how to integrate Keycloak with Nexus Repository Manager Pro 3 (NXRM 3) and/or Nexus 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:

samlflow.png

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.

INFO: Configuring SAML will require switching between Keycloak and the Nexus applications, so to assist you in correctly navigating this configuration, we advise completing this guide in the following order:
  1. Configure Keycloak - Metadata Download and User/Group Creation clipart59277.png
  2. Configure Nexus Applications (configure NXRM 3 clipart59277.png or configure Nexus IQ Server  clipart59277.png )
  3. Configure Keycloak - Client Config and Attribute Mapping clipart59277.png
  4. Verify SAML Login clipart59277.png

Configure Keycloak - Metadata Download and User/Group Creation

Download Keycloak IdP Metadata 

[Top]

1. Login to the Keycloak Admin Console i.e. <KeycloakURL>/auth/admin/master/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 when configuring NXRM/IQ.

keycloak_metadata.png

 

Configure Users and Groups

[Top]

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

keycloak_groups.png

5. In the next screen enter a group name and select 'Save'. This will create a group that will be used for role mapping on the NXRM/IQ side.

keycloak_group2.png

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

keycloak_user1.png

7. In the next screen, enter a username, First Name, Last Name and Email, then click 'Save'

keycloak_user2.png

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

keycloak_user3.png

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

keycloak_groups3.png

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 NXRM/IQ side. Please refer to the Configure NXRM 3 and/or Configure Nexus IQ Server sections below. Once the Nexus side is configured, proceed to the Configure Keycloak - Client Config and Attribute Mapping section to continue with the remaining Keycloak configuration.

 

Configure Nexus Applications

Configure NXRM 3

[Top]

Full SAML configuration documentation for NXRM 3 is available at https://help.sonatype.com/repomanager3/system-configuration/user-authentication/saml

1. Login to the NXRM 3 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.

nexus_saml_config.png

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 in NXRM. 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:

nexus_field_mapping.png

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

nexus_saml_realms.png

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

nexus_external_role_mapping1.png

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.

nexus_external_role_mapping2.png

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

NXRM 3 is now configured for SAML authentication. Obtain a copy of the NXRM 3 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 Nexus IQ Server

[Top]

Full SAML configuration documentation for Nexus IQ Server is available at https://help.sonatype.com/iqserver/managing/user-management/saml-integration

1. Login to the Nexus IQ Server UI.

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

iq_sys_prefs.png

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.

iq_saml_config_keycloak.png

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

iq_saml_config_keycloak2.png

6. The *Attribute section will be used to map the attributes sent in the SAML response, when provisioning the SAML user in IQ Server. 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:

iq_saml_config_keycloak3.png

  • 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 IQ Server, you will need to use the Authorization Configuration (aka Role Membership) REST API - v2. 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:

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

IQ Server is now configured for SAML authentication. Obtain a copy of the 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 NXRM3 and IQ Server then you will need to configure a separate Keycloak Client for each.

1. Further to configuring the NXRM/IQ side, to import the NXRM or IQ SAML metadata into Keycloak, via the Keycloak Admin Console select Clients from the left-side menu, then click 'Create'.

keycloak_client1.png

2. In the Add Client screen, click 'Select file' from the Import field, upload the NXRM or IQ SAML metadata that was obtained when configuring the NXRM/IQ side and click 'Save'.

keycloak_client2.png

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 NXRM 3 or <IQBaseURL>/saml for Nexus IQ Server and click 'Save'.

keycloak_client3.png

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.

keycloak_client4.png

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 Nexus Applications 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'.

keycloak_mapper.png

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

Username:

keycloak_map_username.png

First Name:

keycloak_map_firstname.png

Last Name:

keycloak_map_lastname.png

Email:

keycloak_map_email.png

Groups:

keycloak_map_groups.png

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

 

Verify SAML Login

NXRM 3 SAML Login

[Top]

1. To test login, open a private/incognito browser window and go to the NXRM 3 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 NXRM 3 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 NXRM3 UI.

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

nexus_verify_login.png

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

Note: Due to known NXRM3 issue https://issues.sonatype.org/browse/NEXUS-23052, if the SAML attribute mapping is incorrect or updated, the SAML user provisioned on the NXRM 3 side will need to be deleted via the Users REST API and re-login in order for the new/updated attributes to be picked up.

 

Nexus IQ Server SAML Login

[Top]

1. To test login, open a private/incognito browser window, go to the Nexus 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 Nexus 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'.

iq_verify_login1.png

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

iq_verify_login2.png

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

Have more questions? Submit a request

0 Comments

Article is closed for comments.