Submit a request

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

Avatar
Hardeep Nagra
Created: - Updated:

Overview

This article will outline through example how to integrate Auth0 with Nexus Repository Manager Pro 3 (NXRM 3) and/or Nexus IQ Server.

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

saml_case.png

The configuration of backend authentication is beyond the scope of this article and we advise you to consult the Auth0 documentation available at https://auth0.com/docs for further guidance.

Configuring Auth0

[Top]

Configure Roles/Users and Role Mapping Rule

1. Login to the Auth0 console via https://manage.auth0.com/

2. From the left-side menu, click on Users & Roles

auth0_users.png

 

It will expand to show two sub items - click the Users sub-item.

3. Click 'Create User'. Enter an email and password and then click 'Create'.

4. Next click on the Roles sub-item from the left side menu.

5. Click 'Create Role'. Enter a name and description for the role and then click 'Create'.

6. The configuration page for the newly create role will open. Click on the Users tab and click 'Add Users'.

auth0_roles1.png

 

7. In the modal that loads, search for the user (by name) that was create in step 3 and click 'Assign'.

auth0_roles2.png

8. The user will be assigned to the group and the next step is to create a rule to map the role to the user. This will ensure the role attribute is returned in the SAML response. From the left-side menu, click on Rules and select 'Create Rule'.

auth0_rule1.png

 

9. In the next screen, select 'Empty Rule' and in the Edit Rule page, set a Name for the rule and in the Script box, delete the placeholder code, enter the following function and click 'Save Changes':

function setRolesToUser(user, context, callback) {
  const authorization = context.authorization || {};
  // Update the user object with the authorization roles
  user.Roles = authorization.roles;
  callback(null, user, context);
}

auth0_rule2.png

 

Configure Client Settings

Note: If you are configuring SAML for both NXRM3 and Nexus IQ Server then you will need to configure a separate Auth0 "Application" for each.

10. From the left-side menu, click on Applications.

11. Click 'Create Application'.

12. Select 'Regular Web Applications', give the application a suitable name e.g. "Nexus Login" or "IQ Login" and click 'Create'.

13. On the Application config screen, click on the Settings tab.

auth0_settings.png

 

And near the bottom click, 'Show Advanced Settings'.

auth0_advanced_settings.png

14. Click on the Endpoints menu item from the advanced choices and copy the SAML → SAML Metadata URL to clipboard (suggest saving it to a document since it will be used later).

auth0_saml_endpoints.png

 

15. Click the Addons menu item from the application list and on the SAML2 WEB APP, click the "enable" toggle.

auth0_addons.png

16. This will open a configuration modal. Click on the Settings tab and under the Application Callback URL 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:

auth0_saml_url.png

Then scroll to the bottom and click Enable (future edits will have a Save button instead).  Then click the X to close the modal.

17. This completes the Auth0 configuration. The next set of actions are to configure the NXRM/IQ side. Please refer to the Configuring NXRM 3 and/or Configuring Nexus IQ Server sections below

 

Configure Nexus Applications

[Top]

Configure NXRM 3

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 14 of the Configuring Auth0 setup 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.  For this example, the field mapping is set as follows.

nxrm_auth0_users.png

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 Configuring Auth0 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. The next action is to Verify SAML Login.

 

Configure Nexus IQ Server

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 14 of the Configuring Auth0 setup above into the Identity Provider Metadata XML field.

iq_saml_config.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. For this example, the field mapping is set as follows.

iq_saml_config_auth0.png

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 Configuring Auth0 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 API - v2 e.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 Configuring Auth0 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

IQ Server is now configured for SAML authentication. The next action is to Verify SAML Login.

 

Verify SAML Login

[Top]

NXRM 3 SAML Login

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 Auth0 login UI. Enter the credentials of the user created in the Configuring Auth0 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_auth0.png

The values listed here should match the user attributes configured on the Auth0 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

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 Auth0 login UI. Enter the credentials of the user created in the Configuring Auth0 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_auth01.png

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

iq_verify_auth02.png

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

Have more questions? Submit a request

0 Comments

Article is closed for comments.