U4IDS Admin API and PowerShell commandlets

Getting the Admin Web-API PowerShell commandlets

As described in overview of Administration toolkit, Unit4 Identity Services (U4IDS) includes the Admin Web-API that allows you to configure the U4IDS settings. A set of PowerShell commandlets (cmdlets) is provided to simplify operations on the API.

Getting started

Install the U4.IdentityServices.PowerShell module

Check if the People Platform nuget repository is already registered on your computer:

PS C:\> Get-PSRepository

If not listed, register it:

PS C:\> Register-PSRepository 
        [-Name] U4PP 
        [-SourceLocation] "https://packages.u4pp.com/nuget/nuget/" 
        [-PublishLocation] "https://packages.u4pp.com/nuget/nuget/" 
        [-PackageManagementProvider] NuGet 
        [-InstallationPolicy] Trusted

You can now search for modules like U4.IdentityServices.PowerShell:

PS C:\> Find-module -Name U4.IdentityServices.PowerShell

To install the module:

Make sure you have the latest version of .NET installed when running the Identity Services PowerShell commandlets. The powershell commandlets have been verified on .NET 4.7.2. Always start a new PowerShell session if you have upgraded the .NET framework.

PS C:\> Install-Module -Name U4.IdentityServices.PowerShell -Repository U4PP -Scope AllUsers

Update to the latest version

To keep the module up to date run the following command:

PS C:\> Update-Module -Name U4.IdentityServices.PowerShell -Force

We recomend that you check for new versions of the Identity Services powershell commandlets regularly. To avoid dependency conflicts always make sure you start a new PowerShell session or window after an upgrade.

Get commands available

To find supported commands:

PS C:\> Get-Command -Module U4.IdentityServices.PowerShell

Get help for a command

The latest documentation is always available by using Get-Help, for instance:

PS C:\> Get-Help -Name Get-U4IDSClient -Full

Handling of the session

To use the Admin API capabilities, the user and/or client must be authenticated and authorized. The Admin API supports BearerToken authentication mode (see Administrator API configuration for more details). The cmdlet pair Connect-U4IDS and Disconnect-U4IDS is used to establish/close the session to the U4IDS.

Connect-U4IDS is used to establish a session with identity services and must be executed before using any of the Data administration cmdlets. Once the session is established with Connect-U4IDS it is highly recommended to close the session with the Disconnect-U4IDS cmdlet before exiting.

The list of parameters for Connect-U4IDS is shown below:

Parameter Description
ServerUri the URI address to the IdentityServices. Mandatory
AuthenticationType defines which authentication method shall be used ion the session. Valid values are : ClientCredential and ExternalIdentityProvider
ClientId provides the name under which the Admin API is registered, used only for bearer token authentication modes. A client with ClientId u4ids-admin-client is automatically generated. The secret for this client id chosen at deployment time and set in the application configuration of the IDS instance.
TenantId defines the U4IDS tenant for the Admin API, provides information about the external IdP of Admin API users, used only for AuthenticationType=ExternalIdentityProvider.
RedirectUri used only for AuthenticationType=ExternalIdentityProvider, defines the URI redirect value that is registered in the client's RedirectedURIs list;
ClientSecret used only for AuthenticationType=ClientCredential; in this flow ClientId and ClientSecret are used to authenticate at the token endpoint. Client secret is defined in the Admin API Client object.
Scope required only for AuthenticationType=ExternalIdentityProvider. For AuthenticationType=ClientCredential, Scope is set automatically to u4ids-admin. For users with access assigned through the IDS portal use Scope "u4ids-admin" only. For externally assigned administration role use Scope "u4ids-admin roles".

Authenticate using ClientCredentials

The most common scenario. Bearer token authentication will be applied with use of ClientCredential flow; for this type the ClientId and ClientSecret parameters are required.

Connect-U4IDS -ClientCredentialAuth -ClientId <string> -ClientSecret <string> -IdsUri <string>

Authenticate using InteractiveAuth

Authentication will be applied using Authorization Code with PKCE. The RedirectedUri parameter must correspond to the RedirectedUri that has been configured for the client and must start with oob://. If no RedirectUri is specified, the default value will be oob://localhost/u4ids.admin. The ClientSecret parameter is only mandatory if the client has been configured with a client secret. If the client has been configured with RequireConsent=true, the consent screen will be shown during authentication. Scopeis an optional parameter. 

Connect-U4IDS [-InteractiveAuth] <SwitchParameter> -ClientId <string> -IdsUri <string> -TenantId <string> [-ClientSecret <string>] [-RedirectUri <string>] [-Scope <string>] [<CommonParameters>]

Authenticate using ExternalIdentityProvider

Note

This commandlet has been deprecated in version 221.8.0.

Bearer token authentication will be applied with use of Implicit flow; for this type the ClientId, TenantId and Scope parameters are required (additionally the RedirectUri parameter can be specified). In this flow, execution of this cmdlet will open a login window of the Identity Provider (IdP) where the user is being authenticated - it is not possible to inject the Credential object as a parameter since the authentication is done outside of U4IDS control. 

Connect-U4IDS -ExternalIdentityAuth -ClientId <string> -TenantId <string> -IdsUri <string> [-RedirectUri <string>] [-Scope <string>] [<CommonParameters>]

Note

The Ids Uri should ALWAYS be WITHOUT /identity. If you add it you will get a message saying that this IDS is missing a discovery endpoint.

See the Configuration of clients for PowerShell section on how to configure the clients used as ClientId parameter.

Disconnect-U4IDS - closes the session. No parameters. All session data will be removed.

Note

If you can't connect with error "An error occurred while sending the request", it could be the TLS 1.2 issue. Try setting the SecurityProtocol variable in PowerShell

Example: Set SecurityProtocol variable from PowerShell command prompt

C:\> [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12

Example: Set Tls1.2 "permanently" in Registry

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319]
"SchUseStrongCrypto"=dword:00000001

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319]
"SchUseStrongCrypto"=dword:00000001

Creating a resource

Before you can add configuration data (resources), you have to create them. The configuration resources you can create are Clients, Scopes, Tenants, Secrets and Claims. Use the following commands:

Helper resource for Secret Expiration:

Note

The name and types of the properties that are defined in the resources reflect the properties defined on the Admin API level. See U4IDS-Admin Web-API for more details on these properties.

All the cmdlets listed above do not make any modification on the remote identity services store. They only create resources in the local PowerShell client.

After creation of an object you can set its additional properties, for example:

$client = New-U4IDSClient -ClientId "my_m2m_client" -ClientName "My machine-to-machine client" 
$client.Flow = ClientCredentials
$client.AccessTokenLifetime = 86400

Data administration cmdlets

All further cmdlets are used to modify the U4IDS configuration. The list of available cmdlets is shown below:

Cmdlet name Description
Add-U4IDSCacheCommand Posts a Cache Command to the database to trigger the removal of a SAML2 IDP entity from the in-memory cache using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS with the Connect-U4IDS cmdlet.
Add-U4IDSClient Adds a new client to UNIT4 Identity Services clients repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Add-U4IDSClientClaim Adds a new claim to an existing UNIT4 Identity Services client. Use Set-U4IDSClient to update the client repository with the changes.
Add-U4IDSClientSecret Adds a new client's secret to UNIT4 Identity Services clients repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Add-U4IDSScope Adds a new scope to UNIT4 Identity Services scopes repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Add-U4IDSScopeClaim Adds a new claim to an existing UNIT4 Identity Services scope. Use Set-U4IDSScope to update the client repository with the changes.
Add-U4IDSScopeSecret Adds a new scope's secret to UNIT4 Identity Services scopes repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Add-U4IDSScopeTitles Adds a title or a list of titles for a scope into Identity Services scopes repository.
Add-U4IDSTenantEx Adds a new tenant to UNIT4 Identity Services tenants repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Add-U4IDSTenantExIdp Adds a new idp to an existing UNIT4 Identity Services tenantEx. Use Add-U4IDSTenantEx to update the client repository with the changes.
Get-U4IDSClient If ClientId is provided, get the client with the ClientId. Otherwise, gets a list of all the clients registered in the UNIT4 Identity Services clients repository, using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Get-U4IDSClientClaim List the claims from an existing UNIT4 Identity Services client.
Get-U4IDSScope If TenantId is provided, get the scope with the ScopeId. Otherwise, get the list of all scopes registered in UNIT4 Identity Services scopes repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Get-U4IDSScopeClaim List the claims from an existing UNIT4 Identity Services scope.
Get-U4IDSScopeTitles Adds a title or a list of titles for a scope into Identity Services scopes repository.
Get-U4IDSTenantEx If TenantId is provided, get the tenant with the TenantId. Otherwise, get the list of all tenants registered in UNIT4 Identity Services tenants repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Remove-U4IDSClient Removes client from UNIT4 Identity Services clients repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Remove-U4IDSClientClaim Removes a claim from an existing UNIT4 Identity Services client. Use Set-U4IDSClient to update the client repository with the changes.
Remove-U4IDSClientSecret Removes a client's secret from UNIT4 Identity Services clients repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Remove-U4IDSScope Removes scope from UNIT4 Identity Services scopes repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Remove-U4IDSScopeClaim Removes a claim from an existing UNIT4 Identity Services scope. Use Set-U4IDSScope to update the scope repository with the changes.
Remove-U4IDSScopeSecret Removes a scope's secret from UNIT4 Identity Services scopes repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Remove-U4IDSScopeTitle Removes a title from a scope into Identity Services scopes repository
Remove-U4IDSTenantEx Removes tenant from UNIT4 Identity Services tenants repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Remove-U4IDSTenantExIdp Removes an idp from an existing UNIT4 Identity Services tenantEx. Use Set-U4IDSTenantEx to update the tenantEx repository with the changes.
Set-U4IDSClient Updates client in UNIT4 Identity Services clients repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Set-U4IDSScope Updates scope in UNIT4 Identity Services scopes repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.
Set-U4IDSTenantEx Updates tenant in UNIT4 Identity Services tenants repository using the Rest API accessible at the provided URL and authenticated with Connect-U4IDS cmdlet.

Cmdlet help

To get more information about using cmdlets, see the PowerShell help, for example:

Get-Help Add-U4IDSClient

Or use the -full parameter to get all the information (including example usages):

Get-Help Add-U4IDSClient -full

Parameter pipelineing

For better usability of the cmdlets it is possible to pipeline the model object, for example:

New-U4IDSClient -ClientId "MyClient" -ClientName "MyClientName" | Add-U4IDSClient

Cmdlet usage examples

Connect to the Admin API using ClientCredentials flow

Connect-U4IDS -ClientCredentialAuth -ClientId "u4ids-admin-client" -ClientSecret "<your secret>" -IdsUri "https://<u4ids base path>"

Connect to the Admin API using external identity (Portal assigned rights)

Connect-U4IDS -ExternalIdentityAuth -ClientId "u4ids-admin-client-interactive" -TenantId "u4ids-admin-tenant" -IdsUri "https://<u4ids base path>" -Scope "u4ids-admin"

Connect to the Admin API using external identity (Externally assigned admin role)

Connect-U4IDS -ExternalIdentityAuth -ClientId "u4ids-admin-client-interactive" -TenantId "u4ids-admin-tenant" -IdsUri "https://<u4ids base path>" -Scope "u4ids-admin roles"

Add a new client

$client = New-U4IDSClient -ClientId "test-powershell" -ClientName "test-powershell"
$client.Enabled = $FALSE
$client.Flow = "ClientCredentials"
Add-U4IDSClient $client

Update the ClientName of an existing client

$client = Get-U4IDSClient -ClientId "test-powershell" 
$client.ClientName = "Modified client name"
Set-U4IDSClient $client

Remove-U4IDSClient

Remove-U4IDSClient "test-powershell"

Configuration of clients for PowerShell

There are two methods to connect to the IDS administration API with PowerShell:

These both require clients set up in the IDS and used as Client parameter to the commandlets.

Client for client credentials authentication

Access to the u4ids-admin scope is regarded as a high privilege level of access.

In the example above a client called u4ids-admin-client is used with the ClientCredentialAuth option. This client is a default client in v2 and its initial secret is decided at deployment time. You can use any client that has flow ClientCredentials and is access to the u4ids-admin scope. A client credentials client does not need additional claims, role or configuration in U4 Access Management. It is therefore important that access to this scope is only given to clients whose secrets can be kept secure, i.e. in Azure KeyVault or similar high secure environments.

Client for external authentication

In the example above a u4ids-admin-client-interactive client is used with the ExternalIdentityAuth option. This client you have to configure on the IDS before it is possible to connect with external admin users. This kind of authentication needs additional authorization in the form of externally assigned admin role or individually granted access through the IDS portal. Because of this ExternalIdentityAuth is the preferred method of authentication when administrators work with powershell to configure IDS.

A client for interactive login needs to be configured with the following key settings beyond the default values:

Client property Value Description
ClientId u4ids-admin-client-interactive ClientId parameter to Connect-U4IDS command
ClientName IDS Admin Interactive Client for PowerShell Description of the purpose of this client
AccessTokenType Jwt Jwt tokens are sufficiently secure in this context
AccessTokenLifetime 3600 The lifetime of the token will decide the lifetime of a Connect-U4IDS session
Flow Implicit ExternalIdentityAuth use an embedded browser to complete the authentication of the administrator
AllowedScopes { openid, profile, u4ids-admin, roles } openid and profile for audit trail, u4ids-admin for access to the IDS api, roles for import of any externally assigned role claim
RedirectUris { oob://localhost/u4ids.admin } This is the default redirect uri the PowerShell commandlets use to capture the token after authentication. oob protocol to indicate that this is not a valid https address
RequireConsent True Administrator must consent to personal information, profile and roles to be used for this operation (audit trail)