Skip to main content

Single Registration: Workstation-to-Web: API

Enrollment service API(s)​

The enrollment service polls the server for pending certificate issuance requests.

HYPR recommends having the enrollment agent poll this endpoint every 15 seconds; this is not enforced. The response contains lists of certificates to be issued and revoked.

If an error happens on the enrollment service while processing, no events need be sent for successful processing:

  • Issuing a certificate: Send an WORKSTATION_CERTIFICATE_ISSUED Event with isSuccessful=false

  • Revoking a certificate: Send an WORKSTATION_CERTIFICATE_REVOKED Event with isSuccessful=false

GET /rp/api/certificate/requests​

This request requires a controlCenterAdmin API Bearer token. This will allows one Enrollment service process for all RPApps, without making separate calls for each.

RESPONSE BODY - Certificate Requests Available​

{
  "loginCerts": [
    {
      "requestId": "",   <Unique requestId. Used to co-relate request/response>
      "requestTimeoutInSecs": 5 * 60,      // If the issuer is unable to complete the request in this time, 
                                           // the request is considered a failure and will be re-queued by the server
                                           // If the issuer must drop the request if it gets outside the timeout window
      "machineUserNameWS": "domain/user",  // Server will provide if available from a mapping  
                                           // If not populated by the server, the Enrollment service must attempt
                                           // to resolve this from the Active Directory lookup 
      "machineUserName": "user@email.com",
      
      "deviceId": ""
      "deviceKeyAgreementPublicKey": ""// Public key suuplied by the device. Used to derive DH shared secret
                                       // ⚠️ Implies that a given cert can only be decrypted by the requesting device 
      "encCounter": "01" 
    }
  ],
  "revokedCerts": [
    {
      "requestId": "",                    // Same as above 
      "requestTimeoutInSecs": 5 * 60,     // Same as above
      "certSerialNumber": ""              // Serial number of the certificate to revoke
    }
  ]
}

RESPONSE BODY - No Certificate Requests​

{
  "loginCerts": [],
  "revokedCerts": []
}

The enrollment service POSTs the encrypted certificates back to the server.

Once a certificate is received, a WORKSTATION_CERTIFICATE_ISSUED event is logged by the relying party. Any errorCode attribute greater than 0 is treated as a failure.

It’s clear to POST, process, and acknowledge each certificate.

POST /rp/api/certificate​

This request requires a controlCenterAdmin Bearer token.

REQUEST BODY - Success Payload​

{
  "errorCode": 0,                    // <Int value || Specific error code indicating the break in processing>
  "errorMessage": ""                 // Free form text description of the error
  "requestId": "",                   // Unique requestId. Used to co-relate request/response
  "issuerKeyAgreementPublicKey": "", // Enrollment service's public key used in ECDH to derive the env key 
  "issuerKeyAgreementPublicKeyAuth": "",
  "loginCert": "",
  "loginCertAuth": "",
  "loginCertSerialNumber": "",
  "loginCertExpiryDate": 0,  // Number in millis since January 1, 1970, 00:00:00 GMT
  "ivLoginCert": "",
  "signingCert": "",
  "machineUserNameWS": "",
  "machineUserNames": [""]   // The Active Directory lookup by the Certificate Issuer might result in multiple
                             // user names/emails. Return all of these. The server will then track these as the 
                             // same user entity
}

REQUEST BODY - Error Payload​

{
  "errorCode": <numeric err code>,    // Specific error code indicating the break in processing>
  "errorMessage": "<err text>",       // Free form text description of the error. Max 5000 chars
  "requestId": <numeric req id>       // RequestId from the original poll req
}

RESPONSE BODY - 204 No Content on Success​

  • RFC7807 error if anything goes wrong

  • The enrollment service POSTs confirmation for the revoked certificate

Once a certificate is received, a WS_CERTIFICATE_REVOKED Event is logged by the relying party. Any errorCode attribute greater than 0 is treated as a failure.

Upon failure, a specific error code is logged. This must be monitored by an external system.

POST /rp/api/certificate/revoke​

This request requires a controlCenterAdmin Bearer token.

REQUEST BODY - Success Payload​

{
  "errorCode": 0,            // <Int value || Specific error code indicating the break in processing>
  "errorMessage": ""         // Free form text description of the error
  "requestId": "",           // Unique requestId. Used to co-relate request/response
  "certSerialNumber": "",    // Serial number of the revoked certificate
}

REQUEST BODY - Error Payload​

{
  "errorCode": <numeric err code>,    // Specific error code indicating the break in processing>
  "errorMessage": "<err text>",       // Free form text description of the error. Max 5000 chars
  "requestId": <numeric req id>       // RequestId from the original poll req
}

RESPONSE BODY - 204 No Content on Success​

  • RFC7807 error if anything goes wrong

Workstation Completes Pairing/Enrolling​

Once the initial authorization is done, the workstation runs the following logic:

  • User/pass login → How does HYPR react to this? We can show a popup notification once the vpn is available. The user can do the QR scan flow.

    • VDI: No action taken

    • Not connected to domain: No action taken

    • Connected to domain

      • Persistent and has a paring for the deviceId: No action is taken

      • Persistent and does NOT have a pairing for the deviceId; the following calls are made to finish pairing:

        • Start workstation enrollment

This is conceptually similar to SmartKey enrollment. The objective is to transfer recovery keys and device information.

This API signature is identical to /rp/versioned/client/registrations.

POST /rp/wsapi/client/enroll​

REQUEST BODY​

{
    // If the user logged in with a username/pass - session id will not be available
    // WS may send the rpAppId/machineUserNameWS to enquire whether there is a 
    // registration (not implemented yet)
    "rpAppId": ""
    "machineUserNameWS": ""
    
	"sessionId": "6ead5bdd7fbaedb589afd00094171aaf40f92d0a1632fb1881992aad2425563b",
}

RESPONSE BODY - 200 Client Enroll Request Sucess​

{
	"status": {
		"responseCode": 200,
		"responseMessage": "Client enroll request success"
	},
	"response": {
		"device": {
			"deviceKey": "69663036347368616374356f3433616f76346c6735363737346b",
			"authenticationKey": "69706f6d626c36717639383230676f353937696e74766e757363",
			"friendlyName": "samsung SM-G975U",
			"deviceId": "DevIde9h3453aks4msn8e3hjsitd3gb",
			"modelNumber": "samsung SM-G975U",
			"keyAgreementPublicKey": "suOQnK8KcqKIOK5-3-WSApq9bE4hIXilm9tZPfJGTfhEIQVME8GC07d6n-lqIAdL0E0IExX4HeDsy6d7DbZ_yA",
			"encCounter": "01"
		}
	}
	// Recovery keys have been moved to Auth flow
}

Complete Enrollment​

POST /rp/wasapi/client/enroll/complete​

{
	"errorCode": 0, <Int value: 0 || Specific error code indicating the break in processing> 
	"sessionId": "6ead5bdd7fbaedb589afd00094171aaf40f92d0a1632fb1881992aad2425563b",
	"signingCert": "MIICCjCCAa-gAwIBAgIQRcR3_k_P4YdCBbwn5Og6MTAKBggqhkjOPQQDAjBVMRswGQYDVQQDDBJIWVBSRW1wbG95ZWVBY2Nlc3MxFDASBgNVBAsMC0VuZ2luZWVyaW5nMRMwEQYDVQQKDApIWVBSIENvcnAuMQswCQYDVQQGEwJVUzAgFw0yMTA3MTQxMzE0NDFaGA8yMTAwMDEwMTAwMDAwMFowVTEbMBkGA1UEAwwSSFlQUkVtcGxveWVlQWNjZXNzMRQwEgYDVQQLDAtFbmdpbmVlcmluZzETMBEGA1UECgwKSFlQUiBDb3JwLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAARdpBkicVukJz_QMHw5lK1MaeaYB-unizeqrYlwoi00y_j-iaqocJo-Zt_zBZuiVMpaOzj1fGsjVyPN6-vzZi2Wo18wXTAPBgNVHRMBAf8EBTADAgEAMA4GA1UdDwEB_wQEAwIGwDAbBgNVHREEFDASgRBzdXBwb3J0QGh5cHIuY29tMB0GA1UdDgQWBBTJQz_xBPdh34xthAtGUeGuxkXVTzAKBggqhkjOPQQDAgNJADBGAiEAsuoTSttCVg2qdtKVD9pUk3uJ8ChgyTiQvYCuLoRKYrUCIQDw63fG93u3ZZ_MlEuB2qpr84EgqMmRWkyjbBFPDAXemg",
    "machineName": "WORK-DESKTOP-1",
    "machineId": "MachineId-Auto-1635694246331", \\ to cross check against fido session
	"machineUserName": "xray\\sandhub",          \\ to cross check against fido session
    "machineVersion": "6.18.0"                   \\ to cross check against fido session
}

RESPONSE - 200 Enrollment Success​

{
	"status": {
		"responseCode": 200,
		"responseMessage": "Enrollment Success"
	}
}

Error handling​

A WORKSTATION_ENROLL Event will be logged on success.

  • The server will persist data on the complete call

  • If there is a failure, the workstation should send the OOB_WORKSTATION_REG Event with a success=false attribute

  • The workstation should re-attempt enrollment on the next authentication attempt