LUCY

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Single sign-on authentication (SSO) ======

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

:!: This feature is available in Lucy 4.6 or newer version. \\
:!: We do not recommend using Let's Encrypt certificates with an SSO provider due to the short live term of charge-free certificates. 

Lucy allows you to set the SSO authentication by using the Lightweight Directory Access Protocol (LDAP) to access Admin console and EndUser portal. This also allows you to use a non-unique link for the awareness website within a campaign.

In general terms, SSO in Lucy can be used for:
  * authorization on Lucy’s admin console and End-User portal:
  * to identify users on awareness website.

===== Where can this be configured? =====

To use SSO in Lucy you should have installed [[https://docs.microsoft.com/en-us/windows/desktop/srvnodes/active-directory-federation-services|Active Directory Federation Services]] (AD FS) on your Windows server. Lucy uses [[https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language|Security Assertion Markup Language 2.0]] (SAML 2.0) for exchanging authentication and authorization data, which supports the following versions of AD FS:

  * ADFS 2.0 (Windows Server 2008 and Windows Server 2008 R2)
  * ADFS 2.1 (Windows Server 2012)
  * ADFS 3.0 (Windows Server 2012 R2)
  * ADFS 4.0 (Windows Server 2016)
  * ADFS 5.0 (Windows Server 2019)
  * Azure AD (refer to [[sso_azure|this guide]] to have a detailed instructions)
  * Okta (refer to [[sso_okta|this guide]] for more details)

The connection to the AD FS can be configured within the Settings / SSO Configuration: 

{{ ::sso_configuration_menu.png?500 |}}

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

  * 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 Windows account in Active Directory. Both accounts must have the same email address:

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

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

  * Download the __FederationMetadata.xml__ file from your AD FS server. Log in to Windows Server > open **Server Manager** > click **Tools** > click **AD FS Management** > expand **Service** and select the **Endpoints** node:

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

For example, your Federation Service is located at https://fs.domain.tld/, then the link to download the __FederationMetadata.xml__ file looks like: https://fs.domain.tld/FederationMetadata/2007-06/FederationMetadata.xml

  * Open a browser and navigate to the __FederationMetadata.xml__ location where you’ll be prompted to save the file to disk.

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

  * Navigate to the **SSO Configuration** page
  * Active the option "**Enable Active Directory FS**"
  * Insert the URL in to the field **Identity Provider Endpoint**:

The URL of **Identity Provider Endpoint** can be taken from the __FederationMetadata.xml__ file we downloaded earlier:

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

  * Select the __FederationMetadata.xml__ file in to the field **Identity Provider Server XML metadata**.
  * Insert the __Thumbprint__ information in to the field **Identity Provider Certificate Thumbprint**:

The __Certificate Thumbprint__ can be taken from the AD FS server. Open **Server Manager** > click **Tools** > click **AD FS Management** > expand **Service** and select the **Certificates** node > open the certificate from the "__Token-signing__" section:

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

In the end, the SSO Configuration page will look like this:

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

  * Click Save.

===== Create the Relying Party Trust in AD FS =====

  * Copy the **Lucy Metadata Endpoint** link from the **SSO Configuration** page:

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

  * On your AD FS server, open the **AD FS Management** console, expand **Trust Relationships** and select the **Relying Party Trusts** node. In the Actions pane, click **Add Relying Party Trust**:

**Attention** :!: If the Lucy Admin Console is configured on a non-standard port (for example, port 8443, see more [[firewall_security_settings|here]]), then you will need to add **two separate entry of Relying Party Trust** with the identical parameters, but different Federation metadata address (URL): \\
The first will be: **https://lucydomain.com/service-provider/endpoint/metadata/lucy-sp** \\
Second: **https://lucydomain.com:8443/service-provider/endpoint/metadata/lucy-sp** \\
\\
In case access to the Lucy Admin Console is limited to a range of IP addresses, you must include an ADFS server in this range.

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

  * Click **Start** then paste the **Entity ID** url in to the Federation Metadata address field and click **Next**.

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

  * Accept the warning:

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

  * Click the **Next** button in the wizard until you reach the Ready To Add Trust page. Check the Encryption and Signature tabs have certificates associated with them:

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

  * Click **Next** and the Relying Party Trust is added:

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

  * Select the Relying Party Trust you have just added and then click **Edit Claim Rules**:

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

  * Add an **Issuance Transform Rule** based on the **Send LDAP Attributes as Claims** template:

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

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

  * Select UPN, uid and mail as shown on the screenshot below:

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

  * Add another **Issuance Transform Rule** based on the **Transform an Incoming Claim** template:

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

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

  * Once configured, you should have two **Issuance Transform Rules** that look as follows:

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

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

Now that we have configured Lucy as the service provider, ADFS as the identity provider (IdP), exchanged metadata between the two and configured some basic claims rules. We are now able to test authentication.

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

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

  * You will be immediately forwarded to the AD FS server (or Web Application Proxy depending on how your AD FS farm is configured). Enter your user ID in the format "domain\user" or "user@domain":

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

**Note** :!: User ID may differ from the E-mail address specified in the Active Directory attributes. If this is the case, you can enabled [[https://technet.microsoft.com/en-us/library/dn659436.aspx|Alternate Login ID]]. Microsoft strongly recommend using the mail attribute for sign in.

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

  * Click Logout to test this works as expected. On the Login page you can now choose a way of login to the Admin console:

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


===== Enable SSO for Awareness Websites =====

This option allows you to obtain a static link of the awareness website. This can be useful in the case when you do not need to send e-mail messages to each user, and to distribute only one link through other sources. The link is unique in the context of a specific awareness scenario and campaign.

:!: The list of possible domains for the awareness web site is limited to those domains that you added to the [[sso_authentication#create_the_relying_party_trust_in_ad_fs|Relying Party Trust]] in AD FS. You can add as many domains as you need by simply replacing the domain name in the Lucy Metadata Endpoint link.

The option **SSO for Awareness Websites** is available in the **Base Settings** section of campaign:

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

The option can be used in conjunction with the option "**Do not send emails**" (__Awareness Settings__) that blocking the sending of e-mail messages to users:

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

The global link that can be used by users to access awareness website is placed under the **Website** section of the __Awareness Settings__:

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

Note :!: In order this feature to work you should also enable SSL for the domain used in the awareness scenario:

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


===== Useful tips =====

**How to update or replace SSL certificate used for SSO authentication?**

You should first update your SSL certificate within the SSL Settings. Refer to this [[ssl_configuration|page]] for detailed instructions.

Once the SSL certificate is updated, go to the SSO Settings page, upload XML metadata file and click Save button. To verify whether the certificate is applied, click "Download Certificate" link, open the file and check certificate details.

===== Troubleshooting =====

**Issue**: An error occurs when importing a data about the relying party (Lucy Metadata Endpoint URL):

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

**Solution**: Copy the URL of Lucy Metadata Endpoint from the SSO Configuration page and paste into the address bar in your browser. Rename the downloaded file to "lucy-sp.xml". Use the file to import the data about relying party:

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

**Issue**: A blank page is opened after successful login with a single sign-on. \\

**Solution**: The time difference between AD FS and Lucy servers can cause an authentication problem. Make sure that the time zone setting is correct on the Advanced Settings page in Lucy.

**Issue**: (AD FS) Login with a single sign-on sometimes does not work (it redirects to the Lucy's login page after successful login at AD FS website) . \\

**Solution**: Disable the revocation check on your AD FS server by the PowerShell command (see details [[https://docs.microsoft.com/en-us/powershell/module/adfs/set-adfsrelyingpartytrust?view=win10-ps|here]]):

<code>
Set-AdfsRelyingPartyTrust -TargetName "Your RelyingParty Name" -SigningCertificateRevocationCheck None
</code>

**Issue**: (AD FS) Login with a single sign-on stopped working after update to Lucy 4.7 (it redirects to the Lucy's login page after successful login at AD FS website) . \\

**Solution**: Update the Relying Party Trust on your Windows Server by clicking "Update from Federation Metadata..." link in AD FS Management console or through the [[https://docs.microsoft.com/en-us/powershell/module/adfs/update-adfsrelyingpartytrust|PowerShell]].

**Issue**: A blank window appears after successful authentication at SSO provider website and there an error in the web server logs (Apache): "Uncaught exception 'SimpleSAML\\Error\\Error' with message 'ACSPARAMS'".

**Solution**: Verify your SSO provider settings, make sure that all required attributes are passed to Lucy during Single sign-on authentication.