Document toolboxDocument toolbox

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

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

     

    Response body is the configuration zip.

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

  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.

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.

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

  1. Set properties:

    Set properties

     

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

Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions