Single Sign-on: Integration with Azure AD for Safelink

In this article, we will cover how to integrate Safelink with Azure AD 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

• How to assign users and groups

Requirements

1. A subscription to Azure that includes Azure Active Directory (Azure AD). We will redirect your users to AD in order to authenticate them as part of a Single Sign-On (SSO) login.

2. Users that need to access Safelink must have email addresses defined in Azure AD.

3. All user email addresses must belong to domains that Azure AD considers to be verified and enabled for email. If this is not the case, Azure AD will not include these email addresses in its SAML responses, and authentication will fail. 

Configuration

To allow Safelink to authenticate against Azure AD, settings need to be added in both the Azure management portal and also within Safelink by the Safelink Support Team. Instructions for doing your part are shown below.

Please note that we are in the process of adding Safelink to the Azure application gallery, at which point these instructions will be updated. In the meantime, Safelink can be added as an Unlisted Application.

Information you will need

You will need the following information (in points a through d) to complete the configuration in the next step.

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.

A. Sign-On URL

Example: https://app.safelinkhub.com/redirect/mycompany

B. Identifier (aka. “Entity ID”, or "issuer")

Even if you have a custom domain name, you should still use the above value.

C. Reply URL (aka. “ACS URL”)

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

D. Logout URL

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

Configure Safelink and your Azure AD instance to recognise each other

The following instructions are a summary of the relevant sections of this guide:
https://docs.microsoft.com/en-us/azure/active-directory/active-directory-saas-custom-apps

1. Sign into the Azure management portal using your Azure Active Directory administrator account.

2. Browse to the Azure Active Directory > [Your Directory] > Enterprise applications section, select New Application, and then choose the All category.

3. Choose the All category and then click Non-gallery Application.

4. Enter Safelink as the name for the application and continue. You should see confirmation that the application has been added, and be taken to the Enterprise Application panel for the new Safelink application.

5. Click Single Sign-on.

6. When asked how you would like users to sign on, choose SAML-based Sign-on.

7. Enter the Identifier and Reply URL. These are shown in the “Information you will need” section above.

8. Tick the Show advanced URL settings box.

9. Enter the Sign on URL value. This is also included the “Information you will need” section above.

10. In the User Attributes section, choose the User Identifier to be user.mail.

11. Tick the View and edit all other user attributes tickbox.

12. Use the Add Attribute button to add four new claims. In each case, leave the Namespace blank: 

    • Attribute name: email (type this directly)

    • Attribute value: user.mail (choose this from the dropdown box)
      
      

    • Attribute name: first_name (type this directly)

    • Attribute value: user.givenname (choose this from the dropdown box) 
      
      

    • Attribute name: last_name (type this directly) 

    • Attribute value: user.surname (choose this from the dropdown box)
      
      

    • Attribute name: title (type this directly) 

    • Attribute value: user.jobtitle (choose this from the dropdown box) 

13. Optionally, use Add Attribute again to define a secret value or phrase that is known only to your organisation. The value you choose here is used as input to our encryption key generation routines and improves the security of your data. The value returned here can be different for each user or can be the same for all users, but for any given user, it must remain unchanged forever. If you choose to add this claim, it is critically important that you record the value you choose so that future administrators can recreate this setup. If this claim is supplied but later lost, permanent data loss may occur. 

    • Attribute name: user_secret

    • Attribute value: your secret value 

14. Under the SAML Signing Certificate section of the form, you should be given an opportunity to download a certificate. Use the Certificate (Base64) download option to do so. 

15. Copy/paste the certificate thumbprint into an email for later reference; this is often a 40 character long hexadecimal string, which will look something like this: AB123456FEDCBA2345CDEF6789ABCD1234ABCD01. It may be longer in some cases, and it may also contain colon (":") characters.

16. Tick the Make new certificate active tickbox. 

17. Click the Configure Safelink link at the bottom of the form to continue. 

18. You will reach a screen that allows you to download a certificate, and shows you a SAML Entity ID, a Single Sign-On Service URL and a Single Sign-Out URL.

19. Please send, via email to support@safelinkhub.com, the following information obtained from the previous step:

    • The Single Sign-On Service URL from the Azure AD service. This normally looks something like the following, where the XXX part are hexadecimal digits, forming a UUID:
      https://login.microsoftonline.com/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/saml2

    • The Single Sign-Out URL. This normally looks like:

      https://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0

    • The certificate thumbprint. This is the hexadecimal string of 40 or more characters. 

    • The downloaded certificate

    • A list of all email domains (usually just one) for the users that will authenticate, eg. @mycompany.com 

     

20. Press Save (shown above the form).

21. We will respond with confirmation that the configuration has been applied.

22. When this is complete, proceed to assign users and groups as described below.  

Assign users and groups

Before users can access Safelink via Azure AD, you will need to “assign” them to the Safelink application.

1.  Within the Azure management portal, go to Azure Active Directory > [Your Directory] > Enterprise applications > All Applications section and choose Safelink.

2. Choose the Users and Groups option and click Add User.

3.  Select a user, group or role to assign to Safelink, and click Assign.