10Duke Scale C++ Client
Loading...
Searching...
No Matches
Using Identity-Based Licensing

10Duke Scale supports identity-based licensing for users: Users authenticate themselves and every operation tracks the users identity. For authentication, 10Duke Scale uses Open ID Connect (OIDC), which is an authentication framework built on OAuth 2. To use identity-based licensing, you need an OIDC-based identity provider service. If you don't have one configured, contact our sales for options.

10Duke Scale C++ client provides two types of OIDC authentication: Browser-based authentication and OAuth 2 "Device Authorization Grant" authentication. Device authentication is mostly intended for scenarios, where the device does not have browser: The user authenticates out-of-band using browser on another platform. For browser-based authentication, the client uses default OS-browser to perform the login.

In both cases, the client manages the login session automatically whenever API-method needing authorization is used:

  • If the user has not yet logged, the first API call will automatically trigger a login.
  • If the user has logged in, but it looks like the access token has expired, the client automatically performs access token refresh and then executes the API call
  • If the refresh fails, the client re-logins the user
  • If HTTP request fails because the access token no longer functions (e.g. the access token has expired or the access token has been invalidate in the backend), the client automatically tries to refresh the token. If the refresh fails, the client re-logins the user. Once the access token has been refreshed, the client re-executes the request.

Application developer does not need to explicitly start login or refresh the session. You can register a callback, which gets notified, when certain login-related events (e.g. login is starting) happen, see Registering session event listener for details.

The service to use with identity-based licensing is tenduke::se::TendukeClientWithOIDCSession. See also the client concepts.

To create the client for browser-based authentication:

To create the client for device authentication, use factory functions:

Note the following client limitations:

  • We currently only support OIDC ID-tokens, which are signed with RSA-keys using (RS256)
  • We currently only support OAuth "Authorization Code Grant with PKCE" (see RFC 7636).
  • We currently only support single OIDC Id-token verification key

Browser-based authentication

10Duke Scale C++ client provides default browser-based OIDC authentication using operating system default browser and "loopback interface redirection": When user needs to be authenticated, the client opens default OS-browser and starts the login flow with the OIDC-provider. The client simultaneously opens a simple local HTTP-server, which is used to detect when the login is complete: When the login is complete, the OIDC server will issue HTTP-redirect to a pre-configured URL (the redirect-uri) in the browser. For details see RFC 8252: 7.3 Loopback Interface Redirection.

The client has to be configured with HTTP-message, which is served by the HTTP-server after the login is complete. This HTTP message is full HTTP-response, with status line, headers and response message entity. This allows e.g. using HTTP-redirect to navigate the browser to a external site after login.

For example, to create client for browser-based authentication:

std::string httpMessageAfterLogin =""
"HTTP/1.1 200 OK\n"
"Content-Type: text/html; charset=utf-8\n"
"\n"
"<html>\n"
"<head>\n"
" <title>Login successful, you can close the tab</title>\n"
"</head>\n"
"<body>\n"
" <H1>Login successful</H1>\n"
"</body>\n"
"</html>";
auto tendukeClient = ::tenduke::se::createTendukeClientForBrowserUsingAutodiscovery(
"browser-authentication-client-demo/0.0.1-alpha-1/mac",
::tenduke::se::BackendConfiguration("https://scale.10duke.com"), // ask proper URL from our support
::tenduke::se::ClientPropertiesBuilder()
.hwId("simulated-hardware-id")
.version("0.0.1-alpha-1")
.build(),
"https://genco.10duke.net/.well-known/openid-configuration", // URL for OIDC autodiscovery document
tenduke::oidc::osbrowser::BrowserAuthenticationConfig(
"demo-client", // oauthClientId, this value must also be configured in OIDC backend
"http://localhost/oidc/login", // oauthRedirectUri, this value must also be configured in OIDC backend
httpMessageAfterLogin // the HTTP message
)
);

Note that the redirect uri must start with http://localhost.

Device authentication

If the device, where the client is running, does not have a browser, or using the browser is awkward, the authentication can be done using "Device Authorization Grant", aka. device flow. To start the user login, the device shows an authentication URL and so called "user code" to the user. Using another device (e.g. computer or tablet), the user starts authentication by navigating to the given URL and entering the user code. Once the authentication is complete, the client is notified and user session is set up.

For details of the Device Authorization Grant, see RFC 8628.

When authenticating with device flow, the client has to be configured with a callback, which is called when the client needs to display the URL where user must navigate. The application developer has to implement the display of the information.

Example:

class Callback : public ::tenduke::oauth::device::OAuthDeviceAuthorizationResponseReceived {
void callback(const tenduke::oauth::device::DeviceAuthorizationResponse &response) override {
std::cout << std::endl
<< "Please forward your browser to address:" << std::endl
<< " " << response.verificationUri << std::endl
<< std::endl
<< "Authenticate yourself and enter following code when prompted:" << std::endl
<< " " << response.userCode << std::endl
<< std::endl
<< "Full URL for copy-pasting:" << std::endl
<< " " << response.verificationUriComplete << std::endl
;
}
};
// later in code:
auto callback = std::make_shared<Callback>(); // Keep handle of this for the duration of the client!
auto tendukeClient = ::tenduke::se::createTendukeClientForDeviceClientUsingAutodiscovery(
"device-flow-client-demo/0.0.1-alpha-1/mac",
::tenduke::se::BackendConfiguration("https://scale.10duke.com"), // you can find the API url from 10Duke Scale console
::tenduke::se::ClientPropertiesBuilder()
.hwId("simulated-hardware-id")
.version("0.0.1-alpha-1")
.build(),
"https://genco.10duke.net/.well-known/openid-configuration", // URL for OIDC autodiscovery document
::tenduke::oidc::device::DeviceAuthenticationConfig(
"demo-client", // oauthClientId, this value must also be configured in OIDC backend
*callback // The callback
)
);

Registering session event listener

The client manages the user login session automatically by performing login (either by opening browser or by device flow callback) when you use API which needs valid user login session and the user has not yet logged in or when th login session has expired. The client also refreshes the login session automatically, when required. The application developer does not need to trigger login manually.

You might want to be notified, when login is starting, login is complete or the user session has been refreshed. For example, when login is complete, you might want to bring your application on top of all other windows: in browser login, the browser usually opens on top and you want to bring the user back to your application.

To get the notifications, register instance of tenduke::oidc::OIDCSessionEventListener when creating the client. You can also inherit from tenduke::oidc::DefaultOIDCSessionEventListener, which has empty default implementations for all the callback methods. To configure the listener, use parameter oidcSessionConfiguration in the OIDC authentication configuration, see below for examples.

A sample listener:

class SampleSessionEventListener : public ::tenduke::oidc::DefaultOIDCSessionEventListener {
public:
void loginStarting() override {
std::cout << "LOGIN STARTING" << std::endl;
}
void loginComplete(const ::OIDCState &state) override {
std::cout << "LOGIN COMPLETE (access-token: " << state.getAccessToken() << ")" << std::endl;
}
};

When creating a client for browser-authentication, register the listener using parameter oidcSessionConfiguration of tenduke::oidc::osbrowser::BrowserAuthenticationConfig:

auto sessionEventListener = std::make_shared<::SampleSessionEventListener<>();
auto tendukeClient = ::tenduke::se::createTendukeClientForBrowserUsingAutodiscovery(
"browser-based-client-demo/0.0.1-alpha-1/mac",
::tenduke::se::BackendConfiguration("https://scale.10duke.com"),
::tenduke::se::ClientPropertiesBuilder().version("0.0.1-alpha-1").build(),
"https://genco.10duke.net/.well-known/openid-configuration",
::tenduke::oidc::osbrowser::BrowserAuthenticationConfig(
"demo-client",
"http://localhost/oidc/login",
httpMessageAfterLogin,
::OIDCSessionConfiguration::Builder() // use builder to configure oidcSessionConfiguration
.listenEventsWith(sessionEventListener) // register the custom session event listener
.build()
)
);

When creating a client for device-authentication, register the listener using parameter oidcSessionConfiguration of tenduke::oidc::device::DeviceAuthenticationConfig:

auto tendukeClient = ::tenduke::se::createTendukeClientForDeviceClientUsingAutodiscovery(
"browser-based-client-demo/0.0.1-alpha-1/mac",
::tenduke::se::BackendConfiguration("https://scale.10duke.com"),
::tenduke::se::ClientPropertiesBuilder().version("0.0.1-alpha-1").build(),
"https://genco.10duke.net/.well-known/openid-configuration",
::tenduke::oidc::device::DeviceAuthenticationConfig(
"demo-client",
*callback,
::OIDCSessionConfiguration::Builder() // use builder to configure oidcSessionConfiguration
.listenEventsWith(sessionEventListener) // register the custom session event listener
.build()
)
);

For fully working sample, see identity_based_client_example.cpp under examples.

Examples

Here are some examples on how to work with the client. For further details and complete API documentation, see tenduke::se::TendukeClientWithOIDCSession.

Licensing operations

Checkout licenses:

auto checkoutResponse = tendukeClient->licensing->checkoutLicenses()
.version("1.0.0") // Set default version to check out, this applies to all following licenses,
// unless overridden at license level. Version is optional.
.seat("sample-product") // Check out one seat of "sample-product" with default version
.execute();
// Check for failures:
if (checkoutResponse.hasErrors()) {
// handle errors
}

Heartbeart the lease:

auto heartbeatResponse = tendukeClient->licensing->heartbeatLicenses()
.leases(checkoutResponse.leases)
.execute();
// Check for failures:
if (heartbearResponse.hasErrors()) {
// handle errors
}

NOTE: Heartbeat generates new ids for the leases.

To release the licenses after heartbeat:

auto releaseResponse = tendukeClient->licensing->releaseLicenses()
.leases(heartbeatResponse.leases)
.execute();

The licensing client has a memory cache, which holds leases of checked out licenses and manages the leases automatically after heartbeat or release request. To list all leases currently in cache:

auto allLeases = tendukeClient->leases->getAllLeases();

The client allows you to only operate (heartbeat or release) on leases, which are present in the cache. If you want to release all checked out licenses, you can do:

auto releaseResponse = tendukeClient->licenses->releaseLicenses()
.leases(tendukeClient->leases->getAllLeases()
.execute();

Querying information about available licenses:

Service tenduke::se::licensing::LicenseConsumers can be used to query information e.g. about available licenses. For example, to query Licensees, whose licenses user can consume, use tenduke::se::licensing::LicenseConsumers.describeLicenseConsumerLicensees():

auto licensees = tendukeClient->licenseConsumers->describeLicenseConsumerLicensees();

To list licenses owned by Licensee, which the user can consume:

// Use first of the licensees queried above:
::tenduke::se::licensing::Licensee chosenLicensee = licensees.at(0);
auto licenses = tendukeClient->licenseConsumers->describeLicenseConsumerLicenses(chosenLicensee.id);

To list licenses the user has currently checked out:

// Use first of the licensees queried above:
::tenduke::se::licensing::Licensee chosenLicensee = licensees.at(0);
auto checkedOutLicenses = tendukeClient->licenseConsumers->describeLicenseConsumerClientBindings(chosenLicensee.id);

Working with OIDC session

Get current OIDC ID-token for authenticating requests to other 10Duke Scale APIs:

auto idtoken = tendukeClient->oidcSession->getOIDCState->getIdToken();