Overview
This article outlines how to integrate Azure AD with Nexus Repository Pro 3 (NXRM 3) and/or Sonatype IQ Server for SAML SSO. This setup authenticates against a test user and group created directly within Azure AD.
Configure Azure AD - User/Group Creation and Application Creation
User/Group Creation
For the sake of example, this configuration will create a test group and user via the Azure Admin UI:
1. Via the Azure Portal Home, under 'Azure Services', click on 'Azure Active Directory' and then from the 'Add' drop down, select 'Group':
2. In next screen, configure the group name and description, and click 'create'. For this example, group type selected is "Security":
Once the group is created make a note of its 'Object Id' as this will be needed.
3. Return to the Directory Overview page and from the 'Add' drop down, select 'User':
4. In the next screen configure the user. Ensure the 'First name' and 'Last name' fields are filled in.
Then under 'Groups and roles' click on the "0 groups selected" link in order to assign the user to a group:
This will pop-up a panel on the right-side where you will be able to search and select the nexus-admin group created in step 2 above:
Once the group has been assigned, on the create user screen, scroll to the bottom and click 'Create' to complete the process of creating the test user.
Application Creation
Note: If you are configuring SAML for both Nexus Repository 3 Pro and Sonatype IQ Server then you will need to configure a separate Azure AD "Application" for each.
5. Return to the Directory Overview page and from the 'Add' drop down, select 'Enterprise application':
6. In the 'Browse Azure AD Gallery' screen, select "Create your own application":
And in the pop-up panel that appears on the right, enter a name for the app e.g. 'Nexus3 SAML SSO' and for the question asked, select the "Non-gallery" option and click 'Create':
7. On create (it may take a few seconds), you will be taken to the application overview page. Under 'Getting Started', select the 'Assign user and groups' option:
Then select 'Add user/group':
8. In the 'Add Assignment' screen, click "None Selected", which will pop up a panel on the right-side:
From this panel, locate the user created in step 4 above and assign it to the application.
9. Return the Application Overview page and select "Set up single sign on":
Then in the next screen select 'SAML' which will bring you to the 'Set up Single Sign-On with SAML' page.
10. From the 'Set up Single Sign-On with SAML' page, first edit the 'Basic SAML Configuration' section:
-
Identifier (Entity ID): Enter the Nexus Repository 3 Pro instance's Entity ID URL i.e.
- For NXRM 3 it will be <NXRMBaseURL>/service/rest/v1/security/saml/metadata
- For Sonatype IQ Server it will be <IQBaseURL>/api/v2/config/saml/metadata
-
Reply URL (Assertion Consumer Service URL): Enter the Nexus Repository 3 Pro instance's Assertion Consumer Service (ACS) URL i.e.
- For NXRM 3 it will be <NXRMBaseURL>/saml
- For Sonatype IQ Server it will be <IQBaseURL>/saml
11. Then edit the 'User Attributes & Claims' section. This will determine which attributes are sent to Nexus Repository 3 Pro in the SAML assertion. Both platform products accept three user attributes alongside the username which are: First Name, Last Name and Email.
By default, Azure sets the following attributes:
These values will suffice, however in this example, the nameID has been changed from the user's principal name to the user's mail address:
11a. Next click on "Add a group claim" to add a group attribute. This will pop up a panel on the right-side. In this example, the type selected is 'Security groups' and the source attribute has been set to 'Group ID' (this represents the actual value that will be sent for the group attribute in the SAML assertion):
Click 'Save' to add the group claim. The final attribute mapping is as follows:
Make a note of the 'Claim name' for each attribute as these values will be needed when mapping the attributes on the Nexus Repository side.
NOTE: According to https://docs.microsoft.com/en-us/azure/active-directory/develop/reference-saml-tokens
If the number of groups the user is in goes over a limit (150 for SAML, 200 for JWT) then an overage claim will be added the claim sources pointing at the Graph endpoint containing the list of groups for the user.
12. Finally edit the 'SAML Signing Certificate' section. By default Azure signs only the SAML assertion, but the option exists to also sign only the response or sign both the response and assertion. In this example, the option of signing both the response and assertion have been selected, and this is recommended for production setups:
Note: As well as signing, Azure also has the option of encrypting the SAML response via the 'Token encryption' feature. This is however a premium Azure offering and you can learn more about it via the following Azure documentation: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/howto-saml-token-encryption
13. Once the signing options have been configured, download the Azure SAML metadata via the 'Federation Metadata XML' link - this will be needed when configuring the Nexus Repository side:
Configure Sonatype Platform
Correct the Azure AD SAML Metadata
Before either NXRM3 or IQ Server can be configured for SAML SSO, an additional step of "correcting" the Azure AD metadata downloaded in Step 13 of the Application Creation section above is required.
For details on how to do this, please refer to the How to Correct Microsoft IdP SAML Metadata for NXRM 3 and IQ Server KB article.
Configure Nexus Repository 3 Pro
Full SAML configuration documentation for NXRM 3 is available at https://help.sonatype.com/repomanager3/system-configuration/user-authentication/saml
1. Login to the Nexus Repository 3 Pro UI.
2. Go to the Administration → Security → SAML page and enter the corrected XML IdP metadata 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. If you selected the recommended option of signing both the response and assertion in step 12 of the Application Creation section above, then set both the 'Validate Response Signature' and 'Validate Assertion Signature' fields to "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. The values entered here should match the attribute names set in steps 11 and 11a in the Application Creation section above:
- Username: username
- First Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- Last Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
- Email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- Roles/Groups: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
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 'Object Id' of the group that was configured in Step 2 of the User/Group Creation section above. The remaining fields can be configured per your requirements.
10. Scroll to the bottom and click 'Create role'.
Sonatype Nexus Repository 3 Pro is now configured for SAML authentication.
Configure Sonatype IQ Server
Full SAML configuration documentation for Sonatype IQ Server is available at https://help.sonatype.com/iqserver/managing/user-management/saml-integration
1. Log in 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 corrected XML IdP metadata into the 'Identity Provider Metadata XML' field.
4. Select the appropriate setting for the 'Validate Response Signature' and 'Validate Assertion Signature' fields. If you selected the recommended option of signing both the response and assertion in step 12 of the Application Creation section above, then set both the 'Validate Response Signature' and 'Validate Assertion Signature' fields to "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. The values entered here should match the attribute names set in steps 11 and 11a in the Application Creation section above:
- Username: username
- First Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- Last Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
- Email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- Roles/Groups: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
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 2 of the User/Group Creation 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/{groupId}
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'
- {groupId} is the exact Object Id string of the group configured in Step 2 of the User/Group Creation section.
So if the roleId returned is 1b92fae3e55a411793a091fb821c422d and the groupId is 9930928a-b6c3-47a2-b997-1c0e1caae91d, the actual API call will look similar to:
curl -u admin:admin123 -X PUT 'http://localhost:8070/api/v2/roleMemberships/global/role/1b92fae3e55a411793a091fb821c422d/group/9930928a-b6c3-47a2-b997-1c0e1caae91d'
To confirm the group has been successfully mapped to the role, you can use the following REST endpoint:
GET /api/v2/roleMemberships/global
Sonatype IQ Server is now configured for SAML authentication.
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 Azure AD login UI. Enter the credentials of the user created in the User/Group Creation 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 Azure side. From this screenshot you will also notice the cog icon the top-left menu. This indicates that the user was also mapped to the role that was created in the Configure Sonatype Platform section via the external role mapping option.
Note: If the SAML attribute mapping is incorrect or updated, the SAML user provisioned on the Nexus Repository 3 Pro 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.
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 Azure AD login UI. Enter the credentials of the user created in the User/Group Creation 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 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 Azure side.