Overview

This article outlines how to integrate Auth0 with Nexus Repository 3 Pro and/or Sonatype 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:

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

Configure Roles/Users and Role Mapping Rule

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

2. From the left-side menu, navigate to User Management → Users

3. Click Create User button. Enter the required information (Email, Password, Username, Connection) then click Create to finish creating the user.

4. From the left-side menu, navigate to User Management → Roles

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

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

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

8. The next step is to map the role to the user's authenticated SAML response to facilitate RBAC access control.

Create Login / Post Login Action
These are the steps to create a Login / Post Login flow Action similar to this example.

From the left menu navigate to Actions → Library

Click Create Action → Build from scratch

When prompted, use these Create Action field values:

Name: SetRolesToUser (suggested name)
Trigger: Login / Post Login (Required to be this trigger type)
Runtime: (Use whatever the recommended option is)
Click Create

In the created template of source presented, replace all the content with:

/**
 * Handler that will be called during the execution of a PostLogin flow.
 *
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
    const authorization = event.authorization;
    if (authorization) {
        // Send roles as http://schemas.auth0.com/Roles
        api.idToken.setCustomClaim(`Roles`, authorization.roles);
        return;
    }
    return api.access.deny("Could not map roles to user");
};

Click Save Draft. Click Deploy

9. Add the new Action to the Login Flow. Using the left menu, navigate to Actions → Flows Click Login flow Under Add Action → Custom drag the action you just created to the flow. Click Apply to apply the flow changes.

Configure Client Settings

Note: If you are configuring SAML for both Nexus Repository 3 Pro and Sonatype 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.

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

14. Click on the Endpoints menu item from the advanced choices. Copy the SAML → SAML Metadata URL to clipboard. Open a new browser tab and paste the copied url in the location bar. Press enter. Save the XML document to a file, as its contents will be used later.

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

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. /saml for Nexus Repository 3 Pro or /saml for Sonatype IQ Server:

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 products. Please refer to the Configuring Nexus Repository 3 Pro and/or Configuring Sonatype IQ Server sections below

Configure Sonatype Platform

Configure Nexus Repository 3 Pro

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

1. Login to the Nexus Repository 3 Pro 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.

3. Ensure the 'Entity ID URI' field is set to /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. For this example, the field mapping is set as follows.

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

Configure Sonatype IQ Server

Full SAML configuration documentation for Sonatype IQ Server is available at https://help.sonatype.com/en/saml-integration.html

1. Login 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 14 of the Configuring Auth0 setup 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 /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 in Sonatype IQ Server. For this example, the field mapping is set as follows.

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

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

Verify SAML Login

Nexus Repository 3 Pro SAML Login

1. To test login, 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 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 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 Auth0 side.

Note: If the SAML attribute mapping is incorrect or updated, the SAML user provisioned 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

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 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 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 Sonatype 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 Auth0 side.