Admin API authentication configuration

The Admin API is used to administer configuration data (tenants, clients, scopes and secrets) for Unit4 Identity Services (U4IDS). The Admin API requires authentication, and uses bearer authentication.

Initial setup

You connect a U4IDS service to an Admin API service using the following application settings:

Initial client and scope

A client with ClientId 'u4ids-admin-client' is always available.

Initially, the 'u4ids-admin-client' is an in-memory client. You set the secret for the in-memory client using the configuration value (application settings) 'admin:client-secret'.

Note: 'admin:client-secret' is an application settings for U4IDS, and not for the Admin API service.

If the application setting 'admin:client-secret' it not set, U4IDS will accept 'u4ids-admin-client-secret' as the secret. Change this secret immediately! Either by giving the application setting 'admin:client-secret' a value, or by creating a new client with the same client id.

The 'u4ids-admin-client' has access to the 'u4ids-admin' scope (the Admin API resource). This scope is also created automatically, and can not be changed or deleted.

The in-memory client is not visible from the Portal or Admin API. We reccommend that you create a new "real" 'u4ids-admin-client' client.

Create a new 'u4ids-admin-client'

# Connect to the U4IDS
# <u4ids base path> looks something like this "https://u4ids-sandbox.u4pp.com" 
Connect-U4IDS -ClientCredentialAuth -ClientId "u4ids-admin-client" -ClientSecret "u4ids-admin-client-secret" -IdsUri "https://<u4ids base path>"

# Create the client
$client = New-U4IDSClient -ClientId "u4ids-admin-client" -ClientName "U4IDS Admin API client for non-interactive login (scripting)." -Flow ClientCredentials

# Change settings and add Admin API scope
$client.AccessTokenType = [U4.IdentityServices.AdminSDK.Types.AccessTokenType]::Reference
$client.AccessTokenLifetime = 86400
$client.AllowedScopes.Add("u4ids-admin")

# Add the client. Note that the result of the operation should be stored in a variable
# in order to read the value of the generated secret
$added_client = Add-U4IDSClient -Client $client

# Store the generated secret in a file (this file should be stored securely)
$added_client.Secrets[0].Value > my_client_secret.txt

# You should now restart PowerShell before you connect with the new u4ids-admin-client
# You also have to wait about 5-10 minutes until the old client is purged from the in-memory cache of the IDS

Note: ClientCredentials clients have unlimited access to the Admin API. For these clients, additional role claims are not used.

Migrations

Before you can use U4IDS, the database tables and initial data has to be created. This is done when you start the Admin API service. Every time it is restarted, it will check for new migrations and run them.

Note: Since Admin API service creates the tables that the U4IDS service use, always start the Admin API service before the U4IDS service.

Authentication

Authentication using PowerShell can be setup in two ways:

Note: The BasicAuth and ExternalIdentityAuth parameters are obsolete. Use the InteractiveAuth parameter instead. ExternalIdentityAuth uses the Implicit flow, while InteractiveAuth uses AuthCodeWithPKCE which is more secure.

Authenticate with client credentials clients

There will always be a client called 'u4ids-admin-client' (see above). You can use this to connect to the API and create your initial clients, scopes and tenants.

In addition, you might want to setup other ClientCredentials clients. But remember they they will all have full access to ALL the configuration data for this IDS.

Authenticate with an interactive client

To allow administrators to login using their organizational account, you need an interactive client that forwards authentication to an external identity provider. The following must be configured in U4IDS:

The client

You should create this client with the "AuthCodeWithPKCE" flow. The code below shows an example:

# Connect to U4IDS
# <u4ids base path> looks something like this "https://u4ids-sandbox.u4pp.com" 
Connect-U4IDS -ClientCredentialAuth -ClientId "u4ids-admin-client" -ClientSecret "<your secret>" -IdsUri "https://<u4ids base path>"

$client = New-U4IDSClient -ClientId "u4ids-admin-client-interactive" -ClientName "Identity Services Admin client" 
$client.AccessTokenType = [U4.IdentityServices.AdminSdk.Types.AccessTokenType]::Reference

$allowedScopes = New-Object -TypeName "System.Collections.Generic.List[System.String]";
$allowedScopes.Add("openid");
$allowedScopes.Add("profile");
$allowedScopes.Add("u4ids-admin");
$client.AllowedScopes = $allowedScopes;
$client.AccessTokenLifetime = 86400 # 24 hours

$redirectUris = New-Object -TypeName "System.Collections.Generic.List[System.String]";
# Set your redirectUri. The default Uri for the PowerShell cmdlet is "oob://localhost/u4ids.admin"
$redirectUris.Add("oob://localhost/u4ids.admin");
$client.RedirectUris = $redirectUris;
$client.Flow = [U4.IdentityServices.AdminSdk.Types.OidcFlow]::AuthorizationCodeWithProofKey

# You may also have to include AllowedCorsOrigins

# Add the client. Note that the result of the operation should be stored in a variable
# in order to read the value of the generated secret
$added_client = Add-U4IDSClient -Client $client

Disconnect-U4IDS

# Try connecting with the new client:
Connect-U4IDS -InteractiveAuth -ClientId 'u4ids-admin-client-interactive' `
-IdsUri 'https://u4ids-sandbox.u4pp.com' `
-TenantId '<Your Tenant>' -Scope 'u4ids-admin'

# Note: The AuthorizationCodeWithProofKey flow doesn't require a client secret,
#       but if you add a secret to the client, you also have to use the ClientSecret
#       parameter for the Connect-U4IDS command.

Note

The recommended value for RedirectUris is "oob://localhost/u4ids.admin". This is the default redirect uri of the U4IDS PowerShell Commandlet. You do not have to provide the RedirectUri if the default value is used.

Note:

If there is no u4_role claim, the role is fetched from "Access Management" (see Access Management documentation for configuring this).