# Overview

This article outlines how to integrate [Auth0](https://auth0.com/) 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](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/](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](https://auth0.com/docs/manage-users/access-control/sample-use-cases-actions-with-authorization#add-user-roles-to-tokens).

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:

```javascript
/**
 * 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. _<NXRMBaseURL>/saml_ for **Nexus Repository 3 Pro** or _<IQBaseURL>/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](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV80E0BP55ANTF9R31KMH9WW) and/or [Configuring Sonatype IQ Server](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV80E8YPKAEHWR0A6BYE8VES) 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](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](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV7YS71EM034KPB2KWAJPPT) setup 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. 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**.
   
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](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV7YS71EM034KPB2KWAJPPT) 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.](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV78KSQKK9QNSF3PPT1FXGVQ)

## Configure Sonatype IQ Server
_Full SAML configuration documentation for Sonatype IQ Server is available at_
_[https://help.sonatype.com/en/saml-integration.html](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](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV7YS71EM034KPB2KWAJPPT) 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 _<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 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](https://help.sonatype.com/en/authorization-configuration-rest-api.html). In this example, we will assign the group that was configured in **Step 5** of the [Configuring Auth0](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV7YS71EM034KPB2KWAJPPT)section to the built-in '[System Administrator](https://help.sonatype.com/en/role-management.html#administrator-roles)' IQ role. The API call will take the form of:

```http
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](https://help.sonatype.com/en/role-rest-api.html)e.g

```http
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](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV7YS71EM034KPB2KWAJPPT)section.

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

```http
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:

```http
GET /api/v2/roleMemberships/global
```

Sonatype IQ Server is now configured for SAML authentication. The next action is to [Verify SAML Login.](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV78KSQKK9QNSF3PPT1FXGVQ)

# 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](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV7YS71EM034KPB2KWAJPPT) 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](https://help.sonatype.com/en/security-management-api.html) 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](https://support.sonatype.com/hc/en-us/articles/360052183713-Auth0-SAML-integration-with-the-Sonatype-Platform#h_01EV7YS71EM034KPB2KWAJPPT) 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](https://support.sonatype.com/hc/en-us/articles/360052183713) side.