SafeNet IDPrime Virtual Server Setup

As a prerequisite, you must have a SafeNet IDPrime Virtual server that is up and running on your machine. The SafeNet IDPrime Virtual server runs in a docker container, and stores the configuration in a database.

Configuring Microsoft Entra ID as your identity provider in SafeNet IDPrime Virtual requires:

Configuring the Identity Provider Configuration File
Running the IDPV Server and Setting Up the IDPV Tenant

Configuring the Identity Provider Configuration File

Perform the following steps to configure the idp-configuration.json configuration file:

Create or copy an existing idp-configuration.json file and place it in the /config directory mapped to the container.

SafeNet IDPV v2.4.1 does not support key rotation. The next step (step 2) is a workaround for key rotation that is applicable only for SafeNet IDPV Server v2.4.1. From SafeNet IDPV Server v2.5 onwards, keys can be rotated either usign tenant configuration or Key rotation service.
Access the WELL KNOWN CONFIGURATION URL (openid-connect discovery endpoints) in the respective application under app registration in Microsoft Entra ID to get the IdpPublicKeyModulus, IdpPublicKeyExponent, and IdpKeyId keys. Currently, SafeNet IDPV Server v2.4.1 doesn’t support key rotation. So, to get the correct kid, you need to obtain a jwt using any utility such as postman. You can obtain kid from the jwt header.
A workaround is given below to obtain the kid, n, and e variables. To obtain jwt using Postman tool, perform the following steps:
1. Run postman on any windows machine with internet access. On Postman console. Navigate to New > Select http request > Authorization > OAuth2.0.
2. Provide the following values for the application registered in Microsoft Entra ID:
  - Grant Type: Authorization code
  - Callback URL: Value specified in Microsoft Entra ID app registration
  - Auth URL: Value specified in Microsoft Entra ID app registration
  - Access Token URL: Value specified in Microsoft Entra ID app registration
  - Client ID: Value specified in Microsoft Entra ID app registration
  - Client Secret: Value specified in Microsoft Entra ID app registration
  - Scope: Value specified in Microsoft Entra ID app registration
  - State: Any random value
  - Client Authentication: Send as Basic Auth Header
3. Navigate to New Access Token > Provide User credentials > Copy Access Token Value.
4. Open jwt.io in browser and paste the jwt. Note the kid in decoded jwt header. Look for this same key set in jwks_uri URL.
  
  In jwks_uri URL, kid variable becomes IdpKeyId parameter, n variable becomes IdpPublicKeyModulus parameter, and e variable becomes IdpPublicKeyExponent parameter.

Open the idp-configuration.json file that is placed at the /config path and enter the values of the parameters given in the below table:

Parameter	Value
SigningKeys	`IdpPublicKeyModulus`: Enter the value of n key copied from step 2. `IdpPublicKeyExponent`: Enter the value of e key copied from step 2. `IdpKeyId`: Enter the value of kid key copied from step 2.
IdpIssuerUrl	Enter the value of the Issuer url from ./well-known url.
IdpClientId	Enter the value of the Client ID that is configured on Keycloak server.
IdpRedirectUrl	Enter the VALID REDIRECT URL that is configured in client configuration on Keycoak server. For executing IDPV client only: URL structure: `https://<server-host>/redirect` For example: `https://www.idpvserver.com/redirect` For executing Self-Service Portal and IDPV client: URL structure: `https://<server-host>/redirect` For example: `https://www.idpvserver.com/redirect` Note: This URL is updated as per IDPV server host name.
IdentityProvider	Enter Azure as the IDP type.
RefreshTokenExpirationDuration	By default, the value is 480. The recommended value for RefreshTokenExpirationDuration is less than 24 hours.
JwtExpiration	Enter a timeframe (in seconds) to be used by the IDPV client. The IDPV client obtains the access token value during this timeframe preceding the expiration of the access token.
JwtGroupClaim	Enter Groups
JwtUserClaim	Enter preferred_username.
IDPrimeVirtualAdmin	Enter a list of administrator group claim names.
IDPrimeVirtualUser	Enter a list of user group claim names. User must be a part of any of the groups mentioned in the `IDPrimeVirtualUser` or `IDPrimeVirtualAdmin` parameter.
OfflineTokenEnabledGroup	Enter the list of Group Claim names that are allowed for the offline access. If `*` is entered, all groups are allowed for offline access.
IDPrimeVirtualProvisioningAdmin	Enter the list of Group Claim names that are allowed for Provisioning Admin access. If `*` is entered, all groups are allowed for Provisioning Admin access (as per precedence).
JwtAdminWhiteList	Contains list of IDPrime Virtual Admin users.
JwtExpiration	Enter a timeframe (in seconds) to be used by the IDPV client. The IDPV client obtains the access token value during this timeframe preceding the expiration of the access token.
IdpScope	The mandatory scope added in application on Microsoft Entra ID. IdpScope parameter will read the `IdpScope` field of tenant configuration. When the server is upgraded, old tenant will be populated with value as `openid offline_access api://idpv/idpvscope` or `openid offline_access https://<subdomain>.<domain.com>/idpvscope` for Microsoft Entra ID IDP, if this field is not explicity provided. For new tenant, this field must be configured similar to Microsoft Entra ID client side in the `idp-configuration.json` file.

The JwtAdminWhiteList, IDPrimeVirtualProvisioningAdmin, and OfflineTokenEnableGroup are optional parameters and must be provided if the Provisioning and Offline mode functions are enabled.

Sample 1: idp-configuration.json file for 2.5 release


    vim idp-configuration.json
    {
    "IdentityProvider": "Azure",
    "SigningKeys": [{
    "IdpPublicKeyModulus": "alNhKqAQBQaXTDWt5ns2G5506-W5-sUgWulUMMv7EPmJTlOymAcHFQwwX3kb6ktPWqfOi1POQiHvAa6vYkDu9N-9W0TZLYWsRaS8xrxyeXhYqpQwuRjrVelITBTQEBrfNxypWbVPCUkMrW9uW1JrcAp4Glg3LjJnkmQ_5WA5MkiqB6HcTdZZh2z4V5aqInKKSlim-_KChEo2Z1i5LngCw5dSGo-1_S6tJ_nzhazVlBYNEkfBlA_81sJ3i98_ZA9s67E9MeZ0h1dQJmPAlnnXaghFVWnxVPEmnMOOGDxJomgOgh1xLKAa_5Irgk1qp-Nsn-cXP6NFoBnRfuV8Pamw-Q",
    "IdpPublicKeyExponent": "AQAB",
    "IdpKeyId": "-KI3Q9nNR7bRofxmeZoXqbHZGew"
    },
    {
    "IdpPublicKeyModulus": "wEMMJtj9yMQd8QS6Vnm538K5GN1Pr_I31_LUl9-OCYu-9_DrDvPGjViQK9kOiCjBfyqoAL-pBecn9-XXaS-C4xZTn1ZRw--GELabuo0u-U6r3TKj42xFDEP-_R5RpOGshoC95lrKiU5teuhn4fBM3XfR2GB0dVMcpzN3h4-0OMvBK__Zr9tkQCU_KzXTbNCjyA7ybtbr83NF9k3KjpTyOyY2S-qvFbY-AoqMhL9Rp8r2HBj_vrsr6RX6GeiSxxjbEzDFA2VIcSKbSHvbNBEeW2KjLXkz6QG2LjKz5XsYLp6kv_-k9lPQBy_V7Ci4ZkhAN-6j1S1Kcq58aLbp0wDNKQ",
    "IdpPublicKeyExponent": "AQAB",
    "IdpKeyId": "2ZQpJ3UpbjAYXYGaXEJl8lV0TOI"
    }
    ],
    "IdpClientId":"70e5d608-e18b-491f-9255-31d08b6a68a4",
    "IdpIssuerUrl":"https://login.microsoftonline.com/eead47bc-8446-41a0-93c9-f773ef8c6b02/v2.0",
    "IdpRedirectUrl":"https://www.idpvserver.com/redirect",
    "RefreshTokenExpirationDuration": "480",
    "JwtExpiration":"0000001e",
    "JwtGroupClaim":"Groups",
    "JwtUserClaim":"preferred_username",
    "JwtAdminWhiteList":"LeeG@q1kj.onmicrosoft.com,PattiF@q1kj.onmicrosoft.com",
    "IDPrimeVirtualAdmin":"6df3aa12-11d1-4703-a66b-07aec1429b03",
    "IDPrimeVirtualUser":"2c83849e-a989-45ee-b1ec-48cffc96184b",
    "OfflineTokenEnabledGroup":"fa43885f-2166-49ad-9f22-ba725aa64e37",
    "IDPrimeVirtualProvisioningAdmin":"0a613db9-46cf-4a31-89dd-d5d101de8d53",
    "IdpScope": "openid offline_access api://idpv/idpvscope"
    }

Sample 2: idp-configuration.json file for 2.4.1 release



    vim idp-configuration.json
    {
    "IdentityProvider": "Azure",
    "IdpPublicKeyModulus": "Tjl6wr2JUsxLyNezPQh1J6zn6wSoDAhgRYSDkaMuEHy75VikiB8wg25WuR96gdMpookdlRvh7SnRvtjQN9b5m4zjcmpSRcJ5DuXl4mcd7Cg3Zp1C5-JmMq8J7m7OS9HpUQbA1yhtCHqP7XA4UnQI28J-TnGiAa3viPLlq0663Cq6hQw7jYo5yNjdJcV5-FS-xNV7UHR4zAMRruMUHxte1IZJzbJmxjKoEjJwDTtcd6DkI3yrkmYt8GdQmu0YBHTJSZiz-M10CY3LbvLzf-tbBNKQ_gfnGGKF7MvRCmPA_YF_APynrIG7p4vPDRXhpG3_CIt317NyvGoIwiv0At83kQ",
    "IdpPublicKeyExponent":"AQAB",
    "IdpKeyId":"-KI3Q9nNR7bRofxZemoXbqHZGew",
    "IdpClientId":"70e5d608-e18b-491f-9255-31d08b6a68a4",
    "IdpIssuerUrl":"https://login.microsoftonline.com/eead47bc-8446-41a0-93c9-f773ef8c6b02/v2.0",
    "IdpRedirectUrl":"https://www.idpvserver.com/redirect",
    "RefreshTokenExpirationDuration": "480",
    "JwtExpiration":"0000001e",
    "JwtGroupClaim":"Groups",
    "JwtUserClaim":"preferred_username",
    "JwtAdminWhiteList":"LeeG@q1kj.onmicrosoft.com,PattiF@q1kj.onmicrosoft.com",
    "IDPrimeVirtualAdmin":"6df3aa12-11d1-4703-a66b-07aec1429b03",
    "IDPrimeVirtualUser":"2c83849e-a989-45ee-b1ec-48cffc96184b",
    "OfflineTokenEnabledGroup":"fa43885f-2166-49ad-9f22-ba725aa64e37",
    "IDPrimeVirtualProvisioningAdmin":"0a613db9-46cf-4a31-89dd-d5d101de8d53",
    "IdpScope": "openid offline_access api://idpv/idpvscope"
    }

You can modify the policy-configuration.json file as per your preferred configuration.

Sample: policy-configuration.json file


    {
    "UserPinPolicy": {
    "MaxRetries": 5,
    "IsMustChange": false
    },
    "AdminPinPolicy": {
    "MaxRetries": 5,
    "IsMustChange": false
    },
    "OfflineTokenPolicy": {
    "ValidityDurationInHours": 120,
    "PrivateKeyExportLevel": "All"
    }
    }

Sample: sws-config.json file



    {
    "_comment1": "(Mandatory for SWS API) The commercial name of the remote service. The maximum size of the string is 255 characters.",
    "Name": "Thales Signing Web Service",
    "_comment2": "(Mandatory for SWS API) The ISO 3166-1 [22] Alpha-2 code of the Country where the remote service provider is established (e.g. ES for Spain).",
    "Region": "US",
    "_comment3": "(Mandatory for SWS API) The URI of the image file containing the logo of the remote service which SHALL be published online. The image SHALL be in either JPEG or PNG format
    and not larger than 256x256 pixels.",
    "Logo": "https://example.com/SWSLogo.png",
    "_comment4": "(Mandatory for SWS API) The maximum size of the string is 255 characters.",
    "Description": "The Signing web service (SWS) APIs are based on Cloud Signature Consortium (CSC) standards and it supports web and mobile applications and comply with the most demanding electronic signature regulations in the world.' # (Mandatory for SWS API) The maximum size of the string is 255 characters."
    }

Running the IDPV Server and Setting Up the IDPV Tenant

After configuring the other SafeNet IDPrime Virtual Server files, you need to perform the following steps to create IDPV tenant:

Run the IDPV server, refer to Running the IDPV Server section.
Run the tenant creation utility using one the following commands based on the SafeNet IDPV version you are configuring:

IDPV v2.4.1
```
setuptenant create -i Config/azure-test.json -p Config/policy-configuration.json -a <client_secret> -k <true or false> -u <true or false> -c <IDPV> -n <tenant_name>
```
IDPV v2.5
```
setuptenant create -i Config/idp-configuration.json -p Config/policyconfiguration.json –a <idp secret> -k true (or false) -n <tenant name> -c <tenant category> -m false (or true) -s <swsconfig.json> -u false (or true) -j false (or true) -f true (or false)
```
IDPV v2.6
```
setuptenant create -i Config/idp-configuration.json -p Config/policyconfiguration. json –a <idp secret> -k true (or false) -n <tenant name> -c <tenant category> -m false (or true) -s <swsconfig.json> -u false (or true) -j false (or true) -f true (or false) -o false (or true)
```
Where:
- -i --idpConfigFilePath : accepts json file for idp configuration (file provided for IDPV installation) (Mandatory)
- -p --tokenPoliciesPath : accepts json file for sample policy (Mandatory)
- -a --IdpA : accepts IDP secret (Mandatory)
  
  Client Secret value for various IDPs can be located in the respective IDP configuration.
- -k --exportKeys : accepts the HSM export key flag as either true or false (Optional) and if SKS flag is set to true, -k flag is always set to false.
  
  For HSM, the default value is set true. However, if KeySecure is configured, the default value is auto-set to false.
  
  -k is set to true,
  • when the HSM is configured for the export mode.
  • to download the token offline bundle to support the offline mode feature.
- -n --tenantName : accepts a tenant name.
- -c --tenantCategory : provide tenant category from IDPV or Signature Web Service (SWS)
  
  The default value is set to IDPV if -c is not specified. (Optional)
- -m --sksMode : accepts the HSM SKS flag as either true or false (Optional)
- -s --swsConfigFilePath : accepts a json file as a sws configuration file.
- -u --IsAutoCardCreationEnabled : accepts true or false for IsAutoCardCreationEnabled flag (Optional). It enables/disables the automatic smart card creation for tenant if no smart card exist for the user. The default value is set to true. If -u is not specified, then the default value is used.
  
  Tenant created with -u: true allows auto creation of smart card. Tenant created with -u: false does not allow auto creation of smart card.
- -j --IsAutoRefreshSigningKeyEnabled : Accepts true or false. The default value is false. If it is set to true, the signing key gets rotated automatically on the IDPV server. This flag is added in SafeNet IDPV v2.5.
  
  The signing key is rotated,
  - At period intervals for which the interval value is set in the appsettings file (KeyRotationRefreshIntervalInHrs).
  - At the time of Authorization failure (due to the signing key mismatch).
  If it is set to false, the administrator has to manually update the IDP signing key, in case it gets changed at the IDP level.
- -f --IsOfflineFallbackEnabled : The default value is true. This flag is used to enable or disable the Offline fallback feature. When enabled (-f: true), it allows you to go offline when TPM is FIPS compliant, but the keys are non FIPS. This flag is added in SafeNet IDPV v2.5.
  
  You can set this flag to false using the setuptenant update command.
  
  This feature has a dependency on -k (HSM export key flag). So, if you create a tenant with -k: false, -f will also be set to false, and then you will not be able to configure it. If you set -k: true, the value of -f will be configurable (true/false).
- -o --IsAutoOfflineBundleDownloadEnabled : Accepts true or false. The default value is false. If it is set to true, the offline bundle is downloaded at the client side, after the user enters a correct PIN. This flag is added in SafeNet IDPV v2.6.
  
  You can set this flag to false using the setuptenant update command.
  
  This feature has a dependency on -k (HSM export key flag). So, if you create a tenant with -k: false, -o will also be set to false, and then you will not be able to configure it. If you set -k: true, the value of -o will be configurable (true/false).
- --help
- --version
  
  The /publish/Config path is mapped with host directory /var/thales/config using docker run command in deployment section. So path used inside container must be the same, i.e. /publish/Config.
After running the above command, a Tenant ID is generated and saved as a text file in the /publish/Tenant/<TenantGUID>.txt directory, and displayed on the console.

Examples for IDPV Tenant:
```
SetupTenant create -i Config/idp-staclassic-redirect.json -p Config/policy-configuration.json -k true  -a fd1b4b61-32ba-47b3-a0c9-cf8bda938b4d -n 'IDPV-Tenant' -u true -c IDPV -j false -f true
```
```
SetupTenant create -i Config/idp-azure.json -p Config/policy-configuration.json -k true -a fd1b4b61-32ba-47b3-a0c9-cf8bda938b4d -n 'IDPV-Tenant' -u true -c IDPV  -j false -f true
```
Example for SWS Tenant:
```
SetupTenant create -i Config/idp-staclassic-redirect.json -p Config/policy-configuration.json -k true  -a fd1b4b61-32ba-47b3-a0c9-cf8bda938b4d -n 'SWS-Tenant' -c SWS -m True -s Confg/sws-config.json
```

Copy the Tenant ID to the machine using the following command:


docker cp idprime-virtual-server-containername:/publish/Tenant/<TenantGUID>.txt <location on host>

Suggest A Change

SafeNet IDPrime Virtual Server Setup

Configuring the Identity Provider Configuration File

Running the IDPV Server and Setting Up the IDPV Tenant

On this page