Encap#

The Encap Authenticator has an optional flow which can be used when the app requesting authentication is also the app that implements the encap-client using the encap SDK.

In this scenario it is no longer needed to have any user interaction when activating the device. The user only has to authenticate using some other means of authentication, before activating the device. The activation code can then automatically be passed to the app and the app can finalize the activation.

Encap - Non interactive flow

1. The app opens a browser or webview to the start-auto-activate url. It needs to pass a verifier to start the flow. This verifier is a random value that the app generates and passes in. It serves as protection for token-hijack attacks.
2. If the user isn’t authenticated the user is redirected to authentication.
3. The user authenticates in the configured manner.
4. The Curity Identity Server redirects back to the app using the configured url for the app with the app scheme (example: myapp://activate). In the redirect the Curity Identity Server will pass an activation code to be sent to Encap, an activation token to be used to finish activation with the Curity Identity Server, and an activation url where the activation should be finished.
5. The app activates the device with the activation code to Encap
6. When activation is done, the app posts the activation token along with activation parameters and the verifier used in step 1 to the Curity Identity Server.
7. Upon successful activation the Curity Identity Server returns 200 OK.

Endpoint overview#

The endpoints to be interacted with are located under the authentication profile’s anonymous endpoint. The following sub-paths are used:

start-auto-activate#

Start activate requires a verifier to be sent on the query string. This is a random string that the app should generate before starting activation. The purpose is that if another app hijacks the return redirect it cannot use the activation code to activate the device with the Curity Identity Server since it does not know the verifier.

Example start-auto-activate#

Request:

GET /authn/anonymous/encap1/start-auto-activate?verifier=DMCA12-BBDK442-j4mm22763 HTTP/1.1
Host: login.example.com

Response:

HTTP/1.1 302 Found
Location: myapp://activate?activationCode=95524851&activationToken=3E2GiWTU7oY9PdjNWsrxsQB2vTfAR3l8&finishActivationUrl=https%3A%2F%login.example.com%3A8443%2Fdev%2Fauthn%2Fanonymous%2Fencap1%2Ffinish-auto-activate

In the redirect back to the app the following parameters are found on the query string.

finish-auto-activate#

The finish-auto-activate endpoint is given in the finishActivationUrl above. It is a JSON endpoint and takes a POST request with a body of the following parameters.

Example#

Request:

POST /authn/anonymous/encap1/finish-auto-activate HTTP/1.1
Host: login.example.com
Content-Type: application/json
Accept: application/json

{
  "activationToken" : "3E2GiWTU7oY9PdjNWsrxsQB2vTfAR3l8",
  "verifier" : "DMCA12-BBDK442-j4mm22763",
  "alias" : "Compay ABC App",
  "formFactor" : "phone",
  "phoneNumber" : "+467012345678",
  "deviceExpiresAt" : "2020-02-02T12:00:00.00Z"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

Example without optional parameters#

Request:

POST /authn/anonymous/encap1/finish-auto-activate HTTP/1.1
Host: login.example.com
Content-Type: application/json
Accept: application/json

{
  "activationToken" : "3E2GiWTU7oY9PdjNWsrxsQB2vTfAR3l8",
  "verifier" : "DMCA12-BBDK442-j4mm22763"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{}