Chapter 7. Configuring Authentication

Table of Contents

User management
User creation
User modification
User removal
User status
User login
Sessions

Authentication means verifying the identity of someone (a user, server, or other entity) who wants to use data, resources, or applications. Validating that identity establishes a trust relationship for further interactions. Authentication also enables accountability by making it possible to link access and actions to specific identities.

Within a secure Oracle NoSQL Database, access to the database and internal APIs is generally limited to authenticated users. When a secure Oracle NoSQL Database is first started, there are no users defined, and login to the administrative interface is allowed without authentication. However, no data access operations can be performed without user authentication.

User management

Users can be created, modified or removed in the Oracle NoSQL Database through the admin CLI. Information about a specific user account as well as a summary listing of registered users can also be displayed. For more information, see the next sections describing each user management operation.

User creation

Once you connect to a deployed admin, users can be added. The first user created must have admin rights (permission to perform user creation/modification operations). Use the plan create-user command to create a new user:

plan create-user -name <user-name>
[ -password <password> ] 
[ -admin ] [-disable] [ -wait ] 

where:

  • -name

    Specifies the name of the new user to create. The user name must be non-zero in length and must be composed of characters in a restricted character set composed of letters, digits, and underscore.

  • -password

    Specifies the initial password for the new user. Users are encouraged to provide the password in response to a console prompt rather than specifying it on the command line. The use of this argument may be necessary for scripted configuration.

  • -admin

    Assigns the created user complete system access rights. The first user created must have admin rights and once that first user is created, there must always be at least one admin user defined and enabled.

  • -disable

    Creates the user in disabled state. The initial admin user may not be created in a disabled state. The default state for a newly created user is enabled.

Create an admin user using the plan create-user command with the -admin option. You are prompted to set the password if it is not provided as an argument:

kv-> plan create-user -name root -admin -wait
Enter the new password: 
Re-enter the new password: 
Executed plan 7, waiting for completion...
Plan 7 ended successfully 

User modification

Use the plan change-user command to modify the specified user account (users without the -admin option may also change their own password):

plan change-user -name <user-name> 
[ -disable | -enable ]
[ -set-password [ -password <password> ] 
[ -retain-current-password ] 
[ -clear-retained-password ] ]

where:

  • -name

    Specifies the name of the user to modify. The user name must be non-zero in length and must be composed of characters in a restricted character set composed of letters, digits, and underscore.

  • -disable

    Disables the specified account. Disabling an account prevents a user from logging into the account. It also will cause currently logged-in users to become logged out. The logout of users is not immediate, but may be delayed by the login cache timeout period, which is specified through the loginCacheTimeout parameter.

  • -enable

    Enables the specified account, assuming that it was previously disabled

  • -set-password

    Changes the password for the specified account (valid only for internal password authentication).

  • -password

    Specifies the new password for the new user. Users are encouraged to provide the password in response to a console prompt rather than specifying it on the command line. The use of this argument may be necessary for scripted configuration.

  • -retain-current-password.

    For use only in conjunction with -password. If specified, causes the current password defined for the user to be remembered as a valid alternate password for a limited duration, or until the password is explicitly cleared. Only one alternate password may be retained at a time. This option allows a password to be changed via the CLI while an application is still running without affecting its operation.

  • -clear-retained-password.

    Erases the current alternate retained password.

    Note

    If -set-password, -clear-retained-password and -retain-current-password are all specified in the same command, the current retained password is erased before considering whether a password is currently retained.

User removal

Use the plan drop-user command to remove the specified user account (users cannot remove themselves):

plan drop-user -name <user-name> 

User status

Use the show user command to display information about the specified user account:

show user -name <user-name>  

Use the show users command to display a summary listing of registered users:

show users 

User login

You can use either the -username <user> or the -security <path to security file> runadmin argument to login to the admin CLI:

  • -username <user>

    Specifies the username to log in as. This option is used in conjunction with security properties like oracle.kv.transport.

  • -security <path-to-security-file>

    Specifies the security file that contains property settings for the login. Relative filename references within the security file are interpreted relative to the location of the security properties file. For example, if a security properties file contains the setting oracle.kv.ssl.truststore=client.trust then, the client.trust file should be in the same directory as the security properties file. If the file is named with an absolute path then it can be anywhere in the file system.

    The following properties can be set in the file in addition to any of the SSL communication properties documented in the previous chapter:

    oracle.kv.auth.username
    oracle.kv.auth.wallet.dir
    oracle.kv.auth.pwdfile.file 

    where the the oracle.kv.auth.wallet.dir and oracle.kv.auth.pwdfile.file properties in this file indicate the location of an EE wallet directory or CE password store file, respectively.

    Note

    The oracle.kv.security Java system property can be used as an alternative mechanism for providing a security file path. Setting this system property is equivalent to adding the -security option to the command line. This property is supported by all tools as well as by the KVStore client library.