SAML


NEW IN 3.22

You can configure your instance to work with a SAML Identity Provider for authentication via Single Sign-On (SSO) and to send user groups to it for authorization.

Available in Nexus Repository Manager Pro only

Summary

Nexus Repository Manager 3 implements the Web Browser SSO Profile from the SAML 2.0 specification Supported bindings for sign-on are HTTP-POST (the default) and HTTP-Redirect for requests to the Identity Provider and HTTP-POST binding for responses from the Identity Provider. The Basic Attribute Profile is used for retrieving further information regarding the subjects and supported attributes are explained in  SAML Configuration Details

SAML provides access to the  UI. For clients that don't support SSO, Nexus Repository Manager 3 can generate user tokens, which can be used instead of a user name and password for basic authentication or to make REST API calls.

Integrating with an Identity Provider

Configuring SAML requires the nx-all privilege.

Configuring SAML can be achieved in a few simple steps:

  1. Download the Identity Provider's SAML Metadata file.

  2. In NXRM3, upload the identity provider metadata as described in the section below .
  3. Download Nexus Repository Manager 3's SAML Metadata (also known as the Service Provider Metadata) to provide to the Identity Provider.  Note that some Identity Providers may be configured differently. It can be downloaded with the SAML REST API:

    curl -u admin:admin123 -X GET "http://localhost:8081/service/rest/v1/security/saml/metadata"
  4. If applicable, upload Nexus Repository Manager 3's SAML Metadata (downloaded in the previous step) to the Identity Provider.
    • This is also referred to as registering a Service Provider to an Identity Provider.
    • If the Identity Provider does not allow uploading Nexus Repository Manager 3's SAML Metadata, then you can inspect it to extract the needed values.  Also note that the "Audience" of your Identity Provider should be NXRM3's Entity ID, and its "Recipient" should be Nexus Repository Manager 3's assertion consumer service URL. Please note that Nexus Repository Manager 3's assertion consumer service URL is /saml.
  5. Configure the Identity Provider to send expected subject information as basic attributes. Note that these attribute names can be customized later.
  6. Enable the SAML Realm in Nexus Repository Manager 3.  See the section below.
  7. Enable User Tokens in Nexus Repository Manager 3.  See the section below.

At this point, integration is done and Single Sign-On using SAML should be functional via the SAML Workflow .

Note that:

  • As long as a SAML configuration exists and the SAML Realm is enabled, the user will be prompted to Sign in with SSO  or Sign In Without SSO (the latter for signing in using non-SAML realms).
  • If no SAML configuration exists or the SAML Realm is not enabled, the Single Sign-On prompt dialog will not appear.
  • When you delete an existing SAML configuration and create a new one, even if you use the same Identity Provider Metadata XML, Nexus Repository Manager 3 will generate new keys, requiring SAML Metadata XML to be downloaded and re-registered to the Identity Provider.

Uploading the Identity Provider Metadata and Configuring the Attribute Names Using the UI 

  • Access the SAML Configuration UI using the SAML item of the Security administration section.
  • When SAML is not configured in NXRM3, the SAML Identity Provider Metadata XML will be empty, and the attributes will have their default values populated.
  • Upload the Identity Provider's Metadata XML by pasting the XML directly in the text area.
  • Modify the response/assertion signature validation if needed.
  • Modify the Attribute Names if needed.
  • Press Save.

Enabling the SAML Authentication Realm

Activate your SAML Realm by following these steps:

  • Navigate to Realms in the Security administration section
  • Select the SAML Realm and add it to the list of Active realms on the right
  • Ensure that the SAML Realm is located beneath the Local Authenticating Realm in the list
  • Press Save.

Best practice is to leave the Local Authenticating Realm and the Local Authorizing Realm activated so that the repository manager can be used by anonymousadmin and other users configured in this realm even with SAML authentication offline or unavailable. When users choose Sign In Without SSO , the other realms will be used for authentication, in the order they appear.

Enabling User Tokens

Activate User Tokens by the following steps:

  • Navigate to User Tokens in the Security administration section.
  • Click Enable User Tokens.
  • Press Save.

The User Token Realm will automatically be added to the active Realms.

Refer to the section on User Tokens for more details.

SAML Configuration Details

Entity ID

Entity ID is a unique identifier that will be used when registering NXRM3 to the Identity Provider as a Service Provider. It must be a valid URI. The default value <BaseUrl> /service/rest/v1/security/saml/metadata  is recommended and normally there is no need to modify the Entity ID, but it is required if the deployed instance does not have a fixed URL or port.

Attribute Names

NXRM3 expects the following basic SAML attributes to carry/extract the user information:

  • username attribute
  • first name attribute
  • last name attribute
  • e-mail attribute
  • groups attribute; SAML groups will be mapped to NXRM roles

These attribute names must be configured on the Identity Provider, and must match the SAML Configuration in NXRM3. Note that the values are case-sensitive.

For example, if the Identity Provider sends the email information of a user with the attribute user-email-address, please make sure you configure the email attribute name to user-email-address in NXRM3 as well.

All of these properties are optional to configure. If they are not explicitly configured, default values for them will be used.

Securing SAML Integration

Signed requests and responses between the Identity Provider and NXRM are supported and recommended for security purposes. Signing responses can only be configured from the Identity Provider and not within NXRM3. In case signed messages are used and the Identity Provider's signature keys are renewed (or changed for any other reason), Identity Provider metadata in NXRM3's SAML configuration must be updated.

NXRM3's SAML configuration can be set to validate the Identity Provider's signature(s) on its response and/or its assertions within that response by setting

  • the validate response signature
  • the validate assertion signature

options. By default, if a signing key is found in the Identity Provider metadata, then NXRM3 will attempt to validate signatures on the response and its assertions.

User SAML Workflow

Once NXRM3 is configured to use SAML, users can log into the NXRM3 UI.

  • Login can be done using the Identity Provider's login experience by clicking the Single Sign-On button at the user login.
  • Once the user logs in to the Identity Provider, they will be redirected back to NXRM3 with an active session.
  • Logging out of NXRM3 will not invalidate the session on the Identity Provider.
  • The user can generate a user token to use for secure authentication with format clients.

Some additional considerations :

  • Format clients like mvn, docker and npm don't support SSO, so users that authenticate with SAML must use user tokens.
  • Any existing sessions will not be invalidated once SAML is configured meaning any users already logged in when SAML is configured will need to logout and login again via the Single Sign-On button to use SAML SSO.
  • Roles can be assigned to SAML users by an NXRM3 administrator if additional role based security is required.

After a user has logged into NXRM3, they can obtain a user token:

  • The user must access the menu by selecting their username on the top right area of the main toolbar and select User Token.
  • The user must then click Access User Token.
  • The token can then be copied into the configuration file for the format client.

Revoking User Access

User access is revoked by

  • Disabling the user in the Identity Provider.
  • Revoking user tokens as an NXRM3 administrator.

To revoke user tokens, the User Token REST API can be invoked:

curl -u admin:admin123 -X DELETE "http://localhost:8081/service/rest/beta/security/user-tokens"