Customization REST API

The Customization endpoint allows creating and managing customizations related to the HID Authentication Service IdP and other applications.

Customizations can be the themes (design and localization of the interface), or authentication workflows (authorized first and second factors, actions, etc).

Customization can also be used to define a truststore for mTLS PKI authentication for OpenID client or end users.

Supported configurations:

IDPWorkflows - authentication workflows
IDPThemes - themes to define customized interfaces and localization
Keystores - configuration to define the truststore type and keystore file

Note: The API version supported by HID Authentication Service is 10.1.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

Previous versions of the API are also supported with the corresponding functionality. For details of the version updates, see SCIM API Revision History.

Method Details

HTTPS Method	Entity Action	Request URI	Description
GET	Read	/configuration/{tenant}/v2/Custo/{application}	Obtain all customizations related to the specified application
GET	Read	/configuration/{tenant}/v2/Custo/{application}/{uid}	Obtain a specific customization
POST	Create	/configuration/{tenant}/v2/Custo/{application}	Create a new customization
PUT	Replace	/configuration/{tenant}/v2/Custo/{application}/{uid}	Update a specific customization
DELETE	Delete	/configuration/{tenant}/v2/Custo/{application}/{uid}	Delete a specific customization

Required Permissions

Function	Required Permissions
GET	Get customization
GET ALL	Read customization
CREATE	Get customization Create customization
REPLACE	Get customization Update customization
DELETE	Delete customization

Configure IdP Themes and Worklfows

Each configuration can contain multiple definition entries corresponding to required workflows or themes.

Each definition has a unique identifier:

Theme definition - theme_id
Workflow definition - worfklow_id

These identifiers are then defined in the OpenID client configuration and retrieved when then authentication request is processed.

For further information, see Create the Authentication Workflow and Customizing the Identity Portal.

Note: The samples below are illustrated using theme definitions in the IdPThemes configuration.

Get All Customizations

[GET] /Custo/<application>

Copy

Sample request to get all theme definitions for an application

GET https://[base-server-url]/configuration/{tenant}/v2/Custo/IDPThemes
Authorization: Bearer RTp7HwAAAXyStuhFZfZf2g4BQmVj1yf84hUvta3j
{
    "schemas": ["urn:hid:scim:api:idp:2.0:Customization"],
    "id": "ID_THEME1",
    "payload": {
        "ui": {
            "hid_portal": {
                "gradient-start": "red",
                "gradient-end": "orange",
                "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAVWZqWNWH.....<shortened>...LVjB1zBZk1nJTi/LYLKyb3YxefWSOu1b1t9HnOP+eHXbHZnV95bz0evVCtToyzZqNaY6q1UK9dy/UNmzYsGHDhg1C8D/J9batc1Yi+wAAAABJRU5ErkJggg=="
            },
        "extensions": {
<--- truncated output --->
    "id": "ID_THEME2",
    "payload": {
        "ui": {
            "hid_portal": {
                "gradient-start": "blue",
                "gradient-end": "green",
                "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAVWZqWNWH.....<shortened>...LVjB1zBZk1nJTi/LYLKyb3YxefWSOu1b1t9HnOP+eHXbHZnV95bz0evVCtToyzZqNaY6q1UK9dy/UNmzYsGHDhg1C8D/J9batc1Yi+wAAAABJRU5ErkJggg=="
            },
        "extensions": {
<--- truncated output --->

Get a Customization

[GET] /Custo/<application>/<uid>

Copy

Sample request to get a theme definition

GET https://[base-server-url]/configuration/{tenant}/v2/Custo/IDPThemes/ID_THEME1 HTTP/1.1
 
Content-Type: application/scim+json
Authorization: Bearer RTp7HwAAAX7ojJ6qTs1Tvsz/eQLtbM+ycCQjAo2b
Content-Length: 7149
Host: <hostname>l
User-Agent: Apache-HttpClient/4.5.5 (Java/16.0.1)
 
{
    "schemas": ["urn:hid:scim:api:idp:2.0:Customization"],
    "id": "ID_THEME1",
    "payload": {
        "ui": {
            "hid_portal": {
                "gradient-start": "red",
                "gradient-end": "orange",
                "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAVWZqWNWH.....<shortened>...LVjB1zBZk1nJTi/LYLKyb3YxefWSOu1b1t9HnOP+eHXbHZnV95bz0evVCtToyzZqNaY6q1UK9dy/UNmzYsGHDhg1C8D/J9batc1Yi+wAAAABJRU5ErkJggg=="
            },
            "extensions": {
                "mycustomelement1": {
                    "color": "red"
                },
                "mycustomelement2": {
                    "color": "orange"
                },
                "mycustomelement3": {
                    "mycustomlogo1": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAVWZqWNWH.....<shortened>...LVjB1zBZk1nJTi/LYLKyb3YxefWSOu1b1t9HnOP+eHXbHZnV95bz0evVCtToyzZqNaY6q1UK9dy/UNmzYsGHDhg1C8D/J9batc1Yi+wAAAABJRU5ErkJggg=="
                }
            }
        },
        "localization": {
            "hid_portal": {
                "fr": {
                    "service_name": "Mon service d'authentification HID",
                    "service_tagline": "Construisez et délivrez rapidement vos solutions d'identité de confiance",
                    "company_name": "Mon HID Global",
                    "application_title": "Mon service d'authentification"
                },
                "en": {
                    "service_name": "My HID Authentication Service",
                    "service_tagline": "Rapidly build and deliver your trusted identity solutions",
                    "company_name": "My HID Global",
                    "application_title": "My Authentication Service"
                }
            },
            "extensions": {}
        }
    }
}

Create a Customization

[POST] /Custo/<application>

Copy

Sample request to create a theme definition

POST https://[base-server-url]/configuration/{tenant}/v2/Custo/IDPThemes HTTP/1.1
 
Content-Type: application/scim+json
Authorization: Bearer RTp7HwAAAX7ojJ6qTs1Tvsz/eQLtbM+ycCQjAo2b
Content-Length: 7149
Host: <hostname>l
User-Agent: Apache-HttpClient/4.5.5 (Java/16.0.1)
 
{
    "schemas": ["urn:hid:scim:api:idp:2.0:Customization"],
    "id": "ID_THEME2",
    "payload": {
        "ui": {
            "hid_portal": {
                "gradient-start": "red",
                "gradient-end": "orange",
                "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAVWZqWNWH.....<shortened>...LVjB1zBZk1nJTi/LYLKyb3YxefWSOu1b1t9HnOP+eHXbHZnV95bz0evVCtToyzZqNaY6q1UK9dy/UNmzYsGHDhg1C8D/J9batc1Yi+wAAAABJRU5ErkJggg=="
            },
            "extensions": {
                "mycustomelement1": {
                    "color": "red"
                },
                "mycustomelement2": {
                    "color": "orange"
                },
                "mycustomelement3": {
                    "mycustomlogo1": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAVWZqWNWH.....<shortened>...LVjB1zBZk1nJTi/LYLKyb3YxefWSOu1b1t9HnOP+eHXbHZnV95bz0evVCtToyzZqNaY6q1UK9dy/UNmzYsGHDhg1C8D/J9batc1Yi+wAAAABJRU5ErkJggg=="
                }
            }
        },
        "localization": {
            "hid_portal": {
                "fr": {
                    "service_name": "Mon service d'authentification HID",
                    "service_tagline": "Construisez et délivrez rapidement vos solutions d'identité de confiance",
                    "company_name": "Mon HID Global",
                    "application_title": "Mon service d'authentification"
                },
                "en": {
                    "service_name": "My HID Authentication Service",
                    "service_tagline": "Rapidly build and deliver your trusted identity solutions",
                    "company_name": "My HID Global",
                    "application_title": "My Authentication Service"
                }
            },
        "extensions": {}
        }
    }
}

Copy

Sample request to create a workflow definition

POST https://[base-server-url]/configuration/{tenant}/v2/Custo/IDPWorkflows HTTP/1.1
Content-Type: application/scim+json
Authorization: Bearer RTp7HwAAAX7ojJ6qTs1Tvsz/eQLtbM+ycCQjAo2b
Content-Length: 7149
Host: <hostname>
User-Agent: Apache-HttpClient/4.5.5 (Java/16.0.1)
{
    "schemas":["urn:hid:scim:api:idp:2.0:Customization"],
    "id":"ID_FLOWPUSH",
    "payload":{
        "accessCriteria":[
            {
                "accessCriteriaId":"access_criteria.common_to_all",
                "authenticators":{
                    "firstFactorsFiltering":true,
                    "secondFactorsFiltering":true,
                    "acrFiltering":true
                }
            }
        ],
        "actions":[
            {
                "actionId":"action.change_password",
                "accessCriteriaId":"access_criteria.common_to_all",
                "type":"CHANGE_PWD",
                "retry":3
            },
            {
                "actionId":"action.forgot_password",
                "accessCriteriaId":"access_criteria.common_to_all",
                "type":"FORGOT_PWD",
                "validityPeriod":900,
                "retry":3,
                "resetPasswordMethods":{
                    "email":{
                        "template":"MESSAGE=The temporary password is: {$secret}.\r MESSAGE_fr=Le mot de passe temporaire est : {$secret}.\r SUBJECT=PUSH",
                        "templateHtml":false
                    },
                    "sms":{
                        "template":"MESSAGE=The temporary password is: {$secret}.\r MESSAGE_fr=Le mot de passe temporaire est : {$secret}.\r SUBJECT=PUSH"
                    }
                }
            }
        ],
        "firstFactors":[
            {
                "factorId":"factor.user_password",
                "accessCriteriaId":"access_criteria.common_to_all",
                "type":"LOGIN",
                "code":"AT_EMPPWD",
                "acr":"1",
                "stepUp":"automatic",
                "retry":3,
                "actions":[
                    "action.change_password",
                    "action.forgot_password"
                ]
            },
            {
                "factorId":"factor.otp_token",
                "accessCriteriaId":"access_criteria.common_to_all",
                "type":"OTP",
                "code":"AT_EMPOTP",
                "acr":"2",
                "stepUp":"automatic",
                "retry":1
            }
        ],
        "secondFactors":[
            {
                "factorId":"factor.push_authentication",
                "accessCriteriaId":"access_criteria.common_to_all",
                "type":"PUSH",
                "code":"AT_PASA",
                "acr":"3",
                "retry":3,
                "upon":[
                    "factor.user_password"
                ]
                "allowUserDeviceSelection":true,
                "device":{}
            },
            {
                "factorId":"factor.otp_token.2fa",
                "accessCriteriaId":"access_criteria.common_to_all",
                "type":"OTP",
                "code":"AT_EMPOTP",
                "acr":"2",
                "retry":1,
                "upon":[
                    "factor.user_password"
                ]
            },
            {
                "factorId":"factor.cust_pin",
                "accessCriteriaId":"access_criteria.common_to_all",
                "type":"LOGIN",
                "code":"AT_EMPPIN",
                "acr":"1",
                "retry":1,
                "upon":[
                    "factor.user_password"
                ]
            }
        ]
    }
}

Update a Customization

[PUT] /Custo/<application>/<uid>

Note: As a best practice, use GET to retrieve the current data for the resource before using PUT.

Copy

Sample request to update a theme definition

PUT https://[base-server-url]/configuration/{tenant}/v2/Custo/IDPThemes/ID_THEME1
Authorization: Bearer RTp7HwAAAXyStuhFZfZf2g4BQmVj1yf84hUvta3j
Content-Type: application/scim+json
Host: <hostname>l
User-Agent: Apache-HttpClient/4.5.5 (Java/16.0.1)
 
{
    "schemas": ["urn:hid:scim:api:idp:2.0:Customization"],
    "id": "ID_THEME1",
    "payload": {
        "ui": {
            "hid_portal": {
                "gradient-start": "blue",
                "gradient-end": "orange",
                "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAVWZqWNWH.....<shortened>...LVjB1zBZk1nJTi/LYLKyb3YxefWSOu1b1t9HnOP+eHXbHZnV95bz0evVCtToyzZqNaY6q1UK9dy/UNmzYsGHDhg1C8D/J9batc1Yi+wAAAABJRU5ErkJggg=="
            },
            "extensions": {
                "mycustomelement5": {
                    "color": "blue"
                },
                "mycustomelement2": {
                    "color": "orange"
                },
                "mycustomelement3": {
                    "mycustomlogo1": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAVWZqWNWH.....<shortened>...LVjB1zBZk1nJTi/LYLKyb3YxefWSOu1b1t9HnOP+eHXbHZnV95bz0evVCtToyzZqNaY6q1UK9dy/UNmzYsGHDhg1C8D/J9batc1Yi+wAAAABJRU5ErkJggg=="
                }
<--- truncated output --->

Delete a Customization

[DELETE] /Custo/<application>/<uid>

Copy

Sample request to delete a theme definition

DELETE https://[base-server-url]/configuration/{tenant}/v2/Custo/IDPThemes/ID_THEME1
Authorization: Bearer RTp7HwAAAXyStuhFZfZf2g4BQmVj1yf84hUvta3j
{
...<deletes ID_THEME1 for IDPThemes application>
}

Configure a Truststore for mTLS Authentication

During the Mutual TLS (mTLS) authentication flow (PKI import or authentication), the client X.509 certificates must be forwarded to HID Authentication Service so they can be checked before issuing an access_token.

To enable the certificate check, you must define the truststore so HID Authentication Service can verify the certificate trust path in the keystore file.

You can define a specific truststore for each tenant.

Copy

Sample request to configure a truststore for a tenant

POST https://[base-server-url]/configuration/{tenant}/v2/Custo/Keystores
{
    "schemas": ["urn:hid:scim:api:idp:2.0:Customization"],
    "id": "mtls_truststore",
    "payload": {
        "truststore_type": "pem",
        "truststore_b64": "base64 encoded keystore file"
    }
}

Where:

id - unique identifier for the custom truststore
payload:
- truststore_type - type of the keystore file (for example, .pem)
- truststore_b64 - contents of the keystore file containing the full certificate chain for the certificate authority (CA) encoded in base64

Important: You must also provide the root and intermediate certificates of the certificate authority (CA) to HID Customer Service so they can be uploaded to the back-end truststore.

For further information, see Client ID and User Authentication with mTLS.