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:
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, click on Users & Roles
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'.
7. In the modal that loads, search for the user (by name) that was create in step 3 and click 'Assign'.
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'.
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); }
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.
And near the bottom click, 'Show Advanced Settings'.
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).
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 NXRM 3 or <IQBaseURL>/saml for Nexus 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 NXRM/IQ side. Please refer to the Configuring NXRM 3 and/or Configuring Nexus IQ Server sections below
Configure Nexus Applications
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.
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.
- Username: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
- First Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
- 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 section. The remaining fields can be configured per requirements.
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.
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 <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 IQ Server. For this example, the field mapping is set as follows.
- Username: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
- First Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
- 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 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
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.
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'.
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.
0 Comments