Skip to main content

Okta SAML integration with the Sonatype Platform

Hardeep Nagra
Updated

Overview

This article outlines how to integrate Okta with Nexus Repository Pro 3 (NXRM 3) and/or Sonatype IQ Server.

The given setup will authenticate against a user created directly within Okta, however for real-world/production usage it is expected that you have integrated Okta with your existing LDAP directory or user database for authentication similar to the following:

samlflow.png

The configuration of backend authentication is beyond the scope of this article and we advise you to consult the Okta documentation available at https://help.okta.com/en/prod/Content/index.htm for further guidance.

Configure Okta - 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 Okta Admin UI:

1. Via the left-side dashboard, under 'Directory', click on 'Groups' and then click "Add Group":

okta_add_group.png

 

2. In the pop-up modal, create the group with an appropriate description, then click "Add Group":

okta_create_group_screen.png

3. Next, click on 'People' under 'Directory' then click 'Add person':

okta_add_person.png

 

4. In the pop-modal, fill in the form fields. For the "Groups" field, enter the name of the group created in step 2 above and for the "Password" field select 'Set by admin' and set a suitable password. Once the fields have been filled in click "Save":

.okta_add_person_screen.png

 

Application Creation:

[Top]

Note: If you are configuring SAML for both Nexus Repository 3 Pro and Sonatype IQ Server then you will need to configure a separate Okta "Application" for each.

5. From the left-side dashboard, under 'Applications', click 'Applications', then select "Create App Integration":

okta_create_app_integration.png

 

6. In the pop-up modal, select 'SAML 2.0' then click "Next".

7. In the next screen, give the application a suitable name e.g. "NXRM3 Login" or "IQ Login" and click "Next".

8. On the next "Configure SAML" screen, configure the General form as follows:

  • Single sign on URL: Enter the instance's Assertion Consumer Service (ACS) URL i.e.
    • For Nexus Repository 3 it will be <NXRMBaseURL>/saml
    • For Sonatype IQ Server it will be <IQBaseURL>/saml
  • Check the Use this for Recipient URL and Destination URL option.
  • Audience URI (SP Entity ID): Enter the instance's Entity ID URL i.e.
    • For Nexus Repository 3 it will be <NXRMBaseURL>/service/rest/v1/security/saml/metadata
    • For Sonatype IQ Server it will be <IQBaseURL>/api/v2/config/saml/metadata
  • NameID format: This will serve as the username. For this example, it has been set to email, but other NameID options are available.

 okta_configure_saml_general.png

 

9. Next click "Show Advanced Settings". This is where settings such as assertion signing and encryption can be configured. For production usage it is recommended that at the minimum both the "Response" and "Assertion Signature" are signed:

okta_advanced_settings.png

10. Under the "Attribute Statements (optional)" section, configure the attributes that will be sent to Nexus in the SAML response. Both Nexus Repository 3 and Sonatype IQ Server accept three user attributes alongside the username which are: First Name, Last Name and Email. Username is defined by the Name ID set in step 8 above.

Set these attributes as follows:

okta_user_attributes.png

11. Under the "Group Attribute Statements (optional)" section, set the group attribute. This attribute will contain a list of groups a user is a member which can then be used to configure role mapping. Okta allows you to scope which groups should be included in the response via the use of a filter. If for example, you only wanted to return the group attribute if the user was a member of any group containing the string "nexus" in its name, then the filter configuration would be similar to this:

okta_group_attribute_equals_filter.png

12. Once the section is configured you can preview the SAML assertion and once you have checked the settings, click "Next".

13. The next screen is a "Feedback" page. Most of the questions are optional except for the first. For this question, it is recommended to select "I'm an Okta customer adding an internal app". Once you are done with this feedback page, click "Finish" to create the SAML integration app.

14. Once you click finish, you will be automatically redirected to the "Sign-On" tab of the application you just created. Right-click on the "Identity Provider metadata" link and select "save link as" to download the Okta metadata - this will be needed when configuring the Nexus side.

okta_saml_metadata.png

15. Next click on the "Assignments" tab. Here you can define which users or groups will have access to this SAML application. If a given user is not assigned this app then when they attempt to login from Nexus to Okta, the SSO will fail. Assign the application to users/groups based on your requirements.

This completes the Okta side configuration. The next set of actions are to configure Nexus Repository and Sonatype IQ Server.

 

Configure Sonatype Platform

Configure Nexus Repository 3 Pro

[Top]

Full SAML configuration documentation for Nexus Repository 3 Pro is available at https://help.sonatype.com/en/saml.html

1. Login to the NXRM 3 UI.

2. Go to the Administration → Security → SAML page and enter the XML IdP metadata downloaded in Step 14 of the Application Creation section above into the 'SAML Identity Provider Metadata XML' field.

nexus3_saml_metadata.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 in Nexus Repository pro. The values entered here should match the attribute names set in Step 10 and Step 11 in the Application Creation section above:

  • Username: username
  • First Name: firstName
  • Last Name: lastName
  • Email: email
  • Roles/Groups: groups

nexus_field_mapping.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 exact name 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.

nexus3_role_mapping.png

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

Nexus Repository 3 Pro is now configured for SAML authentication.

 

Configure Sonatype IQ Server

[Top]

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_saml_menu.png

3. Paste or load the XML IdP metadata downloaded in Step 14 of the Application Creation section above into the 'Identity Provider Metadata XML' field.

iq_idp_metadata.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 IQ Server. The values entered here should match the attribute names set in Step 10 and Step 11 in the Application Creation section above:

  • Username: username
  • First Name: firstName
  • Last Name: lastName
  • Email: email
  • Roles/Groups: groups

iq_saml_config_keycloak3.png

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 - 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/{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 2 of the User/Group Creation section.

So if the roleId returned is 1b92fae3e55a411793a091fb821c422d and the groupName is nexus-admin, the actual API call will look similar to:

curl -u admin:admin123 -X PUT 'http://localhost:8070/api/v2/roleMemberships/global/role/1b92fae3e55a411793a091fb821c422d/group/nexus-admin'

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

Nexus Repository 3 Pro SAML Login

[Top]

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

nexus3_verify_user.png

The values listed here should match the user attributes configured on the Okta 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: 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

[Top]

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 Okta 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 Sonatype 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. 

iq_user_details.png

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

Related articles