SAML Quick Start for Nexus Repository

Repository Manager | Reading time: 8 minutes

Is this article helpful?

Introduction

This guide is an introduction to Security Assertion Markup Language (SAML) for Nexus Repository PRO. SAML is an XML-based, open standard that provides single sign-on (SSO) to web- and cloud-based applications and services. As a protocol, SAML is often used to handle authentication and authorization. With the SAML integration, Nexus Repository PRO users will benefit from the ability to use a single set of login credentials to access repositories and applications.

Benefits of SAML

SAML eliminates the need to maintain multiple authentication credentials, such as passwords in multiple locations. Here are some benefits:

  • it eliminates barriers to usage so you no longer have to type in a password
  • it increases security by eliminating additional credentials, which reduces opportunities for identity theft
  • it cuts the risk of phishing by minimizing numerous attempts to access the repository manager
  • it eliminates administration time and costs by reducing duplicate efforts to maintain credentials all the while reducing help desk support calls to reset credentials

Workflow

To see the SAML protocol at work, it relies on three entities:

  • The user agent, which is the client that accesses the application (e.g., your browser).
  • The service provider (SP), an application to which you want to gain access. Nexus Repository is the service provider. The repository manager provides a new security realm – i.e., the SAML realm – to identify and authorize SAML users to access repository contents.
  • The identity provider (IdP), which is the service that authenticates SAML-enabled users on behalf of the SP.

When configuring SAML, you establish a trusted relationship between the SP and the IdP. In your SAML-enabled Nexus ecosystem, you won’t be authorized to access Nexus Repository – as the SP – unless you’re authenticated by your IdP. In order to be authenticated by the IdP, you’ll need a user account set up in the IdP’s database.

In the environment above:

  1. log into the SP from your browser.
  2. the IdP verifies your identity and authenticates you.
  3. the IdP responds by sending an assertion – an HTTP response with XML-based security information – to the SP.
  4. the SP creates a session with authorization information from the IdP, allowing users with specific access rights to interact with repositories and other resources.

Tutorial

NOTE: This tutorial demonstrates how to set up Keycloak as your IdP. SAML SSO for Nexus Repository is not limited to Keycloak. It’s available for other identity providers. See our resources section at the end for additional IdPs you can integrate into the repository manager.

This tutorial will help you configure and onboard SAML users. You’ll also learn how to install a sample npm library to a repository, with the appropriate role and permissions assigned to the newly-created SAML users.

Pre-requisites

  • Download Nexus Repository 3.22 or newer.
  • Set up an npm proxy repository from the steps in our quick start guide (i.e., http://localhost:8081/repository/npm-proxy).
  • Configure npm to your local environment.

Part 1 – Set up administrative and security functions in the IdP and SP

In this part of this guide, you’ll set up an administrator account to configure all necessary authentication functions, allowing you to access the Nexus Repository (the SP). In addition, you’ll create an additional user, whose token-based identity will be used to complete the steps to access and publish a sample application the last part of this guide.

Keycloak (IdP)

Create an admin account in the IdP

  1. Run the standalone script in your terminal, nested in ${KEYCLOAK-ROOT}/bin/, i.e. ./standalone.sh.
  2. Enter http://localhost:8080/ in the URL address field.
  3. Set up your credentials by clicking Administration Console. In this example, use ‘superuser’ as the Username. Then, enter a secure password and confirm it.
  4. Log in as ‘superuser.’

Collect the metadata from the IdP

  1. Navigate to Realm Settings in the left panel.
  2. Click SAML 2.0 Identity Provider Metadata, the second Endpoint, located in the General tab.
  3. Copy the XML script, and save it in a text editor for later.

Nexus Repository

Activate security features

  1. Open a browser tab; log in to Nexus Repository.
  2. Click Realms in the Administration panel on the left.
  3. Drag and drop both the SAML Realm and User Token Realm from the Available to the Active field.
  4. Save your changes.
  5. Navigate to User Token in the Administration panel.
  6. Check the box Enable user tokens.
  7. Save your edits.

Nexus Repository / Keycloak (IdP)

Add identity provider metadata to Nexus Repository

  1. Navigate to the Nexus Repository.
  2. Click SAML in the Administration panel.
  3. Paste the XML markup you saved from the IdP to the SAML Identity Provider XML field.
  4. Enter the word Role in the Roles/Groups field in the IdP Field Mappings section.
  5. Save your edits.

Download service provider metadata

  1. Click API, under System in Nexus Repository; then, locate Security Management: SAML among the list of endpoints.
  2. Download the XML markup from the endpoint /v1/security/saml/metadata.

Configure the client

  1. Navigate back to Keycloak.
  2. Click Client in the left panel.
  3. Click Create on the table, top right, to configure a new client on the list.
  4. Click Import to upload the metadata downloaded from Security Management: SAML (found in API, of the Administration panel). This action auto-populates the Client ID field with <BaseUrl>/service/rest/v1/security/saml/metadata; the Client Protocol field auto-selects saml.
  5. Save the form.

Part 2 – Configure and assign access controls to SAML users

In Part 1, you configured a setting that carries over role definitions to the SP, via the SAML assertion. With that in place, you’ll be able to map external roles (and users) to Nexus Repository. Make sure you’ve already created the npm proxy repository mentioned in the Pre-requisites section above.

First, create and assign a new role to ‘superuser.’ Then, create an additional user with their own assigned role. Keep the latter user on hand to complete the steps in Part 3.

Keycloak (IdP)

Set up external permissions for the admin ‘superuser’

  1. Navigate to Keycloak.
  2. Click Roles in the left panel.
  3. Click Add Role to start a new form.
  4. Enter a new Role Name for your administrator, e.g. ‘nxrm_admin’.
  5. Save your edits.
  6. Click Users in the left panel.
  7. Locate ‘superuser’ and click the ID string.
  8. Click Role Mappings to view Realm Roles.
  9. Use the Add selected button to move ‘nxrm_admin’ from Available Roles to the Assigned Roles field. This automatically saves the changes, applying the role ‘nxrm_admin’ to the user ‘superuser.’

Create a second user

  1. Click Users in the left panel.
  2. Click Add User on the dashboard to the right.
  3. On the Add User screen, fill out the form to create a new user identity:
    • username – bsmith
    • email address – bsmith@z.org
    • First Name – Betty
    • Last Name – Smith
  4. Save the user’s information.
  5. Click the Credentials tab at the top of the screen
  6. Enter a new secure password in the Set Password section, then confirm it in the second field.
  7. Save your edits.
  8. Repeat steps 2-4 in Set up external permissions for the admin ‘superuser’. This time create a new role name: ‘npm_dev.’
  9. Click the Role Mappings tab to view Realm Roles.
  10. Select ‘npm_dev’ in the Available Roles field.
  11. Click Add selected to move ‘npm_dev’ to the Assigned Roles field.

Nexus Repository

Map and assign permissions to your SAML users

Admin: ‘superuser’

  1. Click the Sign In without SSO option, to log in as a non-SAML admin.
  2. Click Roles in the Administration panel on the left.
  3. Click the Create role dropdown and select Nexus role.
  4. Locate nx-admin in the Roles section, drag it from the Available to Contained.
  5. Click Create role to save the edits.

Additional user: ‘bsmith’

  1. Return to Roles then click Nexus role from the Create role dropdown.
  2. Create a new role:
    • Role ID, e.g. ‘npm_dev’
    • Role name, ‘npm Developer’
  3. Locate the following privileges in the Available field search bar; delegate them to the Given field:
    • nx-repository-admin-npm-npm-proxy-*
    • nx-repository-view-npm-npm-proxy-*
    • nx-usertoken-current
  4. Save the role.

Verify SAML users and permissions

  1. Navigate to Users in the left panel.
  2. Select the SAML option from the Source drop-down.
  3. Click on both ‘superuser’ and ‘bsmith’ to confirm the external roles are properly attributed to each user.

Part 3 – Deploy an application as SAML user ‘bsmith’

In this part, you’ll need to assume the credentials for ‘bsmith’ when you log into a new session in Nexus Repository. This role was granted ‘npm_dev’ from the IdP, allowing the user to publish packages to an npm registry. Follow the steps below to install a jquery library.

Log in to the SAML-enabled repository manager

  1. Open a new browser and log into Nexus Repository.
  2. Click Sign in, located in the toolbar on the top left.
  3. Click Sign in with SSO. This action performs a browser redirect through Keycloak.

Install a package as ‘bsmith’

  1. Log into the repository manager UI as ‘bsmith.’
  2. Open your .npmrc, then update the file with the security attributes in Option 2 of our support article.
  3. Download an npm package: npm install --registry=http://localhost:8081/repository/npm-proxy jquery
  4. Verify the jquery library is listed in the Browse screen:
    • Click Browse in the left menu
    • Click the repository ‘npm proxy’ to see the list of nested repositories and assets.

Resources

SAML for Nexus Repository was tested with IdPs other than Keycloak. Feel free to configure and test the following services:

If you have further questions, we have you covered. Check out: