Cloudera Docs

Configure Ranger authentication for SAML

How to configure Ranger to use SAML for user authentication.

This document provides a step-by-step procedural guide for configuring SAML authentication in Ranger Admin using an Identity Provider (IdP) such as Keycloak.

  • Ranger Admin is running and accessible on a physical host.

  • SSL is already configured in Cloudera Manager (the existing keystore will be used for SAML signing).

  • The IdP (for example, Keycloak) is configured and accessible.

  • The IdP certificate and metadata XML are available.

  • You have SSH access to the Ranger Admin host.

  1. Copy IdP files to the Ranger Admin host.
    From your local machine or the IdP host, copy the IdP certificate and metadata file to the Ranger Admin host:
    # Replace <ranger-admin-host> with the hostname or IP of the Ranger Admin host
# Replace <user> with the SSH user (e.g. root or centos)
scp <idp-certificate>.pem <user>@<ranger-admin-host>:/tmp/
scp <idp-metadata>.xml    <user>@<ranger-admin-host>:/tmp/
  2. Log in to the Ranger Admin host. 
    ssh <user>@<ranger-admin-host>
  3. Create the SAML configuration directory and copy metadata. 
    mkdir -p /etc/ranger-saml
cp /tmp/<idp-metadata>.xml /etc/ranger-saml/<idp-metadata>.xml
  4. Import and verify the IdP signing certificate on the Ranger node. To ensure the certificate remains consistent across all hosts, you can use the scp command to copy it to each host. 
    # Import the IDP signing certificate
${JAVA_HOME}/bin/keytool -import -file /tmp/<idp-certificate>.pem -alias keycloak-cert -keystore /var/lib/cloudera-scm-agent/agent-cert/cm-auto-global_truststore.jks -storepass <password>

# Verify the import was successful
$JAVA_HOME/bin/keytool -list -keystore /var/lib/cloudera-scm-agent/agent-cert/cm-auto-global_truststore.jks -alias keycloak-cert -storepass <password>
  5. Fix permissions for the IdP metadata file. 
    chown -R ranger:ranger /etc/ranger-saml/
chmod 644 /etc/ranger-saml/<idp-metadata>.xml
  6. Verify the directory content where you copied the IdP metadata. 
    ls -la /etc/ranger-saml/
    Expected output:
    -rw-r--r-- ranger ranger  <idp-metadata>.xml
  7. Configure the SAML client in IdP (Keycloak).

    Log in to the Keycloak Admin Console and perform the following steps to create a new SAML client:

    1. Go to Clients > Create client.
    2. Set Client type to SAML.
    3. Set Client ID to <entity-id>.
      This must exactly match ranger.saml.entity.id in the ranger-admin-site.xml file.
    4. Click Next.
    5. Configure client settings under the Settings tab:
      Field Value Comments
      Client ID ranger-myorg Must match ranger.saml.entity.id.
      Master SAML Processing URL https://<ranger-host>:<port>/login/saml2/sso/ranger-myorg Must match the entity ID.

      Example: https://ranger.example.com:6080/login/saml2/sso/ranger-myorg
      Valid Redirect URIs https://<ranger-host>:<port>/login/saml2/sso/ranger-myorg Example: https://ranger.example.com:6080/login/saml2/sso/ranger-myorg
      Valid Post Logout Redirect URIs https://<ranger-host>:<port>/logout/saml2/slo Example: https://ranger.example.com:6080/logout/saml2/slo
  8. Add or update the following properties through the safety-valve from Cloudera Manager in the Ranger Admin Advanced Configuration Snippet (Safety Valve) for conf/ranger-admin-site.xml. 
    <!-- Enable SAML authentication -->
<property>
    <name>ranger.authentication.method</name>
    <value>SAML</value>
</property>

<!-- SAML SP Entity ID - must match the Client ID registered in the IdP -->
<property>
    <name>ranger.saml.entity.id</name>
    <value><entity-id></value>
    <description>Must match the Client ID registered in the IdP (e.g. Keycloak)</description>
</property>

<!-- IdP metadata file location -->
<property>
    <name>ranger.saml.idp.metadata.location</name>
    <value>file:/etc/ranger-saml/<idp-metadata>.xml</value>
    <description>IdP metadata file path (file:) or URL (http:/https:)</description>
</property>
  9. Export the Cloudera Manager certificate and import it into the Identity Provider (IdP):
    1. Export the Cloudera Manager certificate to a .pem file: 
      $JAVA_HOME/bin/keytool -exportcert -keystore /var/lib/cloudera-scm-agent/agent-cert/cm-auto-host_keystore.jks -alias <hostname> -storepass <password> -rfc > keystore.pem
    2. Download or copy the generated keystore.pem file to your local machine.
    3. Import into IdP:
      1. Navigate to your client configuration in the IdP.
      2. Go to the Keys tab.
      3. Click Import Key and select the keystore.pem file.
  10. Restart Ranger Admin. 
    cm -> Ranger -> Action -> restart
  11. Verify the setup.
    1. Check catalina.out for successful startup: 
      tail -f <ranger-admin-log-dir>/catalina.out | grep -i "saml\|error\|severe"
      You should see:
      RangerApplicationContextInitializer: activating 'saml' Spring profile
Starting ProtocolHandler ["https-jsse-nio-<port>"]
    2. Open a browser and navigate to: 
      https://<ranger-admin-host>:<port>

      You should be redirected to the Keycloak login page automatically.