10Duke Standby API

The 10Duke Standby API is an optional, standby service that complements 10Duke Enterprise.

The Standby API can be enabled at times when there is an interruption or outage of the 10Duke Enterprise service.

Once enabled, the Standby API accepts licensing requests from authenticated users and issues license tokens based on the information in the requests.

The Standby API signs the issued license tokens with a key-pair specific to the API of your company. The Standby API uses a public key different from the one used by your 10Duke Enterprise service. The public key is accessible via an endpoint on the API.

Supported functionality

The Standby API enables your customers’ applications to maintain access to valid licenses during an outage.

It issues licenses to any authenticated user for any licensed item requested via the /authz/.jwt endpoint. Both HTTP GET and POST requests are supported.

The Standby API echos back any details included in the request, such as the hardware IDs, version information and license IDs.

The Standby API responds to licensing requests with JSON Web Token (JWT) format responses. These tokens grant license leases for eight hours, after which the application can request a new lease. The new lease request can be a new consumption or a renewal.

The tokens can be released, although this is supported for compatibility with existing code flows in your application and has no semantic meaning on the API.

Limitations

The Standby API cannot be used to login, manage entitlements, sign up new users, or issue new licenses.

Note: Although no new licenses are generated, leases are granted for any requested licensed items.
The seat counts or usage counts available for the requested licensed items are not checked. This means that all seat counts, use counts, and use time counts are treated as infinite.
Aggregated licensed items are not supported. The Standby API does not have any configuration defining the parent-child relationships between licensed items. Any licensed item requested generates a valid license token in the response but each of these has separate, unique license IDs in their lic claims.
JSON or text format responses are not supported.

Signing up for the Standby API

Ask your 10Duke Project Manager about adding the Standby API to your 10Duke products.

Once the Standby API has been initialized for you, you will be provided with an API key to use in management requests.

API base URL

The API base path for the Licensing API and Management API:

https://<your id as supplied by 10Duke>.api.standby.10duke.com

Authorization

Licensing API

A request to the Licensing API endpoints can be authorized with one of the two supported authorization schemes: IDToken or 10DukeKeyHash.

IDToken Scheme

Requests are authorized by an Open ID Connect (OIDC) IDToken generated from the associated 10Duke Enterprise instance.

The IDToken should be provided in the authorization header for requests to /authz/.jwt and .well-known/jwks.json.

Authorization: IdToken <idtoken_jwt>

The IDTokens remain valid for up to 24 hours after their expiration, to cover the duration of any expected outage.

10DukeKeyHash Scheme

Requests are authorized by the SHA256 hash of the public key used by your 10Duke Enterprise deployment for signing license tokens and IDTokens.

Authorization: 10DukeKeyHash <hash>

The hash is calculated by converting the public key to PEM format and then generating the SHA256 hash of the PEM data.

Management API

API requests to the Management API endpoints must be authorized using the API key provided to you, the vendor, by 10Duke when you sign up for the Standby API. The API call documentation will refer to the API key by <management_api_key>.

API Documentation

The following endpoints are available for the Standby API.

Management API

Enable the API

[PATCH, POST, PUT] /enabled

This is a management API endpoint provided for you to enable the API during an outage, incident, or maintenance window. PATCH, POST, and PUT can all be used for enabling the API, there is no difference in their semantics.

Once this endpoint has been called, the API is switched from a dormant state to an active state and calls to /authz/.jwt and .well-known/jwks.json are processed. It may take up to 5 minutes for the change in state to take effect for all clients.

This endpoint requires authorization using your management API key and a custom header.

10Duke-ApiKey: <management_api_key>

Disable the API

[GET, PATCH, POST, PUT] /disabled

This is a management API endpoint provided for you to disable the API after an outage, incident, or maintenance window has finished.

Once this endpoint has been called, the API is switched from an active state to a dormant state and calls to /authz/.jwt and .well-known/jwks.json are rejected with a 403 - Forbidden HTTP status code.

This endpoint requires authorization using your management API key and a custom header.

10Duke-ApiKey: <management_api_key>

Generate new license signing key

[POST] /signing-keys

This is a management API endpoint provided for you to generate a new license signing key. The new key will immediately become the default license signing key used by the Standby API to sign license JWTs. The previous signing keys remain active—see the mechanism to specify the signing key.

For the new license signing key, the following certificates are generated by the endpoint:

an x.509 certificate
a root (or CA) certificate

This endpoint requires authorization using your management API key and a custom header.

10Duke-ApiKey: <management_api_key>

Licensing API

Get the JWT signing public key(s)

[GET] /.well-known/jwks.json

The response from this endpoint follows the JSON Web Key (JWK) specification.

The endpoint provides the current and any previous public keys used for signing license tokens issued by the API.

This endpoint requires authorization using an Authorization header holding an OIDC IDToken from the associated 10Duke Enterprise service.

Authorization: IdToken <idtoken_jwt> or Authorization: 10DukeKeyHash <hash>

Consume / renew / release licenses

[GET, POST] /authz/.jwt

This is the main endpoint for consuming, renewing, or releasing licenses.

The endpoint accepts the same query string parameters and returns the same response format as the /authz/.jwt endpoint for 10Duke Enterprise.

This endpoint requires authorization using an Authorization header holding an OIDC IDToken from the associated 10Duke Enterprise service.

Authorization: IdToken <idtoken_jwt> or Authorization: 10DukeKeyHash <hash>

Specifying the license signing key

If the application has the key id for the license signing key generated by the management API endpoint, it can be provided as an optional header.

10Duke-SigningKeyId: <keyId>

If the application is enforcing Authenticity using the x.509 certificates provided by the management API, we recommend providing the key id for the signing key associated with the embedded certificate in the requests.

If the header is not specified, the default (most recently generated) license signing key is used.

Check the status of the API

[GET] /enabled

This endpoint returns true or false based on whether or not the Standby API is currently enabled.

[GET] /disabled

This endpoint returns true or false based on whether or not the Standby API is currently disabled.

These endpoints require authorization using an Authorization header holding an OIDC IDToken from the associated 10Duke Enterprise service.

Authorization: IdToken <idtoken_jwt> or Authorization: 10DukeKeyHash <hash>

Application flow for using the Standby API

Under normal circumstances the Standby API is expected to be inactive and the application(s) use the 10Duke Enterprise service.

If there is an outage of 10Duke Enterprise and it is deemed to be preferable to activate the Standby API, the first step is to enable the Standby API using the Enable endpoint.

Within the application code, the licensing API access will need to detect that the main 10Duke Enterprise service is unavailable and attempt to use the Standby API.

To allow this, the application requires a configuration with the URLs for both services and the logic to switch between them implemented.

Upon encountering failures at the main 10Duke Enterprise service, for example repeated timeouts or DNS failures, the application should switch the licensing client to use the Standby API URL for /authz calls, using the most recently obtained IDToken from the main 10Duke Enterprise service as authorization. The application can call the GET /enabled endpoint to check if the Standby API has been enabled before starting to use the Standby API.

The application should access the /.well-known/jwks.json endpoint of the Standby API, using the same IDToken as authorization, to download the public key that is used for signing any license tokens generated by the API.

The application is responsible for renewing and releasing these license tokens as per normal. This means that any existing logic for renewal or release can be executed using the modified license client.

The application is also responsible for transitioning back to the main 10Duke Enterprise service, once it is restored and becomes available again.

Examples for transition

Two example strategies for managing the transition are presented below. Which is more appropriate will depend on usability and latency constraints for the application.

Example 1

The application attempts any checkout, renewal, or release with the main 10Duke Enterprise service.
The application fails over to the Standby API after a set number of attempts.

Example 2

After the first confirmed failure (following the set number of retry attempts), the application checks the status of the Standby API.
If the Standby API has been enabled, the application switches to the Standby API.
The application continues to use the Standby API until it also fails (that is, the GET /enabled endpoint shows the API to be disabled or it begins returning 403 - Forbidden).
The application attempts to use the main 10Duke Enterprise service.

Security

Integrity

The integrity of license tokens received from the Standby API can be verified by using the public key (identified in the JWT header) to verify the JSON Web Signature (JWS) in the JWT.

The JWS ensures the integrity of the data in the JWT payload (the license token claims).

Authenticity

In order for the application to verify that a license token came from the Standby API, the public key(s) used to sign the license token(s) are available from the /.well-known/jwks.json endpoint of the Standby API.

If an attacker could be in control of the machine that the client application is executing on, we recommend taking further steps to ensure the authenticity of the received tokens and JWKs.

To support this, the Standby API provides x.509 certificates for license signing keys. When a new license signing key is generated, a new root key is generated as well as new x.509 certificates for the root key and the generated license signing key. The new root certificate is returned via the API, along with the key id of the new license signing key.

You can verify that the signature of the JWT was generated by the Standby API as follows:

Embed the generated root certificate in the client application as part of the binary, not distributed as a separate file.
When the client application receives a license token JWT from the Standby API, make sure that the client application retrieves the set of JWKs (from the /.well-known/jwks.json and identifies the JWK for the public key used to sign the JWT. The specific public key is identified by the kid claim in the JWT header.
Use the root certificate to verify that the certificate chain is provided in the x5c claim of JWK.
Check that the license signing key certificate (the first entry in the x5c claim) public key modulus matches the modulus of the public key (the n claim of the JWK).

If these checks pass, the the signature of the JWT was generated by the Standby API, ensuring the authenticity of the license token JWT.

Validity period of x.509 certificate and application life cycle

x.509 certificates are valid for a period of time that is defined by the start and end date encoded into the certificate.

The Standby API sets the validity period for any license signing key to five years from the time they were generated.

This means that after five years, the certificate expires and becomes invalid. Once the certificate has expired, verifying the certificate chain will fail when using the default configuration for most x.509 libraries—an error condition or exception is expected. This means that the application version is no longer able to obtain and verify license tokens from the Standby API.

To manage the expiration of certificates, we recommended that for each new version of the client application (or as a minimum, once a year) a new license signing key is generated and the associated root certificate is used in the new version of the client application.

10 Duke Enterprise Standby API certificate validity

Multiple license signing keys

Generating a new license signing key means that the new license signing key becomes the default license signing key used by the Standby API.

If older versions of the client application (with old root certificates, and therefore, older license signing keys) are still installed and in use, they cannot verify the license tokens signed with the new license signing key.

For these applications to continue working as expected, they must be able to instruct the Standby API to use the license signing key that they expect.

This is achieved by providing the key id as an optional header in the API request.

Multiple versions with different license signing keys can remain active within the install base due to this mechanism.