Library Version 12.1.3.0

Chapter 7. Configuring Authentication
Prev |  | Next

## Chapter 7. Configuring Authentication

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.

Prev |  | Next
SSL communication properties | Home | Sessions