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.

Download the configuration:
Download configuration
GET .../ws/deploy/configuration?tenantId=x

Response body is the configuration zip.
Upload the configuration:
Upload configuration
POST .../ws/deploy/configuration?tenantId=x[&overwrite=true][&mergeNumberRangeFragment=true][&extendNumberRangeByUsedFragments=false]
Request body has to be a valid configuration zip.
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.
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.

Parameter	Default	Description

Parameter	Default	Description
overwrite	true	When set to false, an exception is thrown instead of overwriting an existing object.
mergeNumberRangeFragment	true	Merges the usage data from number range fragments. Setting this to false may break number ranges of produced cards.
extendNumberRangeByUsedFragments	false	When set to false, number ranges are automatically extended, otherwise throws an exception.

Upload license file

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

Upload the license:
Upload license
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).

Property	Default

Property	Default
`licenseRestController.permittedRole`	`Administrator`

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".

Set properties:
Set properties
The request body has to be a json like:

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

Context	Property	DataType	Default Value

Context	Property	DataType	Default Value
smtpContext	host	STRING	localhost
	port	NUMERIC	25
	user	STRING
	password	REF
	defaultSender	STRING	"activiti@localhost"
	timeout	NUMERIC	5000
	connectionSecurity	STRING ("none" \| "smtps" \| "starttls")	"none"
	checkServerIdentity	boolean	false
licenseContext	clientLicense	BINARY
tunnelServerContext	primeUri	STRING	http://localhost:8080/prime_explorer
hagXPIContext	user	STRING	xpiadmin
	password	REF
	authenticationMethodId	NUMERIC	3
coreTemplateContext	searchFieldsChanged	STRING
mdmContext	mobileiron.rest.url	STRING
	mobileiron.rest.username	STRING
	mobileiron.rest.password	STRING
processTimeoutContext	usertaskTimeoutDuration	STRING	PT2H
hideOpenTasksContext	hideOpenTasks	BOOLEAN	false
relatedObjectsContext	expandRelatedObjects	BOOLEAN	false
authMethodsContext	showUserPasswordMethod	BOOLEAN	true
	showCertAuthMethod	BOOLEAN	true
	showSamlAuthMethod	BOOLEAN	true

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

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:

HTTP Code	Example Response Body	Meaning

HTTP Code	Example Response Body	Meaning
200	-	Setting the properties worked fine.
415	-	The logged in user doesn't have the permission to set system properties.
400	Wrong structure	The structure of the request is wrong, like in this case: Invalid Request Body
400		The context does not exist.
400		The property does not exist in the context.
400		The value of the property cannot be transformed to the type of the property
400	Other responses like those above	Like on the UI there are some more validations for contexts and properties depending on the configuration of the property pointing you to the issue. The issues are always provided in English in this REST API.

Nexus Documentation

Smart ID Identity Manager - Deployment REST APIs