Smart ID Identity Manager - Deployment REST APIs

This article is valid for Smart ID 21.10 and later.

This article describes a few REST APIs that can be used to avoid manual steps while deploying Smart ID Identity Manager. All of them are reachable by the path */ws/deploy.

Prerequisites

The REST APIs described in this article:

• require the user or script to authenticate by basic auth or client certificate authentication

• require the "tenantId" as query parameter

Step-by-step instruction

Enable debug logging

• To enable debug logging for the REST APIs, use the package de.nexus.deploy to investigate issues.

Upload and download configuration

The endpoint is available in Identity Manager Admin and Identity Manager Operator.

1. Download the configuration:

   Download configuration

   CODE

   GET .../ws/deploy/configuration?tenantId=x

   Response body is the configuration zip.

2. Upload the configuration:

   Upload configuration

   CODE

   POST .../ws/deploy/configuration?tenantId=x[&overwrite=true][&mergeNumberRangeFragment=true][&extendNumberRangeByUsedFragments=false]

   Request body has to be a valid configuration zip.

3. This endpoint is build to behave similar to the user interface, so you need the same permission, the zip signing and verification is triggered by the same parameters.

4. The authenticated user needs to have the same permission as in the user interface:

   1. For Identity Manager Admin, the user must have the permission "Configuration file" (this gives permission to up- and download configuration).

   2. For Identity Manager Operator, the user must have the permission "Upload Configuration" / "Download Configuration".

Query parameters

These query parameters are optional for configuration upload. Default behavior is the default from the user interface.

Upload license file

The endpoint is available in Identity Manager Admin and Identity Manager Operator.

1. Upload the license:

   Upload license

   CODE

   POST .../ws/deploy/license?tenantId=x.

   Request body has to be a valid license for the specific product (Identity Manager Admin / Operator)

The license upload does not require a specific role on the user interface, but is only possible while there is no valid license.

The REST API can be triggered also while there is a valid license. Due to that, a parameter for the allowed role is introduced in the System Properties (see List of Identity Manager system properties).

Configure system properties

There is a REST API in Identity Manager Operator used to set the system properties of the admin page. This is not related to the SYSTEM_PROPERTIES you can configure in the environment variables.

The authenticated user needs to have the same permission as in the user interface: "Configure system properties".

1. Set properties:

   Set properties

   CODE

   POST .../ws/deploy/property?tenantId=x

2. The request body has to be a json like:

   CODE

   {
     "smtpContext": {
       "host": "my-host",
       "port": 25
     }
   }

List of properties and context (extracted from vps-frontend.jar in spring/systemproperties-beans.xml)

All DataTypes which are supported on the UI are also supported in the REST API. The validation of the properties also works the same way.

DataType	Usage in the request	Further info
NONE, LONG, STRING	String e.g. "sample"	Like on UI these DataTypes are handled the same way, as a text value.
NUMERIC	numeric e.g. 25	Fractional part will be dropped as IDM has in general on natural number handling. E.g. 12.5 is handled like 12.
BINARY, IMAGE	base64 encoded String e.g. "c2FtcGxl"
BOOLEAN	boolean e.g. true
HEX_STRING	String e.g. "0123456789ABCDEF"	Validated by regex to be a valid hexadecimal string.
PASSWORD	String e.g. "sample"	THIS DOESN'T WORK ON UI, but in API. So this is the only type with different behavior between UI and REST API. Value is hashed before saving.
REF	String e.g. "sample"	Value is stored in SecretFieldsStore. Changing still uses the same
DATE, DATETIME, TIME	String in this format "yyyy-MM-dd'T'HH:mm:ss.SSS'Z" e.g. "2021-06-17T08:06:30.000Z"	THEY DON'T WORK ON UI AND FAIL WITH THE SAME BEHAVIOR IN THE REST API! DATE ignores the time part of this datetime string. TIME ignores the date part of this datetime string. DATETIME and TIME ignore the seconds and milliseconds of this datetime string.

Possible Responses:

{
	"host": "my-host"
}

{
  "dummyContext": "Invalid context"
}

{
  "dummyContext.dummyProperty: "Invalid property"
}

{
  "dummyContext.dummyProperty:  "Invalid data type. Expected NUMERIC"
}