# SSO Configuration Introduction Lucy supports single sign-on for both Administrative and End-users through SSO/SAML. SAML (Security Assertion Markup Language) and OAuth 2.0 (Open Authorization) are widely recognized standards for authentication and authorization, each facilitating the implementation of SSO. These technologies allow administrators/users to access Lucy using a single set of credentials, enhancing both user convenience and security. Although SAML and OAuth 2.0 aim to streamline authentication processes, they differ in their specific purposes and operational approaches: {% tabs %} {% tab title="OAuth 2.0 (Azure)" %} * **Purpose**: OAuth 2.0 is a framework for authorization. It enables applications to obtain limited access to user accounts on an HTTP service. While OAuth can be used for authentication (and often is, with extensions like OpenID Connect), its primary role is to authorize third-party applications to access a user's account without exposing their password. * **How it works**: OAuth 2.0 uses access tokens rather than user credentials to authorize requests. When a user logs into an application and consents to give it access to another service, the application receives an access token. This token is then used for subsequent requests to the service on behalf of the user. * **Use Case**: OAuth 2.0 is used in scenarios where an application needs to perform actions on behalf of a user without knowing their password. {% endtab %} {% tab title="SAML 2.0" %} * **Purpose**: SAML is primarily used for authentication in SSO processes. It allows secure domains to exchange user authentication and authorization data. SAML is focused on authenticating users and conveying that authentication status to service providers. * **How it works**: In a SAML SSO flow, when a user attempts to access a service provider (SP), they are redirected to an identity provider (IdP) to authenticate. Upon successful authentication, the IdP sends a SAML assertion (an XML document) back to the SP. This assertion contains the authentication statement and possibly attributes about the user. The SP then grants access based on this assertion. * **Use Case**: SAML is widely used in enterprise applications and services, especially where the interaction is between a browser and web applications. {% endtab %} {% endtabs %} ## Configuration Before connecting to the Identity Provider, the following preparations are necessary: 1. **SSL Certificate**: Upload or create an [SSL certificate](https://wiki.lucysecurity.com/application-reference/settings/common-system-settings/ssl-settings) for the Lucy Admin console. This step is crucial for ensuring that the connection and data exchanged between Lucy and Azure AD are secure. 2. **Administrator Account Matching**: Verify that you have an Administrator account in Lucy, which you can find under Settings -> Users -> Administrative Users. The email address associated with this account must match the email address of your account in the Identity Provider. {% hint style="danger" %} Please ensure to test the authentication via SSO before enabling the **Auto Login** feature.\ \ If Auto Login was activated and you are locked out of your Lucy server, please reach out to our [technical support department](https://wiki.lucysecurity.com/contact-us) for assistance with disabling the Auto Login feature. {% endhint %} {% hint style="info" %} Navigate to Settings -> Common System Settings -> SSO Settings {% endhint %} ## OAuth 2.0 (Entra ID) ### App Registration Ensure you have created the App Registration in Entra ID as outlined [here](https://wiki.lucysecurity.com/application-reference/settings/common-system-settings/azure-applications). ### Connect to Lucy Add your Client ID, Client Secret, and Tenant ID from your Azure Entra ID application.

{% hint style="danger" %} To integrate Lucy with your App Registration, it's essential to have global administrative consent for your organization. If the administrator account in Lucy lacks the necessary privileges to grant consent on behalf of the organization, refer to the guide provided below to establish a consent flow in Azure. {% endhint %}

Setup Admin Consent flow in Azure

### Purpose The integration of third-party applications like Lucy with Azure requires careful configuration to ensure API permissions are correctly set. This is crucial for applications such as Lucy demanding access beyond the Azure permission set of the Lucy administrative users. A common challenge faced during integration is a permissions mismatch, leading to integration errors. This guide aims to navigate administrators through the consent framework in Azure, enabling Lucy to receive the necessary permissions while upholding the security and integrity of the Azure environment. ### **Who Should Use This Guide?** This guide is intended for Lucy Administrators who lack Azure Administrative privileges to grant organizational consent, as well as situations where Lucy servers operate without an Azure Administrator to facilitate the saving of Azure application configurations within Lucy.\ \ Lack of Administrative consent is evident if the following message is displayed after saving your application in Lucy:\ \ ![](https://3536856424-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYPsDfg76rUuy4DWfSsJ%2Fuploads%2FZAXkAwhc23ayLa1vXRyJ%2Fimage.png?alt=media\&token=0b02be22-ca35-487f-a581-f17895b8cc97) ### Configuration #### Accessing Azure 1. **Log into the Azure Portal**: Start by visiting [portal.azure.com](https://portal.azure.com/) and logging in with your credentials. #### Setting Up Consent Flow 2. **Navigate to Microsoft Entra ID**: Find and select the Microsoft Entra ID option to proceed. 3. **Enterprise Applications**: In the Microsoft Entra ID section, locate and click on “Enterprise Applications.” 4. **Consent and Permissions**: Inside Enterprise Applications settings, select “Consent and Permissions.”\

5. **Admin Consent Settings**: Search for “Admin consent settings” and click it to modify the consent flow settings. 6. **Enable Consent Requests**: Activate the option “Users can request admin consent to apps they are unable to consent to” by toggling it to “Yes.” This allows non-admin users to request admin consent for applications. 7. **Designate Reviewers**: Specify Azure Administrative users for the consent review process, selecting your Azure Admin under Review Type as Users.\

8. **Save Your Settings**: Click “Save” to apply the changes. #### Finalizing Configuration in Lucy 9. **Adjustments in Lucy**: Instruct the Lucy admin to try saving the application configuration again, preferably using an incognito window to avoid caching issues. 10. **Consent Request Initiation**: The Lucy admin will see a consent request dialog, allowing them to submit a consent request to the Azure Admin. #### Consent Approval Process 11. **Initiating Approval**: The Lucy admin clicks “Request Approval” to start the consent process.

12. **Notification to Administrator**: An approval request is sent to the Azure Administrator's email, and the request appears under Enterprise Applications -> Admin Consent Requests in the Azure portal.\

13. **Admin Review and Consent Granting**: The Azure Administrator reviews the request in the portal and grants consent on behalf of the organization.\

14. **Confirmation to Lucy Admin**: The Azure Administrator should inform the Lucy admin of the consent approval. #### Completing Integration 15. **Finalizing in Lucy Settings**: The Lucy admin goes to Common System Settings -> Azure Applications in Lucy, selects the application, and clicks “Save” to proceed with the integration. 16. **Microsoft Login and Token Allocation**: This prompts the Lucy admin to log in with Microsoft credentials again to generate a refresh token for the integration. 17. **Binding to Lucy Server**: Successfully obtaining the refresh token completes the integration, effectively binding the Azure app registration to the Lucy server.

### What API permissions are required for this integration? {% hint style="info" %} Lucy is configured to utilize the Microsoft Graph API to access and manage various resources from Microsoft services. The configured permissions include both delegated permissions, which act on behalf of a user, and those requiring administrative consent to access specific types of data, like directory data and full user profiles. These permissions are in line with the version 1.0 standard of the Microsoft Graph API. {% endhint %}

Permission	Type	Description	Admin consent required
User.read	Delegated	Sign in and read user profile	No
Directory.Read.All	Delegated	Read directory data	Yes
email	Delegated	View users' email address	No
offline_access	Delegated	Maintain access to data you have given it access to	No
OpenID	Delegated	Sign users in	No
User.Read.All	Delegated	Read all users' full profiles	Yes

## Entra ID (SAML 2.0) Microsoft Entra ID also supports SSO using SAML 2.0. ### Create Application To begin, log in to your Entra ID portal and go to **Manage -> Enterprise Applications**.\ Select **+ New Application** and then select the option for a **Non-gallery** application:

Click **Create** to create the new application. ### App Configuration Go to **Manage -> Single Sign-On** and select **SAML** for the SSO method. #### **Basic SAML Configuration** Click the **Edit** button and enter these values, then **Save**. **Identifier (Entity ID)** ``` https:///simplesaml/module.php/saml/sp/metadata.php/lucy-sp ``` #### Reply URL (Assertion Consumer Service URL) ``` https:///simplesaml/module.php/saml/sp/saml2-acs.php/lucy-sp ``` #### Attributes and Claims Click the **Edit** button and then **+ Add new claim**. Create a new claim called **mail** using the attribute **user.mail**, then click **Save**:

### Add Users and Groups Next go to **Manage -> Users and Groups** and select **+ Add user/group**. Search for and add your desired Users/Groups so they can use the application to log in to Lucy.

{% hint style="info" %} If you don't want to add specific users or groups to the application, go to **Properties** and set **Assignment Required?** to **No**:

{% endhint %} ### Upload Certificate Data In the **SAML Certificates** section download the **Federation Metadata XML**.\ In the **Set up \** section, copy the **Microsoft Entra Identifier**.

In Lucy, go to **Settings -> Common System Settings -> SSO Settings**. 1. Select **SAML 2.0** for the method. 2. Enter your Lucy admin domain in the **Domain Name** field**.** 3. Enter the **Microsoft Entra Identifier** in the **Identity Provider Endpoint** field. 4. Upload the Federation Metadata file in the **Identity Provider Server XML metadata** field. The **Thumbprint** in Entra ID is created using SHA256. Lucy requires that the thumbprint be SHA1.\ To get the SHA1 thumbprint open the metadata XML file and look for the field labeled `X509Certificate`:

Copy only the text of the certificate and create a new file with this format (you can copy this text): ``` -----BEGIN CERTIFICATE----- paste your certificate content here -----END CERTIFICATE----- ``` Save this as a `.pem` file, then use an [online tool](https://www.samltool.com/fingerprint.php) or the `openssl` command to get the SHA1 thumbprint: ``` openssl x509 -in your_certificate.pem -noout -fingerprint -sha1 ``` Finally, paste the thumbprint in the **Identity Provider Certificate Thumbprint** field.

Click **Save** to apply the settings, then click **Test Connection**. You should be redirected to your SSO login page where you can test that your connection is working. ## Google Workspace (SAML 2.0) ### Create an app in your workspace Log in to your [Google Workspace admin dashboard](https://admin.google.com/) and go to **Apps > Web and Mobile Apps.** Select "Add App" and then select "Add custom SAML app" to begin.

#### 1. App details Give you app a name and optionally create a description and set an icon, then select "Continue". #### 2. Google IdP Details Select the first option, "Download Metadata".\ Then, copy the **Entity ID** and **Certificate** values and save them in a note for later.

{% hint style="success" %} You will need the Entity ID and certificate in a later step, but you will **also** need the metadata file itself.\ Make sure you have all the required data before proceeding! {% endhint %} #### 3. Service Provider Details To retreive the ACS URL and the Service Provider's Entity ID, log in to your Lucy portal and go to **Settings > Common System Settings > SSO Configuration**. Enable SSO and select "SAML 2.0" for the Protocol. Then, copy the **Meta Endpoint** URL and paste it in to your browser. It will download an file called "lucy-sp.xml" which contains the information required for this step.

Open the XML file and search (Ctrl + f) for "entityID". The record should be close to the top of the file. Copy the URL (without the quotation marks) and enter it in the "Entity ID" field back in Google Workspace. It should look like this: ``` https:///simplesaml/module.php/saml/sp/metadata.php/lucy-sp ``` Then, search for "Assertion Consumer Service" and locate the "Location" portion of that record. Copy that URL and enter it in the "ACS URL" field in Google Workspace. It should look like this: ``` https:///simplesaml/module.php/saml/sp/saml2-acs.php/lucy-sp ``` Finally, under **Name ID** select "Email" as the format and leave the **Name ID** default setting as primary email. Select "Continue" to move on to attribute mapping. #### 4. Attribute Mapping Create a mapping for **Primary Email > mail** like this:

It is not necessary to configure group information. #### 5. User Access After creating your app select the "User Access" dashboard and select "ON for everyone", then save. We are now ready to complete the process in Lucy. ### Configure SSO in Lucy Fill out the form on the **SSO Configuration** page like so:

Field	Value
Protocol	SAML 2.0
Auto Login	Do not enable until after testing
Domain name	Your Lucy URL
Identity Provider Endpoint	The EntityID value you copied from Google Workspace
Identity Provider Server XML metadata	Upload the metadata file you downloaded from Google Workspace
Identity Provider Certificate Thumbprint	Get the SHA-1 formatted fingerprint using the certificate data you copied from Google Workspace and a tool like this one: https://www.samltool.com/fingerprint.php
Token Encryption	Do not enable unless you are using token encryption in your SSO workflow

When you are ready, click "Save". ### Testing the Connection You can test that the SSO workflow is working from both Lucy's side and from Google Workspace. To test from Lucy simply select the "Test Connection" button **after saving the configuration**. To test from Google Workspace you can select "Test SAML Login" from the application page.

{% hint style="success" %} In order to test the connection from Lucy, you must be logged in to Lucy as a user that exists in your Google Workspace environment. In addition, your users must exist in Google Workspace in order to use the SSO workflow. {% endhint %} ## SAML 2.0 (Any) The exact method of deploying a SAML application for SSO will vary depending on the application your organization uses. These are the general steps for deploying a SAML app and connecting with Lucy. ### **Configure the IdP** Define Lucy as a SP within the IdP, specifying its endpoint and required SAML attributes. ### **Upload IdP Metadata** In Lucy, navigate to **Settings -> Common System Settings -> SSO Settings**.

Enter your administrative domain and IdP endpoint. Then, upload your IdP metadata file and paste in the thumbprint. Your IdP should provide a thumbprint for your X.509 certificate, but you can also use an online tool like . {% hint style="success" %} Lucy requires a SHA1 thumbprint. SHA256 or other algorithms will not work. {% endhint %} ### **Attribute Mapping** Map user attributes from the IdP to fields in Lucy (e.g., email, full name) as required. ### **Test Authentication** Verify the SSO connection with the IdP by clicking **Test Connection**.\ Testing should be completed before enabling Auto Login to avoid login issues. #### **Enable Automatic Login (optional)** This setting allows seamless login but should be used carefully, as enabling it can restrict alternative access methods. [Contact Lucy support](https://wiki.lucysecurity.com/contact-us) if auto login prevents access.