Cloudera Enterprise 6.3.x | Other versions

Configuring Cloudera Navigator for SAML

Cloudera Navigator supports SAML (Security Assertion Markup Language), an XML-based open standard data format for exchanging authentication and authorization details between identity providers and service providers. One of the main benefits of SAML is that it enables Single Sign-on (SSO) for browser-based clients, such as the Cloudera Navigator console. That means that you can integrate Cloudera Navigator with SSO solutions such as Shibboleth or CA Single Sign-On (formerly, SiteMinder).
  Note: Not all SAML identity providers are interoperable. Cloudera Navigator has been tested with Shibboleth and CA Single Sign-On.

Continue reading:

Overview of SAML and SSO

The steps below assume you have a functioning SAML IDP already deployed. Here is a brief summary of some of the high level details as background to the configuration tasks:

  • An identity provider or IDP is one of the main functions provided by an organization's SAML/SSO solution. The IDP provides identity assertions (tokens) to service providers that want to identify users when those users request access. service.
  • A service provider or SP, such as Cloudera Navigator, protects itself from unauthorized access by checking the identity of users requesting the service against the IDP. When the SP gets back the assertion from the IDP, the service gives the requesting user the level of access for that user.
  • The service's users or principals obtain access to the SP when they open their browsers to the URL of the service. Transparently to users, the SP—Cloudera Navigator, but specifically the web service hosted on the Navigator Metadata Server—sends an authentication request to the IDP through the user agent (browser) and obtains an identity assertion back from the IDP.
There are two properties that control whether the SSO process is initiated from the IDP or the SP (Navigator):
  • SAML Login URL nav.saml.login.url
  • Skip Authorization Check nav.auth.skip_saml_auth_check (set in Navigator Metadata Server Advanced Configuration Snippet (Safety Valve) for cloudera-navigator.properties)
As shown in the following table, when SAML authentication is enabled, the default Navigator login URL always produces a service-provider initiated SSO process (SP initiated SSO); in this process, users log into the Navigator login page and Navigator sends the authentication request to the identity provider. Specifying a SAML Login URL produces an identity provider-initiated SSO process (IdP initiated SSO); in this process, users log into the identity provider's login page and are redirected to the Navigator console and logged in.
SAML Login URL Property Skip Authorization Check Property No addition to the login URL (/) /login.html /locallogin.html
Set True SP initiated SSO IdP initiated SSO Login page
Set False SP initiated SSO IdP initiated SSO IdP initiated SSO
Not set True SP initiated SSO SP initiated SSO Login page
Not set False SP initiated SSO SP initiated SSO SP initiated SSO

See the OASIS SAML Wiki for more information about SAML.

Preparing Files

You must obtain the following files and information and provide to Cloudera Navigator:

  • A Java keystore containing a private key for Cloudera Navigator to use to sign/encrypt SAML messages.
  • The SAML metadata XML file from your IDP. This file must contain the public certificates needed to verify the sign/encrypt key used by your IDP per the SAML Metadata Interoperability Profile.
  • The entity ID that should be used to identify the Navigator Metadata Server instance.
  • How the user ID is passed in the SAML authentication response:
    • As an attribute. If so, what identifier is used.
    • As the NameID.
  • The method by which the Cloudera Navigator role will be established:
    • From an attribute in the authentication response:
      • What identifier will be used for the attribute
      • What values will be passed to indicate each role
    • From an external script that will be called for each use:
      • The script takes user ID as $1
      • The script must assign an exit code to reflect successful authentication of the assigned role:
        • 0 - Full Administrator
        • 1 - User Administrator
        • 2 - Auditing Viewer
        • 4 - Lineage Viewer
        • 8 - Metadata Administrator
        • 16 - Policy Viewer
        • 32 - Policy Administrator
        • 64 - Custom Metadata Administrator
        • A negative value is returned for a failure to authenticate
        To assign more than one role, add the numbers for the roles. For example, to assign the Policy Viewer and User Administrator roles, the exit code should be 17.

Configuring the Navigator Metadata Server

  1. Select Clusters > Cloudera Management Service.
  2. Click the Configuration tab.
  3. Select Navigator Metadata Server from the Scope filter.
  4. Select External Authentication from the Category filter.
  5. Type SAML in the Search box to display only the SAML relevant settings.
  6. Enter the values for the properties in the table based on your SAML implementation.
    Property Description and usage note
    Authentication Backend Order Set to External then Cloudera Manager.
    External Authentication Type SAML
    Path to SAML IDP Metadata File Set to the location (complete path) of the metadata file obtained from the IDP.
    Path to SAML Keystore File Path to the Java keystore file containing the Cloudera Navigator private key (prepared above).
    SAML Keystore Password Enter the SAML keystore password.
    Alias of SAML Sign/Encrypt Private Key Enter the alias used to identify the private key for Cloudera Navigator to use.
    SAML Sign/Encrypt Private Key Password Enter the password for the sign/encrypt private key.
    SAML Entity ID Default setting is clouderaNavigator. Leave set to the default unless more than one Cloudera Navigator instance is using the same IDP. Each Cloudera Navigator instance needs a unique entity ID as assigned by organizational policy.
    SAML Entity Base URL  
    SAML Response Binding HTTP-Artifact (selected by default), or HTTP-Post
    SAML Login URL (IDP-initiated SSO only) If your IDP does not support SP-initiated SSO (very uncommon), specify the user login URL for the IDP.
    Source of User ID in SAML Response Attribute (selected by default), or NameID—Specifies the source of the user ID, an attribute or NameID. For attribute, also set the attribute name in the SAML Attribute Identifier for User ID property.
    SAML Attribute Identifier for User ID urn:oid:0.9.2342.19200300.100.1.1 (Default) The standard object identifier (OID) for user IDs. This setting is used only when Source of User ID in SAML Response specifies Attribute.
    SAML Role Assignment Mechanism Attribute (selected by default), or Script—Specifies how user roles are assigned to authenticated user:
    • Attribute—Set the SAML Attribute Identifier for User Role and the SAML Attribute Values for Roles properties.
    • Script—A binary or shell script executable that assigns user roles. Set the path to the executable in Path to SAML Role Assignment Script.
    SAML Attribute Identifier for User Role urn:oid:2.5.4.11 (Default) The standard OID typically used for OrganizationalUnits. Can be left to this setting.
    SAML Attribute Values for Roles Set the attribute values that will be used to indicate the user roles. For more than one role, the attribute can return comma-separated values, such as "role1, role2".
    Path to SAML Role Assignment Script Path to executable (binary or shell script) that assigns Cloudera Navigator user roles upon authentication. Required when SAML Role Assignment Mechanism specifies Script.
  7. Click Save Changes.
  8. Restart the Navigator Metadata Server role.

Configuring the Identity Provider

After Cloudera Navigator restarts, attempted logins to Cloudera Navigator are redirected to the identity provider's login page. Authentication cannot succeed until the IDP is configured for Cloudera Navigator. The configuration details are specific to the IDP, but in general you must download the SAML file from your Cloudera Navigator instance and perform the other steps below.

  1. Download Cloudera Navigator's SAML metadata XML file from your Cloudera Navigator instance: 
    http://hostname:7187/saml/metadata
  2. Inspect the metadata file and ensure that any URLs contained in the file can be resolved by users’ web browsers. The IDP will redirect web browsers to these URLs at various points in the process. If the browser cannot resolve them, authentication will fail. If the URLs are incorrect, you can manually fix the XML file or set the SAML Entity Base URL property in the Navigator Metadata Server configuration to the correct value, and then re-download the file.
  3. Provide this metadata file to your IDP using whatever mechanism your IDP provides.
  4. Ensure that the IDP has access to whatever public certificates are necessary to validate the private key that was provided by Cloudera Navigator earlier.
  5. Ensure that the IDP is configured to provide the User ID and Role using the attribute names that Cloudera Navigator was configured to expect, if relevant.
  6. Ensure the changes to the IDP configuration have taken effect (a restart may be necessary).

Testing Cloudera Navigator and the SSO Setup

  1. Return to the Cloudera Navigator home page at: http://hostname:7187/.
  2. Attempt to log in with credentials for a user that is entitled. The authentication should complete and you should see the Home page.
  3. If authentication fails, you will see an IDP provided error message. Cloudera Navigator is not involved in this part of the process, and you must ensure the IDP is working correctly to complete the authentication.
  4. If authentication succeeds but the user is not authorized to use Cloudera Navigator, they will be taken to an error page that explains the situation. If a user who should be authorized sees this error, then you will need to verify their role configuration, and ensure that it is being properly communicated to the Navigator Metadata Server, whether by attribute or external script. The Cloudera Navigator log will provide details on failures to establish a user’s role. If any errors occur during role mapping, Cloudera Navigator will assume the user is unauthorized.

Bypassing SAML SSO

The SAML-based SSO can be bypassed by accessing the Cloudera Navigator login page directly:

http://fqdn-1.example.com:7187/locallogin.html

You can turn off this bypass by setting the Skip Authorization Check property (nav.auth.skip_saml_auth_check) in the Navigator Metadata Server Advanced Configuration Snippet (Safety Valve) for cloudera-navigator.properties.

Page generated August 29, 2019.