OrientDB Security Configuration

The new OrientDB security system uses a JSON configuration file that's located by default in the config directory. The default name of the file is security.json, but it can be overridden by setting the "server.security.file" property in orientdb-server-config.xml or by setting the global server property, "server.security.file".

The security.json configuration file may contain up to eight global properties: "enabled", "debug", "server", "authentication", "passwordValidator", "ldapImporter", and "auditing".

Here's a description of each top-level property in the security.json file.

"server"

The "server" object contains one property called "createDefaultUsers".

"authentication"

The "authentication" object specifies security authenticators for OrientDB and their order. Here's an example:

"authentication" :
{
    "allowDefault" : true,

    "authenticators" :
    [
        {
            "name"        : "Kerberos",
            "class"        : "com.orientechnologies.security.kerberos.OKerberosAuthenticator",
            "enabled"    : true,
            "debug"        : false,

            "krb5_config"    : "/etc/krb5.conf",

            "service" :
            {
                "ktname"     : "/etc/keytab/kerberosuser",
                "principal"    : "kerberosuser/[email protected]"
            },

            "spnego" :
            {
                "ktname"     : "/etc/keytab/kerberosuser",
                "principal"    : "HTTP/[email protected]"
            },

            "client" :
            {
                "useTicketCache"    : true,
                "principal"         : "[email protected]",
                "renewalPeriod"        : 300
            }
        },

        {
            "name"                : "Password",
            "class"                : "com.orientechnologies.orient.server.security.authenticator.ODefaultPasswordAuthenticator",
            "enabled"            : true,
            "users"             :
            [
                { "username" : "guest", "resources" : "connect,server.listDatabases,server.dblist" }
            ]
        },

        {
            "name"                : "ServerConfig",
            "class"                : "com.orientechnologies.orient.server.security.authenticator.OServerConfigAuthenticator",
            "enabled"            : true
        },

        {
            "name"                : "SystemAuthenticator",
            "class"                : "com.orientechnologies.orient.server.security.authenticator.OSystemUserAuthenticator",
            "enabled"            : true
        }    ]
}

Notice that "authentication" has two sub-properties, "allowDefault" and "authenticators". The "allowDefault" property, when set to true, tells the security system that if authentication fails for all the specified authenticators to allow OrientDB's default (built-in) authentication mechanism to also try.

The "authenticators" property is an array of authenticator objects. The order of the authenticators is significant, as the first is the primary authenticator. Subsequent authenticators in the list are called, if the first authenticator fails. This continues until either authentication succeeds or the list of authenticators is exhausted. If the "allowDefault" property is true and authentication is being called for a database, then OrientDB's native database security will then be attempted.

Each authenticator object supports at least three properties: "name", "class", and "enabled".

ODefaultPasswordAuthenticator

ODefaultPasswordAuthenticator supports an additional "users" property which contains an array of user objects. Each user object must contain "username" and "resource" properties. An optional "password" property is also permitted if authentication using a password is required.

Each user object can be used for authorization of the specified resources as well as authentication, if a password is present.

The full classpath for the "class" property is "com.orientechnologies.orient.server.security.authenticator.ODefaultPasswordAuthenticator".

Here's an example of the "users" property:

    "users"                 :
    [
        { "username" : "someuser", "resources" : "*" }
    ]

The "resources" property uses the same format as the "resources" property for each <user> in the <users> section of the orientdb-server-config.xml file.

Additionally, ODefaultPasswordAuthenticator supports a "caseSensitive" property. It defaults to true. When set to false, usernames are not case-sensitive when retrieved for password or resources look-up.

OServerConfigAuthenticator

OServerConfigAuthenticator utilizes the element in the orientdb-server-config.xml file and permits its list of server users to be used for authentication and authorization of resources. Beyond "name", "class", and "enabled", OServerConfigAuthenticator requires no additional properties.

The full classpath for the "class" property is "com.orientechnologies.orient.server.security.authenticator.OServerConfigAuthenticator".

OServerConfigAuthenticator's "caseSensitive" property is always false, meaning that usernames are not case-sensitive when retrieved for password or resources look-up.

OSystemUserAuthenticator

OSystemUserAuthenticator implements authentication and authorization support for system users that reside in the OrientDB system database. Beyond "name", "class", and "enabled", OSystemUserAuthenticator requires no additional properties.

The full classpath for the "class" property is "com.orientechnologies.orient.server.security.authenticator.OSystemUserAuthenticator".

OSecuritySymmetricKeyAuth

OSecuritySymmetricKeyAuth implements support for symmetric key authentication for server users.

Here's an example:

"authenticators": [
    {
        "name": "SymmetricKey-Key",
        "class": "com.orientechnologies.agent.security.authenticator.OSecuritySymmetricKeyAuth",
        "enabled": true,
        "users": [
            {
                "username": "sysadmin",
                "resources": "*",
                "properties" :
                {
                    "key" : "8BC7LeGkFbmHEYNTz5GwDw==",
                    "keyAlgorithm" : "AES"
                }
            }
        ]
    }
]

The authenticator class is "com.orientechnologies.agent.security.authenticator.OSecuritySymmetricKeyAuth".

Each user has a "properties" field that can specify an actual key, a path pointing to a file with the key inside, or a KeyStore containing the key. Each is mutually exclusive.

"key"

The key property is a Base64-encoded string of a secret key. The keyAlgorithm property must also be used with key.

"keyFile"

The keyFile property is a path to a file containing a Base64-encoded secret key string. The keyAlgorithm property must also be used with keyFile.

Here's an example:

"properties" :
{
    "keyFile" : "${ORIENTDB_HOME}/config/AES.key",
    "keyAlgorithm" : "AES"
}

"keyStore"

The keyStore property is a JSON object that contains four sub-properties.

Here's an example of the keyStore property and its sub-properties.

"properties" : { "keyStore" : { "file" : "${ORIENTDB_HOME}/config/test.jks", "password" : "password", "keyAlias" : "keyAlias", "keyPassword" : "password" } }

"file"

The file property is a path to a Java KeyStore file that contains the secret key. Note that the JCEKS KeyStore format must be used to hold secret keys.

"password"

The password property holds the password for the KeyStore file. It is optional.

"keyAlias"

The keyAlias property is the alias name of the secret key in the KeyStore file. It is required.

"keyPassword"

The keyPassword property holds the password for the secret key in the KeyStore and is optional.

OSystemSymmetricKeyAuth

OSystemSymmetricKeyAuth implements support for symmetric key authentication for system users.

Here's an example:

"authenticators": [
    {
        "name": "OSystemSymmetricKey",
        "class": "com.orientechnologies.agent.security.authenticator.OSystemSymmetricKeyAuth",
        "enabled": true
    }
]

The authenticator class is "com.orientechnologies.agent.security.authenticator.OSystemSymmetricKeyAuth".

Each system user will have an embedded-JSON "properties" field that supports the same sub-properties as the OSecuritySymmetricKeyAuth authenticator.

OKerberosAuthenticator

OKerberosAuthenticator provides support for Kerberos/SPNEGO authentication. In addition to the usual "name", "class", and "enabled" properties, the OKerberosAuthenticator component also supports "debug", "krb5_config", "service", "spnego", and "client" properties. All of these properties are defined in greater detail below.

The full classpath for the "class" property is "com.orientechnologies.security.kerberos.OKerberosAuthenticator".

"debug"

When set to true, all of the Kerberos and SPNEGO authentication are displayed in the server's logfile. This can be very useful when debugging authentication problems.

"krb5_config"

By default, the KRB5_CONFIG environment variable is used to tell the Java Kerberos libraries the location of the krb5.conf file. However, the krb5_config property may be used to override this.

"service"

The "service" property contains two sub-properties, "ktname" and "principal".

"spnego"

The "spnego" property contains two sub-properties, "ktname" and "principal".

"client"

The "client" property is used by OrientDB for configuring the LDAP/AD importer user, and it may contain five different sub-properties: "ccname", "ktname", "principal", "useTicketCache", and "renewalPeriod".

"passwordValidator"

The "passwordValidator" object specifies an optional password validator that the OrientDB security system uses when applying new passwords. The supported properties of the password validator object depend on the type of object specified but always contain at least "class" and "enabled". The "class" property defines which password validator component is instantiated. The "enabled" property (defaults to true) specifies whether the password validator component is active or not.

OrientDB ships with an ODefaultPasswordValidator component. Its properties are defined below, and each is only required if it's included in the "passwordValidator" property.

The full classpath for the "class" property is "com.orientechnologies.security.password.ODefaultPasswordValidator".

ODefaultPasswordValidator

Here is an example of the ODefaultPasswordValidator's configuration in the security.json file:

"passwordValidator" :
{
    "class"                : "com.orientechnologies.security.password.ODefaultPasswordValidator",
    "minimumLength"        : 5,
    "numberRegEx"        : "(?:[0-9].*){2}",
    "uppercaseRegEx"    : "(?:[A-Z].*){3}",
    "specialRegEx"        : "(?:[^a-zA-Z0-9 ].*){2}"
}

"ldapImporter"

The "ldapImporter" object defines the properties for the LDAP importer security component. As with the other security components, the LDAP importer object always has a "class" property and optional "enabled" and "debug" properties. The "class" property defines which LDAP importer component is instantiated. The "enabled" property (defaults to true) specifies whether the LDAP importer component is active or not.

OrientDB provides a default OLDAPImporter component, and its properties are defined below. The full classpath for the "class" property is "com.orientechnologies.security.ldap.OLDAPImporter".

OLDAPImporter

Database Object

Each database object contains three properties: "database", "ignoreLocal", and "domains". The "database" property is just the name of the OrientDB database. The "ignoreLocal" property is an optional boolean property that defaults to true. When true it indicates that existing users in the specified database will not be deleted if they are not present in the imported LDAP users list. The "domains" property is described below.

"domains"

The "domains" property contains an array of objects, each with "domain", "servers", and "users" properties, and an optional "authenticator" property.

"servers"

"users"

LDAP users are imported based on a starting location within the directory and filtered using a standard LDAP filter rule.

As an alternative to the "users" property in the security configuration file, OLDAPImporter also supports using a class in the database, called _OLDAPUser, for importing LDAP users based on the same properties. See below for more details.

Example

Here's an example of the "ldapImporter" property:

"ldapImporter" :
{
    "class"        : "com.orientechnologies.security.ldap.OLDAPImporter",
    "enabled"    : true,
    "debug"        : false,
    "period"    : 60,
    "databases" :
    [
        {
            "database"        : "MyDB",
            "ignoreLocal"    : true,
            "domains"        : 
            [
                {
                    "domain"        : "ad.domain.com",
                    "authenticator" : "Kerberos",

                    "servers"    :
                    [
                        {
                            "url"        : "ldap://alias.ad.domain.com:389",
                            "isAlias"    : true
                        }
                    ],

                    "users" :
                    [
                        {
                            "baseDN"    : "CN=Users,DC=ad,DC=domain,DC=com",
                            "filter"    : "(&(objectCategory=person)(objectclass=user)(memberOf=CN=ODBUser,CN=Users,DC=ad,DC=domain,DC=com))",
                            "roles"        : ["reader", "writer"]
                        },
                        {
                            "baseDN"    : "CN=Users,DC=ad,DC=domain,DC=com",
                            "filter"    : "(&(objectCategory=person)(objectclass=user)(memberOf=CN=ODBAdminGroup,CN=Users,DC=ad,DC=domain,DC=com))",
                            "roles"        : ["admin"]
                        }
                    ]
                }
            ]
        }
    ]
}

_OLDAPUser Class

The OrientDB _OLDAPUser class can be used in place of or in addition to the "users" section of "ldapImporter".

The class has four properties defined: Domain, BaseDN, Filter, and Roles.

"auditing"

The auditing component of the new security system is configured with the "auditing" object. It has four possible properties, the usual "class" and "enabled" properties, and "distributed" and "systemImport" properties.

"distributed"

The distributed property is an object and is used to configure what node events are recorded in the auditing log.

The distributed object may contain these properties:

Customing the Message

The variable ${node} will be substituted in the specified message, if node joined or node left auditing is enabled.

Example

Here's an example of a "distributed" section:

  "auditing": {
    "class": "com.orientechnologies.security.auditing.ODefaultAuditing",
    "enabled": true,
    "distributed": {
      "onNodeJoinedEnabled": true,
      "onNodeJoinedMessage": "Node ${node} has joined...",
      "onNodeLeftEnabled": true,
      "onNodeLeftMessage": "Node ${node} has left..."
    }
  }

"systemImport"

The systemImport property is an object and is used for importing a database's auditing log into the system database, where all new auditing is stored.

Each auditing log record from the specified databases is moved to a cluster in the new system database with the name databasename_auditing.

The systemImport object may contain these properties:

The importer stops for each database once all the auditing log records have been transferred to the system database.

Here's an example of a "systemImport" section:

  "auditing": {
    "class": "com.orientechnologies.security.auditing.ODefaultAuditing",
    "enabled": true,
    "systemImport": {
      "enabled": true,
      "databases": ["MyDB", "MyOtherDB", "OneMoreDB"],
      "auditingClass": "AuditingLog",
      "limit": 1000,
      "sleepPeriod": 2000
    }
  }