Register a Device for Validation with Push

The sample to register a user's device for push-based validation integrates the ActivID AS OAuth/OpenID Connect API and ActivID AS SCIM API to:

  1. Authenticate to the ActivID AS using the spl-api user.

  2. Create a User in the ActivID AS.

  3. Create a device of type DT_TDSV4 in the PENDING state.

  4. Create a Device registration request for the device type DT_TDSV4 and authentication policy AT_SMK.

  5. Retrieve the corresponding registration information from the ActivID AS.

  6. Display the registration information required for manual registration or displays the corresponding QR code to be scanned with the HID Approve application.

You can then launch the HID Approve application and scan the QR code or manually enter 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.
Prerequisites: Download and install the HID Approve application.

Configure the Sample

  1. 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.

  2. Edit the <SAMPLES Path>\config\deviceProvision.properties configuration file by updating the properties with information from your deployment.

    Property Description
    server.url The URL of your ActivID AS in the format
    https://<ActivID AS hostname>:443
    server.domain The name (ID) of the domain
    provisioning.url The provisioning URL in the format:
    <ActivID AS hostname>:443/<Domain Name>

    Do not include the 'https://' prefix.
    direct.user.code The ID of the OpenID client
    direct.user.password The OpenID client password (secret)

    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 Registration-listener Sample where the URL is http://<server_name>:<server_port>/RegistrationListener/CB/status.

  3. Edit the <SAMPLES Path>\scripts\ script for your operating system by updating the parameters with the path and password of the truststore:

    • RequestDeviceRegistration.bat for Microsoft Windows

    • RequestDeviceRegistration.sh for Linux

Run the Sample

  1. Open a terminal on the <SAMPLES Path>\scripts folder.

  2. Run the sample for a user of your choice (in this example, myuser) using the following command:

    Copy

    On Microsoft Windows systems

    RequestDeviceRegistration.bat -u myuser -showqrcode
    Copy

    On Linux systems

    RequestDeviceRegistration.sh -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):

        • User ID

        • Invite Code

        • Provider URL

      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:

    Note: The provisioning message is also available in the <SAMPLES Path>\scripts\request.txt file.

Register the Service with HID Approve

  1. Start the HID Approve application.

  2. Enter either the parameters for manual activation or directly scan the above QR code.

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:

Copy
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

Copy

Application searches for user myTestUser1 and, if not found, will create it.

The access_token value is used on Authorization: Bearer header so that ActivID AS authorizes this call.

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":[]}
Copy

As the user is not found (not already created as per “totalResults”:0 in the response), it is created

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}
Copy

Creation of the device of type DT_TDS_V4 (PENDING state)

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"}}
Copy

Binding of the created device (13275) to the user myTestUser1

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"}}
Copy

Creation of the device issuance request:

  • Device of type DT_TDSV4
  • For authentication type AT_SMK
  • For user 13274 (userid of myTestUser1)
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:

Copy
{"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

Device Registration for Offline Activation

The following sample illustrates the provisioning of a device for offline activation where scim.example.com is a placeholder for the ActivID AS server host name.

Copy

Sample Request for Offline Activation (Time-Based)

[POST] /scim/{tenant}/v2/Device/Provision
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Provision"],
	"deviceType": "DT_APPR_OT",
	"owner": {
		"value": "11066"
	},
	"attributes": [{
		"name": "AUTH_TYPE",
		"value": "AT_EMPOTP",
		"readOnly": false
		}
	]
}

Copy

Sample Response for Offline Activation (Time-Based)

HTTP/1.1 201 Created
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Provision"],
	"id": "1",
	"meta":    {
		"resourceType": "Provision",
		"created": "2021-09-16T13:20:51Z",
		"location": "https://[base-server-url]/scim/tenant/v2/Device/Provision/1",
		"version": "1"
	},
	"deviceType": "DT_APPR_OT",
	"status":    {
		"status": "PROCESSED",
		"active": false
	},
	"owner":    {
		"type": "User",
		"display": "aaaa1000000",
		"value": "11066",
		"$ref": "https://[base-server-url]/scim/tenant/v2/Users/11066"
	},
	"attributes": [   {
		"name": "PROV_MSG",
		"type": "string",
		"value": "otpauth://totp/HID%20Global:aaaa1000000?secret=2J4DYTYSNHUCGCUY3QZ2YI4UCDQXFSGE&issuer=HID%20Global&algorithm=SHA1&digits=6&period=30&pinmode=pin&lockpolicy=delay&initialdelay=2&maxcountervalue=6",
		"readOnly": false
	}]
}
Copy

Sample Request for Offline Activation (Event-Based)

[POST] /scim/{tenant}/v2/Device/Provision
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Provision"],
	"deviceType": "DT_APPR_OE",
	"owner": {
		"value": "11066"
	},
	"attributes": [{
		"name": "AUTH_TYPE",
		"value": "AT_EMPOTP",
		"readOnly": false
		}
	]
}
Copy

Sample Response for Offline Activation (Event-Based)

HTTP/1.1 201 Created
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Provision"],
	"id": "1",
	"meta":    {
		"resourceType": "Provision",
		"created": "2021-09-16T13:09:29Z",
		"location": "https://[base-server-url]/scim/tenant/v2/Device/Provision/1",
		"version": "1"
	},
	"deviceType": "DT_APPR_OE",
	"status":    {
		"status": "PROCESSED",
		"active": false
	},
	"owner":    {
		"type": "User",
		"display": "aaaa1000000",
		"value": "11066",
		"$ref": "https://[base-server-url]/scim/tenant/v2/Users/11066"
	},
	"attributes": [   {
		"name": "PROV_MSG",
		"type": "string",
		"value": "otpauth://hotp/HID%20Global:aaaa1000000?secret=XYHJUYR3Y3GI7BTHEDCNOB4CSDNXFAJE&issuer=HID%20Global&algorithm=SHA1&digits=6&counter=1474460590&pinmode=pin&lockpolicy=delay&initialdelay=2&maxcountervalue=6",
		"readOnly": false
	}]
}

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:

Copy
"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).

Note: The offline Key Secret activation method is only available for time-based HID Approve Offline Soft Tokens where the device type uses the following default configuration:

  • OTP type - TOTP

  • Hashing algorithm - SHA1

  • OTP length - 6 digits

  • Timestep - 30 seconds

For further details, see Configure HID Approve Offline Soft Tokens.

Next step:

Validate an Operation with Push