Versions Compared

Version Old Version 38 New Version 39
Changes made by

Ylva Andersson

Josefin Klang (Deactivated)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...


excerpt
Info
This article includes updates for Smart ID 23.04.2. 


Smart

Info!

Smart ID Mobile App will sign the request data and Identity Manager will verify the mobile client's data signature using the attestation key. The attestation key is configured in the task's attestationKeySet parameter and in the Sign and encrypt engine in Identity Manager.

If the verification fails, the task will not accept the data but set two process variables instead:

  • The errorTypeField (see the parameters below) will be set to "HERMOD_ERROR_JWT_SIGNATURE". Use this in your process design to react to validation errors.
  • The errorMessageField (see the parameters below) will contain a more descriptive message

Configuration

To use this task, configure the following delegate expression in your service task:

Expand
titleMobile App: Create Key

Description

Use this task to provision a new profile or update an existing one, overwriting existing keys. The task will create the keys needed for the "Mobile App: Install certificates" task.

The task will generate the following PKCS#10 request templates:

  • Signature Certificate (optional)
  • Authentication Certificate (optional)
  • Device Encryption (used to secure the communication with Smart ID Mobile App)

These requests will then be sent to the mobile phone and transformed into new PKCS#10 requests (with keypairs generated on the client but keeping all subject data). The new requests userid will then be sent to the message catching intermediate event identified by the parameter 'messageName'. Identity Manager will put these PKCS#10 requests into the process map under the keys "SIG_P10_VAR", "AUTH_P10_VAR" and "DEVICE_ENC_P10_VAR". If a new profile was created, Identity Manager will also put the new profileId into the process map under the key "profileId". In order to save the profile id you will need to copy it into a data pool field.

After this task is executed, you need to request certificates using the requests stored in the process variables "SIG_P10_VAR" and "AUTH_P10_VAR" before proceeding to the "Mobile App: Install certificates" task. Store the requested certificates into the process map.

Info
titleAttestation key
Code Block
${hermodKeyCreationTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified

Example value:

  • MessagingServer
The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.

messageName

Image Modified

Example value:

  • p10PreparationCallback
The name of the intermediate message catching event that will be triggered by Smart ID Messaging.
userid

Image Modified

Example value:

  • ${Person_Email}

ID representing the user on the messaging server. This will be displayed in the profile on the mobile app to verify the correct data is provided.

A common approach is to use the user's email address.

errorMessageField

Image Modified

Example value:

  • ErrorMessage
Process variable to put the error message in case of failure.
errorTypeField

Image Modified

Example value: 

  • ErrorType
Process variable to put the error type in case of failure.
signCertificateTemplate-
Signature certificate template.
authCertificateTemplate-
Authentication certificate template.
profileName

If new profile

Leave empty (when updating a profile)

Profile name for Smart ID Messaging. Will be displayed in the Smart ID Mobile App. Leave empty if you want to update an existing profile.
serverName

If new profile

Example value: 

  • Smart ID
Name of the server that issued the provisioning request. This is for the user to understand where the profile comes from. 
attestationKeySet

-

(If not set will default to "ATTESTATION")

Example value:

  • ATTESTATION (default value)

The name of the attestation key that will be used for signing (by the client) and validating (by Identity Manager) the mobile client's data. The available values are the names of the descriptors in the sign and encrypt engine that start with "att_", without this prefix. An attestation key with the same name must be defined in Smart ID Mobile App/MDM device.

Default value is "ATTESTATION" when no descriptor value is provided.

qrResultField

If new profile

Example value:

  • QR_CODE_VAR
Process variable to put the resulting url. This url may be converted to a QR-Code for the Smart ID Mobile App by using GenerateQRCodeParametrizedAction.
profileIdIf update profile

Leave empty (for new profile)

Id of the Smart ID Mobile App profile that will be updated with new keys. Leave empty if you want to provision a new profile.

storagePriority

Image Modified

Valid values:

  • APP (for Smart ID Mobile App, default)
  • EXT (for Mobile Iron device)
  • MDM (replaced by EXT, but still supported)
Storage priority of certificates. MDM is replaced by EXT, however MDM is still supported.
visualIdLayout

If using visual ID

Example value:

  • Default Layout
The layout to be used for creating the visual ID. If there is a juel expression configured for the front or backside image, this will take precedence over the statically configured image. If there is no image found for the juel expression, and there is no statically configured image, the task will fail.
cardDatapool

If using visual ID

Example value:

  • PcmDpPersonalMobile
 The datapool used for saving the mobile ID profile.
contentId

If using visual ID

Example value:

  • ${GeneratedContentId}
 A unique ID in UUID format, which will be associated with the personal mobile profile. Can be generated with the service task "MISC: Generate Random GUID into Data Map Field".



Expand
titleMobile App: Install Certificates

Description 

Use this task to request and install certificates that were prepared using the "Mobile App: Create Key" task.

As a prerequisite

  • you must already have requested certificates with the authentication and signature certification requests generated by the "Mobile App: Create Key" task and stored them as process variables.
  • if you want to perform certificate recovery, you must prepare the data for that using 'Cert: Load Key History List'.

Use this task to install a number of certificates on the mobile phone:

  • Signature Certificate, will be bound to the key pair created by "Mobile App: Create Key".
  • Authentication Certificate, will be bound to the key pair created by "Mobile App: Create Key".
  • Device Encryption Certificate, will be bound to the key pair created by "Mobile App: Create Key".
  • Encryption Certificate created with key archival.
  • Any number of recovered certificates.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${hermodInstallCertificatesTask}

The following parameters can be configured in Identity Manager Admin: 

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.

messageName

Image Modified

p10FinishedCallbackThe name of the intermediate message catching event that will be triggered by Smart ID Messaging.
userid

Image Modified

${Person_Email}ID representing the user on the messaging server. This must match the userid provided when the profile was requested.
errorMessageField

Image Modified

ErrorMessage

Process variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorType

Process variable to put the error type in case of failure.
signatureCertificate-

${SIG_VAR}

The signature certificate.
authenticationCertificate-

${AUTH_VAR}

The authentication certificate.
deviceEncryptionP10

Image Modified

${DEVICE_ENC_P10_VAR}

The PKCS#10 request for the Device Encryption Certificate, created by the "Mobile App: Create Key" task.
profileId

Image Modified

${profileId}

The id of the profile under which to store the certificates. This is initially provided by the "Mobile App: Create Key" task.
encryptionCertificate-
Encryption certificate template.
recoveryCertificate-
Recovery certificate template.
processVariable-Certificate_CoreObjectsVariable name which holds Core object ids list or Core object descriptor list of certificates to be recovered.
p12PasswordField

Image Modified

profilePasswordReference field where the created password is stored. This password is used for all PKCS#12 containers in this communication. There are a number of actions for creating passwords.
storagePriority

Image Modified

Valid values:

  • APP (for Smart ID Mobile App, default)
  • EXT (for Mobile Iron device)
  • MDM (replaced by EXT, but still supported)
Storage priority of encryption certificates. MDM is replaced by EXT, however MDM is still supported.



Expand
titleMobile App: Delete Profile

Description

Use this task to delete a profile managed by Smart ID Desktop App. It can also delete all Smart ID Messaging mailboxes for a specific user id.

This task can be used in the following ways:

Delete profile on Smart ID Mobile App and Smart ID Messaging

Executed the task on a card profile which contains information about the profile id.

  1. Specify a profile id and set the confirmation flag to true. All other parameters must be provided as well.
  2. The request will be sent to Smart ID Mobile App, which will delete the profile identified by the specified profile id.
    • The result will be sent to the message catching intermediate event identified by the parameter 'messageName'.
    • After receiving a successful response from Smart ID Mobile App, Smart ID Messaging also deletes the mailbox and forwards the same response back to Identity Manager.

Delete mailbox on Smart ID Messaging only

  1. Set the confirmation flag to false.

    Note

    Even if the confirmation flag is set to false, you need to set the 'messageName' parameter to a dummy value to be able to delete the mailbox(es).


  2. Smart ID Messaging will delete either a specific mailbox when a profile id is provided or all mailboxes of the specified user id when the profile id is absent.
    The profiles themselves in their respective apps will be retained, as the deletion request will not be forwarded.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${pmHermodDeleteProfileTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.
messageName

Image Modified


The name of the intermediate message catching event that will be triggered by Smart ID Messaging.
errorMessageField

Image Modified

ErrorMessageProcess variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorTypeProcess variable to put the error type in case of failure.
profileId

when confirmation flag is true

${Card_ProfileId}

ID of the profile to be deleted, as created via 'Mobile App: Create Key'.

userid

Image Modified

${Person_Email}

ID representing the user on the messaging server. This must match the userid provided when the profile was requested.
confirmation

Image Modified

Valid values:

  • true
  • false

Messaging Server will forward the profile deletion request to Smart ID Mobile App when set to true.



Expand
titleDesktop App: Create Virtual Smart Card Key

Description

Use this task to create up to three template PKCS#10 requests that can be used to request certificates needed for the "Desktop App: Install Certificates on Virtual Smart Card" task.

Use this task to create up to three template PKCS#10 requests:

  • Signature Certificate (if template name is provided)
  • Authentication Certificate (if template name is provided)
  • Device Encryption (always, used to secure the communication with Smart ID Desktop App)

These requests will then be sent to Smart ID Desktop App and transformed into new PKCS#10 requests (with keypairs generated on the client but keeping all subject data). The new requests will then be sent to the message catching intermediate event identified by the parameter 'messageName'. Identity Manager will put these PKCS#10 requests into the process map under the keys "SIG_P10_VAR" and "AUTH_P10_VAR". Identity Manager will also put the new profile id into the process map under the key "profileId". In order to save the profile id you will need to copy it into a data pool field.

This task can only provision a new profile - updating an existing profile is currently only supported in Smart ID Mobile App at this time, not in Smart ID Desktop App.


Info
titleAttestation Key

Smart ID Desktop App will sign the request data and Identity Manager will verify the client's data signature using the attestation key. The attestation key is configured in the task's attestationKeySet parameter and in the Sign and encrypt engine in Identity Manager.

If the verification fails, the task will not accept the data but set two process variables instead:

  • The errorTypeField (see the parameters below) will be set to "HERMOD_ERROR_JWT_SIGNATURE". Use this in your process design to react to validation errors.
  • The errorMessageField (see the parameters below) will contain a more descriptive message

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${pxVscHermodKeyCreationTask}

The following parameters can be configured in Identity Manager Admin: 

ParameterMandatoryValueDescription
messagingServer

Image Modified

Example value:

  • MessagingServer
The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.

messageName

Image Modified

Example value:

  • p10PreparationCallback
The name of the intermediate message catching event that will be triggered by Smart ID Messaging.
userid

Image Modified

Example value:

  • ${Person_Email}

ID representing the user on the messaging server. This will be displayed in the profile(-list) on the desktop app to verify the correct data is provided.

A common approach is to use the user's email address.

errorMesageField

Image Modified

Example value: 

  • ErrorMessage
Process variable to put the error message in case of failure.
errorTypeField

Image Modified

Example value: 

  • ErrorType
Process variable to put the error type in case of failure.
signCertificateTemplate-

Example value:

  • Sign-Certificate
Certificate template of the signature certificate.
authCertificateTemplate-

Example value:

  • Authentication-Certificate
Certificate template of the authentication certificate.
profileName

Image Modified

Example value:

  • VSC 1
Profile name for Smart ID Messaging. Will be displayed in Smart ID Desktop App as the heading of the profile.
serverName

Image Modified

Example value:

  • Smart ID

Name of the server that issued the provisioning request. This is for the user to understand where the profile comes from.

attestationKeySet

-

(If not set will default to "ATTESTATION")

Example value:

  • ATTESTATION (default value)

The name of the attestation key that will be used for signing (by the client) and validating (by Identity Manager) the client's data. The available values are the names of the descriptors in the sign and encrypt engine that start with "att_", without this prefix. An attestation key with the same name must be defined in Smart ID Desktop App.

Note

Currently, Smart ID Desktop App accepts only default key set named "ATTESTATION".


plugoutResultField

If new profile

Example value: 

  • plugoutUri
Process variable to put the resulting Smart ID Plugout URI that will open Smart ID Desktop App on the client machine.
adminKey

Image Modified

Example value: 

  • ${Card_CardManagerKey}

The secret field reference of 24-byte 3DES admin key in HEX format. The key can also be set directly as plain hex value for testing.

Note: Smart ID Desktop App.s own default is 123456781234567812345678123456781234567812345678, but you must make sure Identity Manager always defines the value!

smartCardId

Image Modified

Example Value: 

  • ${Card_VscId}
Virtual smart card id. Usually it will be created via a dedicated number-range.
provisionReader

Image Modified


Valid values:

  • CreateTPM
  • FreeTPM
  • RenewTPM 
  • 0TPM/1TPM..../15TPM
  • CreateTPM (create a new VSC on the TPM) 
  • FreeTPM (use first free VSC on the TPM) .
  • RenewTPM Use this option to renew existing TPM certificates.
  • 0TPM / 1TPM / ... / 15TPM  Specific VSC on the TPM can be also used for installing certificates.

The value is passed as-is to Smart ID Desktop App.

pinMinLength

Image Modified

Example value:

  • 6
Min. length of the VSC PIN (Windows API allows 4-127 characters,
see https://docs.microsoft.com/en-us/uwp/api/windows.devices.smartcards.smartcardpinpolicy.minlength)
pinMaxLength

Image Modified

Example value:

  • 15
Max length of the VSC PIN (Windows API allows 4-127 characters,
see https://docs.microsoft.com/en-us/uwp/api/windows.devices.smartcards.smartcardpinpolicy.maxlength)
pinUppercase

Image Modified

Valid values:

  • ALLOWED (default)
  • DISALLOWED
  • REQUIRED
Whether uppercase chars in the PIN are ALLOWED / DISALLOWED / REQUIRED
pinLowercase

Image Modified

Valid values:

  • ALLOWED (default)
  • DISALLOWED
  • REQUIRED
Whether lowercase chars in the PIN are ALLOWED / DISALLOWED / REQUIRED
pinDigits

Image Modified

Valid values:

  • ALLOWED (default)
  • DISALLOWED
  • REQUIRED
Whether digits in the PIN are ALLOWED / DISALLOWED / REQUIRED
pinSpecialChars

Image Modified

Valid values:

  • ALLOWED (default)
  • DISALLOWED
  • REQUIRED
Whether special chars in the PIN are ALLOWED / DISALLOWED / REQUIRED
hybridProfile-

Valid values:

  • FALSE (default)
  • TRUE

oldAdminKey-

-

This field only makes sense in case the "FreeTPM" provisionReader is configured. If provided, it will change the VSC's admin key. "oldAdminkey" must hold the old admin key and "adminKey" must hold the new admin key.

For example, default admin key of 010203040506070801020304050607080102030405060708 when you create VSC from Tpmvscmgr tool.

storagePriority

Image Modified

Valid values (version-dependent, Smart ID Desktop App or Smart ID Messaging update may be required for some):

  • VSC (TPM-based virtual smart card, default)
  • TPM (direct TPM storage, depending on the version of Smart ID Desktop App, it might have same meaning as VSC)
  • YUBI (Yubico YubiKey 5 PIV Token, since Identity Manager 3.12.5)
  • OS (operating system certificate store)

Storage priority - defines where certificates and keys are stored. Usually just a single value.
If hybridProfile is TRUE, then this may be a comma-separated list.

Example:

VSC, OS would mean: try to write to a virtual smart card first, and if that fails, use the OS certificate store instead.

desktopKeyProtectionLevel

Image Modified

Valid values:

  • NONE (default)
  • CONSENT
  • PASSWORD
  • BIOMETRICS

Specifies the key protection level at OS key store. It is only used in case of OS storage priority. 

  • NONE - No strong key protection.
  • CONSENT - The user is notified through a dialog box when the private key is created or used.
  • PASSWORD - The user is prompted to enter a password for the key when the key is created or used.
  • BIOMETRICS - The user is prompted to enter a fingerprint verification for the key when the key is created or used.



Expand
titleDesktop App: Install Certificates on Virtual Smart Card

Description

This task requests and installs certificates that were prepared using the "Desktop App: Create Virtual Smart Card Key" task.

As a prerequisite

  • you must already have requested certificates with the authentication and signature certification requests generated by the "Desktop App: Create Virtual Smart Card Key" task. Store the certificates as process variables.
  • if you want to perform certificate recovery, you must prepare the data for that using 'Cert: Load Key History List'.

Use this task to install a number of certificates on a profile maintained by the Smart ID Desktop App:

  • Signature Certificate, will be bound to the key pair created by 'Desktop App: Create Virtual Smart Card Key'.
  • Authentication Certificate, will be bound to the key pair created by 'Desktop App: Create Virtual Smart Card Key'.
  • Device Encryption Certificate, will be bound to the key pair created by 'Desktop App: Create Virtual Smart Card Key'.
  • Encryption Certificate created with key archival.
  • Any number of recovered certificates.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${pxVscHermodInstallCertificatesTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.

messageName

Image Modified

p10FinishedCallbackThe name of the intermediate message catching event that will be triggered by Smart ID Messaging.
userid

Image Modified

${Person_Email}ID representing the user on the messaging server. This must match the userid provided when the profile was requested.
errorMessageField

Image Modified

ErrorMessage

Process variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorType

Process variable to put the error type in case of failure.
signatureCertificate

${SIG_VAR}

The signature certificate.
authenticationCertificate

${AUTH_VAR}

The authentication certificate.
deviceEncryptionP10

Image Modified

${DEVICE_ENC_P10_VAR}

The PKCS#10 request for the Device Encryption Certificate, created by the "Desktop App: Create Virtual Smart Card Key" task.
profileId

Image Modified

${profileId}

The id of the profile under which to store the certificates. This is initially provided by the 'Desktop App: Create Virtual Smart Card Key' task.
encryptionCertificate

Encryption certificate template.
recoveryCertificate

Recovery certificate template.
processVariable
Certificate_CoreObjectsVariable name which holds Core object ids list or Core object descriptor list of certificates to be recovered.
p12PasswordField

Image Modified

p12passwordReference field where the created password is stored. This password is used for all PKCS#12 containers in this communication. There are a number of actions for creating passwords.
smartCardId

Image Modified

${Card_VscId}

Virtual smart card id. Usually it will be created via a dedicated number-range.
storagePriority

Image Modified

Valid values (version-dependent, Smart ID Desktop App or Smart ID Messaging update may be required for some):

  • VSC (TPM-based virtual smart card, default)
  • TPM (direct TPM storage, depending on the version of Smart ID Desktop App, it might have same meaning as VSC)
  • YUBI (Yubico YubiKey 5 PIV Token, since Identity Manager 3.12.5)
  • OS (operating system certificate store)

Storage priority - defines where certificates and keys are stored. Usually just a single value.

If the profile was created with hybridProfile set to TRUE (see 'Desktop App: Create Virtual Smart Card Key'), then this may be a comma-separated list.

Example:

VSC, OS would mean: try to write to a virtual smart card first, and if that fails, use the OS certificate store instead.

desktopKeyProtectionLevel

Image Modified

Valid values:

  • NONE (default)
  • CONSENT
  • PASSWORD
  • BIOMETRICS

Specifies the key protection level at OS key store. It is only used in case of OS storage priority. 

  • NONE - No strong key protection.
  • CONSENT - The user is notified through a dialog box when the private key is created or used.
  • PASSWORD - The user is prompted to enter a password for the key when the key is created or used.
  • BIOMETRICS - The user is prompted to enter a fingerprint verification for the key when the key is created or used.



Expand
titleDesktop App: Delete Virtual Smart Card profile

Description

Use this task to delete a virtual smart card profile managed by Smart ID Desktop App on a TPM and also to delete all Smart ID Messaging mailboxes for a specific user id.

This task can be used in the following ways:

Delete Virtual Smart card profile on Smart ID Desktop App and Smart ID Messaging

Execute this task on a smart card profile which contains information about smart card id, profile id and card manager key (admin key).

  1. Specify a profile id and set the confirmation flag to true. All other parameters must be provided as well.
  2. The request will be sent to Smart ID Desktop App, which will delete the profile identified by the specified profile id and smart card id. Smart ID Desktop App will also change the card's admin key to the new value provided.
    • The result will be sent to the message catching intermediate event identified by the parameter 'messageName'.
    • After receiving a successful response from Smart ID Desktop App, Smart ID Messaging also deletes the mailbox and forwards the same response back to Identity Manager.

Delete mailbox on Smart ID Messaging only

  1. Set the confirmation flag to false. Smart card id and keys can be omitted.
  2. Smart ID Messaging will delete either a specific mailbox when a profile id is provided or all mailboxes of the specified user id when the profile id is absent.
    • The profiles themselves, in their respective apps, will be retained, as the deletion request will not be forwarded.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${pxVscHermodDeleteProfileTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.
messageName

Image Modified

deleteSmartCardCallbackThe name of the intermediate message catching event that will be triggered by Smart ID Messaging.
errorMessageField

Image Modified

ErrorMessageProcess variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorTypeProcess variable to put the error type in case of failure.
profileId

when confirmation flag is true

${Card_ProfileId}

ID of the profile to be deleted, as created via 'Desktop App: Create Virtual Smart Card Key'.

smartCardId

when profileId provided and confirmation flag is true

${Card_VscId}ID of the virtual smart card, as created via 'Desktop App: Create Virtual Smart Card Key'.
plugoutUrl

when profileId provided and confirmation flag is true

plugoutUrl

Process variable to put the resulting Smart ID Plugout URI that will open Smart ID Desktop App on the client machine.

userid

Image Modified

${Person_Email}

ID representing the user on the messaging server. This must match the userid provided when the profile was requested.
adminKey

when profileId provided and confirmation flag is true


The secret field reference of the new 24-byte 3DES admin key to be set, in HEX format. The key can also be set directly as plain hex value for testing.

oldAdminKey

when profileId provided and confirmation flag is true

${Card_CardManagerKey}

The secret field reference of the 24-byte 3DES current admin key, in HEX format. The key can also be set directly as plain hex value for testing.

confirmation

Image Modified

Valid values:

  • true (default)
  • false

Messaging Server will forward the delete profile request to Smart ID Desktop App when this set to true.



Info!

Smart ID Desktop App will sign the request data and Identity Manager will verify the client's data signature using the attestation key. The attestation key is configured in the task's attestationKeySet parameter and in the Sign and encrypt engine in Identity Manager.

If the verification fails, the task will not accept the data but set two process variables instead:

  • The errorTypeField (see the parameters below) will be set to "HERMOD_ERROR_JWT_SIGNATURE". Use this in your process design to react to validation errors.
  • The errorMessageField (see the parameters below) will contain a more descriptive message

Configuration

To use this task, configure the following delegate expression in your service task:

Expand
titleDesktop App: Create Windows Cert Store Key

Description

Use this task to create a template PKCS#10 request that can be used to request the certificate needed for the "Desktop App: Install Certificates On Windows Cert Store" task:

  • Device Encryption (used to secure the communication with Smart ID Desktop App)

Identity Manager will also put the new profileId into the process map under the key "profileId". In order to save the profile id you will need to copy it into a data pool field.

This task can only provision a new profile - updating an existing profile is currently only supported in Smart ID Mobile App at this time, it is not supported in Smart ID Desktop App.

Info
titleAttestation Key
Code Block
${pxOsHermodKeyCreationTask}

The following parameters can be configured in Identity Manager Admin: 

Currently
ParameterMandatoryValueDescription
messagingServer

Image Modified

Example value:

  • MessagingServer
The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.

messageName

Image Modified

Example value:

  • p10PreparationCallback
The name of the intermediate message catching event that will be triggered by Smart ID Messaging.
userid

Image Modified

Example value:

  • ${Person_Email}

ID representing the user on the messaging server. This will be displayed in the profile(-list) on the desktop app to verify the correct data is provided.

A common approach is to use the user's email address.

errorMesageField

Image Modified

Example value: 

  • ErrorMessage
Process variable to put the error message in case of failure.
errorTypeField

Image Modified

Example value: 

  • ErrorType
Process variable to put the error type in case of failure.
profileName

Image Modified

Example value:

  • Windows Certs
Profile name for Smart ID Messaging. Will be displayed in Smart ID Desktop App as heading of the profile.
serverName

Image Modified

Example value:

  • Smart ID

Name of the server that issued the provisioning request. Will be displayed in Smart ID Desktop App so the user can understand where this profile comes from. 

plugoutResultField

Image Modified

Example value: 

  • plugoutUri
Process variable to put the resulting Smart ID Plugout URI that will open Smart ID Desktop App on the client machine.
desktopKeyProtectionLevel

Image Modified

Valid values:

  • NONE (default)
  • CONSENT
  • PASSWORD
  • BIOMETRICS

Specifies the key protection level at OS key store. It is only used in case of OS storage priority. 

  • NONE - No strong key protection.
  • CONSENT - The user is notified through a dialog box when the private key is created or used.
  • PASSWORD - The user is prompted to enter a password for the key when the key is created or used.
  • BIOMETRICS - The user is prompted to enter a fingerprint verification for the key when the key is created or used.
attestationKeySet

-

(If not set will default to "ATTESTATION")

Example value:

  • ATTESTATION (default value)

The name of the attestation key that will be used for signing (by the client) and validating (by Identity Manager) the client's data. The available values are the names of the descriptors in the sign and encrypt engine that start with "att_", without this prefix. An attestation key with the same name must be defined in Smart ID Desktop App.

Note

Smart ID Desktop App only accepts

only only

the default key set named "ATTESTATION".


If new profile





Expand
titleDesktop App: Install Certificates On Windows Cert Store

Description

Use this task to request and install certificates that were prepared using the "Desktop App: Create Windows Cert Store Key" task.

As a prerequisite

  • you must already have requested certificates with the authentication and signature certification requests generated by the "Desktop App: Create Virtual Smart Card Key" task. Store the certificates as process variables.
  • if you want to perform certificate recovery, you must prepare the data for that using 'Cert: Load Key History List'.

Use this task to install a number of certificates on the Windows Certificate store:

  • Device Encryption Certificate, will be bound to the key pair created by 'Desktop App: Create Windows Cert Store Key' task.
  • Softtoken certificate created with key archival.
  • Any number of recovered certificates.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${pxOsHermodInstallCertificatesTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.

messageName

Image Modified

p10FinishedCallback

The name of the intermediate message catching event that will be triggered by Smart ID Messaging.
userid

Image Modified

${Person_Email}

ID representing the user on the messaging server. This must match the userid provided when the profile was requested.
errorMessageField

Image Modified

ErrorMessage

Process variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorType

Process variable to put the error type in case of failure.
deviceEncryptionP10

Image Modified

${DEVICE_ENC_P10_VAR}

The PKCS#10 request for the Device Encryption Certificate, created by the "Desktop App: Create Virtual Smart Card Key" task.
profileId

Image Modified

${profileId}

The id of the profile under which to store the certificates. This is initially provided by the 'Desktop App: Create Virtual Smart Card Key' task.
softttokenCertificate

Softtoken certificate template.
recoveryCertificate

Recovery certificate template.
processVariable
Certificate_CoreObjectsVariable name which holds Core object ids list or Core object descriptor list of certificates to be recovered.
p12PasswordField

Image Modified

p12PasswordReference field where the created password is stored. This password is used for all PKCS#12 containers in this communication. There are a number of actions for creating passwords.
desktopKeyProtectionLevel

Image Modified

Valid values:

  • NONE (default)
  • CONSENT
  • PASSWORD
  • BIOMETRICS

Specifies the key protection level at OS key store. It is only used in case of OS storage priority. 

  • NONE - No strong key protection.
  • CONSENT - The user is notified through a dialog box when the private key is created or used.
  • PASSWORD - The user is prompted to enter a password for the key when the key is created or used.
  • BIOMETRICS - The user is prompted to enter a fingerprint verification for the key when the key is created or used.



Expand
titleDesktop/Mobile App: Start Connection

Description

Use this task to start a connection to Smart ID Messaging. With this connection, scripts can be executed. Finally, the connection needs to be closed.

Once the connection is established you receive a boxId and a plugoutUrl which can be used to start Smart ID Desktop App and connect it to the corresponding box on Smart ID Messaging.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${hermodStartConnectionParametrizedTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.
boxId

Image Modified


Process variable to put the boxId.
plugoutUrl

Image Modified


Process variable to put the plugout url.
messageToUser

An optional message to the user which will be displayed in Smart ID Desktop App.
messageName

The name of the intermediate message catching event that will be triggered by Smart ID Messaging.



Expand
titleDesktop/Mobile App: Execute Script

Description

Use this service task to execute a script in Smart ID Desktop App. The script needs to be passed as a JSON array (for example: [{"type":"APDU", "data":"00A4040000", "response":".*(9000)"}]) 

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${hermodExecuteScriptParametrizedTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.
boxId

Image Modified


Process variable to put the boxId.
scriptCommands

Image Modified

Example value:

  • [{"type":"APDU", "data":"00A4040000", "response":".*(9000)"}]
Process variable containing the script commands. The commands need to be formatted as a JSON array.
messageToUser

An optional message to the user which will be displayed in Smart ID  Desktop App.
messageName

Image Modified


The name of the intermediate message catching event that will be triggered by Smart ID Messaging.



Expand
titleDesktop/Mobile App: End Connection

Description

Use this service task to close a scripting connection to Smart ID Messaging.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${hermodEndConnectionParametrizedTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.
boxId

Image Modified


Process variable to put the boxId.
messageToUser

An optional message to the user which will be displayed in Smart ID Desktop App.
messageName

Image Modified


The name of the intermediate message catching event that will be triggered by Smart ID Messaging.



Expand
titleDesktop/Mobile App: Encrypt Secret for Transport

Description

Use this task to encrypt the pin or card manager key that is sent during a pin operation. The corresponding app while provide this one time key in the callback message when the operation is requested.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${jweEncryptTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
jweAlgorithm

Image Modified

${transportKeyType}The value as provided by the corresponding app via a callback message. In most cases the default value should be used. RSA-OAEP, RSA-OAEP-256, and RSA1-5 are supported. 
key

Image Modified

${transportKey}The value as provided by the corresponding app via a callback message. In most cases the default value should be used. Supports only X509 encoded RSA key in byte array.
sourceData

Image Modified

${Card_CardManagerKey}The secret to be encrypted. 
targetField

Image Modified

${encryptedSecret}Process variable to hand over the encrypted secret to the acknowledge task.



Expand
titleDesktop App: Request PIN Reset on Virtual Smart Card

Description

Use this task to initiate a pin reset on a virtual smart card.

Once the operation is confirmed by the user through the Smart ID Desktop App, Identity Manager will receive a challenge that needs to be encrypted via the card manager key in order to authorize the pin reset. The challenge will be set in the process variable "challenge".

After this task is executed, use the 'Credentials: Calculate Minidriver Offline Unblocking Response' task to encrypt the challenge stored in the process variable "challenge" and store the encrypted challenge in the process variable "encryptedChallenge". Then you can proceed to the "Desktop App: Acknowledge PIN Reset on Virtual Smart Card" task.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${hermodStartPinResetTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.

messageName

Image Modified

startPinResetCallback

The name of the intermediate message catching event that will be triggered by Smart ID Messaging.
userid

Image Modified

 ${Person_Email}

ID representing the user on the messaging server. This must match the userid provided when the profile was requested.
errorMessageField

Image Modified

ErrorMessageProcess variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorTypeProcess variable to put the error type in case of failure.
profileId

Image Modified

 ${Card_ProfileId}Id of the profile whose pin to change, as created via 'Desktop App: Create Virtual Smart Card Key'.
smartCardId

Image Modified

 ${Card_VscId}Id of the virtual smart card, as created via 'Desktop App: Create Virtual Smart Card Key'.
boxId

Image Modified

 boxIdProcess variable to put the boxId. This will be needed to complete the pin reset.
plugoutUrl

Image Modified

 plugoutUrl

Process variable to put the plugout url.



Expand
titleDesktop App: Request PIN Operation on Physical Smart Card

Description

Use this task to initiate a pin reset on a physical smart card.

The Smart ID Desktop App, will in turn provide a challenge and a transport security key, so that the actual pin operation can be executed.

Supported operations are:

  • Reset the pin
  • Change the card manager key

The challenge Identity Manager will receive, needs to be encrypted via the card manager key in order to authorize the pin operation. The challenge will be set in the process variable "challenge" by a callback message.

The transport security key can be used to encrypt the new card manager key, when it is changed.

After this task is executed, use the 'Credentials: Calculate Minidriver Offline Unblocking Response' task to encrypt the challenge stored in the process variable "challenge" and store the encrypted challenge in the process variable "encryptedChallenge". Then you can proceed to the "Desktop App: Acknowledge PIN Reset on Virtual Smart Card" task.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${hermodStartScPinResetTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.

messageName

Image Modified

startPinResetCallback

The name of the intermediate message catching event that will be triggered by Smart ID Messaging.
operation

Image Modified

 resetPIN

  • resetPIN: reset the user pin
  • changeAdminKey: set a new card manager key
errorMessageField

Image Modified

ErrorMessageProcess variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorTypeProcess variable to put the error type in case of failure.
driverType

Image Modified

MiniDriverWhat kind of driver is used for the operation. At the moment only MiniDriver is supported.
driverName

Image Modified

 CardOSName of the driver to be used .



Expand
titleDesktop App: Acknowledge PIN Reset on Virtual Smart Card

Description

Use this task to complete a pin reset on a virtual smart card. Once the pin is reset by Smart ID Desktop App, Identity Manager will receive an event indicating success or failure of the operation.

As a prerequisite you must have encrypted the challenge received in the "Desktop App: Request PIN Reset on Virtual Smart Card" task.

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${hermodEndPinResetTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.

messageName

Image Modified

endPinResetCallback

The name of the intermediate message catching event that will be triggered by Smart ID Messaging.
errorMessageField

Image Modified

ErrorMessageProcess variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorTypeProcess variable to put the error type in case of failure.
profileId

Image Modified

${Card_ProfileId}Id of the profile whose pin to change, as created via 'Desktop App: Create Virtual Smart Card Key'.
smartCardId

Image Modified

${Card_VscId}Id of the virtual smart card, as created via 'Desktop App: Create Virtual Smart Card Key.
boxId

Image Modified

${boxId}The boxId that was created with 'Desktop App: Request PIN Reset on Virtual Smart Card'
response

Image Modified

${encryptedChallenge}The challenge received in the callback of 'Desktop App: Request PIN Reset on Virtual Smart Card' encrypted with the card manager key of this VSC using 'Credentials: Calculate Minidriver Offline Unblocking Response'.



Expand
titleDesktop App: Acknowledge PIN Operation on Physical Smart Card

Description

Use this task to complete a pin operation on a virtual smart card. Once the pin is changed by Smart ID Desktop App, Identity Manager will receive an event indicating success or failure of the operation.

As a prerequisite you must have encrypted the challenge received in the "Desktop App: Request PIN Reset on Virtual Smart Card" task, and, if the pin (or card manager key) is provided by the Identity Manager is has to be encrypted for secure transport using the "Desktop/Mobile App: Encrypt Secret for Transport" task. 

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${hermodScEndPinResetAction}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.

messageName

Image Modified

endPinResetCallback

The name of the intermediate message catching event that will be triggered by Smart ID Messaging.
errorMessageField

Image Modified

ErrorMessageProcess variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorTypeProcess variable to put the error type in case of failure.
encryptedSecret


${encryptedSecret}Only required, if the secret (like card manager key or pin) in managed by Identity Manager. It is encrypted using the "Desktop/Mobile App: Encrypt Secret for Transport" task. If the secret is entered by the user into the app, this can be omitted.
boxId

Image Modified

${boxId}The boxId that was created with 'Desktop App: Request PIN Reset on Virtual Smart Card'.
response

Image Modified

${encryptedChallenge}The challenge received in the callback of 'Desktop App: Request PIN Reset on Virtual Smart Card', encrypted with the card manager key of this VSC using 'Credentials: Calculate Minidriver Offline Unblocking Response'.



Expand
titleDesktop App: Ping Virtual Smart Card profile

Description

Use this task to retrieve profile and device information of virtual smart cards that are managed by Smart ID Desktop App.

You can request information of a virtual smart card or of a single virtual smart card profile.

The task will put a "commandId" value into a process variable which must be used for polling the response using "Desktop App: Poll meta data from client".

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${pxVscHermodPingRequestTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.
errorMessageField

Image Modified

ErrorMessageProcess variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorTypeProcess variable to put the error type in case of failure.
profileId


${Card_ProfileId}If provided, restrict requested information to this profile. ProfileId values are created in the 'Desktop App: Create Virtual Smart Card Key' task.
plugoutUrl

Image Modified

 plugoutUrl

Process variable to put the plugout url.

userid


Valid values:

  • If profileid is set: provided userid 
  • Otherwise: any value

ID representing the user on the messaging server. If a profileId parameter is set, this must match the userid provided when the profile was requested. Otherwise any value will do.

deviceInfo

Image Modified

Valid values:

  • true (default)
  • false

Request device information.

profileInfo

Image Modified

Valid values:

  • true (default)
  • false

Request profile information.

commandId

Image Modified

commandIdProcess variable to put the commandId value, which is needed for polling in the "Desktop App: Poll meta data from client" task.



Expand
titleDesktop App: Poll meta data from client

Description

Use this task to poll a ping response from Smart ID Messaging based upon the 'commandId' (which was created at the ping request to Smart ID Messaging).

Execute this task after a ping request to Smart ID Messaging. It polls the message from Smart ID Messaging, based upon the provided command id. After receiving the response from Smart ID Messaging it stores the profile and device Information into configured service task parameters. 

Configuration

To use this task, configure the following delegate expression in your service task:

Code Block
${pxVscHermodPingResponsePollingTask}

The following parameters can be configured in Identity Manager Admin:

ParameterMandatoryValueDescription
messagingServer

Image Modified


The name of the Smart ID Messaging configuration as defined in Identity Manager Admin. This configuration provides data (url, authentication token, lifespan and timeout) needed for the Smart ID Messaging connection.
errorMessageField

Image Modified

ErrorMessageProcess variable to put the error message in case of failure.
errorTypeField

Image Modified

ErrorTypeProcess variable to put the error type in case of failure.
commandId

Image Modified

${commandId}CommandId which was received by the "Desktop App: Ping Virtual Smart card profile" task, needed for polling.
profileInfo

Image Modified

profileInfoProcess variable to put the profile information.
deviceInfo

Image Modified

deviceInfoProcess variable to put the device information.