Skip to main content
Version: v4.1

SSO with ADFS

With Cyral, you can authenticate database users against your Active Directory Federation Service (ADFS) identity provider running in Windows Server 2016. Optionally, Cyral can read each user's group memberships from ADFS to determine the user's privileges.

Follow these steps to use your ADFS instance to authenticate database users and Cyral administrators. During this set up, you will configure a Relying Party Trust that connects ADFS and Cyral.

info

If you're using Azure AD, see the section, SSO with Azure AD.

Prerequisites​

Make sure the following prerequisites are in place:

  • You're running Windows Server 2016 Datacenter edition
  • ADFS is activated
  • SSL is configured. Cyral does not recommend using a self-signed certificate. If a self-signed certificate is to be used, it must be correctly configured (see for example, these steps.)
  • Forms authentication is active for the ADFS server that will receive calls from Cyral. (You have the option to customize it as described here.)

Get ADFS properties​

  1. In the Active Directory Server Manager, go to AD FS Management.
  2. Click on AD FS and choose Edit Federation Service Properties.
  3. Note the values for
    • Federation Service display name
    • Federation Service name
    • Federation Service identifier

You will need these values later.

Add a relying party trust in ADFS​

  1. In the Active Directory Server Manager, go to AD FS Management.

  2. Create a connection for Cyral by adding a relying party trust. Click AD FS: Relying Party Trusts: Add Relying Party Trust



  3. Select Claims aware and click Start.

  4. Choose Enter data about relying party manually and click Next.

  5. Give this trust a Display name and click Next.

  6. In Configure certificate, leave the certificate blank. Since communication will already be conducted over SSL and signed by a certificate, no additional layer of encryption is needed.

  7. Enable SAML 2.0 WebSSO support. For the Relying party SAML 2.0 SSO service URL. We call this the endpoint; it's the SAML 2.0 endpoint provided by the Cyral control plane. Use an address in this format:

    https://$CYRAL_CONTROL_PLANE_DOMAIN/auth/realms/default/broker/adfs-2016.$FEDERATION_SERVICE_NAME/endpoint

    Where $CYRAL_CONTROL_PLANE_DOMAIN is the domain of your Cyral control plane, and $FEDERATION_SERVICE_NAME is the name you copied from the Federation Service Properties window in the previous section.

    For example,

    https://example.app.cyral.com/auth/realms/default/broker/adfs-2016.my_federation_service.com/endpoint

    Click Next.

  8. Enter a Relying party trust identifier that points to the Cyral control plane. This has the following format:

    https://$CYRAL_CONTROL_PLANE_DOMAIN/auth/realms/default

    For example,

    https://example.app.cyral.com/auth/realms/default

  9. In the Access Control Policy, choose Permit everyone and proceed through the wizard without further edits.

Set up claims​

You must create two claims as shown below. Values shown are case-sensitive.

  1. Still working in the Active Directory Server Manager's AD FS Management section, navigate to AD FS: Relying Party Trusts.

  2. Find the Cyral relying party trust entry that you created in the preceding section. Right click its name and choose Edit Claim Issuance Policy.



  3. Add or edit the Inbound Claim rule, choosing the values as shown below.



    Set the following:
    • Claim rule name: Inbound
    • Incoming claim type: UPN
    • Outgoing claim type: Name ID
    • Outgoing name ID format: Transient Identifier
    • Choose Pass through all claim values

  4. Click OK.

  5. Add or edit the Outbound Claim rule, choosing the values as shown below.



    Set the following:
    • Claim rule name: Outbound
    • Attribute store: Active Directory
    • User-Principal-Name: UPN
    • E-Mail-Addresses: Email
    • Given-Name: FirstName
    • Surname: LastName
    • Token-Groups - Unqualified Names: Groups

  6. Click OK.

Get SAML metadata​

Now that you've saved your SAML configuration in ADFS, you can retrieve the SAML metadata file from your ADFS instance.

  1. In your browser, navigate to the SAML metadata file address on your ADFS instance. This address uses the same base URL as the Federation Service name you noted in your Federation Service Properties earlier. It has the format:

    https://$FEDERATION_SERVICE_NAME/FederationMetadata/2007-06/FederationMetadata.xml

    For example:

    https://my_federation_service.com/FederationMetadata/2007-06/FederationMetadata.xml
    tip

    If this document is not available, it's likely that setup hasn't been completed correctly, or that the ADFS server isn't reachable, and debugging should be performed.

    The SAML metadata file is a single-line XML document. Here's a partial example:

    <EntityDescriptor ID="_t55a1ea-c11b-4091-9555-562026ed5d75" entityID="http://EC2AMAZ-5554MQA.ad.example.com/adfs/services/trust" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">...

  2. Download this document to your desktop.

Your configuration in ADFS is nearly complete. You'll return to ADFS later to add the Cyral SAML certificate.

Add your ADFS as an IdP in Cyral​

In this section, you'll register your ADFS instance as an SSO identity provider (IdP) in Cyral so your users can choose it and authenticate against it.

  1. Open the Cyral control plane UI in your browser, click Integrations, find the Microsoft Active Directory Federation Services tile, click Configure and click New Integration.

  2. Provide a Display Name for this SSO provider. This is the name your users and administrators will see when they use or set up this SSO provider.

    caution

    Once you've set this name, you cannot change it without deleting and recreating this SSO configuration.

  3. Choose your ADFS version in the dropdown. Currently, Cyral supports Windows Server 2016 Datacenter.

  4. In the Upload the SAML metadata document section, click Upload a file and choose the SAML metadata file you saved to your desktop in the preceding section.

  5. Click Save.

  6. Click the download icon to download the Cyral SAML certificate, and save it to your desktop.



In the next section, you'll add this certificate to your ADFS instance. This connection won't work until you've added the certificate in ADFS.

Add Cyral SAML certificate to ADFS​

In this section, you'll add the Cyral SAML certificate as the signature certificate for your Cyral relying party in ADFS.

  1. In the Active Directory Server Manager's AD FS Management section, navigate to AD FS: Relying Party Trusts.
  2. Find the Cyral relying party trust entry and right click its name and choose Properties.

  3. In the Properties window, click the Signature tab, click Add, and upload the Cyral SAML certificate you saved in the preceding section.

  4. Click Apply.

Your setup is complete. Your ADFS instance is now configured as an SSO provider in Cyral.

Next step​

See Set up SSO authentication for users for the steps to activate SSO authentication on each repository that will use it.