Microsoft Windows Active Directory

Microsoft Windows Active Directory (AD) provides identity based access controls for a wide range of Microsoft products. You host Windows AD, either in your Azure tenant or on your premises. With Windows AD, you can authenticate third party extranet applications such as Databricks using Windows Active Directory Federation Services (AD FS). AD FS uses SAML 2.0.

This article shows how to configure AD FS as the identity provider for Databricks. To use Azure Active Directory hosted in your Azure tenant for SSO with Databricks, see Microsoft Azure Active Directory.

Note

  • The following guide is for configuring AD FS integration using Windows Server 2012 R2 Active Directory Federation Services version 6.3.0.0. Existing customers who need support for other versions of AD FS or Azure Directory Services can contact help@databricks.com. If you are a new customer, contact sales@databricks.com.
  • Windows AD typically uses a short employee ID or employee username as the authentication principal, rather than an email address. When a user logs in to Databricks, the user’s workspace directory is automatically appended to the username to create an email address. For example, the username john.doe might become john.doe@example.com.
  • Time synchronization issues can lead to a situation where all AD FS logins are invalidated. Make sure the clock on your AD FS server is updated.
  • If you are having trouble enabling AD FS SSO and your organization uses multiple certificates, contact Databricks at help@databricks.com (for existing customers) or sales@databricks.com (for new customers).

Requirements

  • Install and configure the following Windows services:

    • Windows Domain Server
    • Windows DNS Service
    • Microsoft IIS
    • Windows AD
    • Windows AD FS

    For details on configuring these services, see Microsoft KB c66c7f4b-6b8f-4e44-8331-63fa85f858c2.

  • Install a signed SSL certificate for your AD FS login page and the fingerprint for that certificate.

  • Verify that all user objects in AD have an email address attribute. This is required to map AD users to Databricks users.

  • In Databricks, make a note of the SAML URL.

    1. As an administrator, go to the admin console.
    2. Go to Single Sign On.
    3. Copy the Databricks SAML URL.

Configure AD FS

Configure the AD FS Federation service

  1. Go to the AD FS management console.

    ActiveDirectory Federation Services Management console
  2. Click Edit Federation Service Properties on the right side action bar.

  3. Verify that the federation service name and identifier both match the DNS entry for the environment. The following example doesn’t use a custom DNS entry:

    Edit Federation Service Properties
  4. Databricks uses SAML 2.0 as the standard authentication mechanism. To verify that your AD FS service supports SAML 2.0, go to AD FS > Service > Endpoints and confirm that the URL Path /adfs/ls exists.

    Confirm /adls/fs URL path
  5. The first time you configure AD FS to authenticate a client outside of your corporate intranet, you must enable Intranet Forms Authentication.

    1. Go to AD FS Management application > AD FS > Authentication Policies > Edit Global Authentication Policy.
    2. Select Intranet Forms authentication.
    Intranet Forms authentication
  6. To view the SSO page for your organization, go to https://<your-sso-domain>.com/adfs/ls/idpinitiatedsignon.

Configure the trust relationship

To add Databricks as a relying party trust:

  1. Go to AD FS > Trust Relationships > Relying Party Trusts.

  2. Follow the instructions to create an AD FS relying party trust.

  3. Set Display name to Databricks.

  4. If desired, enter information in Notes.

  5. Click Next.

  6. Click AD FS profile.

    Select AD FS profile
  7. Configure a certificate for encryption between AD FS and Databricks.

    Configure certificate
    1. Under Configure URL, click Enable support for the SAML 2.0 WebSSO protocol.

    2. Enter the Databricks SAML URL you copied in Requirements.

      Configure URL
    3. In Configure Identifiers, enter the Databricks SAML URL again.

      Configure Identifiers
    4. Click Add to add another identifier. Enter the Databricks workspace URL, such as https://<databricks-instance>.cloud.databricks.com.

  8. Next to Configure Multi-factor Authentication …, select I do not want to configure ….

    Configure Multi-factor Authentication
  9. Under Choose Issuance Authorization Rules, select Permit all users to access this relying party. After the testing period, you can update this setting to selectively allow Active Directory groups or members to access Databricks.

    Choose Issuance Authorization Rules

    Click Next.

  10. Review the configuration.

    Review configuration
  11. Leave Open the Edit Claim Rules … selected, then click Close to finish adding the relaying party trust.

    Complete add Relying party trust

    Keep this dialog open and continue to Add transform claim rules.

Add transform claim rules

Claim rules in AD FS map user objects in Windows AD to users in Databricks. To create a claim rule to map users based on their email addresses:

  1. If necessary, click Relaying Party Trusts and click Databricks.

  2. In the right actions bar, click Edit Claim Rules, then click Add Rule.

  3. Click Send LDAP Attributes as Claims.

    Send LDAP Attributes as Claims
    1. Set the Claim Rule Name to Outgoing Databricks LDAP Email.
    2. Set the Attribute Store to Active Directory.
    3. Select the LDAP attribute used by your company for email addresses. The default is E-Mail Addresses. Map it to Name ID and E-Mail Address:
    Configure claim rule name
  4. Click Finish.

  5. Click Add Rule to add another rule.

  6. Set Claim Rule Template to Transform an Incoming Claim.

    Add rule
    1. Set Claim Rule Name to Incoming Databricks LDAP Email.
    2. Set Incoming claim type to E-Mail Address.
    3. Set Incoming name ID format to Unspecified.
    4. Set Outgoing claim type to Name ID.
    5. Set Outgoing name ID format to Email.
  7. Click Pass through all claim values.

    Pass through all claim values
  8. Click Finish.

  9. Click Apply then Ok to return to the main screen.

Change Signature to SHA-256

  1. On the AD FS Relying Party Trusts screen, select Databricks.

  2. Click Properties on the Action bar.

    Configure Databricks properties
  3. Go to the Advanced tab.

  4. Set Secure hash algorithm to SHA-256.

    Set secure hash algorithm

Copy the AD FS service certificate

  1. From the AD FS Management Console go to AD FS > Service > Certificates.
  2. Find the Token-signing certificate. Click View Certificate in the action sidebar. View certificate
    1. Click the Details tab.
    2. Click Copy to File.
    3. Choose Base-64 encoded X.509 (.CER) when prompted.
    4. Open the file with Notepad or another text editor.
    5. Copy the text between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

(Required) Configure signing of the SAML response

To configure signing of the SAML response and the SAML assertion within it, use the following PowerShell command. If your relying party trust is not named Databricks, set -TargetName accordingly.

Set-ADFSRelyingPartyTrust -TargetName Databricks -SamlResponseSignature “MessageAndAssertion”

For more information about this requirement, see Requirements for different SSO versions.

Configure Databricks

As a Databricks administrator:

  1. Go to the admin console.

  2. Go to the Single Sign On tab.

    SSO tab
  3. Set Single Sign-On URL to https://<your-sso-domain>.com/adfs/ls/.

  4. Set Identity Provider Entity ID to https://<your-sso-domain>.com/adfs/services/trust.

  5. Paste the certificate from Copy the AD FS service certificate into the X.509 Certificate field.

  6. Click Enable SSO.

  7. Optionally, click Allow auto user creation.

Test the configuration

  1. In an incognito browser window, go to your Databricks workspace.
  2. Click Single Sign On. You are redirected to AD FS.
  3. Enter your AD FS credentials. If SSO is configured correctly, you are redirected to Databricks.

If the test fails, review Troubleshooting.