User Authentication and Authorization

To enable user and role management, the nuoadmin.conf property domainUser must be set to a non-empty value. This value should be the Common Name of the X509 certificate in the truststore of APs that belongs to the domain user, which is the first user in the system and is authorized to invoke any NuoDB Admin functionality. The domainUser property must be set to the same value on all APs in the domain.

The nuoadmin.conf setting requireLocalDomainUser=true is used to prevent remote access for clients using the domain user certificate.

The examples below assume that the environment variable NUOCMD_CLIENT_KEY is set to the PEM file associated with the domain user. This sets the default value of --client-key for nuocmd invocations. The examples below also assume that an AP is running on the same host that the nuocmd commands are being invoked on.

To determine whether user and role management is enabled on an AP, the following command can be run:

In the example above, it is assumed that the domain user is the one that has the certificate with CN=nuocmd.nuodb.com. All of the certificates that are trusted by APs can be obtained by using the following command:

As the domain user, a simple role can be created using the nuocmd command-line tool as follows:

This role is authorized for requests with any HTTP method and any URL. Role management is explored in more detail in a later section.

As the domain user, an ordinary user can be created using the nuocmd command-line tool as follows:

The command above creates a user with certificate authentication. If the file specified with --cert does not exist, a PEM-encoded key and self-signed X509 certificate is generated and stored there. If the file specified with --cert does exist, it must be a self-signed certificate with a subject name that has attribute CN (Common Name) identical to the user name.

The command above also adds the certificate of the new user to the truststore of all APs in the domain, before finally creating the user. When an AP services a REST request that is authenticated with a client certificate, the user name is derived from the CN attribute of the certificate’s subject name.

To verify that the command above was successful, the truststore can be checked for the presence of the user certificate, and the user can be listed as follows:

Finally, to issue commands as the new user, the PEM file associated with the user can be explicitly specified:

A user with password-based authentication can be created as follows:

To issue commands as a password-authenticated user, the username and password must be specified using --basic-creds as follows:

Alternatively, the username and password of a password-authenticated user can be specified using the NUOCMD_BASIC_CREDS environment variable.

The user’s password hash is cached in memory on successful authentication to avoid calculating it on every REST API call made by this user. The cache has a time-based eviction policy which is controlled by the authCacheTimeoutMillis setting (by default 60 seconds) which can be configured in nuoadmin.conf. This optimization reduces any performance penalties and delays on password verification caused by the strong password hashing algorithms.

To prevent potential denial of service (DoS) attacks causing high CPU and memory usage in case malicious users send a high rate of REST API requests with a wrong password, an authentication failure threshold is available. Any requests originated by clients with a remote IP address for which authentication or authorization failures above the configured threshold rate have been registered will be throttled. The failure threshold rate is controlled by the allowedClientAuthFailuresPerSecond setting (by default 5.0) which can be configured in nuoadmin.conf.

Existing users can be updated to change authentication information, including changing the certificate for a user, changing the password for the user, or changing from certificate authentication to password authentication or vice-versa, by using the nuocmd update user-credentials subcommand:

Existing users can have the set of roles assigned to them updated by using the nuocmd update user-roles subcommand:

Finally, existing users can be deleted by using the nuocmd delete user subcommand:

As mentioned earlier, users are assigned roles, which are granted privileges by specifying requests that they are authorized for and by specifying sub-roles, whose privileges they inherit. An authorized request specification has the following form:

The method field specifies the HTTP request method, which is one of PUT, GET, POST, DELETE (these are the HTTP request methods used by the NuoAdmin REST API and not an exhaustive list of HTTP request methods), and *, which means that this request specification applies to any request method.

The url field specifies URL that this request specification applies to, which can include the wildcard character, *. The url field should not include base of the URL, i.e. the hostname and port, since that varies by AP, but request specification should apply to all APs. For example, the URL associated with database configuration operations can be specified as follows:

The pathParamConstraints, queryParamConstraints, and payloadParamConstraints fields specify constraints on request parameters as mappings of field name to required value. pathParamConstraints specify constraints on parameters that are part of the URL of a request, queryParamConstraints specify constraints on query parameters, and payloadParamConstraints specify constraints on the request body, which is encoded as JSON in the NuoAdmin REST API.

To specify a constraint on a sub-field nested within the request payload, the path to the sub-field can be specified using . as a delimiter. For example, to constrain a hot-copy request so that it has the form shown below, the following payload constraints can be specified:

The nuocmd command-line tool can be used to create roles, to update the set of privileges granted to roles, and to delete roles. The nuocmd create role subcommand can be used to specify a set of sub-roles and to define the first authorized request specification for that role:

The --method, --url, --path-param-constraints, --query-param-constraints, and --payload-param-constraints correspond to the fields of the authorized request specification described in the previous section. A role may have several authorized request specifications, not just one. To grant more privileges to an existing role, the nuocmd add role-privileges subcommand can be used, which takes the same arguments as nuocmd create role:

To remove privileges from an existing role, the nuocmd remove role-privileges subcommand can be used, which takes the same arguments as nuocmd create role and nuocmd add role-privileges:

nuocmd remove role-privileges removes any specified sub-roles from the specified role, and the authorized request specification generated by the command.