Set Up Trusted Registration

One security concern with setting up PushAuth is registering clients. Without the concept of trusted registration, anybody could register their device under a given user. Trusted registration is the process by which the app asserts that a new mobile SDK client registration for a particular user is authorized. For more information on trusted device registration, read our blog post on the topic.

When our mobile SDKs initialize for the first time on a new device or newly installed application, one of the first tasks is to register a new client with our backend systems. This process establishes the existence of the new client by assigning a unique identifier and enables the client to begin interacting with our system.

The current method employed to accomplish trusted registration is via webhook. This registration process follows these steps:

1. As part of the SDK initialization, the challenge parameter passes a string value to be used in verification by the webhook endpoint.
2. UnifyID backend receives the request to register a client and passes the payload along to the provided webhook target URL.
3. Your webhook endpoint validates the basic auth header, user string, and challenge string to return an appropriate response.
4. If the endpoint returns 200 as the status code, the registration request will be approved. Otherwise, it will be denied.

For an example of a server-side endpoint that does the above, check out our sample project on GitHub.

Setting up Trusted Registration

The values used in the trusted registration process can be configured on the UnifyID Developer Dashboard.

Add to Dashboard

Visit your project settings on the dashboard, paste the target url, and click “Add”:

The target URL must use the https scheme.

Doing this will require trusted registration for your project. This also sets username and password strings for use in basic authentication for the webhook requests. The username value, “unifyid,” cannot be changed. The password is a random string and can be rotated in case it becomes compromised.

To edit the target url value, rotate the password, or disable trusted registration, click “Edit”:

If you choose to disable trusted registration, uncheck the box next to “Webhook Enabled” and click “Update”:

At any time you can choose to re-enable trusted registration by clicking “Edit” and ensuring the “Webhook Enabled” box is checked. The value previously set for the target url will still be populated, but you can update it if necessary.

Authorizing Client Registration

Once your project has trusted registration configured, you will need a method for verifying client registration requests. This decision involves the value used in the challenge parameter.

You also need a webhook endpoint able to serve requests from our backend and provide verification logic of the username, password, user and challenge values.

Register a Device Using Webhook Trusted Registration

This API is used for verification of device registration. The path will be that of your endpoint that handles the verification logic for client registration requests.

POST https://example.com/webhook/endpoint

Request Body

Request body format: application/json.

Name	Type	Description
user	string	The id of the user for which the device is being registered.
challenge	string	The string used for verification of the user attempting to register a device.

Response

200 Verification of the user and challenge values succeeded.

400 A badRequest type error may be returned when verification fails, or if there are missing or invalid parameters.