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
|Parameter name||Parameter type||Description|
|Description||string||Description of the secret|
|Expiration||DateTimeOffset||Expiration time of the secret nullable if never expires|
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:
- Add-IdentityServicesClientSecret -ClientId myClientId [-Description secretDescription] [-Expiration myExpiration]
- Add-IdentityServicesScopeSecret -ScopeName myScopeName [-Description secretDescription] [-Expiration myExpiration]
-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.
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.
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.Value > my_client_secret.txt