Introduction
From version 6.10 it will be possible to trigger self-service workflows from a browser or a script. It will be possible to trigger the following flows:
- Issuance
- Reissue of certificate(s)
- Change PIN
- Unblock
- Update credential.
Using Windows support for URL protocols, the vSEC:CMS Application will register the protocol as part of the installation process. Then it will be possible to trigger these flows using the registered protocol.
This article will provide very simple examples of how you can implement these flows. For more advanced flows please contact Versasec support.
How to Implement
vSEC:CMS User application needs to be installed on the client where you wish to trigger the flows from. vSEC:CMS User application registers a custom URI handler named cmsuss:// that the application will listen for. For each of the possible flows available, a JSON object needs to be constructed and passed into the URI handler. The JSON object will need to be base64URL encoded.
Issuance
For triggering issuance flow the following parameters can be used to construct a JSON object:
| Parameter Name | Description |
| URL | cmsuss://issue/v1 |
| Options | This is a bit mask value that can be used for debugging purposes when the flow is not working for some reason. Default value is 0 which means the error dialog will not be shown. Set the value to 1 if you want to see error dialog with more details shown if errors occur. |
| MsgOptions | Decimal value to always show popup dialog that is always on top. The value should be 1281. |
| TemplateId | Predefined template ID in decimal that is to be used for issuance. This value can be retrieved from Templates - Card Templates and selecting the template you want to use and click View. Then take the Template ID and convert the hexadecimal value to decimal. |
| UserId | Predefined user ID for issuance. This needs to be the user's DN. |
For example, the JSON object could look like below:
"Options": 0,
"MsgOptions": 1281,
"TemplateId": 131081,
"UserId": "CN=Joe Bloggs 2,CN=Users,DC=vs,DC=local"
}
You should then base64URL encode the JSON object and pass this into the URL. For example, the URL would look similar to below. Just copy and paste the URL into a browser to try.
Reissuance of Certificate(s)
For triggering reissuance flow the following parameters can be used to construct a JSON object:
| Parameter Name | Description |
| URL | cmsuss://reissue/v1 |
| MsgOptions | Decimal value to always show popup dialog that is always on top. The value should be 1281. |
| Flags |
Integer value which should be set to 1 to reissue all certificates issued to the credential. Enter 2 if you want to issue a specific certificate on the credential. |
| Params | If 2 is set as the Flags parameter then enter the decimal value of the certificate template that you want to issue. You can get the certificate template ID from Repository - Smart Cards and select an entry that you want to do this flow with. Click the Details button. In the Certificate(s) section you will see the decimal and hexadecimal value. Enter the decimal value for the Params. |
For example the JSON object could look like below:
"MsgOptions": 1281,
"Flags": 1
}
You should then base64 encode the JSON object and pass this into the URL. For example, the URL would look similar to below. Just copy and paste the URL into a browser to try.
Change PIN
For triggering change PIN flow the following parameters can be used to construct a JSON object:
| Parameter Name | Description |
| URL | cmsuss://changepin/v1 |
| MsgOptions | Decimal value to always show popup dialog that is always on top. The value should be 1281. |
| ReaderName |
Optionally you can enter the name of the specific reader that the credential is expected to be inserted into. For example, you can get the reader name using the Windows command: certutil -scinfo |
For example, the JSON object could look like below:
"MsgOptions": 1281
}
You should then base64URL encode the JSON object and pass this into the URL. For example, the URL would look similar to below. Just copy and paste the URL into a browser to try.
Unblock PIN
For triggering unblock PIN flow the following parameters can be used to construct a JSON object:
| Parameter Name | Description |
| URL | cmsuss://unblockpin/v1 |
| MsgOptions | Decimal value to always show popup dialog that is always on top. The value should be 1281. |
| ReaderName |
Optionally you can enter the name of the specific reader that the credential is expected to be inserted into. For example, you can get the reader name using the Windows command: certutil -scinfo |
For example, the JSON object could look like below:
"MsgOptions": 1281
}
You should then base64URL encode the JSON object and pass this into the URL. For example, the URL would look similar to below. Just copy and paste the URL into a browser to try.
Update Credential
For triggering credential update flow the following parameters can be used to construct a JSON object:
| Parameter Name | Description |
| URL | cmsuss://updatecard/v1 |
| MsgOptions | Decimal value to always show popup dialog that is always on top. The value should be 1281. |
| ReaderName |
Optionally you can enter the name of the specific reader that the credential is expected to be inserted into. For example, you can get the reader name using the Windows command: certutil -scinfo |
For example, the JSON object could look like below:
"MsgOptions": 1281
}
You should then base64URL encode the JSON object and pass this into the URL. For example, the URL would look similar to below. Just copy and paste the URL into a browser to try.
Simple HTML Example
In this section we will provide a very simple example of how you could construct a HTML page to be used to trigger an issuance flow from a browser. We used the sample JSON object from Issuance section above for this example. Copy and paste the code below and save as a .html file and launch it from a browser.
<!doctype html>
<html>
<head>
<title>vSEC:CMS User Application URL Launcher Simple Example</title>
</head>
<body>
<center>
<h1>vSEC:CMS User Application URL Launcher Simple Example</h1>
<table>
<tr>
<td></td>
<td>
<input type="button" name="bt" id="btProcess" value="Issuance"
onclick="process_it()" style="height:50px;width:200px">
</td>
</tr>
</table>
</center><pre><div id="content"></div></pre>
</body>
</html>
<script>
function process_url(msg, url)
{
document.getElementById("content").innerHTML = msg;
if(!confirm(msg))
{
return;
}
window.location.href=url;
document.getElementById("btProcess").disabled = true;
document.getElementById("btCardTemplate").disabled = true;
var seconds = 10;
var countdown = setInterval(function() {
seconds--;
document.getElementById("btProcess").value = "Wait "+seconds+"...";
document.getElementById("btCardTemplate").value = "Wait "+seconds+"...";
if (seconds <= 0)
{
clearInterval(countdown);
process_reset_ui();
}
}, 1000);
}
function process_it()
{
var url="cmsuss://issue/v1/" + "ew0KIk9wdGlvbnMiOiAwLA0KIk1zZ09wdGlvbnMiOiAxMjgxLA0KIlRlbXBsYXRlSWQiOiAxMzEwODEsDQoiVXNlcklkIjogIkNOPUpvZSBCbG9nZ3MgMixDTj1Vc2VycyxEQz12cyxEQz1sb2NhbCINCn0";
var msg = "Launch URL Param\r\n--------------------\r\n";
process_url(msg, url);
}
</script>
For more advanced examples and queries please contact Versasec Support.