Example: Personal Desktop Client authentication
Step-by-step instruction
The URI from the response is added as a link on the login page and can be invoked either on loading the page or when user clicks the link.
Please note that user needs to verify that the server domain is the same as he is trying to log in to.
Add the URI from the response as a link on the login page. Execute the link either on loading the page or when user clicks the link.
Example URI
TEXTcom.nexusgroup.plugout:///?url=https%3a%2f%2fnexus-cod1.test.nexusgroup.com%3A20400%2fhermod%2Frest%2Fms%2F56480f29-9c16-4178-b770-730037db82e2&token=759da21e-7977-45bf-b60d-a3c2388fc8a7
The protocol handler for Personal Desktop Client will open the plugout dialog.
The user needs to verify that the correct URL is used and then confirm the login by select a certificate that is inserted and enter the PIN.
When the user has provided the smart card and entered the PIN then personal will sign the authentication request and send the response to Hermod which sends the response to the Application Server in a callback.
Validate the response and check the following:
- That the signature is valid.
- That the certificate corresponds to the user.
- That the certificate is trusted and not revoked.
- That FQDN included in the signature matches the domain name for the Hermod server.
Example: Authentication response callback
CODEPOST https://my-registered-callbackserver/rest/callback/authenticate { "responseHeader" : { "inReplyTo" : "https://nexus-cod1.test.nexusgroup.com:20400/hermod/rest/ms/62806293-ee37-45e4-b618-3b4db82bdfb5/81627ebb-0ac8-4292-9b0b-961c4e71cfaa", "status" : 200 }, "authResponse" : { "code" : 0, "result" : { "signature" : "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", "mechanism" : "CKM_SHA256_RSA_PKCS", "format" : "pkcs7", "signer" : { "certificate" : "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" } } }, "commandId" : "726", "destinations" : [ { "to" : "@tmp", "bid" : "62806293-ee37-45e4-b618-3b4db82bdfb5", "uri" : "com.nexusgroup.plugout:///?url=https%3a%2f%2fnexus-cod1.test.nexusgroup.com%3A20400%2fhermod%2Frest%2Fms%2F62806293-ee37-45e4-b618-3b4db82bdfb5&token=73dcd669-1efc-41e7-afaf-b3feb7a7e386", "mid" : "81627ebb-0ac8-4292-9b0b-961c4e71cfaa", "location" : "https://nexus-cod1.test.nexusgroup.com:20400/hermod/rest/ms/62806293-ee37-45e4-b618-3b4db82bdfb5/81627ebb-0ac8-4292-9b0b-961c4e71cfaa" } ], "commandType" : "AUTH", "state" : "COMPLETED", "fqdn" : "nexus-cod1.test.nexusgroup.com" }
To avoid MITM attacks it is important to verify that FQDN included in the signature matches the domain name of the deployed Hermod server
Callbacks are not guaranteed
Callbacks are not guaranteed, as a best effort to optimize response times. If callback are not received in expected time frame it is the responsibility of the integrator to poll for the status.
To poll for the status, use the command
GET /rest/command/poll/{commandId}. See example code:Example: Poll command
CODEGET https://nexus-cod1.test.nexusgroup.com:20400/hermod/rest/command/poll/730Example: Poll response
CODEResponse 200 OK { "commandId": "730", "destinations": [ { "to": "@tmp", "bid": "2c112368-c1aa-4562-9329-1446e5a22454", "uri": "com.nexusgroup.plugout:///?url=https%3a%2f%2fnexus-cod1.test.nexusgroup.com%3A20400%2fhermod%2Frest%2Fms%2F2c112368-c1aa-4562-9329-1446e5a22454&token=e21b7e4b-6626-4548-85ea-2274f67cead2", "mid": "48798402-9033-4869-9653-f8d28b1f93dc", "location": "https://nexus-cod1.test.nexusgroup.com:20400/hermod/rest/ms/2c112368-c1aa-4562-9329-1446e5a22454/48798402-9033-4869-9653-f8d28b1f93dc" } ], "commandType": "AUTH", "state": "IN_PROGRESS", "fqdn": "nexus-cod1.test.nexusgroup.com" }