Invite device clients

If you’re providing device-based licenses, you can create new device clients by invitation using the 10Duke Identity Management REST API. The invitation associates the new device client with an organization and adds it to the specified device client groups to allow access to licenses.

From the 10Duke Enterprise point of view, a device client is an OAuth client application that runs on a specific device (hardware) and authenticates itself with a client ID (OAuth client_id) and client secret using the OAuth client credentials grant flow to get an access token.

If the invitation is used on a device that has already been registered in the system as a device client, the device client authenticates itself to get an access token, and accepting the invitation just adds the device client to the device client groups.

If needed, you can allow an invitation to be used by existing device clients only, or even restrict an invitation to a specific device client.

Before you start

• Connect the client application that will be running on the device to 10Duke Enterprise with the OAuth client credentials grant flow.

• To allow the invited device clients to consume licenses and access your software, at least one device client group must be set up for the organization using the Identity Management REST API, and the group must be authorized to access licenses in the organization’s entitlements using the 10Duke Entitlement Management REST API.

Invitation flow for a device client

Invite a device client to a device client group as follows:

1. An invitation is created that invites the device to one or more device client groups. This is typically done by the administrator of the customer organization that owns the device.

   For example, an invitation can be created and sent through 10Duke Enterprise by email to the device administrator, who needs to accept the invitation on the device where your software application is running. The invitation recipient doesn’t need to be a registered user in 10Duke Enterprise.

   The invitation includes an invitation token, which authorizes the invitation recipient to access the invitation. This is usually provided in the invitation email as part of a URL, but you can also include it as a text string.

2. The device client (your client application running on the device) handles the invitation.

   When the invitation recipient clicks the link in the email, open a welcome window in the client application where the recipient accepts the invitation. The application needs to have a custom URL scheme implemented to handle this.

   Optionally, you can allow the recipient to manually enter the token in the client application.

   You can also allow the invitation recipient to change the name of the device client when they’re accepting the invitation.

   If the device client has already been registered to 10Duke Enterprise, at this point the client application authenticates itself and gets an access token.

3. The client application sends a request to accept the invitation to 10Duke Enterprise.

   The request must include the invitation token. If the device client was already registered, also include the access token to make an authorized request.

   With a new device, 10Duke Enterprise now creates a new OAuth device client in the system and generates a client secret for it. With both a new or existing device client, 10Duke Enterprise adds the device client to the requested device client groups.

   For a new device client, 10Duke Enterprise returns the client details. From the response, your client application must store the unique ID of the client (id), and the client ID (clientId, the OAuth client_id) and client secret (clientSecret, the OAuth client_secret) needed for authentication.

Next, the (new or existing) device client can authenticate itself to 10Duke Enterprise to get an access token, and start consuming the organization licenses that the invitation’s device client groups are authorized to use.

API operations

The following 10Duke Identity Management REST API operations can be used in the above process. There may also be alternative operations you can use, depending on your use case.

Next steps

• The content of the device client invitation email is defined by the email template set up for this in your 10Duke Enterprise deployment. Contact the 10Duke Integration Support team about any customizations you need.

• Implement license consumption for the client application.