Creation of secrets

About this topic

This topic describes how secrets can be configured on Unit4 Identity Services (U4IDS). Secrets can be defined for clients (for example, for ClientCredential flow a secret is required) or scopes (for example, scope with a secret is required to authenticate at Introspect endpoint of U4IDS).

The table below describes the structure of the Secret class:

Parameter name Parameter type Description
Description string Description of the secret
Expiration DateTimeOffset Expiration time of the secret nullable if never expires
Value string Secret value

U4IDS-Admin does not allow to define the secret value by the user. Secret values are always generated by the U4IDS. The secret value is returned to the user only once in the result of a new secret registration. It is not possible to obtain the value of an already defined secret as only its hash is stored in the U4IDS database, so it is important to securely store the generated secret value immediately after its provisioning.

API for secrets administration

Provisioning of secrets is possible with use of dedicated API endpoints:

Both endpoints support the POST VERB. It will create a new secret. As mentioned before, Value must not be specified as this is generated on the server side. It is possible to provide values for the Description and Expiration fields. If the Expiration field is not provided, then the secret never expires. In the result of the POST operation newly created secret will be returned (including its value) and this is the only moment when secret value can be obtained.

Powershell Commandlets for secrets administration

Additionally, the following cmdlets are available for administrating the secrets:

If -Description or -Expiration parameter is not provided for Add-IdentityServicesClientSecret or Add-IdentitySerivcesScopeSecret then a new secret with no description and/or no expiration date (respectively) will be generated.

Examples

Creating a client with a secret that never expires:

$client = New-IdentityServicesClient -ClientId "myClient" -ClientName "My client name" -Flow Hybrid
Add-IdentityServicesClient $client

$added_secret = Add-IdentityServicesClientSecret -ClientId "myClient" -Description "my client secret"

# store the generated secret in a file (this file should be stored securely)
$added_secret.Value > my_client_secret.txt

Creating a scope with a secret that expires on 12/31/2016:

$scope = New-IdentityServicesScope -Name "myScope" 
Add-IdentityServicesScope $scope

$expiration = [System.DateTimeOffset]::Parse("12/31/2016")
$added_secret = Add-IdentityServicesScopeSecret -ScopeName $scope -Description "my scope secret" -Expiration $expiration

# store the generated secret in a file (this file should be stored securely)
$added_secret.Value > my_scope_secret.txt

Client credential flow

When a new client is created with Client credential flow set, U4IDS always generates a secret, even if it is not requested explicitly. An implicitly generated secret has no expiration.

Example

Provision client with client credential flow, secret set implicitly:

$client = New-IdentityServicesClient -ClientId "myClient2" -ClientName "My Identity Services client with credential" -Flow ClientCredentials

# add client to the DB
$added_client = Add-IdentityServicesClient $client

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