How to configure ADFS for SSO

This topic details how to configure Microsoft Active Directory Federated Services (ADFS) for single sign-on (SSO).

This topic is part of Phase Two in Configuring SAML SSO authentication. For an overview of the complete process, see Working with SAML for single sign-on (SSO).

IMPORTANT  Before completing these steps, you will need to follow the steps in Prepare Venafi Platform for SAML SSO. You will need configuration information from the Venafi Service Provider Metadata XML file to complete this process.

ADFS is a common identity provider due to the integration with many organizations' existing identity infrastructure, while supporting SSO to cloud and other SaaS resources, even though ADFS typically sits behind the corporate firewall.

NOTE  These setup instructions were written based on Windows Server 2016. If your Windows server is different, there may be minor adjustments you need to make.

You must have an existing functional ADFS deployment to use these steps. These instructions detail how to add a new Application (Venafi Platform) to ADFS. The application is referred to in ADFS as a "Relaying Party Trust."

You will want to consult with your identity provider management team to determine who should be able to authenticate to Venafi Platform via ADFS. You'll need that information near the end of the procedure below.

IMPORTANT  While Venafi makes an effort to provide accurate information on third-party integration steps, these steps may differ for your service provider, especially as identity providers release new updates. If you have questions about how to use this third-party integration, we recommend you start with the vendor's documentation and support teams. These instructions should be considered a template, not definitive steps. Your specific steps may vary, depending on how your organization integrates with each third-party platform.

To configure ADFS for single sign-on

  1. Log in to your ADFS Windows server and launch AD FS Management console.
  2. In the Action Panel, click Add Relying Party Trust.
  3. Click Claims aware, then click Start.
  4. Select Import data about the relying party from a file.
  5. Click Browse, and browse to the location where you saved the Service Provider Metadata XML file (done in Prepare Venafi Platform for SAML SSO).
  6. Click Next.

  7. Provide the Application (Relying Party Trust) name, then click Next.

    For example, you could enter something like: Venafi Platform Production.

    TIP  If needed, you may want to differentiate between production, stage, and test environments.

  8. Select who within you organization will be able to authenticate to Venafi Platform via ADFS, based on your access control policy and your discussions with your identity team and your machine identity management (or PKI) team, then click Next.
  9. [Optional] Review, if desired, the data on the tabs on the Ready to Add Trust screen. These values were either set by you using the wizard, or were configured automatically from the Service Provider Metadata XML file you imported.
  10. Click Next.
  11. Leave Configure claims insurance policy for this application checked, then click Close.

  12. In the Edit Claim Insurance Policy window you configure how ADFS identifies a user within the SAML assertion, and should match exactly the User Search Expression you used for Venafi Platform in Phase 1.3: Configure SAML user search expression.

    For example, if your search expression is (&(|(ANR=$search$)(userPrincipalName=$search$))(objectCategory=$userclass$)) then you are expecting a UPN to be specified in the SAML assertion created by ADFS.

    If your search expression is (&(|(ANR=$search$)(mail=$search$))(objectCategory=$userclass$)) then you are expecting an email address to be specified in the SAML assertion.

    TIP  Active Directory does not enforce uniqueness of the email field, so be careful to choose attributes that are guaranteed to uniquely identify a user.

  13. Click Add Rule...
  14. Click Send LDAP Attributes as Claims, then click Next.

  15. On the Configure Claim Rule tab, do the following:

    1. Give the rule a descriptive name.
    2. For the Attribute Store, select Active Directory.
    3. For LDAP Attribute, select User-Principal-Name (or whatever selection best matches your user search expression.)
    4. For Outgoing Claim Type, select Name ID.
    5. Click Finish.
  16. Click your rule in the list, then click OK.
  17. Open a PowerShell prompt (run as Administrator) on the ADFS server.

  18. Enter the following command, replacing '<Name goes here>' with the name you gave your application earlier in the process:

    Get-AdfsRelyingPartyTrust -Name '<Name goes here>' |Set-AdfsRelyingPartyTrust -SamlResponseSign MessageAndAssertion

    For example, if you used the name from our example, you would use the following PowerShell command:

    Get-AdfsRelyingPartyTrust -Name 'Venafi Platform Production' |Set-AdfsRelyingPartyTrust -SamlResponseSign MessageAndAssertion

    This command sets an option that is not exposed in the ADFS UI to sign all SAML responses, which is a requirement of Venafi Platform.

  19. From your ADFS server, open a web browser and visit:

    https://localhost/federationmetadata/2007-06/federationmetadata.xml

    We refer to this file as the IDP Metadata XML file in our documentation.

  20. Download the federationmetadata.xml file to your Venafi Platform server as an XML file.

You are ready to finish configuring SSO in Venafi Configuration Console. See Importing Identity Provider Metadata XML into Venafi Configuration Console for SAML.