SSO - Microsoft Entra Id

Enable Single Sign On (SSO) in Katalogue to let users sign in with their Microsoft Entra Id account instead of local username and password. Enabling this is highly recommended in a production scenario, both for convenience for Katalogue users and easier user management for Katalogue admins.

This need to be configured both in Microsoft Entra Id (formerly Azure Active Directory) and in Katalogue. Begin with Azure.

Azure Configuration

Microsoft Entra Id App Registration

1. Go to the Azure portal and create a new “App Registration” in Microsoft Entra ID

2. Select “Accounts in this organizational directory only (… - single tenant)” as “Supported account types”

3. Select “web” as platform and the base URL of the frontend/spa application as Redirect URI. Example: https://katalogue-demo.azurewebsites.net

4. Once the application is registered, copy and save the Application ID and Directory ID on the overview page. These must be entered in Katalogue later.

5. On the “Authentication” pane:

   • Make sure you have a “Web” platform with the “Redirect URI” you configured earlier.
   • Leave “Front-channel logout URL” empty
   • Leave both Access tokens and ID tokens unchecked in the “Implicit grand and hybrid” flows section
   • Make sure “Accounts in this organizational directory only (… - single tenant)” is selected under “Supported account types”
   • Leave “Allow public client flows” set to “No”

6. On the Certicifates & secrets pane:

   • Create a new Client secret and save the Client Secret value. You cannot retrieve it once you leave the page. This must be entered in Katalogue later.

7. On the “Token configuration” pane:

   • Add the following optional “ID” token claims: “email”

8. On the “API permissions” pane, add the following permissions:

   • Microsoft Graph -> Delegated permissions -> OpenId permissions -> email (Required for SSO/OIDC login)
   • Microsoft Graph -> Delegated permissions -> OpenId permissions -> profile (Required for SSO/OIDC login)
   • Microsoft Graph -> Delegated permissions -> User -> User.Read (Required for SSO/OIDC login)
   • Microsoft Graph -> Application permissions -> User -> User.Read.All (Required to fetch user info, including photos)
   • Microsoft Graph -> Application permissions -> GroupMember -> GroupMember.Read.All (Required to fetch user group members and basic user group info)
   • Microsoft Graph -> Application permissions -> ProfilePhoto -> ProfilePhoto.Read.All (Required to fetch user group photos)

   The last three need “admin consent” to become effective. Click the “Grant admin consent for <your organization>” button above the list with permissions. If you cannot see the button or if it is disabled, you need to get a Microsoft Entra IDministrator to grant consent for you. Entra ID sync will not work before this is done.

Security Hardening Settings (Optional)

Complete the Katalogue Configuration and make sure that everything works before applying these.

1. Go to the Azure portal and “Enterprise Applications” in Microsoft Entra ID. There should be an enterprise application with the same name as the App registration created in the previous steps.
2. In the Enterprise Application and the “Properties” section, set the following:
   • “Assignment required?”: “Yes” (This enforces that all users that should have access to Katalogue must be in a user group assigned to this enterprise application)
   • “Visible to users?”: “No” (This hides the app from myapps.microsoft.com for users)
3. Go to the “Users and groups” section.
4. Add the user groups with users that should have access to Katalogue. Ideally, these should be the same as the ones that is added in Katalogue itself later.

Katalogue Configuration

Configuring Authentication

1. Log in as an admin user and go to the Settings -> Authentication page
2. Check Enable Azure Open ID Connect Authentication to enable the feature.
3. Fill in the details that you saved from the Azure configuration above:
   • Directory (tentant) Id
   • Application (client) Id
   • Client Secret
   • Redirect URI
4. Go to the User Provisioning tab.
5. The default settings should be fine but you might have to adjust some of them depending on how Microsoft Entra ID is configured in your organization. If you need to change anything, the most likely options you will need to look into are these:
   • “User-” and “User Group Base Filters”. These determine which user accounts and user groups that the search function and AD sync task can find. By default, inactive user accounts (property “accountEnabled”) are filtered out. See default filter string below.
   • “Id”, “Username”, “Full Name” and “Email” user attribute mappings must always return data. “Title” and “Department” are optional. See default mappings in table below
   • “Id” and “Name” user group attribute mappings must always return data.
6. Click Save. Wait for the backend API to reboot.
7. Reload the frontend webpage (to get fresh settings from the API)

Configuring User Provisioning

These settings are found on the Settings -> User Provisioning page.

Katalogue uses the Microsoft Graph API to get user and user group data from Microsoft Entra Id. The endpoints used by Katalogue are listed in the table below. The graph api base url is configurable through the MSGRAPH_ENDPOINT_BASE_URL configration parameter, and the endpoints listed here are appended directly to that string.

Microsoft Graph API Endpoint	Purpose
/users	Get user data
/groups	Get user group data
/groups/{group_id}	Get user group data for a specific user group
/groups/{group_id}/members	Get direct user group members
/groups/{group_id}/transitiveMembers/microsoft.graph.user	Get user group members from nested user groups
/users/{user_id}/photos/120x120/$value	Get user profile photo
/groups/{group_id}/photos/120x120/$value	Get user group profile photo

Default User Base Filter

This is the default Microsoft Graph API filter string for users. The intention is to only find user accounts that are enabled and represent a real person (and not rooms or other things that might be in the user account list).

userType eq 'Member' and surName ge ' ' and accountEnabled eq true

Default User Group Base Filter

This is the default Microsoft Graph API filter string for user groups. The intention is to only find user groups in a security context and user groups that represent teams or organizational units.

NULL

Syncing Users In Nested User Groups

Enable this option to include users in all nested user groups. If not enabled, only users that are direct members of the user group will be synced.

Note that the nested user groups themselves cannot be synced to Katalogue. Even if this option is enabled, all users will be presented as members of the user group in a flat list.

Default User Attribute Mapping

Katalogue Attribute	Microsoft Entra ID Attribute	Is Mandatory
Id	id	Yes
Username	userPrincipalName	Yes
Full Name	displayName	Yes
Email	mail	Yes
Title	jobTitle	No
Department	Department	No

Default User Group Attribute Mapping

Katalogue Attribute	Microsoft Entra ID Attribute	Is Mandatory
Id	id	Yes
Name	displayName	Yes
Email	mail	No
Description	description	No

Danger

The Id attribute is used to match users in Katalogue with Microsoft Entra Id. If this attribute is changed in either system, or if the mapped attribute is changed, the Microsoft Entra Id sync task will result in an insert & delete instead of an update.

Testing SSO

You are now done! Perform these tests to verify that it works:

1. Add a user or user group in Katalogue from Microsoft Entra ID
2. Create a Microsoft Entra ID sync task and run it
3. Logout and login with a Microsoft Entra ID account

If something does not work, check the backend API logs. Set the log level to “debug” on the Settings -> Logging page to get more detailed logs.