Invite device clients

If you’re providing device-based licenses, new device clients are created into 10Duke Enterprise by invitation.

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: The invitation is created

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

Step 2: The device client handles the invitation

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

When the invitation recipient clicks the link in the email, this opens a 10Duke Enterprise page in a browser that provides instructions for the invitation recipient on how to proceed and connect the device. When the recipient clicks the link on the page to connect the device, open a welcome window in the client application where the recipient accepts the invitation. The application needs to have a custom URL scheme registered in the operating system to handle this.

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

You can 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 to 10Duke Enterprise and gets an access token.

Step 3: The device client accepts 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.