Tenant registration

About tenant configuration

The tenant configuration reflects an organization that is known to your applications. Whereas the client configuration defines how your application will authenticate with the Unit4 Identity Services (U4IDS), the tenant configuration dictates how a specific organization (tenant) known to the client will authenticate with an external identity provider (IdP). All communication with the external identity system is orchestrated by U4IDS. It is important that the tenantId is uniquely identifying the Unit4 customer organization, and that the value corresponds to the tenantId used in other Unit4 services and applications the organization is using.

How to register a tenant?

There are two available methods for registering a tenant see Administrator toolkit overview

Register a OpenID Connect Identity Provider

This section outlines how to configure a tenant to connect to Azure AD using the OpenID Connect protocol. Azure AD supports by default the OpenID Connect protocol. You must register U4IDS as an application on your Azure AD, during these steps you will obtain a Client ID and a key - these properties must be set as the IdpRegId and IdpSecret in the tenant configuration. The Authority property should be set to your Azure AD name, usually in this format https://login.windows.net/.onmicrosoft.com, where the tenant name is the tenant name or directory name. Internally U4IDS uses the Authority to read the OpenID Connect metadata from Azure AD.

The next step is to map a known claim provided by Azure AD to the unit4_id claim using the Unit4IDClaimType property. You must to do the same for NameClaimType.

A configuration could look like this:

{
    "tenantId": "Tenant1",
    "tenantName": "Azure AD",
    "description": "Tenant1 using central Azure AD",
    "idps": [
    {
       "idpName": "Tenant1idp",
       "description": "Azure AD",
       "idpRegId": "12345678-ff04-4ecb-a966-71c6c7a63236",
       "idpSecret": "nfLmHH5yK4HuRBpkTcOFdLT7JkVUX7uv8KrI+7D90TE=",
       "authority": "https://login.windows.net/tenant1.onmicrosoft.com",
       "protocol": "openidconnect",
       "unit4IdClaimType": [ "email" ],
       "nameClaimType": "name"
    }]
}

Note that the tenantId will usually be a globally unique identifier for the Unit4 customer organization and should be a guid. "Tenant1" is used here for readability. Optionally an OIDC tenant configuration can contain an openIDConnectOptions settings where response_type and scope requested externally can be set.

Register a WS-Federation Identity Provider

If you configure a tenant to use WS-Federation the Authority property needs to point to the metadata endpoint published by the external identity provider. The IdpRegId contains the App ID URI obtained when you configure U4IDS with the Azure AD. With WS-Federation there is no need to configure the IdpSecret property.

A configuration could look like this:

{
    "tenantId": "Tenant2",
    "tenantName": "AD with WS-Federation",
    "description": "Tenant2 using central AD and WS-Federation protocol",
    "idps": [
    {
       "idpName": "Tenant2idp",
       "description": "AD & WS-Federation",
       "idpRegId": "spn:b339aec8-5ae8-40b1-8009-18246b689ea3", 
       "authority": "https://login.microsoftonline.com/<guid>/federationmetadata/2007-06/federationmetadata.xml",
       "protocol": "ws-federation",
       "unit4IdClaimType": [ "email", "name" ],
       "nameClaimType": "name"
    }]
}

You may see how to configure AD FS in the appendix here.

Register a SAML2-P Identity Provider

To enable SAML for a Tenant, the protocol property has to be set to saml2. The authority property should be configured to point to the external identity providers metadata endpoint. Value of idpRegId property should be the identity provider's Entity Id. The SAML middleware used by U4IDS is using identityserver:providers:saml2:entity-id app setting as Service Provider Entity Id. This value will be sent as application identifier in the authentication request to the external identity provider.

The configuration could look like this:

{
    "tenantId": "Tenant3",
    "tenantName": "AD with SAML",
    "description": "Tenant3 using Azure AD with the SAML protocol",
    "idps": [
    {
       "idpName": "Tenant3idp",
       "description": "Azure AD with the SAML",
       "authority": "https://login.microsoftonline.com/<guid>/federationmetadata/2007-06/federationmetadata.xml",
       "protocol": "saml2",
       "idpRegId": "https://sts.windows.net/12345678-da7c-484c-ade2-92bb3f948cf8/",
       "nameClaimType": "name"
    }
    ]
}

You may see a sample how to configure SAML-P tenant here.

Claims transformation

When the user is authenticated by the external identity provider, U4IDS receives incoming claims from the external identity provider.

For the client application to have a set of reliable user claims, U4IDS returns a specific claim named unit4_id which can be used to connect an external user to a user known by the client application. The unit4_id claim must be unique.

When a tenant is registered with U4IDS, you must define the name of the claim that should be set as the unit4_id claim. The configuration property supports a list of claim names to make it possible to fallback if the first claim is not present in the claims returned by the external identity provider.

Reply URLs

As part of the authentication process, the configured external identity provider will need call URLs (endpoints) on U4IDS. To make the external identity provider call these endpoints you might need to add them to a list of accepted reply URLs. If this is the case these endpoints needs to be registered as reply URLs:

 https://<domain>/identity/callback
 https://<domain>/identity/postlogoutcallback