How to enable Single Sign-On (SSO) in an existing cluster #

Single Sign-On (SSO) allows users to log in to Nimbra Edge using their existing identity provider. Nimbra Edge automatically onboards users and assigns their group and role based on their IdP group memberships, making it easy to manage access to the platform.

This how-to assumes you have an existing cluster and would like to enable SSO.

Prerequisites #

Nimbra Edge supports two SSO mechanisms: SAML and OIDC. This means your Identity Provider (IdP) must support one of these.

Open Network Manager on your Nimbra Edge URL, not on an IP address or another host name, when you configure SSO. The Callback URL field is built from the address in your browser, but Nimbra Edge always uses its own URL when it talks to the IdP.

Nimbra Edge onboards every user that your IdP lets sign in. Users who match no group mapping get the basic role in the system group. Restrict who can use the application in your IdP, for example by requiring users to be assigned to it.

Setting up SAML SSO #

The following steps are required to enable SAML SSO in Nimbra Edge:

Log in to your IdP and configure a SAML endpoint; this is usually called Application, Service Provider, or similar.
By default, Nimbra Edge uses email to extract the email address from the SAML token. Make sure this field is available in your IdP, or you will need to change the Email claim field in Nimbra Edge in step 5.
Copy the URL to the SAML metadata file from your IdP.
Login to Nimbra Edge and navigate to Global settings → Auth provider → SAML, tick Enabled and go down to Settings.
Optional: If your IdP uses a non-standard field for the email address in the SAML token, you can change the Email claim field.
Paste the metadata URL to automatically fetch the login URL and certificate.
Enter a unique name in the Provider ID field. It must match the identifier (entity ID) of the application in your IdP.
Copy the Callback URL and add it to the allowed redirect URLs in your IdP.
Click Save and log out of Nimbra Edge to test the SSO login.

Setting up OIDC SSO #

The following steps are required to enable OIDC SSO in Nimbra Edge:

Log in to your IdP and configure an OIDC endpoint; this is usually called Application or Client.
By default, Nimbra Edge uses scope email to request an email field in the ID token. Make sure this field is exported by your IdP, or you will need to change the Email claim and/or Scope field in Nimbra Edge in step 5.
Note the Client ID and Client Secret from your IdP, and copy the metadata URL (commonly ending in .well-known/openid-configuration).
Login to Nimbra Edge and navigate to Global settings → Auth provider → OIDC, tick Enabled and go down to Settings.
Optional: If your IdP uses a non-standard field for the email address in the ID token, you can change the Email claim field.
Paste the metadata URL to automatically fetch the OIDC endpoints (issuer, authorization, token, and user info).
Enter the Client ID and Client Secret from your IdP.
Copy the Callback URL and add it to the allowed redirect URLs in your IdP.
Click Save and log out of Nimbra Edge to test the SSO login.

Setting up group mappings #

Group mapping allows you to map groups from your IdP to groups and roles in Nimbra Edge. This is useful for managing access to the platform based on group memberships in your IdP.

For instance, a group mapping could look like this:

IdP Group	Nimbra Edge Group	Nimbra Edge Role
`nimbra-super`	`system`	`super`
`nimbra-admins`	`system`	`admin`
`nimbra-users`	`system`	`basic`

To set up group mappings, navigate to Global settings → Auth provider → SAML or OIDC and go down to Group Mappings. Here you can add mappings between IdP groups and Nimbra Edge groups and roles. The super role can only be mapped together with the system group. If a user is in more than one mapped group, the first matching row in the list decides both the group and the role.

Please note that the Groups claim field must be configured properly for the group mappings to work. This field is used to extract group information from the IdP token. Also note that group mappings are ONLY applied during onboarding of new users, and will not affect existing users.

The default value for the Groups claim field is:

SAML: groups
OIDC: groups

Internal and external users #

Users onboarded using SSO are tagged as external users in Nimbra Edge and are, from an authentication perspective, mutually exclusive with internal users. This means that a user cannot be both an internal and external user at the same time.

For instance, if a user is onboarded using SSO, the email address cannot be used to create an internal user with the same email address. However, it is possible to have multiple IdP accounts pointing to the same Nimbra Edge account (such as if both OIDC and SAML are configured).

Understanding the flow #

The following is a sequence diagram that shows the flow of a user logging in with SSO. On a higher level, the flow is the same for both strategies.

sequenceDiagram actor User as End User participant Client as Network Manager participant Server as Backend participant IdP as Identity Provider User->>Client: Login with OIDC/SAML Client->>Server: GET /api/sso/oidc or /api/sso/saml Server-->>IdP: Redirect to IdP login IdP-->>Server: Redirect to /api/sso/oidc/callback or /api/sso/saml/callback Activate Server Server->>Server: Validate user Server->>Server: Create user if not exist Server->>Server: Generate token deactivate Server Server-->>Client: Redirect to Network Manager (with token in cookie)

Troubleshooting #

Error on login
Most of the errors are self-explanatory, but some common errors are:
- Missing email in SAML profile or Missing email in OIDC ID token - The email claim is missing in the IdP token and you need to either add it to the token or change the Email claim field in Nimbra Edge.
Group is not mapped correctly
If the group is not mapped correctly, verify that the Groups claim field is correctly set in Nimbra Edge and that the group is correctly set in the IdP token. Also, verify that the group is correctly mapped in the Group Mappings section in Nimbra Edge. When testing a new configuration, make sure the user does not already exist in Nimbra Edge, as the group mappings are only applied during onboarding of new users.

Many IdP’s allow you to fetch your ID token and inspect the claims. This can be useful to verify that the groups are correctly set in the token.
SSL error with SAML
If the error implies some form of SSL error when using SAML, such as routines::unsupported, it usually means that the certificate is not correctly set in Nimbra Edge or it is pasted in an unsupported format. Also verify that no leading or trailing characters are present in the certificate field. The input accepts the certificate with and without the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. Mismatched signature can also occur if the provider ID is not correctly set in Nimbra Edge.

Examples #

Using Microsoft Entra ID as an IdP (SAML) #

1. Create your own application in Microsoft Entra admin center. #

Navigate to Microsoft Entra admin center → Applications → Enterprise applications → New application → Create your own application.

Select Integrate any other application you don't find in the gallery (Non-gallery) and fill in a name for your application.

2. Set up single sign-on in your Enterprise application. #

In your enterprise application, go to Manage → Single sign-on → SAML.

Find 1. Basic SAML Configuration and click Edit.

You need to set a unique Identifier (Entity ID) and Reply URL. The reply URL is your public URL to Nimbra Edge, for example, https://mydomain.com/api/sso/saml/callback. You can always copy this from Nimbra Edge by navigating to Global settings → Auth provider → SAML and copying the Callback URL.

Important! The Identifier (Entity ID) must match the Provider ID in Nimbra Edge later.

3. Ensure the correct claims are available in the SAML token. #

In your Enterprise application, go to Manage → Single sign-on, then find 2 Attributes & Claims and click Edit. Ensure that email is added as a claim and that it is mapped to user.mail.

If you want to use group mappings, you need to add a group claim. Click on Add a group claim and select All groups, then click Save. Nimbra Edge defaults to groups for the group claim, but it could be different in your case, in which case you need to change the Groups claim field in Nimbra Edge to match.

4. Copy the `App Federation Metadata Url`. #

Navigate to Manage → Single sign-on → SAML and copy the App Federation Metadata Url.

5. Set up SAML SSO in Nimbra Edge #

As a user with the super role, log in to Nimbra Edge and navigate to Global settings → Auth provider → SAML, tick Enabled and go down to Settings.

Paste the metadata URL to automatically fetch the login URL and certificate, enter the Identifier (Entity ID) from step 2 in the Provider ID field, and click Save.

(Optional) 6. Setup group mappings #

If you want to map groups to roles in Nimbra Edge, you need to find the ID of the group you want to map to a role in Edge. You can do this by finding a group in Microsoft Entra ID and copying the Object ID.

Once you have the group ID, go to Global settings → Auth provider → SAML and go down to Group Mappings.

Add a mapping between the Object ID of the group and a group and role in Edge, then click Save.

Log out of Nimbra Edge and make sure a new button SAML appears on the login page. Click the button and log in with your Microsoft Entra ID credentials. Verify that you could login successfully and that your role is basic (or a specific role if you have set up group mappings).

Using Auth0 as an IdP (OIDC) #

Auth0 supports both OIDC and SAML out-of-the-box. This example shows how to set up OIDC with Auth0, but the steps are similar for SAML.

1. Create an application in Auth0. #

Navigate to Applications → Create Application and select Regular Web Applications.

2. Get the Client ID and Client Secret. #

Go to Settings and note the Client ID and Client Secret.

3. Get the OpenID Configuration URL. #

Go to Settings → Advanced Settings → Endpoints and copy the OpenID Configuration URL.

4. Set up OIDC SSO in Nimbra Edge #

As a user with the super role, log in to Nimbra Edge and navigate to Global settings → Auth provider → OIDC, tick Enabled and go down to Settings.

Paste the metadata URL to automatically fetch the OIDC endpoints (issuer, authorization, token, and user info), then enter the Client ID and Client Secret from Auth0, and click Save.

5. Add the Callback URL to Auth0. #

Copy the Callback URL from Nimbra Edge and add it to the Allowed Callback URLs list in Auth0.

Log out of Nimbra Edge and make sure a new button OIDC appears on the login page. Click the button and log in with your Auth0 credentials. Verify that you could login successfully and that your role is basic.