Setting up single sign-on using Active Directory with ADFS and SAML

Deployteq supports single sign-on (SSO) logins through SAML 2.0. A SAML 2.0 identity provider (IDP) can take many forms, one of which is a self-hosted Active Directory Federation Services (ADFS) server. ADFS is a service provided by Microsoft as a standard role for Windows Server that provides a web login using existing Active Directory credentials.

Requirements

To use ADFS to log in to your Deployteq instance, you need the following components:

  • An Active Directory instance where all users have an email address attribute.
  • A server running Microsoft Server 2012 or 2008. This guide uses screenshots from Server 2012R2, but similar steps should be possible on other versions.

After you meet these basic requirements, you need to install ADFS on your server. Configuring and installing ADFS is beyond the scope of this guide, but is detailed in a Microsoft KB article. 

Step 1 - Adding a Relying Party Trust

At this point you should be ready to set up the ADFS connection with your Deployteq account. The connection between ADFS and Deployteq is defined using a Relying Party Trust (RPT).

Select the Relying Party Trusts folder from AD FS Management, and add a new Standard Relying Party Trust from the Actions sidebar. This starts the configuration wizard for a new trust.

wizzard_start.png

  1. In the Select Data Source screen, select the option: Import data about the relying party from a file, and select the deployteq-metadata.xml you can download here.

    deployteq-metadata.xml 
    <?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://deployteq.net">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIEcjCCAtoCCQC8BLma3E3YizANBgkqhkiG9w0BAQsFADB7MQswCQYDVQQGEwJOTDEQMA4GA1UECAwHVVRSRUNIVDEXMBUGA1UEBwwOSHVpcyB0ZXIgSGVpZGUxEDAOBgNVBAoMB1RlYW1JVEcxDzANBgNVBAsMBkRldm9wczEeMBwGA1UEAwwVYXV0aC5jYW5vcHlkZXBsb3kubmV0MB4XDTIxMDIyNDA2MzQ1MloXDTMxMDIyNDA2MzQ1MlowezELMAkGA1UEBhMCTkwxEDAOBgNVBAgMB1VUUkVDSFQxFzAVBgNVBAcMDkh1aXMgdGVyIEhlaWRlMRAwDgYDVQQKDAdUZWFtSVRHMQ8wDQYDVQQLDAZEZXZvcHMxHjAcBgNVBAMMFWF1dGguY2Fub3B5ZGVwbG95Lm5ldDCCAaIwDQYJKoZIhvcNAQEBBQADggGPADCCAYoCggGBAN8BIsaRvWnijN350i0V2ldZmjg7o/huoXR6qfJil1BfzwSYIn6ky8lFDmD+kcpdcG+lCpELM6u72I+dvDS8heZOWhQxFQGlgMwbMgkOJS+y5pBf5EG4CRoo0tl8ASd0XrmH/+wdHX0jPYa/anp5b3FC2Sq5L00FaAK4V3/KqQtDxedR1c5zfleBqZ2lgwg83U+TARZajLXWXAbWUFt8cC1zF8gdaAPjcIjJpAZIyk4uTKATw9L/u/gS6j+kJdvKWbtqQcmSO5d9wUicJm7BJrhoJYF+fvuYxn1Ci7vW5JzmzcbL7P1V2qtRRlq8k0zdGD+QWjRSkQpiSDciR9LD01yCLMDEl8LBii8Dg2fpMtQdAyqrJVAPXgeG6tU3gFheoZmljSbR7wmJFiz5JFkySPbS8AlJveerRClb3PYG3VlIpKHCleRZm0xgM2TGnqO2/6mUN7oijJ0QRDb3Lj24Q0uDqqgYdE1O9tpNmjt3wKQc5JbgHS+ME4Txu1EdomPjXwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBgQCMmv1qKoBEg2WdECGLTe2XTYJxJInv8n72VoOk9agsmPm3L7MDsNz4NRB/0GH1IZ7RW8On6NA8Aw4O7odhuqTrITsLos/okpP1ermdFioBnhYD9OUoU2KBX4rldBmLOyGFFzjjHm+6s3t/xaep8hHEbFcqdOHVKn81DErqTkFeSux8LcnzxEPGGh6v68E5vDKcnwmiuTmUi1wC+0II0V0yXOWKBMy7bjBxnvHWE7kp1X6PE6ugNmHoCmg7Tx648v9y4IviaWdUSNNVKMAX09iFrzIko+98dK77L4NjUZhjiI0DkATOS2E9SjodnNZGxANnk6DxEWMeUY6IGFVQCeTtdQZ/P5dHAEoP1l6jDWAw0mE5yqsBasWoUdK2FkqjEsxkKzyA2uWIdPQPwVvUmyKtvbKBKwDXOrOyxfo/RL3KB/3Bef2NsPLb42SlB2rGhUziSvXc/7xDF899N/E6IEHfIH16i4ANjbrGm8t3X7Qk/KNUuGtyV+RObVdEqxki5M8=</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIEcjCCAtoCCQC8BLma3E3YizANBgkqhkiG9w0BAQsFADB7MQswCQYDVQQGEwJOTDEQMA4GA1UECAwHVVRSRUNIVDEXMBUGA1UEBwwOSHVpcyB0ZXIgSGVpZGUxEDAOBgNVBAoMB1RlYW1JVEcxDzANBgNVBAsMBkRldm9wczEeMBwGA1UEAwwVYXV0aC5jYW5vcHlkZXBsb3kubmV0MB4XDTIxMDIyNDA2MzQ1MloXDTMxMDIyNDA2MzQ1MlowezELMAkGA1UEBhMCTkwxEDAOBgNVBAgMB1VUUkVDSFQxFzAVBgNVBAcMDkh1aXMgdGVyIEhlaWRlMRAwDgYDVQQKDAdUZWFtSVRHMQ8wDQYDVQQLDAZEZXZvcHMxHjAcBgNVBAMMFWF1dGguY2Fub3B5ZGVwbG95Lm5ldDCCAaIwDQYJKoZIhvcNAQEBBQADggGPADCCAYoCggGBAN8BIsaRvWnijN350i0V2ldZmjg7o/huoXR6qfJil1BfzwSYIn6ky8lFDmD+kcpdcG+lCpELM6u72I+dvDS8heZOWhQxFQGlgMwbMgkOJS+y5pBf5EG4CRoo0tl8ASd0XrmH/+wdHX0jPYa/anp5b3FC2Sq5L00FaAK4V3/KqQtDxedR1c5zfleBqZ2lgwg83U+TARZajLXWXAbWUFt8cC1zF8gdaAPjcIjJpAZIyk4uTKATw9L/u/gS6j+kJdvKWbtqQcmSO5d9wUicJm7BJrhoJYF+fvuYxn1Ci7vW5JzmzcbL7P1V2qtRRlq8k0zdGD+QWjRSkQpiSDciR9LD01yCLMDEl8LBii8Dg2fpMtQdAyqrJVAPXgeG6tU3gFheoZmljSbR7wmJFiz5JFkySPbS8AlJveerRClb3PYG3VlIpKHCleRZm0xgM2TGnqO2/6mUN7oijJ0QRDb3Lj24Q0uDqqgYdE1O9tpNmjt3wKQc5JbgHS+ME4Txu1EdomPjXwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBgQCMmv1qKoBEg2WdECGLTe2XTYJxJInv8n72VoOk9agsmPm3L7MDsNz4NRB/0GH1IZ7RW8On6NA8Aw4O7odhuqTrITsLos/okpP1ermdFioBnhYD9OUoU2KBX4rldBmLOyGFFzjjHm+6s3t/xaep8hHEbFcqdOHVKn81DErqTkFeSux8LcnzxEPGGh6v68E5vDKcnwmiuTmUi1wC+0II0V0yXOWKBMy7bjBxnvHWE7kp1X6PE6ugNmHoCmg7Tx648v9y4IviaWdUSNNVKMAX09iFrzIko+98dK77L4NjUZhjiI0DkATOS2E9SjodnNZGxANnk6DxEWMeUY6IGFVQCeTtdQZ/P5dHAEoP1l6jDWAw0mE5yqsBasWoUdK2FkqjEsxkKzyA2uWIdPQPwVvUmyKtvbKBKwDXOrOyxfo/RL3KB/3Bef2NsPLb42SlB2rGhUziSvXc/7xDF899N/E6IEHfIH16i4ANjbrGm8t3X7Qk/KNUuGtyV+RObVdEqxki5M8=</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://auth.deployteq.net/saml2.0/module.php/saml/sp/saml2-logout.php/deployteq"/>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://auth.deployteq.net/saml2.0/module.php/saml/sp/saml2-logout.php/deployteq"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://auth.deployteq.net/saml2.0/module.php/saml/sp/saml2-acs.php/deployteq" index="0"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="https://auth.deployteq.net/saml2.0/module.php/saml/sp/saml1-acs.php/deployteq" index="1"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://auth.deployteq.net/saml2.0/module.php/saml/sp/saml2-acs.php/deployteq" index="2"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" Location="https://auth.deployteq.net/saml2.0/module.php/saml/sp/saml1-acs.php/deployteq/artifact" index="3"/>
  </md:SPSSODescriptor>
  <md:ContactPerson contactType="technical">
    <md:GivenName>Devops</md:GivenName>
    <md:EmailAddress>mailto:devops@deployteq.com</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>





  2. On the next screen, enter a Display name that you'll recognise in the future, and any notes you want to make.

    wizzard_label.png

  3. On the next screen, check the box labeled Enable Support for the SAML 2.0 WebSSO protocol. The service URL will be https://auth.clang.cloud/saml2.0/.

  4. On the next screen, you may configure multi-factor authentication but this is beyond the scope of this guide.

    wizzard_multi-factor.png
  5. On the next screen, select the Permit all users to access this relying party radio button.

    wizzard_auth.png

  6. On the next two screens, the wizard will display an overview of your settings. On the final screen use the Close button to exit and open the Claim Rules editor.

    wizzard_finished.png

Step 2 - Creating claim rules

Once the relying party trust has been created, you can create the claim rules and update the RPT with minor changes that aren't set by the wizard. By default the claim rule editor opens once you created the trust.

  1. To create a new rule, click on Add Rule. Create a Send LDAP Attributes as Claims rule.

    claim_LDAP_1.png

  2. On the next screen, using Active Directory as your attribute store, do the following:
    1. From the LDAP Attribute column, select E-Mail Addresses.
    2. From the Outgoing Claim Type, select E-Mail Address.

    claim_ldap_2.png

  3. Click on OK to save the new rule.

  4. Create another new rule by clicking Add Rule, this time selecting Transform an Incoming Claim as the template.

  5. On the next screen:
    1. Select E-mail Address as the Incoming Claim Type.
    2. For Outgoing Claim Type, select Name ID. 
            3. For Outgoing Name ID Format, select Email.
    Leave the rule to the default of Pass through all claim values.

    claim_transform_2.png

  6. Finally, click OK to create the claim rule, and then OK again to finish creating rules.

Note: Your instance of ADFS may have security settings in place that require all Federation Services Properties to be filled out and published in the metadata. Check with your team to see if this applies in your instance.  If it is, be sure to check the Publish organization information in federation metadata box.

Step 4 - Configuring Deployteq

After setting up ADFS, we need to configure your Deployteq account to authenticate using SAML. The SAML2.0 Metadata XML is available for download at https://adfshelp.microsoft.com/MetadataExplorer/GetFederationMetadata. Please download this XML file and send it to the Deployteq Support Desk or your contactperson. We will then enable SAML on your account and assist with testing.