Configuring Cloudera Navigator for SAML
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.
- 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)
|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.
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
- From an attribute in the authentication response:
Configuring the Navigator Metadata Server
- Select Clusters > Cloudera Management Service.
- Click the Configuration tab.
- Select Navigator Metadata Server from the Scope filter.
- Select External Authentication from the Category filter.
- Type SAML in the Search box to display only the SAML relevant settings.
- 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:126.96.36.199 (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.
- Click Save Changes.
- 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.
- Download Cloudera Navigator's SAML metadata XML file from your Cloudera Navigator instance:
- 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.
- Provide this metadata file to your IDP using whatever mechanism your IDP provides.
- Ensure that the IDP has access to whatever public certificates are necessary to validate the private key that was provided by Cloudera Navigator earlier.
- 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.
- Ensure the changes to the IDP configuration have taken effect (a restart may be necessary).
Testing Cloudera Navigator and the SSO Setup
- Return to the Cloudera Navigator home page at: http://hostname:7187/.
- Attempt to log in with credentials for a user that is entitled. The authentication should complete and you should see the Home page.
- 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.
- 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:
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.