Configure SSO

Zmanda supports integration with OpenID Connect providers including Azure AD v2 and Google.

OpenID Connect 1.0​

Zmanda Pro supports using OpenID Connect 1.0 (OIDC) compatible authentication providers for external authentication and management of administrator users.

The following OIDC-compatible authentication sources (OpenID Providers, or OPs) can be used:

• Microsoft Entra ID (formerly known as Azure AD v2)

• Google

• "Generic" OpenID Providers that implement OpenID Connect Discovery using .well-known/openid-configuration discovery documents

Configuring an OIDC authentication source consists of two parts: the Zmanda Pro configuration, and the configuration at the OP. Both ends must be done manually; Zmanda Pro does not support OIDC Dynamic Client Registration.

When an OIDC authentication source is configured, authentication can be started by clicking on the "Login with ..." button on the Zmanda Pro Server login page, which will redirect the browser to the external authentication provider.

OpenID Connect 1.0 configuration on the Zmanda Pro Server​

• Admins can configure an OIDC authentication source from the "External authentication sources..." button in the "Integrations" settings section. If you do not see this option and would like to use SSO, please reach out to [email protected]

The following fields apply to all OpenID Connect authentication sources:

Name	Required?	Description
Description	No	A human-readable description of the authentication source.
Display name	Yes	The name to use on the "Login with ..." button on the Zmanda Pro Server login page.
Tenant	N/A	The tenant to which this source belongs. Not editable.
Provider	Yes	The type of OIDC provider, e.g., Google or Azure AD. This changes which other fields are required.
Client ID	Yes	An OAuth 2.0 client ID. This must be generated at the OP and then entered into Zmanda Pro.
Client secret	Yes	The OAuth 2.0 client secret associated with the client ID. This must be generated at the OP and then entered into Zmanda Pro.
Skip multi-factor authentication	No	Whether or not Zmanda Pro should enforce its own multi-factor authentication.
Scopes	No	A comma-separated list of OpenID Connect scopes to request from the OP. This will affect the information that the OP returns to Zmanda Pro and should be used to ensure that required claims are present in the ID token. Zmanda Pro will always request the scopes necessary to authenticate if no required claims are configured.
Required claims	No	A set of OpenID Connect claims whose presence (and optionally value) will be checked for in the ID token returned from the OP.
Redirect URI	N/A	The redirect URI that must be configured at the OP. This field is generated automatically based on the Zmanda Pro Server's hostname and the OIDC authentication source's ID, and cannot be edited.
New account permissions	No	A set of default permissions to apply to admin users created by this authentication source. An admin user with permissions applied to their account cannot enable or disable settings that are restricted on their own account.

Zmanda Pro requests the following OpenID Connect scopes from all providers:

• openid: required for OpenID Connect.

• profile: basic information about the user. Used for authentication purposes and to generate a username.

• email: information about the user's email address. Used to generate a username.

Generic OpenID Connect provider configuration​

The following fields apply to OIDC authentication sources with the provider type "Generic OpenID Connect":

Name	Required?	Description
Discovery document URL	Yes	The URL of the OpenID Connect discovery document for the OP. This is normally a URL ending with .well-known/openid-configuration.

Microsoft Entra ID (Azure AD v2) provider configuration​

To register an OpenID Connect provider in Azure AD, see the following links:

• https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app

• https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc#enable-id-tokens

The following fields apply to OIDC authentication sources with the provider type "Azure AD v2":

Name	Required?	Description
Azure tenant ID	Yes	The tenant ID for the Azure AD tenant to which the app registration belongs.

Google provider configuration​

To register an OpenID Connect provider in Google, see the following links:

• https://developers.google.com/identity/openid-connect/openid-connect

The following fields apply to OIDC authentication sources with the provider type "Google":

Name	Required?	Description
Hosted domain	No	The domain of a Google Cloud organization. This controls the value of the hd parameter submitted to Google in the OIDC request. Setting this field also causes Zmanda Pro to validate the value of the hd claim returned in the ID token against it, restricted the allowed users to those who belong to the Google Cloud organization.

Required claim validation​

The "Required claims" field causes Zmanda Pro to enforce the presence and value of claims in the ID token returned from the OP. This can be used to restrict which users at the OP are allowed to be administrators in Zmanda Pro.

How claims are validated depends on how the claim is configured in Zmanda Pro, and the type of data returned in the ID token for that claim:

• For a claim configured in Zmanda Pro with only a name and no value, only the presence of that claim name in the ID token is checked. The value associated with the claim is ignored.

• For a claim configured in Zmanda Pro with a name and a value, validation depends on the type of data of the value associated with the claim in the ID token:

  • If the claim value is a string, the claim is valid if the configured value and the value in the ID token are equal.

  • If the claim value is a JSON array, the claim is valid if any of the array entries are equal to the configured value.

  • If the claim value is of any other type (such as a JSON object), the claim is considered invalid.

Example: Requiring Azure AD v2 group membership​

A common use case for required claims is to enforce that a user at the OIDC OP should be allowed to be an administrator in Zmanda Pro. One way to enforce this is using group membership: create a group that includes the users who should be Zmanda Pro admins, ensure that the group membership is included in the ID token, and add a required claim to the OIDC authentication source in Zmanda Pro.

This section will give an example of one way to do this using Azure AD v2. It assumes you already have an Azure AD v2 OIDC authentication source configured in your Zmanda Pro Server; this section only covers how to add group membership validation to the existing source.

1. Create a new "zmandapro-admins" group with the group type "Security" in Azure AD by following these instructions.

   Note the value of the "Object Id" field; this is what will be sent to Zmanda Pro Server.

2. From Manage > Members, add the Azure AD users you wish to be Zmanda Pro Server administrators.

3. Navigate to the existing app registration that was used to configure the existing OIDC authentication source, and then to the "Token configuration" section for that app registration.

4. Click "Add groups claim". Ensure that "Security groups" is checked, and that "Group ID" is selected in "Customize token properties by type" > ID. Save this groups claim.

   

   Groups are now included as the groups JSON array claim in the ID token returned from Azure AD to Zmanda Pro. The next step is to ensure that they are validated.

5. In the Settings page in the Zmanda Pro Server, navigate to the existing OIDC authentication source and edit it.

6. Add a new required claim with the name groups and the value of the "Object Id" of the Azure AD group from step 1.

   

   
7. No additional scopes are needed; group claims are included by default once step 4 is complete.

8. Save the OIDC authentication source and the server settings using the "Save Changes" button.

The Zmanda Pro Server will now validate group membership of authenticating users and prevent those who are not members of the group from logging into Zmanda Pro. Existing admin users who are not members of the group will retain their Zmanda Pro admin accounts, but they will no longer be able to authenticate.

When a user without the configured group attempts to authenticate, they will be rejected and the following message will appear in the server logs:

/api/v1/auth/sso/oidc/callback: failed admin OIDC login (failed to validate claims: missing value for required claim groups)

Copy

Multi-factor authentication with OpenID Connect​

Zmanda Pro supports its standard multi-factor authentication when an administrator authenticates using OpenID Connect; if an admin user has multi-factor authentication enabled on their account, Zmanda Pro will prompt them to complete the appropriate MFA process when they have successfully authenticated at the OIDC OP and have been returned to the Zmanda Pro Server web interface.

However, if a user has MFA enabled at their OP as well as Zmanda Pro, they will be prompted to perform MFA twice --- once when authenticating at the OP, and again when they are returned to Zmanda Pro. To avoid this, OIDC authentication sources can use the "Skip multi-factor authentication" option to opt out of Zmanda Pro's MFA even if admin users belonging to that source have it enabled for their account. This will cause Zmanda Pro to fully defer to the OP for MFA; if the OP does not have MFA enabled or the user does not have it configured for their account at the OP, then no MFA will occur at either side.