Table of Contents

Configuring the SDK

The 10Duke SDKs requires certain configuration items to connect and interact with the 10Duke Enterprise or Scale API. Additional configuration items can be specified to control the behavior of the SDK.

The TendukeConfig object is used to provide most of the required configuration to a 10Duke SDK.

The TendukeConfigurationBuilder is used to construct a TendukeConfig object from a variety of sources.

Configuration items can be loaded from the following sources:

  • Hardcoded values supplied directly to the builder

  • Configuration file (HOCON, JSON, or YAML format supported)

  • Web.config or App.Config

  • appsettings.json

  • Environment variables

    Important

    HOCON is supported for .NET 8+, but is not supported for .NET Framework or netstandard2.0.

The configuration can be composed from a variety of these source or all loaded from a single source.

The configuration builder can also be instructed to load the details of the OpenID Connect (OIDC) provider from the Discovery URL.

Where a key exists in more than one source the last source added to the configuration builder will take precedence.

Using the builder, you can provide defaults or slow moving configuration items in code, then load values from a configuration file, and then apply any settings from environment variables.


var builder = new ConfigurationBuilder();
builder
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .AddEnvironmentVariables();

Configuration items

Almost all of the configuration items are optional, and which you need to provide will depend on how you are using the 10Duke API.

For identity based licensing, the minimum configuration would be licensing_api_url and idp_oidc_discovery_url, provided that the OIDC provider (also known as Identity Provider IdP) implements a discovery endpoint.

Configuration items keys (names) are accepted in snake_case, camelCase, or PascalCase.

licensing_api_url

(Mandatory) API base URL for the 10Duke API. Used to send requests to the 10Duke API. For 10Duke Scale You can view your API base URL on the dashboard at the 10Duke Scale console.

idp_oidc_discovery_url

OIDC provider Discovery URL. Used to retrieve the details of the OIDC endpoints for the identity provider.

idp_oauth_authorization_url

Endpoint for Authorization Request in Authorization Code or Implicit Grant flows. This can either be provided in the configuration or loaded using the Discovery URL (see TendukeConfigurationBuilder.AddOidcDiscoveryLoader()).

idp_oauth_device_code_url

Endpoint for Device Authorization Request in Device Authorization Grant flow. This can either be provided in the configuration or loaded using the Discovery URL (see TendukeConfigurationBuilder.AddOidcDiscoveryLoader()).

idp_oauth_token_url

Endpoint for Access Token Request or Device Access Token Request. This can either be provided in the configuration or loaded using the Discovery URL (see TendukeConfigurationBuilder.AddOidcDiscoveryLoader()).

idp_userinfo_url

Endpoint handling the UserInfo Request. This can either be provided in the configuration or loaded using the Discovery URL (see TendukeConfigurationBuilder.AddOidcDiscoveryLoader()).

idp_jwks_uri

URL path to read public key used to verify JWTs received from Authorization Server authenticating OIDC session. This can either be provided in the configuration or loaded using the Discovery URL (see TendukeConfigurationBuilder.AddOidcDiscoveryLoader()).

idp_oauth_client_id

Application credentials for OAuth/OIDC. This is set when you configure your application on the OIDC provider.

idp_oauth_client_secret

Application credentials for OAuth/OIDC. Required for some OAuth flows or for some Identity Providers. This is set when you configure your application on the OIDC provider.

idp_oauth_scope

Scopes to include in the Access and ID tokens requested via OIDC. Scopes are provided as a list, separated by spaces. You will need a minimum of openid.

token_refresh_leeway_seconds

The number of seconds before expiry time that an ID Token or Scale JWT will be automatically refreshed (default: 30 seconds).

auth_redirect_uri

URI to use for the redirect_uri in the OAuth Authorization Code flow (with or without Proof Key for Code Exchange). This URI can be used for localhost or remote processing of the redirect callback. If this configuration option is populated, auth_redirect_path will be ignored.

auth_redirect_path

Path fragment for local redirect URL to use for PKCE Flow Client. This should be the path on http://localhost that the IDP will redirect to for successful authentication during the PKCE flow. Defaults to /login/callback (interpreted as http://localhost/login/callback).

auth_redirect_port

Local port number to list for PKCE Flow redirect. Defaults to a random port. If auth_redirect_path is used with a localhost or loopback HTTP listener then this port will be used for the HTTP listener. The port will also be used if auth_redirect_uri is specified with localhost or loopback as the host name.

auth_redirect_timeout_seconds

Timeout for the PKCE Flow redirect. Defaults to 300 (five minutes).

This timeout covers the time to open the Authorization Server's login endpoint, the time it takes for the user to log in, and the time for the redirect to be processed on the local machine.

It is recommended that this be long enough for the user to attempt at least two or three rounds of password entry.

A value of zero indicates that the process should not timeout but wait indefinitely. When using an infinite timeout, consider also using a CancellationToken so that the process can be canceled by the user.

http_timeout_seconds

Timeout for HTTP requests (default: 30.0 seconds).

https_proxy

Not supported for the .NET implementation of the 10Duke Scale SDK. See Proxy section.

auth_success_message

A file to send as the content of the response to the redirect during PKCE flow. This is sent as the body of a 200 OK response.

OpenIdProviderHttpClientName

The name of the HttpClient to use for requests to the OIDC provider.

LicenseCheckouHttpClientName

The name of the HttpClient to use for requests to the 10Duke Scale License Checkout API.

Loading from app.config or web.config

If your .NET Framework application is already using an App.config or web.config XML file to define its configuration settings, you may wish to also store the configuration items for the 10Duke SDK in that file.

Add a section to the configuration XML file like so:

<configSections>
  <section name="TendukeApp"
           type="System.Configuration.NameValueSectionHandler"/>
</configSections>

and populate that section with the values for the 10Duke SDK configuration items as follows:

<TendukeApp>
  <add key="LicensingApiUrl" value="YOUR_LICENSING_API_URL_GOES_HERE" />
  <add key="TokenRefreshLeewaySeconds" value="6.2" />
</TendukeApp>

The configuration can then be loaded with the TendukeConfigurationBuilder:

using Tenduke.Core.Config;

var config = new TendukeConfigurationBuilder().AddConfigurationManager("TendukeApp").Build();

Loading from appsettings.json

If your .NET application is already using appsettings.json to define its configuration settings, you may wish to also store the configuration items for the 10Duke SDK in that file.

Add a section to the configuration JSON file like so:

"TendukeScale": {
    "LicensingApiUrl": "YOUR_LICENSING_API_URL_GOES_HERE"
}

and populate the section with the configuration items for the 10Duke SDK.

The configuration can then be loaded with the TendukeConfigurationBuilder:

var builder = new ConfigurationBuilder();
builder
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .AddEnvironmentVariables();

var config = builder.Build();

var tendukeConfig = new TendukeConfigurationBuilder().AddConfigurationSection(config).Build();

In the code sample, the Microsoft.Extensions.Configuration.ConfigurationBuilder class is used to build the configuration from the appsettings.json and environment variables.

Then the named section is retrieved and passed to the TendukeConfigurationBuilder.

Loading OIDC Discovery URL

If you want to load the details the OIDC provider you are using from the discovery URL, the configuration builder can do that for you.

To load the data from the URL, the configuration builder will use an HttpClient.

To control how this client is constructed and managed, you will need to provide an IHttpClientFactory.

Proxy

The configuration key https_proxy is not supported by the .NET version of the 10Duke SDK.

To set a proxy for the HttpClient, you can either set the HTTPS_PROXY environment variable, set the DefaultProxy static property of HttpClient, or to configure proxy settings per HttpClient, the HttpClientHandler.Proxy can be set when the HttpClient is created. See this article for more details.