====== Enabling single sign-on authentication (SSO) for Azure Active Directory (Azure AD) ======

===== Background Info =====

:!: This feature is available in Lucy 4.6 or newer version.

This article describes step by step instruction of the SSO integration with Azure AD. An additional information about what SSO in Lucy is designed for can be found [[sso_authentication|here]].

===== What preparations need to be done before connecting to Azure AD? =====

  * Upload or create an SSL certificate for Lucy Admin console - see [[ssl_configuration|this article]].

  * Make sure you have an Administrator account in Lucy (Settings > Users) with an email address that corresponds to your account in Azure Active Directory. Both accounts must have the same email address:

{{ ::sso_azure_user1.png?600 |}}

{{ ::sso_azure_user2.png?600 |}}

===== Enable Single sign-on in Lucy =====

  * Configure SAML-based single sign-on to your non-gallery application

Find more about Azure AD Single Sign-on configuration [[https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications|here]]

{{ ::sso_azure_enable_saml.png?600 |}}

  * Add a new non-gallery web app to your Azure AD, see more [[https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-non-gallery-app|here]]

{{ ::sso_azure_new_app.png?600 |}}

  * Open Lucy Admin console

  * Navigate to the **SSO Configuration** page (Settings > SSO Settings)

  * Tick the option "**Enable Active Directory FS**"

  * Download a pre-configured SAML metadata file (copy the URL and paste into your web browser address bar, change the extension of the file to .XML, for example "lucy-sp.xml")

{{ ::sso_azure_lucy_metadata_file.png?450 |}}

{{ ::sso_azure_lucy_metadata_file2.png?600 |}}

 
  * Upload the pre-configured SAML metadata file

{{ ::sso_azure_lucy_metadata_file3.png?600 |}}


  * Download the __FederationMetadata.xml__ file from Azure AD and fill the __Identity Provider__ Endpoint and __Certificate Thumbprint__ in Lucy

{{ ::sso_azure_lucy_configs.png?600 |}}

{{ ::sso_azure_lucy_configs2.png?400 |}}


  * Add a new Claim "__mail__" that contain an e-mail address of the user, see more [[https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-saml-claims-customization|here]]

{{ ::sso_azure_new_claim1.png?600 |}}

{{ ::sso_azure_new_claim2.png?600 |}}

**Note** :!: The attribute __user.mail__ is always empty if the user does not exist in your Office 365 Exchange server. Instead you will have to use the attribute __user.userprincipalname__ or other one that contains user's email address.

  * Configure Azure AD SAML token encryption, see more [[https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/howto-saml-token-encryption|here]]

{{ ::sso_azure_lucy_download_ssl.png?400 |}}

{{ ::sso_azure_import_ssl.png?600 |}}

:!: Do not forget to activate the encryption for the uploaded certificate

{{ ::sso_azure_import_ssl2.png?600 |}}

  * (**optional**) You may also configure a domain name that Azure AD will use to receive authentication requests. Azure supports both single domain and range of subdomains, however, for this you need to use a wildcard SSL certificate. By default, Lucy is configured to use system domain.

To enable support for the subdomains, set the value in the Domain field in the following way ".domain.com"

{{ ::sso_azure_domain_name.png?400 |}}

Using wildcard domain name will allow you to use different subdomains in your campaigns. \\
:!: Please note, Azure AD does not support multiple second-level domains in a single application.

  * (**optional**) If the option "**Auto Login**" enabled, Lucy tries to automatically log in using Single Sign-on instead of showing the Login page.

===== Testing Authentication =====

   * Make sure you have added users to your app

{{ ::sso_azure_users.png?600 |}}

   * Navigate to the **SSO Configuration** page in Lucy Admin console and click the button **Test Connection**:

{{ ::sso_azure_lucy_test1.png?600 |}}

  * You will be immediately forwarded to the Microsoft login page. Enter your username and password:

{{ ::sso_azure_lucy_test2.png?600 |}}

  * Once signed in, you will be bounced back to Lucy Admin console. If an error occurs, double-check everything and then check the Sign-ins page within the Activity section for hints as to what could have gone wrong. 

{{ ::sso_azure_login_activity.png?600 |}}

===== OAuth 2.0 =====

The method of authentication is described [[microsoft_azure_oauth_2_0|here]].

===== Troubleshoot problems =====

   * I am redirected back to Lucy's login page after successful authorization through the Single sing-on.
If you are getting back to the login page, try checking the Claim rules (see the section [[sso_azure#enable_single_sign-on_in_lucy|Enable Single sign-on in Lucy]], "Add a new Claim 'mail'..."). There must be a claim named "mail", with empty "Namespace" and Source attribute that contains user email address. For example:

{{ ::sso_azure_new_claim3.png?600 |}}