SSO between externally hosted web applications and Azure AD can generally be achieved via the use of either SAML (Security Assertion Mark-up Language or OIDC (OpenID Connect). These are the most widely used federation protocols for this purpose. 


OIDC is built on top of the OAuth2.0 framework. The flows of both protocols are very similar but in differ in areas such as terminology etc. Another key difference is the response returned from the Identity provider to the Service Provider. 


With SAML the response is a large XML mark-up containing information about the authenticating party and various attributes about the identity that has been authentication. Similar information is returned in OIDC but in the form of a base64 encoding known as id_token.  Attributes about the authenticated identity are returned in what is known as claims.


Another difference between the authentication flows is that the OIDC flow will always ask the user for consent before passing information to the Service Provider. This consent prompt also informs the user as to what information will be made available to the service provider. This helps with data privacy regulations such as GDPR.


SafeTitan supports the OIDC federation protocol for SSO integration with Azure AD. The configuration steps for setting up this integration are listed below. It is broken into 3 steps:


  1. Register Application in Azure AD
  2. Configure the Reply Urls against the Application Registration in Azure AD.
  3. Update Authentication Settings in your SafeTitan portal.


NOTE: The Same Application Registration can be used for both Azure AD SSO and Azure AD Synchronization. 


Register Application in Azure AD



The first step is to register the SafeTitan application within your Azure Active Directory. This will generate an application id and allow for your application to receive security tokens. Basically, when the SafeTitan application provides the generated application ID during the authentication flow, Azure AD will provide a level of trust by providing the authenticated security token to SafeTitan to progress with login. The steps involved in registering the application are listed below:


  • Sign in to your Azure portal: https://portal.azure.com
  • Choose your Azure AD tenant by clicking on your account in the top right corner of the page, followed by clicking on the Switch Directory navigation and then select the appropriate tenant.

    • You may skip this step if you've only one Azure AD tenant under your account or if you've already selected the appropriate Azure AD tenant. 
    • Click the X underneath your user details as below to return to your Azure homepage.


  • From the homepage, click on Azure Active Directory.



  • Click on App Registrations and click on New application registration.


  • Set the following values in the form:
    • Name: SafeTitan
    • Supported Account Types:  Default option
    • Redirect URI: https://{your domain name}.safetitan.com (example https://mycompany.safetitan.com) – This will be your SafeTitan portal URL




  • Once you've completed registration, Azure AD will assign your application a unique client identifier, the Application ID. You need this value in the next sections, so copy it from the application page. The Application ID can be found on the Overview screen of your App registration. Take note of this value. 


Generate Application Secret

The next step is to generate an application secret. Your SafeTitan instance will use this value to prove its identity when connecting to Azure.


  • Select the Certificates & Secrets tab.




  • In the next screen, click New client secret. Provide a description and select an expiration date.

  • Once you've created the Client Secret, please take note of the secret value (and NOT the secret ID), as this field will be needed when configuring the Authentication Settings on the SafeTitan portal.


Configure the Reply URLs against the Application Registration in Azure AD


The next step is to assign the allowed reply URLs to your app registration. This basically means telling the app registration in your Azure AD what URLs are allowed to be redirected to upon successful authentication with the AD.




  • In the overview section, you will be see your Application (Client) ID. Please take note of this as you will need it later.


  • In the Authentication Section of the app registration enter and save the following URIs for the Redirect URIs


        https://{your domain name}.safetitan.com/auth/osignedin (example would be https://mycompany.safetitan.com/auth/osignedin)

        https://{your domain name}.safetitan.com (example would be https://mycompany.safetitan.com)




  • Finally, also with in the Authentication section, in the Advanced Settings mark the check box for ID Tokens. This ensures the ID Token is passed to the SafeTitan portal.

Click save.



Configuration on SafeTitan


The last step is to add the minimal configuration needed to your SafeTitan portal.  


  • Login to your SafeTitan portal as an administrative user.
  • From the menu on the left, select Settings and then Authentication Settings

  • From the Authentication Type drop-down, select OpenIdConnect.




The common in the url denotes Microsoft’s common gateway, meaning the indirect path to login.

                When the common is replaced with the tenant id, it’s a direct path to their tenant to login.


                Both will work but using the common means the tenant isn’t initially identified until the user enters their email, it                     just means there is an extra step involved.

  • Client Id: This should be the Application Id you will have been provided with from Azure i.e. The Application Id from creating the Application Registration in Azure.

  • Client Secret: This is the password/secret value generated when creating your app registration above.

  • Domain Hint: your-domain.com

  • Username Claim: This will default to preferred_username if left blank, but it can be updated to a claim of your choosing, an example of the UPN claim would be: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

  • Click Save


Note: These changes may take up to 24 hours to take effect.

 

That said, they usually are in place after an overnight refresh, so you should see a change on the morning of the next day. If a full 24 hours has elapsed and you see no change, please contact support.


This concludes the setup.