Configuring Cloudera Navigator for SAML

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.

See the OASIS SAML Wiki for more information about SAML.

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

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.

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

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.