- Created by Ann Base, last modified on May 05, 2022
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
- To enable debug logging for the REST APIs, use the package de.nexus.deploy to investigate issues.
The endpoint is available in Identity Manager Admin and Identity Manager Operator.
Download the configuration:
Response body is the configuration zip.Download configurationGET .../ws/deploy/configuration?tenantId=x
Upload the configuration:
Upload configurationPOST .../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:
- For Identity Manager Admin, the user must have the permission "Configuration file" (this gives permission to up- and download configuration).
- 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 |
|---|---|---|
| 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. |
The endpoint is available in Identity Manager Admin and Identity Manager Operator.
Upload the license:
Upload licensePOST .../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 |
|---|---|
licenseRestController.permittedRole | Administrator |
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 propertiesPOST .../ws/deploy/property?tenantId=x
The request body has to be a json like:
{ "smtpContext": { "host": "my-host", "port": 25 } }
List of properties and context (extracted from vps-frontend.jar in spring/systemproperties-beans.xml)
| 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 |
|---|---|---|
| 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 |
|---|---|---|
| 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 {
"host": "my-host"
}
|
| 400 | {
"dummyContext": "Invalid context"
}
| The context does not exist. |
| 400 | {
"dummyContext.dummyProperty: "Invalid property"
}
| The property does not exist in the context. |
| 400 | {
"dummyContext.dummyProperty: "Invalid data type. Expected NUMERIC"
}
| 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. |