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

Fig. 179 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. Curity redirects back to the app using the configured url for the app with the app scheme (example: myapp://activate). In the redirect Curity will pass an activation code to be sent to Encap, an activation token to be used to finish activation with Curity, 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 Curity.
  7. Upon successful activation Curity returns 200 OK.

Endpoint overview

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

SubPath Method Type Description
start-auto-activate GET Redirect endpoint This endpoint will not show any data but redirect to authentication if needed
finish-auto-activate POST Json endpoint This endpoint takes a JSON message in the post body

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 Curity since it does not know the verifier.

Parameter Value
verifier Random string generated by the app.

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.

Parameter Value
activationCode The activation code that should be sent to Encap using the mobile SDK
activationToken A one time token to be used when finishing activation against Curity
finishActivationUrl A URL encoded URL that describes where to finish the activation against Curity

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.

Parameter Value | Required
activationToken The parameter given in redirect back from the previous request | mandatory
verifier The verifier that was used as input to the previous request | mandatory
alias An alias given to the newly activated device. Example: Company ABC App | optional
formFactor phone, tablet or other will produce icons when selecting devices | optional
phoneNumber Can be used to identiy the device if users have many devices | optional
deviceExpiresAt A UTC timestamp to be set if this device only is allowed for a limited period.| optional Example: 2017-02-02T11:07:00.00Z. |

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

{}