Implement identity-based licensing

You can implement identity-based licensing for 10Duke Scale by using a standards-based OpenID Connect (OIDC) identity provider.

To summarize the process:

1. Your licensed application handles the process of authenticating the license consumer (typically a user) with the external identity provider. Your application delegates the authentication to the identity provider, which typically also provides the login page for the user.

2. After a successful authentication, the identity provider grants and signs an ID token and returns it to your application.

3. When requesting license consumption for the license consumer through the 10Duke Scale License Checkout API, your application provides the signed ID token to 10Duke Scale.

4. 10Duke Scale verifies the ID token signature, relies on the authentication done by the identity provider, and authorizes the application to access the API on behalf of the license consumer.

   The mapping between user data in the identity provider and license consumers in 10Duke Scale is based on unique OIDC user IDs. The OIDC user ID is included in the ID token, and 10Duke Scale identifies the correct license consumer based on a matching OIDC user ID in the license consumer’s details.

Typically your application would be connected to your (the vendor’s) identity provider. If your B2B customers have their own identity providers that they wish to use for authenticating their users, one option for handling this is to use chaining of identity providers, so that your application only needs to connect to one identity provider.

Step 1: Implement user login and OIDC authentication

Implement an OIDC/OAuth authentication flow between your application and the external identity provider.

OIDC/OAuth 2.0 provides a selection of authentication flows to choose from. Use the flow that is best suited for your application type. Whichever flow you choose, the key requirement is that the identity provider returns an ID token.

The following are commonly used authentication flows:

• Authorization code grant

  This flow should only be used by a confidential application, such as a web or SaaS application that runs in your (the vendor’s) own infrastructure, because it requires the ability to securely store a client secret. Your application uses a browser to interact with the user.

• Authorization code grant with Proof Key for Code Exchange (PKCE)

  This flow can be used by a public application, such as a desktop or mobile application. The PKCE extension provides a secure way to use the authorization code grant flow by relying on a request-specific code challenge instead of a client secret. Your application uses a browser to interact with the user.

• Device authorization grant

  This flow is suitable for a device application that has a limited user interface and is not capable of using a browser to interact with the user.

  The user logs in using a browser on a secondary device, for example, on their mobile device. The authentication process provides the user with a verification code, which they enter to complete the authentication.

  For example, your device could display a QR code with a URL to the login page. The user scans the code using their mobile device, which opens a web browser where the user can log in. Your device could either display the verification code to the user and have them enter the code manually on the login page, or your device could include the code as part of the URL.

To help with the implementation, you can use the 10Duke Scale SDKs and clients which provide support for implementing an authentication flow and, for example, with the PKCE flow, for starting the default OS browser for the user login.

Which flow to choose?

Here’s a cheatsheet to help you evaluate the most appropriate flow for your application type.

UI implications

Your choice of authentication flow has some implications for how you implement the user interface for the user login.

Note, for example, the following:

• When using the authorization code grant flow with a desktop or mobile application, the current recommendation is that you use a standard browser (such as the default OS browser) instead of an embedded (in-app) browser.

  Major third-party identity providers, such as Google, often have their own policies that limit the use of embedded browsers.

• When using the device authorization grant flow, the user typically uses another device that provides the login page.

Refresh the ID token

The ID token granted by the identity provider is valid for a certain period of time, the length of which varies by identity provider. Before using the ID token for API authorization, your application should check that it’s still valid (in the ID token’s exp field).

If the ID token has expired, your application can refresh the ID token with the identity provider without any interaction needed from the user. The refresh in practice returns a new ID token with a new validity period. Refreshing the ID token is done using a refresh token, which the identity provider always returns together with an ID token.

Your application can refresh the ID token until the refresh token expires. After this, the user needs to log in again. See the identity provider’s documentation for information on token expiration and refreshing the ID token.

The 10Duke Scale SDKs and clients provide an implementation for handling the refresh.

Step 2: Implement API authorization using ID token

After receiving the ID token from the identity provider, your application needs to pass it to 10Duke Scale. The application does this by including it in the authorization header in each API request to the License Checkout API. See how to authorize API requests using an ID token.

Store the identity provider’s public key

The identity provider signs the ID token using the identity provider’s private key. The ID token’s kid field identifies the private key that was used.

When your application provides the ID token in an API request to 10Duke Scale, 10Duke Scale needs to be able to verify the ID token’s signature using the identity provider’s public key.

For 10Duke Scale to have access to the public key, store it in the API authorization keys in the 10Duke Scale UI console. See the identity provider’s documentation for information on where to find the public key.

If more than one identity provider is being used for user authentication, 10Duke Scale needs the public key of each identity provider that it connects to. If your application only connects to one identity provider, only that identity provider’s public key is needed, even if it delegates the authentication forward—the ID token given to the client application is signed by the first identity provider in the chain.

Step 3: Map external users to 10Duke Scale license consumers

To enable license consumption for the authenticated users, the users in the identity provider must exist as license consumers in 10Duke Scale, mapped to each other using an OIDC user ID (also referred to as the “connected identity ID” in 10Duke Scale).

Even if a user was successfully authenticated with the identity provider, they won’t be able to consume the requested license if no matching license consumer is found in 10Duke Scale with the OIDC user ID given in the ID token.

You can create license consumers and define OIDC user IDs for them manually in the UI console, or do this automatically, for example, from your CRM or e-commerce system, through an event-driven integration or the 10Duke Scale License Management API.

See how to create license consumers in 10Duke Scale.