Authorize API requests using an ID token

If identity-based licensing is in use, you can authorize API requests sent on behalf of a license consumer of type person (user) or device by using a standard OpenID Connect (OIDC) ID token granted by an external identity provider.

This authorization can be used for requests to the 10Duke Scale License Checkout API: for handling the license checkout flow in both enforced and metered consumption mode, and to retrieve information on the licenses that the license consumer has access to.

The ID token is a JSON Web Token (JWT) that contains the details of the authenticated license consumer in a standard format. Your client application includes the ID token in the API request to authorize access to the API for the license consumer.

The scope of the authorization is limited to the licenses that the license consumer can access. No separate permissions are used.

To help with the implementation, you can use the 10Duke Scale SDKs and clients that provide support for sending authorized requests that carry the ID token.

For background, see how to choose the right authorization method for your use case.

Before you start

• To get the ID token, the implementation for identity-based licensing must be in place. Your application must be able to authenticate the license consumer with an identity provider to get the ID token, and the license consumer must have an OIDC user ID defined in 10Duke Scale.

• The license consumer must have access to the license. For example, in the case of a B2B license, make sure the license consumer has been granted access to the B2B customer’s licenses.

• Before using the ID token in an API request, your application needs to check that it’s still valid in the ID token’s exp field, and refresh the ID token if needed.

ID token content

An ID token consists of three parts: the header and the token payload which both contain claims, and the signature produced by encrypting the header and the payload. The parts are separated by a . character.

ID token header

This example shows the header in an ID token:

{
  "alg": "RS256"
  "kid": "KEY_ID"
}

• alg: The algorithm used. Only RS256 is supported.

• kid: The key ID that identifies the private key that was used to sign the ID token.

ID token payload

This example shows the token payload in an ID token:

{
  "iss": "TOKEN_ISSUER",
  "iat": 1693916792,
  "exp": 1693999792,
  "sub": "SUBJECT",
  "aud": "AUDIENCES"
  "email": "firstname.lastname@company.com"
}

The timestamps are in seconds since the epoch, Jan 1st 1970 at 00:00:00.

See details on these standard OIDC claims in the OpenID Connect specification.

Required claims

• iss: The OIDC issuer (the identity provider’s token issuer).

• iat: The time when the ID token was issued.

• exp: The time when the ID token expires.

• sub: The OIDC user ID, which is mapped to the connected identity ID of the 10Duke Scale license consumer.

• aud: The audiences that this ID token is intended for.

  This claim must contain the OAuth 2.0 client_id of the relying party as an audience value. It may also contain identifiers for other audiences. In the general case, the aud value is an array of case-sensitive strings.

Optional claims

• email: The email address of the subject of the API call.

  The email address is not used for matching the license consumer, but can be added for tracking and audit purposes.

ID token signature

The identity provider has signed the ID token using their private key.

An example of a signed ID token:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJhenAiOiIxMjM0OTg3ODE5MjAwLmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29tIiwiYXVkIjoiMTIzNDk4NzgxOTIwMC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbSIsInN1YiI6IjEwNzY5MTUwMzUwMDA2MTUwNzE1MTEzMDgyMzY3IiwiYXRfaGFzaCI6IkhLNkVfUDZEaDhZOTNtUk50c0RCMVEiLCJoZCI6ImV4YW1wbGUuY29tIiwiZW1haWwiOiJqc21pdGhAZXhhbXBsZS5jb20iLCJlbWFpbF92ZXJpZmllZCI6InRydWUiLCJpYXQiOjEzNTM2MDEwMjYsImV4cCI6MTM1MzYwNDkyNiwibm9uY2UiOiIwMzk0ODUyLTMxOTA0ODUtMjQ5MDM1OCJ9.kIEjrJdT0iTvsLVsplYmrT79jyggOlzuMJgETyQFbd9i3wp95jit172uKIHpgfxUqdknogbqy_Fd4JTWIahhsXOSWB4a_e2n_3ag5pDz3yXpj13iIOG4uMvWn1zV1D_Jmhfd-DhWoQB_tXv5dHUXVNhsrULWtLMGFwl1xG2XprtnoZaJ5VHQjOqqinKb7Yv2N_M2kQTVu9S-F4xXGV7hnQKOy9mVVI5sSxy9Vc8mGR7zteH83jveohlJiXbgMAVq39L92rfsw0H_34Bw44gym_XWCQoZomFAYtky6rRchBue0Qu2NCFLpAAVkrye_gshwdBvNiL7R4HQtscV8CQruw

Provide ID token in API request

To make an authorized API request, include an authorization header that specifies the ID token.

The format of the authorization header:

Authorization: IdToken <ID token>

An example request with an authorization header containing a signed token:

curl -H "Authorization: IdToken eyJhbGciOiJSUzI1NiIsInR5cCI6..." /
     -H "Content-Type: application/json" /
     -X POST --data '[{"productName":"string","qty":1,"qtyDimension":"SEATS"}]' /
      https://<API_BASE_URL>/licensing/actions/checkout

See more

• Choosing the right authorization method for your use case

• API error handling