corda/docs/source/node-auth-config.rst

Access security settings

Access to node functionalities via SSH or RPC is protected by an authentication and authorisation policy.

The field security in node.conf exposes various sub-fields related to authentication/authorisation specifying:

• The data source providing credentials and permissions for users (e.g.: a remote RDBMS)
• An optional password encryption method.
• An optional caching of users data from Node side.

Warning

Specifying both rpcUsers and security fields in node.conf is considered an illegal setting and rejected by the node at startup since rpcUsers is effectively deprecated in favour of security.authService.

Example 1: connect to remote RDBMS for credentials/permissions, with encrypted user passwords and caching on node-side:

security = {
    authService = {
        dataSource = {
            type = "DB",
            passwordEncryption = "SHIRO_1_CRYPT",
            connection = {
               jdbcUrl = "<jdbc connection string>"
               username = "<db username>"
               password = "<db user password>"
               driverClassName = "<JDBC driver>"
            }
        }
        options = {
             cache = {
                expiryTimeSecs = 120
                capacity = 10000
             }
        }
    }
}

Example 2: list of user credentials and permissions hard-coded in node.conf

security = {
    authService = {
        dataSource = {
            type = "INMEMORY",
            users =[
                {
                    username = "user1"
                    password = "password"
                    permissions = [
                        "StartFlow.net.corda.flows.ExampleFlow1",
                        "StartFlow.net.corda.flows.ExampleFlow2",
                        ...
                    ]
                },
                ...
            ]
        }
    }
}

Let us look in more details at the structure of security.authService:

Authentication/authorisation data

The dataSource field defines the data provider supplying credentials and permissions for users. The type subfield identify the type of data provider, currently supported one are:

• INMEMORY: a list of user credentials and permissions hard-coded in configuration in the users field (see example 2 above)

• DB: An external RDBMS accessed via the JDBC connection described by connection. The current implementation expect the database to store data according to the following schema:

  • Table users containing columns username and password. The username column must have unique values.
  • Table user_roles containing columns username and role_name associating a user to a set of roles
  • Table roles_permissions containing columns role_name and permission associating a role to a set of permission strings

  Note in particular how in the DB case permissions are assigned to _roles rather than individual users. Also, there is no prescription on the SQL type of the columns (although in our tests we defined username and role_name of SQL type VARCHAR and password of TEXT type) and it is allowed to put additional columns besides the one expected by the implementation.

Password encryption

Storing passwords in plain text is discouraged in production systems aiming for high security requirements. We support reading passwords stored using the Apache Shiro fully reversible Modular Crypt Format, specified in the documentation of org.apache.shiro.crypto.hash.format.Shiro1CryptFormat.

Password are assumed in plain format by default. To specify an encryption it is necessary to use the field:

passwordEncryption = SHIRO_1_CRYPT

Hash encrypted password based on the Shiro1CryptFormat can be produced with the Apache Shiro Hasher tool

Cache

Adding a cache layer on top of an external provider of users credentials and permissions can significantly benefit performances in some cases, with the disadvantage of introducing a latency in the propagation of changes to the data.

Caching of users data is disabled by default, it can be enabled by defining the options.cache field, like seen in the examples above:

options = {
     cache = {
        expiryTimeSecs = 120
        capacity = 10000
     }
}

This will enable an in-memory cache with maximum capacity (number of entries) and maximum life time of entries given by respectively the values set by the capacity and expiryTimeSecs fields.