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:

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.

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.

Configuration

Before connecting to the Identity Provider, the following preparations are necessary:

1. SSL Certificate: Upload or create an SSL certificate 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.

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 for assistance with disabling the Auto Login feature.

Navigate to Settings -> Common System Settings -> SSO Settings

OAuth 2.0 (Microsoft Azure)

Ensure you have created the App Registration in Azure Entra ID as outlined >>here<<

Add your Client ID, Client Secret, and Tenant ID from your Azure Entra ID application.

To integrate Lucy with your Azure App Registration, it's essential to have Global Azure 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.

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:

Configuration

Accessing Azure

1. Log into the Azure Portal: Start by visiting 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?

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.

API / Permissions name	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

SAML 2.0