Single Sign-on: Integration with ADFS for Safelink

In this article, we will cover how to integrate Safelink with ADFS for single sign-on. The information below is intended for IT professionals.

We will cover:

• Integration requirements

• Configuration

• What information you will need

• How to configure Safelink and ADFS

Requirements

1. Active Directory Federation Services (ADFS) version 2.0 or above must be installed on your network. This is where we will redirect your users in order to authenticate them as part as part of an SSO login, and the ADFS server will contact your Active Directory server to check the credentials.
   1. On Windows Server 2008 R2, the latest version of ADFS you can install is version 2.0. It is not included within the normal installation of Windows Server 2008 R2, but is available as a free add-on from Microsoft at the following URL: http://www.microsoft.com/en-ca/download/details.aspx?id=10909
   2. On Windows Server 2012 R2, use ADFS 3.0. 2.
2. Your ADFS instance must be externally accessible, using HTTPS on its own domain name, and with its own SSL/TLS certificate, in order to allow your users to authenticate from outside your firewall. This is not the same certificate that would be used by the ADFS server for signing the security tokens that it issues. 

Setting up Safelink as a Relying Party

To allow Safelink to authenticate against your ADFS server, you need to create a “Relying Trust” in ADFS, within which you will need to define a number of specific claims. Instructions for doing so are shown below. Before that will work, we need to apply a matching configuration on our side.

Information you need to provide to us

Please send the following information to support@safelinkhub.com:

1. Single Sign-On URL

   • eg. "https://sso.yourdomain.com/adfs/ls”

   • For ADFS 2.0 and 3.0, this can be found in the ADFS Management Console under [Service] > [Endpoints] > [The URL of the endpoint with type "SAML 2.0/WS-Federation”]

2. Single Logout Service URL

   • eg. "https://sso.yourdomain.com/adfs/ls/?wa=wsignout1.0”

   • This is normally derived from the SSO URL, but if you’ve overridden this, please provide the updated value.

3. Entity ID (of the ADFS deployment)

   • eg. "http://sso.yourdomain.com/adfs/services/trust”

   • For ADFS 2.0 and 3.0, this can be found in the ADFS Management Console under [Service] > [Edit Federation Service Properties] > [General Tab] > [Federation Service Identifier field]

4. The SHA1 fingerprint of the X509 token signing certificate for the ADFS instance

   • eg. “90 C3 16 F0 8D …”

   • For ADFS 2.0 and 3.0, this can be found in the ADFS Management Console under [AD FS] > [Service] > [Certificates] > [Token-signing] > [View Certificate] > [Details Tab] > [The value of the field named Thumbprint]

5. Email domain name(s) for users who will be allowed to authenticate through this setup.

   • eg. "yourdomain.com"

Information you will need

Note that in each case below, clientname must be replaced with the client name given to you by us, and safelinkhostname must be replaced with the fully qualified internet domain name of your Safelink deployment, which might be at a shared or a custom domain.

• ACS URL (aka. “Relying Party SAML 2.0 SSO Service URL”):

Example:  https://app.safelinkhub.com/auth/saml/clientname/callback

• Logout URL:

Example: https://app.safelinkhub.com/auth/saml/clientname/slo

• Entity ID (aka. "issuer")

Setting up the Relying Party Trust for Safelink in ADFS 2.0

1. Goto [ADFS 2.0 manager] > [Trust Relationships] > [Relying Party Trusts] > [Add Relying Party Trust]

2. Data source: Choose to enter data about the relying party manually

3. Display name: Choose a suitable display name, eg. Safelink Data Rooms

4. Profile: Choose the AD FS 2.0 profile

5. Certificate: Press Next to continue (the claims are encrypted using HTTPS so tokens do not need to be separately encrypted)

6. Configure URL: Choose to “Enable Support for the SAML 2.0 WebSSO Protocol”, and enter the ACS URL supplied above

7. Identifiers: Add the entity ID supplied above (“safelinkdatarooms.com”)

8. Issuance Authorization Rules: Permit all users to access this relying party

9. Ready to Add Trust: Press Next to continue.

10. Finish the setup to create the new Relying Party Trust.

Setting up the Relying Party Trust for Safelink in ADFS 3.0

1. Goto [AD FS] > [Trust Relationships] > [Relying Party Trusts] > [Add Relying Party Trust]

2. Data source: Choose to enter data about the relying party manually

3. Display name: Choose a suitable display name, eg. Safelink Data Rooms

4. Profile: Choose the AD FS profile

5. Certificate: Press Next to continue (the claims are encrypted using HTTPS so tokens do not need to be separately encrypted)

6. Configure URL: Choose to “Enable Support for the SAML 2.0 WebSSO Protocol”, and enter the ACS URL supplied above

7. Identifiers: Add the entity ID supplied above (“safelinkdatarooms.com”)

8. Multi-factor Authentication: Choose “I do not want to configure multi-factor authentication settings for this relying party trust at this time”.

9. Issuance Authorization Rules: Permit all users to access this relying party

10. Ready to Add Trust: Press Next to continue.

11. On the Finish screen, finish creating the Relying Party Trust, and do not choose to “Open the Edit Claim Rules dialog”.

12. Open the Properties dialog for the new Relying Party Trust, under [AD FS] > [Trust Relationships] > [Relying Party Trusts] > [Safelink Data Rooms] > [Properties].

13. Under the [Endpoints] tab, click [Add SAML]

14. Add an endpoint of type “SAML Logout”, with binding “POST”, and for the Trusted URL, enter the Single Logout Service URL you provided to us earlier, eg. https://sso.yourdomain.com/adfs/ls/?wa=wsignout1.0

15. Under the [Advanced] tab, ensure that the “Secure Hash Algorithm” is chosen to be “SHA-256”.

Add claims for the new Relying Trust in ADFS 2.0

1. Open the claim rules editor (if not already opened from the previous step)

2. On the Issuance Transform Rules tab, choose to Add a Rule, and choose “Send LDAP Attributes as Claims". Name the rule “User Attributes”, or similar; use Active Directory as the Attribute Store, and add four mappings: "E-Mail-Addresses” as outgoing claim type “email” (type this, rather than choose it from the drop-down box); “Given-Name” as “first_name”, “Surname” as “last_name”, “Title” as “title".

3. On the Issuance Transform Rules tab, choose to Add a Rule, and choose “Send Claims using a Custom Rule”. Name the rule “User Secret”, or similar; the rule value should be [ => issue(Type = “user_secret”, Value = “a_secret_value”); ], without the square brackets. Replace a_secret_value with some other secret token known only to yourselves, and make a record of what you chose. The value you choose here is used as input to our encryption key generation routines and improves the security of your data. You may wish to write a more elaborate user-specific rule here (or refer to a field from AD or an SQL server). The value returned here must remain unchanged, for all users.

4. On the Issuance Transform Rules tab, choose to Add a Rule, and choose “Transform an Incoming Claim”. Name the rule “Generate NameID”, or similar. The “Incoming Claim Type” should be “email”; “Outgoing Claim Type” should be “Name ID”, Outgoing name ID format should be “Persistent Identifier”. Choose to “Pass through all claim values”.

Add claims for the new Relying Trust in ADFS 3.0

1. Open the Claim Rules Editor the new Relying Party Trust, under [AD FS] > [Trust Relationships] > [Relying Party Trusts] > [Safelink Data Rooms] > [Edit Claim Rules]

2. On the Issuance Transform Rules tab, choose to Add a Rule, and choose “Send LDAP Attributes as Claims". Name the rule “User Attributes”, or similar; use Active Directory as the Attribute Store, and add four mappings: "E-Mail-Addresses” as outgoing claim type “email” (type this, rather than choose it from the drop-down box); “Given-Name” as “first_name”, “Surname” as “last_name”, “Title” as “title".

3. On the Issuance Transform Rules tab, choose to Add a Rule, and choose “Send Claims using a Custom Rule”. Name the rule “User Secret”, or similar; the rule value should be [ => issue(Type = “user_secret”, Value = “a_secret_value”); ], without the square brackets. Replace a_secret_value with some other secret token known only to yourselves, and make a record of what you chose. The value you choose here is used as input to our encryption key generation routines and improves the security of your data. You may wish to write a more elaborate user-specific rule here (or refer to a field from AD or an SQL server). The value returned here must remain unchanged, for all users.

4. On the Issuance Transform Rules tab, choose to Add a Rule, and choose “Transform an Incoming Claim”. Name the rule “Generate NameID”, or similar. The “Incoming Claim Type” should be “email”; “Outgoing Claim Type” should be “Name ID”, Outgoing name ID format should be “Persistent Identifier”. Choose to “Pass through all claim values”.