Class KVStoreAuthorizationProvider

Authorization provider for the secure On-Premise Oracle NoSQL Database.
Inheritance
Object
AuthorizationStringProvider
KVStoreAuthorizationProvider
Inherited Members
Namespace: Oracle.NoSQL.SDK
Assembly: Oracle.NoSQL.SDK.dll
Syntax
public class KVStoreAuthorizationProvider : AuthorizationStringProvider, IAuthorizationProvider
Remarks

Applications should use this provider to authenticate against the secure on-premise kvstore. The instance of this class should be set as AuthorizationProvider in the initial configuration.

The authorization for the database operations requires the kvstore login token. The authorization provider is used to perform the following functions:

  1. The driver will log in to kvstore using the provided credentials and obtain the login token. The login is only performed the first time the authorization is needed (for the first database operation) and may also be performed after the login token expires. In the latter case the operation will throw InvalidAuthorizationException and will be automatically retried by the default retry handler, which will involve obtaining the new login token.
  2. If the AutoRenew property is set to true (which is the default), then after the initial login, the driver will renew the login token when it reaches half of its lifetime (half-point between acquisition and expiration). Renew request requires only the existing login token and does not require user credentials. If the renew request fails, the token will eventually expire and the driver will perform another login as described above.
  3. The driver will log out of the kvstore using the existing login token when the NoSQLClient instance is disposed.

To obtain the login token the driver needs user name and password of existing kvstore user that has required permissions to perform needed database operations. These credentials are only used for the login operation as described above and are not needed for every database operation. The are 3 ways in which you may set these credentials, in order of increased security:

  1. You may provide credentials explicitly as Credentials property. The user name and password are provided as KVStoreCredentials object. This option is not very secure because the password is stored in main memory in plain text. You can erase the password after you finish using NoSQLClient instance and the password is no longer needed.
    Note that it is also possible to provide clear text credentials if you are storing NoSQLConfig in JSON file, in which case credentials may be stored as the sub-field within the value of AuthorizationProvider field. This latter option is not secure and should only be used during development/testing.
  2. You may store the user name and password in separate JSON file and set the path to this file as CredentialsFile property. This file should contain JSON representation of KVStoreCredentials object in the same format as NoSQLConfig is stored in JSON as discussed in the remarks section of NoSQLConfig. This option is more secure because the credentials file may be restricted by the appropriate permissions. The driver will load the credentials from this file on demand every time they are needed and it will erase the password from the main memory every time after the credentials are used.
  3. You can define your own credentials provider delegate and set it as CredentialsProvider. This is the most secure option because you can choose where the credentials are stored and how they are accessed. The credentials provider delegate will be called every time the credentials are needed and the password will be erased from the main memory every time after the credentials are used.
Instead of specifying one of the properties described above you may also use one of KVStoreAuthorizationProvider constructors that initialize one of these properties, as shown in the examples.

Note that secure on-premise NoSQL Database uses the same endpoint for the authentication and to perform the database operations. This endpoint must be using HTTPS protocol. See Endpoint.

Examples
Creating KVStoreAuthorizationProvider with the explicitly provided credentials. 
var config = new NoSQLConfig
{
    Endpoint = "https://myhost:8888",
    AuthorizationProvider = new KVStoreAuthorizationProvider(
        userName, password)
    {
        RequestTimeout = TimeSpan.FromSeconds(15)
    }
};
Credentials in a JSON file ~/my_app/credentials.json. 
{
    "UserName": "John",
    "Password": "..."
}
Initial configuration in JSON file using the KVStoreAuthorizationProvider with the credentials file. 
{
    "Endpoint": "https://myhost:8888",
    "AuthorizationProvider": {
        "AuthorizationType": "KVStore",
        "CredentialsFile": "~/my_app/credentials.json"
    }
}
Using the credentials provider delegate. 
...
public static async Task<KVStoreCredentials> LoadCredentialsAsync(
    CancellationToken cancellationToken)
{
    // Load user name and password from a secure location.
    ...
    return new KVStoreCredentials(userName, password);
}
...
var config = new NoSQLConfig
{
    Endpoint = "https://myhost:8888",
    AuthorizationProvider = new KVStoreAuthorizationProvider(
        LoadCredentialsAsync);
};

Constructors

Name Description
KVStoreAuthorizationProvider() Initializes a new instance of KVStoreAuthorizationProvider.
KVStoreAuthorizationProvider(KVStoreCredentials) Initializes a new instance of KVStoreAuthorizationProvider with the specified user credentials.
KVStoreAuthorizationProvider(Func<CancellationToken, Task<KVStoreCredentials>>) Initializes a new instance of KVStoreAuthorizationProvider with the specified credentials provider delegate.
KVStoreAuthorizationProvider(String) Initializes a new instance of KVStoreAuthorizationProvider with the specified path to the JSON credentials file.
KVStoreAuthorizationProvider(String, Char[]) Initializes a new instance of KVStoreAuthorizationProvider with the specified user credentials.

Properties

Name Description
AutoRenew Gets or sets the value that determines whether the login token should be automatically renewed.
Credentials Gets or sets user credentials.
CredentialsFile Gets or sets the path to the JSON credentials file.
CredentialsProvider Gets or sets the credentials provider delegate.
RequestTimeout Gets or sets the timeout for login, renew and logout requests.

Methods

Name Description
ConfigureAuthorization(NoSQLConfig) Validates and configures the authorization provider.
Dispose() Releases resources used by this KVStoreAuthorizationProvider instance.
Dispose(Boolean) Releases the unmanaged resources used by this instance and optionally releases the managed resources.
GetAuthorizationStringAsync(Request, CancellationToken) Gets the authorization string.

See Also