/
Single Sign-On (SSO) setup

Single Sign-On (SSO) setup

This page provides documentation on integrating an Identity Provider (IdP) with Unique's authentication system, enabling a seamless and secure SSO experience for the users. Unique uses Zitadel as its Identity and Access Management (IAM) solution and various IdPs can be connected to it for allowing users to login via Single Sign-On.



Supported Identity Providers

Unique supports all the IDPs that Zitadel supports in the version that is deployed on the environment where SSO will be setup. The list of supported identity providers can be found in Zitadel’s documentation in the “Configuring IdP Providers” section.

This documentation includes a guide for setting up SSO with Microsoft Entra ID, Generic OIDC and SAML, and will be expanded in the future with guides for other providers as needed.

Microsoft Entra ID (OIDC)

In case SCIM will be used for user provisioning - visit https://unique-ch.atlassian.net/wiki/x/S4B4Ow and setup the enterprise application for SCIM first following the documentation.

After setting up the enterprise application for SCIM you will already have a linked app registration created by Entra ID. Proceed with the step “Configure app registration after SCIM setup” on this page (skipping the “Create an app registration” step).

Create an app registration

An App Registration needs to be created in Microsoft Azure. This can be done in Azure under App registrations > New registrations.

c23f3ac4-5541-4783-86fe-2cd4abfab18f.png
Registering an app registration in Azure

Configure the following:

  • Choose a name (e.g.: “Unique AI”)

  • Select who should have access to this application

  • Redirect URL → select “Web” and enter the callback URL for the environment you’re running on

Redirect URL is environment specific

  • Multitenant (Europe)

    • https://id.unique.app/ui/login/login/externalidp/callback

  • Multitenant (US)

    • https://id.us.unique.app/ui/login/login/externalidp/callback

  • Single tenant

    • https://id.<your-tenant-name>.unique.app/ui/login/login/externalidp/callback

  • Customer managed tenant

    • https://<custom-unique-zitadel-url>/ui/login/login/externalidp/callback

Configure app registration after SCIM setup

Skip this section in case you did not setup SCIM with an enterprise app and proceed with the “Authentication” step.

After setting up the enterprise application for the user provisioning via SCIM, Entra ID will automatically create a corresponding app registration. This app registration must be configured to use “Web” as a platform and the redirect URL must be added to enable users to login via SSO to Unique.

Screenshot 2025-02-25 at 20.57.54-20250225-195937.png
Add “Web” as the platform in the authentication section of the app registration.

You will be prompted to enter the redirect URL for the application.

Redirect URL is environment specific

  • Multitenant

    • https://id.unique.app/ui/login/login/externalidp/callback

  • Single tenant

    • https://id.<your-tenant-name>.unique.app/ui/login/login/externalidp/callback

  • Customer managed tenant

    • https://<custom-unique-zitadel-url>/ui/login/login/externalidp/callback

Proceed now with the next section (“Authentication”) to finish the authentication setup for the app registration.

Authentication

After the app registration has been created, navigate to the “Authentication” section and make sure the “Access tokens” and “ID tokens” settings are selected. This is to ensure that the Access token and ID token are issued and sent along when a user uses SSO to login to Unique.

  • ID token → contains information about the user (name, email, group IDs)

  • Access token → used for making an additional Microsoft GraphAPI request to get the group names

Screenshot 2024-06-14 at 09.22.52-20240614-072313.png
Configure Access tokens and ID tokens to be included with SSO

Token configuration

Next navigate to the “Token configuration” section and add necessary claims to the token. This is to ensure that the needed claims are sent on the ID token.

If you want to be able to sync your user groups from Azure to Unique, make sure to also add the groups claim as shown in the second screenshot below. What kind of groups you want to include on the groups claim is ultimately up to you. Unique recommends to include only the groups assigned to the application in order to have more control over what groups are synced and avoid exceeding the limit on the number of groups that can be included on the ID token.

Screenshot 2024-05-29 at 11.13.01-20240529-091403.png
Token configuration - add necessary claims
Screenshot 2024-05-29 at 13.28.00-20240529-112901.png
Token configuration - add groups claim

API permissions

Under the “API permissions” navigation entry you need to configure the correct permissions for the Microsoft Graph API. The permissions should include:

  • email

  • openid

  • profile

  • User.Read

  • GroupMember.Read.All (only when not using SCIM for provisioning)

The GroupMember.Read.All permission (https://learn.microsoft.com/en-us/graph/permissions-reference#groupmemberreadall ) is only required in cases where SCIM is not used to provision users and groups. If you setup SCIM - skip adding this API permission.

GroupMember.Read.All requires admin consent to be enabled. This permission is needed to query the group names via the Microsoft Graph API on behalf of the user. The ID token groups claim includes only the groups' IDs and to be able to sync the user’s Entra ID groups to Unique we require an ID and a name.


For more information on the syncing of user groups, refer to this page: User Provisioning

Screenshot 2024-06-18 at 12.13.43-20240618-101404.png
Ensure the correct API permissions are set

The GroupMember.Read.All permission needs to be manually added. This can be done by clicking on the “+ Add a permission” button on the top of the list. Select the “Microsoft Graph” API and choose the “Delegated permissions” tab on top. This allows the Unique solution to query the group names for the group IDs received in the groups claim on the ID token.

Make sure that the status column indicates “Granted for …” for all the added API permissions. The GroupMember.Read.All permissions requires explicitly granting admin consent by using the “Grant admin consent for …” button above the permission list.

 

Screenshot 2024-06-18 at 12.15.55-20240618-101622.png
Adding the GroupMember.Read.All API permission for the Microsoft Graph API
Screenshot 2024-06-18 at 12.17.40-20240618-101805.png
Granting admin consent for the permissions.

Certificates & secrets

After the application has been registered and configured, create a Client Secret by navigating to “Certificates & secrets” and copy the value of the secret. The secret is only visible once and is needed in order to setup SSO with Unique.

app-registration-client-secret.png
Creating a client secret for the App registration in Azure

Required information for setting up SSO

Now all the information required to setup SSO for the Unique solution using Microsoft Entra ID (OIDC) is available.

rd.png
Client ID and Tenant ID visible in App registration detail view in Azure

 

These are the required values that are needed to setup SSO.

  • Client ID - (found under “Application (client) ID”)

  • Client Secret - (copied after creation)

  • Tenant ID - (found under “Directory (tenant) ID”)

If you are running on a Unique managed environment (Multi- or Single-tenant), then this is all you need. Provide these values to Unique in a secure way (sensitive client credentials) and Unique will take care of enabling SSO for your organization.

SAML

Zitadel is able to connect to any identity provider that supports SAML. SAML can even be used in a closed network not available from the internet.

Prerequisites

You need to register a new client with your SAML provider and provide us with either the Metadata URL or the Metadata XML. In case of an internal network not reachable from the internet only the Metadata XML is possible.

How to setup Okta SAML as an example you can check here:

On the multitenant system we additionally need the E-Mail domain that the users will be using to login.

Configuring Zitadel

On the settings tab you need to Allow External Login and you need to remove all 2FA methods and Disable Username and password. The only that should be checked is for external login!

Then create a SAML SP Identity Provider. Give it a name and either paste the Metadata XML in base64 encoded form into the Metadata XML field, or give the Metadata URL in the respective field.

Choose SAML_BINDING_POST and activate:

  • Signed Request

  • Automatic Creation

  • Automatic Update

  • Account creation allowed

Do not forget to activate the new Identity Provider with the icon. Account linking should never be activated for security reasons.

Configuring SAML provider with Zitadel metadata

After configuring the SAML SP Identity Provider click on it again and check the URL. It will end with a sequence of numbers ui/console/org/provider/saml/<SAML-PROVIDER-ID>. Copy the SAML-PROVIDER-ID for the next step (the numbers).

Zitadel documentation claims that you see the metadata URLs after creating the provider, but we never saw this screen, so the only reliable way is to copy the provider ID from the URL.

If Zitadel is reachable from your SAML instance you can configure the following URL as Metadata URL:

  • Multitenant

    • https://id.unique.app/idps/<SAML-PROVIDER-ID>/saml/metadata

  • Single tenant

    • https://id.<your-tenant-name>.unique.app/idps/<SAML-PROVIDER-ID>/saml/metadata

  • Customer managed tenant

    • https://<custom-unique-zitadel-url>/idps/<SAML-PROVIDER-ID>/saml/metadata

If it is not reachable you either get the Metadata XML from us or you can download it from the respective URL above and configure it in your SAML IDP.

Zitadel is using signing and encryption for the SAML communication, and we configured Zitadel to only accept signed requests. There might be additional steps necessary in your SAML provider to work correctly with signing and encryption.


Author

@Sandro Camastral

Author

@Sandro Camastral

 

Related content

© 2025 Unique AG. All rights reserved. Privacy PolicyTerms of Service