Azure AD SAML Integration with Nexus Applications

Overview

This article will outline through example how to integrate Azure AD with Nexus Repository Manager Pro 3 (NXRM 3) and/or Nexus IQ Server for SAML SSO. The given setup will authenticate against a test user and group created directly within Azure AD.

Configure Azure AD - User/Group Creation and Application Creation

User/Group Creation

[Top]

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

azure_add_group.png

 

2. In next screen, configure the group name and description, and click 'create'. For this example, group type selected is "Security":

azure_configure_group.png

Once the group is created make a note of its 'Object Id' as this will be needed when configuring the Nexus side.

3. Return to the Directory Overview page and from the 'Add' drop down, select 'User':

azure_add_user.png

 

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:

azure_configure_user.png

 

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:

azure_assign_group.png

 

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

[Top]

Note: If you are configuring SAML for both NXRM3 and Nexus 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':

azure_add_app.png

 

6. In the 'Browse Azure AD Gallery' screen, select "Create your own application":

azure_add_app_2.png

 

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

 

azure_add_app3.png

 

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:

azure_configure_app1.png

 

Then select 'Add user/group':

azure_configure_app2.png

 

8. In the 'Add Assignment' screen, click "None Selected", which will pop up a panel on the right-side:

azure_configure_app3.png

 

From this panel, locate the user created in step 4 above and assign it to the application.

azure_configure_app4.png

9. Return the Application Overview page and select "Set up single sign on":

azure_configure_app5.png

 

Then in the next screen select 'SAML' which will bring you to the 'Set up Single Sign-On with SAML' page.

azure_configure_app6.png

 

10. From the 'Set up Single Sign-On with SAML' page, first edit the 'Basic SAML Configuration' section:

  • Identifier (Entity ID): Enter the Nexus instance's Entity ID URL i.e.
    • For NXRM 3 it will be <NXRMBaseURL>/service/rest/v1/security/saml/metadata
    • For Nexus IQ Server it will be <IQBaseURL>/api/v2/config/saml/metadata
  • Reply URL (Assertion Consumer Service URL): Enter the Nexus instance's Assertion Consumer Service (ACS) URL i.e.
    • For NXRM 3 it will be <NXRMBaseURL>/saml
    • For Nexus IQ Server it will be <IQBaseURL>/saml

azure_configure_app7.png

 

11. Then edit the 'User Attributes & Claims' section. This will determine which attributes are sent to Nexus in the SAML assertion. Both NXRM3 and IQ accept three user attributes alongside the username which are: First Name, Last Name and Email. 

By default Azure sets the following attributes:

azure_configure_app8.png

And these values will suffice for Nexus and IQ, however in this example, the nameID has been changed from the user's principal name to the user's mail address:

azure_configure_app9.png

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

azure_configure_app10.png

Click 'Save' to add the group claim. The final attribute mapping is as follows:

azure_configure_app11.png

Make a note of the 'Claim name' for each attribute as these values will be needed when mapping the attributes on the Nexus side.

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:

azure_configure_app12.png

 

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

azure_configure_app13.png

 

Configure Nexus Applications

Correct the Azure AD SAML Metadata

[Top]

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

[Top]

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 corrected XML IdP metadata into the 'SAML Identity Provider Metadata XML' field:

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

azure_configure_nexus2.png

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

azure_configure_nexus3.png

10. Scroll to the bottom and click 'Create role'.

NXRM 3 is now configured for SAML authentication.

 

Configure Nexus IQ Server

[Top]

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.

iq_saml_menu.png

3. Paste or load the corrected XML IdP metadata into the 'Identity Provider Metadata XML' field.

azure_configure_iq1.png

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

azure_configure_iq2.png

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

azure_configure_iq3.png

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

IQ Server is now configured for SAML authentication. 

 

Verify SAML Login

NXRM 3 SAML Login

[Top]

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. 

nexus3_verify_user.png

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 Nexus Applications section via the external role mapping option.

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

[Top]

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

iq_user_menu.png

5. This will open a small modal that will list the user details similar to the following. 

azure_configure_iq4.png

The values listed here should match the user attributes configured on the Azure side.

Have more questions? Submit a request

0 Comments

Article is closed for comments.