Contents x
    OpenID Connect Identity Providers
    • 11 Oct 2024
    • 6 Minutes to read
    • Dark
      Light
    Contents

    OpenID Connect Identity Providers

    • Updated on 11 Oct 2024
    • 6 Minutes to read
    • Dark
      Light
    Article summary

    General

    OpenID Connect Identity Providers are identity providers using the OpenID Connect identity layer.

    Example: An example for an OpenID Connect Identity provider is Auth0.

    Properties

    OpenID Connect Identity Providers have the following properties:

    Name

    		Description
    NameThe name of the identity provider; this is a free text you can assign.
    DomainThe domain of the identity provider.
    Authorization Server IDThe ID of the authorization server. If left empty 'default' will be used. This property is only available if the type is set to Okta.
    IssuerThe issuer of ID tokens provided by the identity provider.
    Client IDThe client ID associated with Mail & Deploy in the identity provider.
    Client SecretThe client secret associated with Mail & Deploy in the identity provider.
    Custom ScopesZero, one, or more custom scopes separated by whitespaces.
    Callback URLThe callback URL to whitelist in the configuration of the identity provider.
    WARNING

    The callback URL depends on the name of the identity provider; if you change the Name property, the callback URL may change as well and that change also needs to be adjusted for in the configuration of the identity provider.

    Claims

    A claim is a property of an identity provided by the identity provider after a successful authentication attempt.

    Example: The nickname, e-mail address etc. are claims of an identity.

    Claims do not necessarily have the same name between individual OpenID Connect Identity Providers, which is why Mail & Deploy allows you to map the claim names to specific properties of a User with the following properties:

    Name

    		Description
    User IDThe name of the claim that uniquely identifies the user in the context of the identity provider.
    User NameThe name of the claim that contains the name of the user.
    E-Mail AddressThe name of the claim that contains the e-mail address of the user.
    GroupsThe name of the claim that contains an array of names of groups to which the user belongs in the context of the identity provider.

    Group Mappings

    Every authenticated identity is required to have a Groups claim that contains an array of the names of all groups to which the user belongs in the context of the identity provider.

    Groups Claim Example

    "Groups": ["Administrators", "UK Users"]

    Whenever an identity is authenticated, Mail & Deploy checks whether that identity has access to Mail & Deploy. It does that by looking at the group mappings of the identity provider. Only users who have at least one group name in their Groups claim that has an associated group mapping will have access to Mail & Deploy. Group mappings have the following properties:

    Name

    		Description
    IdP Group NameThe name of the group in the context of the identity provider.
    Users of this Group are AdministratorsWhen enabled, Users who belong to the identity provider group will be of type Administrator in Mail & Deploy. If a user is a member of multiple mapped groups, the user will be of type Administrator if he is a member of at least one mapped group that has this property enabled.
    Add Users to User GroupWhen enabled Mail & Deploy will not only create a User to grant authenticated identities who belong to the identity provider group access to Mail & Deploy but also add those users to the User Group specified in the User Group property (see below).
    User GroupThe User Group to add Users whose identity belongs to the identity provider group to.

    Defaults

    Every OpenID Connect Identity Provider has the following default properties:

    Name

    		Description
    Default LanguageThe default language to assign to Users authenticated through the identity provider.
    Default Time ZoneThe default time zone to assign to Users authenticated through the identity provider.
    Default CultureThe default culture to assign to Users authenticated through the identity provider.
    Users of this Group are AdministratorsWhen enabled, Users who belong to the identity provider group will be of type Administrator in Mail & Deploy. If a user is a member of multiple mapped groups, the user will be of type Administrator if he is a member of at least one mapped group that has this property enabled.

    These properties will be the default properties for Users who authenticate through the identity provider. You can use Rules (see below) to override these default values.

    Rules

    The default properties (see above) defined the defaults to assign to Users authenticating through the identity provider. The following properties allow you to specify a dynamic assignment of these properties and to override the defaults:

    Name

    		Description
    Language Code RuleAn optional Expression that returns a String that contains the code of the language (e.g. en for English) to assign to a Users authenticating through the identity provider.
    Time Zone RuleAn optional Expression that returns a TimeZoneInfo or a String that contains the ID of a time zone (one of the values in the Timezone column of the Windows Default Time Zones) to assign to a Users authenticating through the identity provider.
    Culture RuleAn optional Expression that returns a CultureInfo or a String that contains the code of a culture (one of the values in the CultureInfo Code column of the Culture Code List) to assign to a Users authenticating through the identity provider.

    Expression used in rules have access to the expression parameter IdpUser which represents the identity provided by the identity provider; this object provides access to the claims of the identity.

    The Id property contains the value of the User ID claim of the identity.

    Id Proberty Expression Example

    [IdpUser].Id

    The Name property contains the value of the User Name claim of the identity.

    Name Proberty Expression Example

    [IdpUser].Name

    The EMailAddress property contains the value of the E-Mail Address claim of the identity.

    Name Proberty Expression Example

    [IdpUser].Name

    The Groups property contains an array of the name of all groups of the identity in the context of the identity provider which are provided through the Groups claim of the identity.

    Groups Expression Example

    [IdpUser].Groups

    The HasProperty function returns whether the identity has a claim with the given name.

    HasProberty Expression Example

    [IdpUser].HasProperty("Locale")

    The GetProperty function returns the value of the claim with the given name or the default value, if the identity does not have such a claim.

    GetProberty Expression Example

    [IdpUser].GetProperty("Locale", "en")

    Example

    Let's suppose your specific OpenID Connect Identity Provider returns the following identity after a successful authentication:

    Identity

    {
    "Id": "1234",
    "Username": "Bob Adams",
    "Mail":"bob.adams@company.com",
    "UserGroups":["Mail & Deploy Administrators", "US Users"]
    }

    Step 1: Configuring Claims

    To set up the claims of the OpenID Connect Identity Provider, the User ID claim name needs to be set to Id (because that is the property of the identity returned by the identity provider), the User Name claim name needs to be set to UserGroups etc.

    Step 2: User Group Mappings

    If the identity provider does not contain any group mappings, the user will not have access to Mail & Deploy. Only if Mail & Deploy finds at least one group mapping for any of the groups of the returned identity will it create a User and allow to use Mail & Deploy.

    Example: In our case, there must be a group mapping for the the identity provider group Mail & Deploy Administrators and/or US Users to grant the identity access to Mail & Deploy.

    If you create a group mapping where you set IdP Group to Mail & Deploy Administrators and you enable Users of this Group are Administrators, then the authenticated user will not only have access to Mail & Deploy but will also be of type Administrator.

    NOTE

    If an authenticated identity has at least one mapped group where Users of this Group are Administrators is enabled, the resulting User will be of type Administrator.

    Step 3: Defaults and Rules

    Let's suppose you have set the Default Language of the identity provider to German; this means that all Users authenticating through the identity provider will have the language German assigned. However, you can create a rule that allows to override this default value. Let's say we want to create a rule that assigns the language English to all identity who are members of the US Users group in the identity provider, and German for all other users. This can be achieved with the following expression in the Language Rule property:

    Language Code Rule

    If([IdpUser].Groups.Contains("US Users"), "en", "de")

    Was this article helpful?
    What's Next