Register a Device for Validation with Push

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

Authenticate to the ActivID Appliance using the spl-api user.
Create a User in the ActivID Appliance.
Create a device of type DT_TDSV4 in the PENDING state.
Create a Device registration request for the device type DT_TDSV4 and authentication policy AT_SMK.
Retrieve the corresponding registration information from the ActivID Appliance.
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 Appliance notifies the result of the registration:

On the JMS topic, if A JMS topic was configured in ActivID Appliance 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

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

For example, download the ActivID Appliance SSL certificate from the ActivID Console Key Stores menu and copy it to a local folder.

Then, run the following keytool command to import the certificate:

Copy

keytool -import -file <file path>/RootCA.cer -alias <serverName> -keystore <request-device--registration-sample_path>/config/truststore.jks -storepass <mypassword> -noprompt

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

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 Appliance in the format https://<ActivID Appliance hostname>:443
server.domain	The name (ID) of the domain
provisioning.url	The provisioning URL in the format: <ActivID Appliance 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.

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

Open a terminal on the <SAMPLES Path>\scripts folder.
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
```
Note: The provisioning message is also available in the <SAMPLES Path>\scripts\request.txt file.

Register the Service with HID Approve

Start the HID Approve application.
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 Appliance 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 Appliance.

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 Appliance 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 Appliance 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 Appliance 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