Invite device clients

If you’re providing device-based licenses, we recommend that new device clients are created into 10Duke Enterprise by invitation. If needed, you can also create new device clients without invitations using the Identity Management REST API. Note that this requires you to gather information on customer devices beforehand.

Note: Support for device licensing is available from 10Duke Enterprise release 5.0.0.

The invitation associates the new device client with an organization and adds it to specified device client groups to grant access to licenses. This also associates the organization to the device client as the “owner”.

Typically, the administrator of the organization that owns the physical devices invites the device clients using the 10Duke OrgAdmin tool. However, depending on your use case and possible integrations to your other systems, you can handle the invitations using the 10Duke Identity Management REST API, or invite device clients on behalf of the customer using the 10Duke SysAdmin tool.

This article guides you how to invite device clients through API integration and how to handle the invitation at the client end.

From the 10Duke Enterprise point of view, a device client is an OAuth client application that runs on a specific device (hardware). The device client uses the OAuth client credentials grant flow to authenticate itself with a client ID (OAuth client_id) and client secret and to receive 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, and accepting the invitation just adds the device client to the specified 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

The invitation flow for inviting a device client goes as follows.

Step 1: Create the invitation

An invitation is created that invites the device to one or more device client groups.

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 that authorizes the recipient to access the invitation. This token is typically provided as part of a URL in the invitation email, but it can also be provided as a text string if required.

Step 2: Handle the device client invitation

The invitation link in the email sent to the recipient is configurable and determines how the client application is launched.

By default, clicking the link opens a 10Duke Enterprise Connect device page in the browser, providing instructions on how to proceed and connect the device. This intermediary page is used because many email clients block or restrict the custom URL schemes used to directly launch client applications from an email link. To bypass these restrictions, the user is directed to this page instead. The default page also ensures a smooth user experience, especially in cases where the client application is not yet registered to handle the URL scheme, and allows you to provide further guidance to users.

This page contains a Connect device button. If your application supports a custom URL scheme, clicking this button launches the client application and processes the invitation token. The link behind this button includes all the necessary information, such as the invitation token, allowing the application to automatically process the invitation and submit the required acceptance request upon launch.

If your application does not support a custom URL scheme, the Connect device button or any link using a custom URL scheme is not able to launch the application. In this case, you must modify the email or the Connect device page to display the invitation token as a text string. You can then provide a user interface within the application where the recipient can manually enter this token. Once the token is entered, the application makes the necessary request to accept the invitation and connects the device to 10Duke Enterprise.

If the device client has already been registered with 10Duke Enterprise, the client application authenticates itself and retrieves an access token.

Step 3: Accept the invitation

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 and an 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 and client secret needed for authentication (clientId and clientSecret, the OAuth client_id and client_secret). After this, the new device client can authenticate itself and get an access token.

The device client is now authorized to consume the organization licenses that the invitation’s groups have access to.

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. The content of the page that opens from the invitation link is also customizable.

  Contact the 10Duke Integration Support team about any customizations you need.

• Implement license consumption for the client application.