Skip to main content

Auth0 SAML integration with the Sonatype Platform

Hardeep Nagra
Updated

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:

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, 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 create 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");
}

/**
* Handler that will be invoked when this action is resuming after an external redirect. If your
* onExecutePostLogin function does not perform a redirect, this function can be safely ignored.
*
* @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.onContinuePostLogin = async (event, api) => {
// };

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.

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

 

Configure Sonatype Platform

[Top]

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.

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

Field Value
Username http://schemas.auth0.com/username
First Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Last Name lastName
Email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Roles/Groups http://schemas.auth0.com/Roles

 

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

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.

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

Field Value
Username http://schemas.auth0.com/username
First Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Last Name lastName
Email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Roles/Groups http://schemas.auth0.com/Roles

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

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

 

Verify SAML Login

[Top]

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. 

nexus_verify_auth0.png

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

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.

Related articles