Client registration

About client registration

A trust relationship is required between the client and the Identity Server. When allowing clients to get an identity, trust must exist between the client and the Identity Server (IdP). For Unit4 Identity Services (U4IDS) to trust your client, the client must be registered in the U4IDS client store. The properties of the client give the IdP needed information about how it can communicate with the client in a secure way. When a client performs an authentication request, the properties will be validated by U4IDS.

How to register a client?

When registering a client, U4IDS needs information about the client in order to validate and authenticate. The properties you must register for a client are based on your requirements for authentication and the client type you have. For more details of client type and respective properties, see client configuration.

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

Client types registration

The client configuration reflects an application in your eco system that requires federated authentication, either for authenticating a user or for accessing a resource. Depending on your type of application, different properties are required. The type of application will dictate the authentication flow that is applicable. In the simple scenarios you need to configure the following properties:

Register a client-side rendered browser application

Below is a list of properties connected to a browser application that renders the code on the server.

Property name	Description
ClientId	A unique identifier of your client
ClientName	Name on your client that will be used for logging
AllowedCorsOrigins	To enable CORS for your client you must register the base address of your application.
AccessTokenType	Reference or Jwt token, default to Jwt
Flow	Specifies allowed flow. Implicit for client-side rendered applications.
RedirectUris	Specifies allowed URIs to return tokens or authorization codes to.
Scopes	Either allow all scopes using the AllowAccessToAllScopes property or specify the supported scopes via the AllowedScopes property

Example

Below is an example of a implicit client resource with JSON that can be used with the Administrator toolkit Web API.

 {
    "clientId": "shurikeninc-webclient",
    "clientName": "Shuriken Inc.",
    "flow": "implicit",
    "AllowedScopes": [ "openid" ],
    "LogoutUri": "https://shurikeninc.com/endsession.html",
    "PostLogoutRedirectUris": [ "https://shurikeninc.com/logout.html" ],
    "RedirectUris": [ https://shurikeninc.com ],
    "AllowedCorsOrigins": [ "https://shurikeninc.com" ],
    "AccessTokenType": "Jwt"
  }

Register a native application client or server-rendered (browser) application

Below is a list of properties connected to a native or server-rendered application.

Property name	Description
ClientId	A unique identifier of your client
ClientName	Name on your client that will be used for logging
AccessTokenType	Reference or Jwt token, default to Jwt
Flow	Specifies allowed flow. Implicit, Hybrid or AuthorizationCode.
RedirectUris	Specifies allowed URIs to return tokens or authorization codes to.
Scopes	Either allow all scopes using the AllowAccessToAllScopes property or specify the supported scopes via the AllowedScopes property
ClientSecrets	A shared secret. Note: must be stored in a secure place.

Example

Below is an example of a hybrid client resource with JSON that can be used with the Administrator toolkit Web API.

{
    "clientId": "shurikeninc-smartclient",
    "clientName": "Shuriken Inc.",
    "flow": "hybrid",
    "AllowedScopes": ["openid", "offline_access"],
    "RedirectUris": [ "https://shurikeninc.com"],
    "PostLogoutRedirectUris": [ "https://shurikeninc.com/logout.html" ],
    "ClientSecrets": [ { } ]
  }

Note The Implicit flow was previously recommended for native, mobile, and browser-based apps to immediately grant the user an access token. However, the Authorization Code flow (with PKCE) is now the new standard for more secure authorization for these types of apps. The next paragraph provides more information.

Proof Key for Code Exchange (PKCE)

PKCE (RFC 7636) is an extension to the Authorization Code flow to prevent several attacks and to be able to securely perform the OAuth exchange from public clients.

For native and browser-based JavaScript apps, it is now widely considered a best practice to use the Authorization Code flow with the PKCE extension, instead of the Implicit flow or hybrid flow.

This flow is like the regular Authorization Code flow, except PKCE replaces the client secret used in the standard Authorization Code flow with a one-time code challenge. This means the client app doesn't have to store a client secret, unless it wants to.

Below is a list of properties connected to a native or server-rendered application using PKCE flow.

Property name	Description
ClientId	A unique identifier of your client
ClientName	Name on your client that will be used for logging
AllowedCorsOrigins	To enable CORS for your client you must register the base address of your application.
AccessTokenType	Reference or Jwt token, default to Jwt
Flow	Specifies allowed flow. AuthorizationCodeWithProofKey.
RedirectUris	Specifies allowed URIs to return tokens or authorization codes to.
Scopes	Either allow all scopes using the AllowAccessToAllScopes property or specify the supported scopes via the AllowedScopes property
ClientSecrets	Optional. Shared secrets. Note: must be stored in a secure place.
AccessTokenType	Reference or Jwt token, default to Jwt

Example

Below is an example of a PKCE client resource with JSON that can be used with the Administrator toolkit Web API.

{
    "clientId": "shurikeninc-smartclientwithpkce",
    "clientName": "Shuriken Inc.",
    "flow": "AuthorizationCodeWithProofKey",
    "AllowedScopes": ["openid", "profile", "fooapi"],
    "RedirectUris": [ "https://shurikeninc.com"],
    "PostLogoutRedirectUris": [ "https://shurikeninc.com/logout.html" ],
    "ClientSecrets": [ { } ] // set client secret for confidential clients
    "AllowedCorsOrigins": [ "https://shurikeninc.com" ],
    "AccessTokenType": "Jwt"
  }

Machine to machine (server to server)

Below is a list of properties connected to a server client with no user interaction.

Property name	Description
ClientId	A unique identifier of your client
ClientName	Name on your client that will be used for logging
AccessTokenType	Reference or Jwt token, default to Jwt
Flow	Specifies allowed flow. ClientCredentials for server to server integration.
Scopes	Either allow all scopes using the AllowAccessToAllScopes property or specify the supported scopes via the AllowedScopes property
ClientSecrets	A shared secret

Example

Below is an example of a clientCredential client resource with JSON that can be used with the Administrator toolkit Web API.

{
    "clientId": "shurikeninc-workflowclient",
    "clientName": "Shuriken Inc. workflow process",
    "flow": "clientCredential",
    "AccessTokenType": "Jwt",
    "ClientSecrets": [ { } ]
  }

User impersonation clients (custom)

Below is a list of properties connected to a server clients with user interaction.

Property name	Description
ClientId	A unique identifier of your client
ClientName	Name on your client that will be used for logging
AccessTokenType	Reference or Jwt token, default to Jwt
Flow	Specifies allowed flow. custom for user impersonation grant type.
Scopes	Either allow all scopes using the AllowAccessToAllScopes property or specify the supported scopes via the AllowedScopes property. Specify the AllowedScopes is more common for user impersonation grant type
ClientSecrets	A shared secret
AllowedCustomGrantTypes	user_impersonation

Example

Below is an example of a custom flow client resource with JSON that can be used with the Administrator toolkit Web API.

{
    "clientId": "shurikeninc-userimpersonatorclient",
    "clientName": "Shuriken Inc.",
    "flow": "Custom",
    "ClientSecrets": [
        { }
    ],
    "AllowedScopes": [ "openid"],
    "AllowedCustomGrantTypes": [ "user_impersonation ]
  }

Claims upgrade clients (custom)

Below is a list of properties used for this flow

Property name	Description
ClientId	A unique identifier of your client
ClientName	Name on your client that will be used for logging
AccessTokenType	Reference or Jwt token, default to Jwt
Flow	Specifies allowed flow. custom for claims upgrade grant type.
Scopes	Either allow all scopes using the AllowAccessToAllScopes property or specify the supported scopes via the AllowedScopes property. Refer to a scope that defines the claim types you are planning to include
ClientSecrets	A shared secret
AllowedCustomGrantTypes	claims_upgrade

Example Below is an example of a custom flow client and its matching scope (JSON format).

{
    "clientId": "shurikeninc-claimsupgradeclient",
    "clientName": "Shuriken Inc. Claims Upgrade",
    "flow": "Custom",
    "ClientSecrets": [
        { }
    ],
    "AllowedScopes": [ "some_upgrade_scope"],
    "AllowedCustomGrantTypes": [ "claims_upgrade ]
}

{
    "displayName": "Some Claims Upgrade Scope",
    "enabled": true,
    "includeAllClaimsForUser": true,
    "name": "some_upgrade_scope",
    "type": "Resource",
    "claims": [{
        "name": "some_claim",
        "description": "Some claims provided by Shuriken Inc"
    }]
}

All available client properties are documented here. Note that documented properties might not be applicable for U4IDS.

Note

Client secret: for code based flows, you must embed the client secret in the client application. However, you cannot treat that as a secret anymore - no matter how good you protect it, a motivated attacker will be able to reverse engineer it. It is still better than no secret at all. Specifications like Proof Key for Code Exchange (PKCE) make it also better.