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. The ID token is a JSON Web Token (JWT) that contains the details of the authenticated license consumer in a standard format.

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.

Before calling the License Checkout API, your client application authenticates the license consumer with an identity provider to get an ID token. The identity provider signs the ID token using the identity provider’s private key.

Your client application includes the ID token in the API request to authorize access to the API for the license consumer. 10Duke Scale verifies the signature of the ID token using the identity provider’s public key.

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

To help implement API authorization using ID tokens, you can use the 10Duke Scale SDKs and clients which provide support for handling the authentication flow with an identity provider to get an ID token, and 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

  • The client application must be able to run an OIDC/OAuth authentication flow with an identity provider to authenticate the license consumer and get the ID token.

  • To enable authentication, the license consumers must have an OIDC user ID specified as the connected identity ID.

  • The license consumer must be associated with a customer to have access to licenses.

  • To verify the signature of the ID tokens, 10Duke Scale needs the identity provider’s public key. See the identity provider’s documentation on where to find the public key, and see how to store the public key for 10Duke Scale.

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

Contents