Getting Started with Authentication and Authorization by Using ScalarDB Cluster .NET Client SDK

The ScalarDB Cluster .NET Client SDK supports authentication and authorization, which allows you to authenticate and authorize your requests to ScalarDB Cluster.

Install the SDK

Install the same major and minor version of the SDK as ScalarDB Cluster into the .NET project. You can do this by using the built-in NuGet package manager, replacing <MAJOR>.<MINOR> with the version that you're using:

dotnet add package ScalarDB.Client --version '<MAJOR>.<MINOR>.*'

Set credentials in the settings file

You need to set credentials in the settings file, replacing the contents in the angle brackets as described. ScalarDB Cluster supports two authentication types: username and password authentication, and authentication that uses a JWT access token issued by an OpenID Connect (OIDC) provider. Select the tab for the authentication type that you want to use.

Username and password

To authenticate by using a username and password, set Username and Password as follows:

{
  "ScalarDbOptions": {
    "Address": "http://<HOSTNAME_OR_IP_ADDRESS>:<PORT>",
    "HopLimit": 10,
    "AuthEnabled": true,
    "Username": "<USERNAME>",
    "Password": "<PASSWORD>"
  }
}

OIDC JWT access token

To authenticate by using an OIDC JWT access token instead of a username and password, set AuthType to OidcJwt and set AuthOidcJwtAccessToken to a valid access token issued by your OIDC provider as follows:

{
  "ScalarDbOptions": {
    "Address": "http://<HOSTNAME_OR_IP_ADDRESS>:<PORT>",
    "HopLimit": 10,
    "AuthEnabled": true,
    "AuthType": "OidcJwt",
    "AuthOidcJwtAccessToken": "<OIDC_JWT_ACCESS_TOKEN>"
  }
}

When you use OidcJwt, Username and Password aren't required. For details about how to configure ScalarDB Cluster to accept OIDC JWT access tokens and how to obtain a token from an OIDC provider, see Control User Access via OIDC-Based JWT Access Tokens.

note

The SDK doesn't refresh OIDC JWT access tokens. Because the token is set when TransactionFactory is created, it can't be refreshed afterward. When the token expires or becomes invalid, the authentication error is propagated to your application. To use a new token, obtain a valid token and create a new TransactionFactory and transaction manager with that token.

For details about settings files and other ways to configure the client, see Client configuration.

Get a transaction manager

You need to get a transaction manager or transaction admin object by using TransactionFactory as follows. Be sure to replace <GET_TRANSACTION_MANAGER> with GetTransactionManager(), GetTwoPhaseCommitTransactionManager(), GetSqlTransactionManager(), or GetSqlTwoPhaseCommitTransactionManager().

// Pass the path to the settings file.
var factory = TransactionFactory.Create("scalardb-options.json");

// To get a transaction manager
using var manager = factory.<GET_TRANSACTION_MANAGER>();

// To get a transaction admin
using var admin = factory.GetTransactionAdmin();

A transaction manager or transaction admin object created from TransactionFactory with the provided credentials will automatically log in to ScalarDB Cluster and can communicate with it.

Wire encryption

Wire encryption is also supported. It can be turned on by setting Address to the URL starting with https as follows:

{
  "ScalarDbOptions": {
    "Address": "https://<HOSTNAME_OR_IP_ADDRESS>:<PORT>"
  }
}

For details about settings files and other ways to configure the client, see Client configuration.