Skip to content

Authentication and authorization

Kura 5 introduces a centralized authentication and authorization framework based on the OSGi UserAdmin specification. This framework introduces the concepts of identities and permissions:

  • Identity: A Kura identity is related to authentication, an identity has a name and a set of associated credentials, for example a password.

  • Permission: A Kura permission is related to authorization. Zero or more permissions can be assigned to a given identity. Each permission allows to access a set of resources and/or perform certain operations. Permissions can be defined by applications.

Examples of applications that use the new authentication and authorization framework are the Web Console and the REST API framework:

  • Kura Web Console provides multi user support, Web Console users are mapped to Kura identities, the Web Console also defines a set of permissions that allow to restrict the operations that a given identity is allowed to perform.
  • The Kura REST API framework users are now mapped to Kura identities and REST roles are mapped to Kura permissions. The old ConfigurationService based user and role definition mechanism has been dropped.

The authentication and authorization framework only allows to define and store identities and permissions, it does not provide implementation of authentication methods and/or session management. These aspects are left to applications.

Permission and identity representation

Permissions and identities are implemented on top of the UserAdmin User and Group concepts. See OSGi UserAdmin specification for more details on the Role, User and Group concepts.

IdentityService Java APIs

Kura 5.5 introduces a new set of Java APIs that allow to manage Kura identities, the implementation is based on the UserAdmin conventions described in this page, and allows to manipulate Kura identities without interacting directly with the UserAdmin. Please refer to the Javadoc for more details.

The new APIs also provide the capability to implement and register IdentityConfigurationExtensions in the framework.

An IdentityConfigurationExtension can define additional custom configuration parameters for each identity. The custom configuration can be inspected and modified in the Identities section of Kura Web UI and using the identity/v2 rest APIs and MQTT request handler. The IdentityConfigurationExtension implementation can store the additional configuration in the way that is most suitable for the application, for example by adding custom UserAdmin properties or credentials.

Identities

A Kura identity is represented as a UserAdmin User with the following properties:

  • The User name must be in the kura.user.${identity_name} form where ${identity_name} is a non empty string representing the identity name. The name of an User representing a Kura identity must start with the kura.user. prefix.

  • A password may be assigned to an identity by defining a property in User credentials with the following format:

  • The property name must be kura.password
  • The property value must be a string containing SHA256 hash of the password, as computed by the 
    String org.eclipse.kura.crypto.CryptoService.sha256Hash(String)
    method.

Starting from Kura 5.1, it is possible to force an identity to change the password at next login by setting the following property in User properties: - kura.need.password.change : true encoded as a JSON string. - The property will be cleared automatically after a successful password change on next login.

Starting from Kura 5.5 the following restrictions will be applied by the IdentityService:

  • New Identity Names:
    • must be at least 3 and at most 255 characters long.
    • can only be composed by one or more sequences of alphanumeric characters ([A-Za-z0-9]+) separated by the dot or underscore symbols, dot and underscore is not allowed at the beginning or at the end of the permission name, sequences of consecutive dots and/or underscores are not allowed (examples of valid names are foo1.bAr, foo, a.b.c, foo.bar_baz).
  • New Passwords:
    • cannot be empty.
    • must satisfy the password strenght requirements configured on the system.
    • the maximum allowed length is 255 characters.
    • cannot contain whitespace characters.

Permissions

A Kura permission is represented as a UserAdmin Group with the following properties:

  • The Group name must be in the kura.permission.${permission_name} form where ${permission_name} is a non empty string representing the permission name. The name of a Group representing a Kura permission must start with the kura.permission. prefix.

  • Assigning a permission to a specific identity can be done by adding the User representing the identity to the basic members of the Group representing the permission.

Starting from Kura 5.5 the following restrictions will be applied by the IdentityService to the name new permissions:

  • must be at least 3 and at most 255 characters long.
  • can only be composed by one or more sequences of alphanumeric characters ([A-Za-z0-9]+) separated by the dot symbol, the dot is not allowed at the beginning or at the end of the permission name (examples of valid permission names are foo1.bAr, foo, a.b.c).

Identity and permission management through the REST APIs

Starting from Kura 5.6.3, the REST APIs that manage identities, permissions and the UserAdmin persistence apply the same rules enforced by the Kura Web UI, where identity management is reserved to identities holding the kura.admin permission:

  • Identity V2 and Identity V1 REST APIs: an identity holding the rest.identity permission, but not kura.admin, can only create, update or delete identities whose permissions are a subset of its own permissions, and can only assign permissions that it holds. Creating and deleting permissions requires kura.admin. Requests that do not satisfy these rules are rejected with the 403 Forbidden status. The additional configurations of an identity, provided by the identity configuration extensions, are returned by the Identity V2 REST APIs to such an identity only for the identities it is allowed to manage.
  • Configuration V2 REST APIs: the configuration of the UserAdmin persistence component (org.eclipse.kura.internal.useradmin.store.RoleRepositoryStoreImpl, see UserAdmin persistence) is returned and can be updated only by identities holding the kura.admin permission; for other identities it is also omitted from the pid lists and the default configuration requests. Snapshot rollback, which also restores the identities and permissions, requires kura.admin as well.

Identities holding the kura.admin permission and requests received through the cloud request handlers (IDN-V1, IDN-V2 and CONF-V2) are not affected.

Restoring the previous behaviour

The behaviour of the previous releases can be restored by adding the following arguments to the Java command line used to start Kura:

Argument Effect
-kura.rest.identity.legacyIdentityManagement Identity management requests received through the Identity V1 and V2 REST APIs are not checked against the permissions of the requesting identity.
-kura.rest.configuration.legacyUserStoreAccess The UserAdmin persistence component configuration and snapshot rollback are available through the Configuration V2 REST APIs to all the identities holding the rest.configuration permission.

The arguments are not present in the start scripts by default. To enable one of them, append it to the Java command line, after -configuration /tmp/.kura/configuration, in /opt/eclipse/kura/bin/start_kura_background.sh (production mode), /opt/eclipse/kura/bin/start_kura_debug.sh (development mode) and /opt/eclipse/kura/bin/start_kura.sh, for example:

        -configuration  /tmp/.kura/configuration -kura.rest.identity.legacyIdentityManagement

and restart Kura. The arguments are read only at startup and cannot be modified through the REST APIs, the cloud request handlers or the Kura Web UI. A warning is logged at startup for each enabled argument.

Note

These are framework command line arguments, not Java system properties: Java system properties with the same names (for example set with -D, in the Equinox config.ini file or through the JAVA_TOOL_OPTIONS environment variable) are ignored. The arguments must be specified exactly as shown above, without a value.

Warning

These arguments restore a less restrictive behaviour: an identity holding rest.identity or rest.configuration will be able to modify any identity, including the ones holding kura.admin. Enable them only if required by existing applications, and only for the time needed to adapt them.

Note

The start scripts are generated by the Kura installer; if Kura is reinstalled or upgraded, the arguments need to be added again.

UserAdmin persistence

The org.eclipse.kura.internal.useradmin.store.RoleRepositoryStoreImpl Kura service allows to persist the UserAdmin state in Kura configuration snapshot, this includes the defined identities and permissions.

The following configuration properties are used to store the UserAdmin concepts in Json format:

  • Role configuration (id roles.config):

Stores the UserAdmin Roles, plain Roles are non used for representing Kura identities and permissions.
The value must be a JSON array of Role elements.

  • User configuration (id users.config):

Stores the UserAdmin Users.
The value must be a JSON array of User elements.

  • Group configuration (id groups.config):

Stores the UserAdmin Groups.
The value must be a JSON array of Group elements.

JSON representation details

This section describes the JSON format used in org.eclipse.kura.internal.useradmin.store.RoleRepositoryStoreImpl configuration.

UserAdminDictValue

A value appearing in UserAdmin dictionaries like properties and credentials

  • type : variant

    Variants:

  • a String property

    • type : string
  • a byte[] property
    • type : array, element description:
      a byte of the array encoded as an unsigned integer
    • type : number

Examples:

"A string property"

[1, 2, 3, 4, 5]

UserAdminDict

A UserAdmin property dictionary, there are no well known property names, property values must be of UserAdminDictValue type

  • type : object

Example:

{
  "stringProperty": "A string property",
  "byteArrayProperty": [1, 2, 3, 4, 5]
}

Role

An object describing and UserAdmin Role

  • type : object

    Properties:

  • name
    The role name

  • type : string

  • properties

  • optional If the dictionary is empty

User

An object describing and UserAdmin User

  • type : object

    Properties:

  • name
    The role name

  • type : string

  • properties

  • optional If the dictionary is empty

  • credentials

  • optional If the dictionary is empty

Example:

{
  "name": "kura.user.appadmin",
  "credentials": {
    "kura.password": "3hPckF8Zc+IF3pVineBvck3zJERUl8itosySULE1hpM="
  }
}

Group

An object describing and UserAdmin Group

  • type : object

    Properties:

  • name
    The role name

  • type : string

  • properties

  • optional If the dictionary is empty

  • credentials

  • optional If the dictionary is empty

  • basicMembers

  • optional If the list is empty
    The list of the group basic members

    • type : array, element description:
      A role name
    • type : string

  • requiredMembers

  • optional If the list is empty
    The list of the group required members
    • type : array, element description:
      A role name
    • type : string

Example:

{
  "name": "kura.permission.kura.wires.admin",
  "basicMembers": ["kura.user.appadmin"]
}