Request-device-registration Samples

This sample uses the ActivID OAuth/OpenID Connect API and ActivID SCIM API to request a service registration for a user:

• Authenticates to ActivID AS using the spl-api user.

• Creates a User in ActivID AS.

• Creates a device of type DT_TDSV4 in PENDING state.

• Creates a Device registration request on ActivID AS for device type DT_TDSV4 and authentication policy AT_SMK.

• Retrieves the corresponding registration information from ActivID AS.

• Displays registration information required for Manual registration or displays the corresponding QR code to be scanned by the HID Approve application.

The user then uses the mobile device to scan the QR code or manually enters the registration information to start the service registration.

ActivID AS notifies the result of the registration:

• On the JMS topic, if A JMS topic was configured in ActivID AS to post messages to a Message Queue.

• Using the HTTP Callback URL, if this URL was configured in the sample.

Install the Sample

1. Unzip the Push_Authentication_Sample\Request-device-registration-samples.zip file to the destination of your choice (for example, a request-device-registration-sample folder).



2. Create the truststore file in the config subfolder using the Java keytool located on your client machine in <JAVA_HOME>/bin.

   • For JBoss, retrieve <JBOSS_HOME>/ssl-server.truststore and copy it to your client system under request-device-registration-sample\config
   • For WebSphere:
     • Retrieve your server SSL certificate (as described in the ActivID AS installation guide).

     • Create the truststore file using Java keytool

       Copy

       keytool -import -file ssl-server.cer -alias <serverName> -keystore truststore.jks -storepass <mypassword> -noprompt

     Where <mypassword> is the password you set to protect the certificate.

3. Edit the device-registration-sample\config\deviceProvision.properties configuration file and update with information from your deployment.

   You can configure a callback URL and a client notification token so that the result of the device activation is automatically posted to an HTTP callback.

   See section Registration-listener Sample where the URL is http://<server_name>:<server_port>/RegistrationListener/CB/status.

4. Go to device-registration-sample\script directory and edit the RequestDeviceRegistration.bat and RequestDeviceRegistration.sh files to configure the path and password of the truststore created earlier.

Run the device-registration Sample

1. Run the sample for a user of your choice (in this example, myuser).

   In the scripts subfolder, run the following command:

   Copy

   RequestDeviceRegistration.bat –u myuser -showqrcode

   The output displays:

   • Registration information allowing mobile device registration.

   • Information for manual activation (to be entered manually in the HID Approve application).



If the -showqrcode option is present in command line, the sample will launch the default browser and display a page with the registration information as a QR code:



2. Proceed with the registration on the mobile device:

   • Start the HID Approve application.
   • Enter either the parameters for manual activation or directly scan the above QR code.

The Registration process starts.

REST API Request Samples for Device Registration

This sample is delivered as Java source code and binaries. This section describes how to give the equivalent functionality using ActivID AS REST APIs requests.

The multi-step HID Approve activation workflow sends an invitation to a user to register their device until authentication credentials are created asynchronously in ActivID AS.

The following sample illustrates the authentication of the application using the spl-api direct user (using the ActivID OpenID Connect REST API) where myserver is a placeholder for the ActivID AS server host name:

POST https://myserver:8445/idp/ONLINEBANK/authn/token
Body
        grant_type=client_credentials&client_id=spl-api&client_secret=password01
 
Response
        header
            {Cache-Control=no-store, Connection=keep-alive, Content-Length=141, Content-Type=application/json;charset=UTF-8, Date=Thu, 30 Nov 2017 10:50:38 GMT, Pragma=no-cache, Server=JBoss-EAP/7, X-Powered-By=Undertow/1}
        content
{"access_token":"RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay","token_type":"Bearer","expires_in":1576800}

The application gets the access_token value (RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay) to be used for the subsequent calls.

Device Registration for Online Activation

POST https://myServer:8445/scim/ONLINEBANK/v2/Users/.search
 Headers:
   Authorization: Bearer RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay
   Content-Type: application/scim+json
   Accept: application/scim+json
 Body:
{"schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],"filter":"externalid eq myTestUser1"}
 
Response: HTTP/1.1 200 OK
 Headers:
   Cache-Control: no-cache
   X-Powered-By: Undertow/1
   Server: JBoss-EAP/7
   Pragma: no-cache
   Date: Thu, 30 Nov 2017 10:54:26 GMT
   Connection: keep-alive
   Strict-Transport-Security: max-age=16070400; includeSubDomains
   X-Content-Type-Options: nosniff
   Transfer-Encoding: chunked
   Content-Type: application/scim+json;charset=utf-8
{"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"totalResults":0,"resources":[]}

POST https://myserver:8445/scim/ONLINEBANK/v2/Users/?excludedAttributes=urn%3Ahid%3Ascim%3Aapi%3Aidp%3A2.0%3AUserAttribute%2C%20groups%2C%20roles
 Headers:
   Authorization: Bearer RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay
   Content-Type: application/scim+json
   Accept: application/scim+json
 Body:
{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"externalId":"myTestUser1","groups":[{"value":"USG_CUST1"}]}
 
Response: HTTP/1.1 201 Created
 Headers:
   Cache-Control: no-cache
   X-Powered-By: Undertow/1
   Server: JBoss-EAP/7
   Pragma: no-cache
   Location: https://myServer:8445/scim/ONLINEBANK/v2/Users/13274
   Date: Thu, 30 Nov 2017 10:54:26 GMT
   Connection: keep-alive
   Strict-Transport-Security: max-age=16070400; includeSubDomains
   X-Content-Type-Options: nosniff
   Transfer-Encoding: chunked
   Content-Type: application/scim+json;charset=utf-8
{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"id":"13274","externalId":"myTestUser1","meta":{"resourceType":"User","created":"2017-11-30T10:54:26Z","location":"https://myServer:8445/scim/ONLINEBANK/v2/Users/13274","version":"1"},"userName":"myTestUser1","userType":"FTRESS","active":true}

POST https://myServer:8445/scim/ONLINEBANK/v2/Device
 Headers:
   Authorization: Bearer RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay
   Content-Type: application/scim+json
   Accept: application/scim+json
 Body:
{"schemas":["urn:hid:scim:api:idp:2.0:Device"],"externalId":"myTestUser1-1392877576","type":"DT_TDSV4","status":{"status":"PENDING","active":false,"expiryDate":"2019-11-30T11:54:31+0100","startDate":"2017-11-30T11:54:31+0100"}}
 
Response: HTTP/1.1 200 OK
 Headers:
   Cache-Control: no-cache
   X-Powered-By: Undertow/1
   Server: JBoss-EAP/7
   Pragma: no-cache
   Date: Thu, 30 Nov 2017 10:54:26 GMT
   Connection: keep-alive
   Strict-Transport-Security: max-age=16070400; includeSubDomains
   X-Content-Type-Options: nosniff
   Transfer-Encoding: chunked
   Content-Type: application/scim+json;charset=utf-8
{"schemas":["urn:hid:scim:api:idp:2.0:Device"],"id":"13275","externalId":"myTestUser1-1392877576","meta":{"resourceType":"Device","created":"2017-11-30T10:54:26Z","location":"https://myServer:8445/scim/ONLINEBANK/v2/Device/13275","version":"1"},"friendlyName":"","type":"DT_TDSV4","status":{"status":"PENDING","active":false,"expiryDate":"2019-11-30T10:54:31Z","startDate":"2017-11-30T10:54:31Z"}}

PUT https://myServer:8445/scim/ONLINEBANK/v2/Device/13275
 Headers:
   Authorization: Bearer RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay
   Content-Type: application/scim+json
   Accept: application/scim+json
 Body:
{"schemas":["urn:hid:scim:api:idp:2.0:Device"],"id":"13275","externalId":"myTestUser1-1392877576","meta":{"resourceType":"Device","created":"2017-11-30T11:54:26+0100","location":"https://myServer:8445/scim/ONLINEBANK/v2/Device/13275","version":"1"},"friendlyName":"","type":"DT_TDSV4","status":{"status":"PENDING","active":false,"expiryDate":"2019-11-30T11:54:31+0100","startDate":"2017-11-30T11:54:31+0100"},"owner":{"display":"myTestUser1"}}
 
Response: HTTP/1.1 200 OK
 Headers:
   Cache-Control: no-cache
   X-Powered-By: Undertow/1
   Server: JBoss-EAP/7
   Pragma: no-cache
   Date: Thu, 30 Nov 2017 10:54:26 GMT
   Connection: keep-alive
   Strict-Transport-Security: max-age=16070400; includeSubDomains
   X-Content-Type-Options: nosniff
   Transfer-Encoding: chunked
   Content-Type: application/scim+json;charset=utf-8
{"schemas":["urn:hid:scim:api:idp:2.0:Device"],"id":"13275","externalId":"myTestUser1-1392877576","meta":{"resourceType":"Device","created":"2017-11-30T10:54:26Z","location":"https://myServer:8445/scim/ONLINEBANK/v2/Device/13275","version":"1"},"type":"DT_TDSV4","status":{"status":"PENDING","active":false,"expiryDate":"2019-11-30T10:54:31Z","startDate":"2017-11-30T10:54:31Z"},"owner":{"type":"User","display":"myTestUser1","value":"13274","$ref":"https://myServer:8445/scim/ONLINEBANK/v2/Users/13274"}}

POST https://myServer:8445/scim/ONLINEBANK/v2/Device/Provision
 Headers:
   Authorization: Bearer RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay
   Content-Type: application/scim+json
   Accept: application/scim+json
 Body:
{"schemas":["urn:hid:scim:api:idp:2.0:Provision"],"deviceType":"DT_TDSV4","description":"did=13275,url=myServer:8445/ONLINEBANK,pch=CH_TDSPROV,pth=AT_TDSOOB,pct=CT_TDSOOB,pdt=DT_TDSOOB,mod=GEN,sec=","owner":{"value":"13274"},"attributes":[{"name":"AUTH_TYPE","value":"AT_SMK","readOnly":false}]}
 
Response: HTTP/1.1 201 Created
 Headers:
   Cache-Control: no-cache
   X-Powered-By: Undertow/1
   Server: JBoss-EAP/7
   Pragma: no-cache
   Location: https://myServer:8445/scim/ONLINEBANK/v2/Device/Provision/11199
   Date: Thu, 30 Nov 2017 10:54:26 GMT
   Connection: keep-alive
   Strict-Transport-Security: max-age=16070400; includeSubDomains
   X-Content-Type-Options: nosniff
   Transfer-Encoding: chunked
   Content-Type: application/scim+json;charset=utf-8
{"schemas":["urn:hid:scim:api:idp:2.0:Provision"],"id":"11199","meta":{"resourceType":"Provision","created":"2017-11-30T10:54:26Z","location":"https://myServer:8445/scim/ONLINEBANK/v2/Device/Provision/11199","version":"1"},"deviceType":"DT_TDSV4","status":{"status":"UNPROCESSED","active":false},"owner":{"type":"User","display":"myTestUser1","value":"13274","$ref":"https://myServer:8445/scim/ONLINEBANK/v2/Users/13274"},"attributes":[{"name":"PROV_MSG","type":"string","value":"{\"ver\":\"v7\",\"url\":\"myServer:8445/ONLINEBANK\",\"uid\":\"myTestUser1\",\"did\":\"13275\",\"dty\":\"DT_TDSV4\",\"pch\":\"CH_TDSPROV\",\"pth\":\"AT_TDSOOB\",\"sec\":\"\",\"pss\":\"QlVHRkVZM0lNQw==\"}","readOnly":false}]}

The response attribute PROV_MSG contains information to bootstrap the device registration:

{"ver":"v7","url":"myServer:8445/ONLINEBANK","uid":"myTestUser1","did":"13275","dty":"DT_TDSV4","pch":"CH_TDSPROV","pth":"AT_TDSOOB","sec":"","pss":"QlVHRkVZM0lNQw=="}

This information is then used to generate the QR code or the manual registration/activation information:

• User ID: myTestUser1

• Invite Code: BUGFEY3IMC

• Provider URL: myServer:8445/ONLINEBANK

The response attribute PROV_MSG contains the device registration information to be used (offline) by the mobile to create the service in the HID Approve application:

"otpauth://totp/HID%20Global:aaaa1000000?secret=2J4DYTYSNHUCGCUY3QZ2YI4UCDQXFSGE&issuer=HID%20Global&algorithm=SHA1&digits=6&period=30&pinmode=pin&lockpolicy=delay&initialdelay=2&maxcountervalue=6"

This information is then used to generate the QR code or the manual registration/activation information using the Key Secret (in the above example, 2J4DYTYSNHUCGCUY3QZ2YI4UCDQXFSGE).