Identity and access management (IAM)

Introduction

Enonic XP ships with a standard concept handling users, authentication, groups and roles based authorization. Additionally, the NoSQL storage supports fine-grained access control mechanisms down to a single item.

IAM Concepts

XP IAM consists of three central concepts:

Principals

Principals are object that can be given permissions. There are three different types of principals:

Users: Principals that can be authenticated.
Groups: Used to group other principals to simplify management.
Roles: Provides access to application specific functionality.

Permissions

Principals may be given with fine grade access to items stored in the NoSQL storage. An example of this is the XP CMS, where users typically get access to create or publish content in specific areas of the solution.

Identity providers

ID providers offer pluggable abstraction layer for user authentication. As such, in order to authenticate or even create users in XP, you will need to define an ID provider.

ID providers are linked to your webapp or site through virtual hosts.

Creating an ID provider

ID providers can be created and managed through the API, or through the Users app in the XP admin console.

An ID provider essentially consist of the following:

A unique name (cannot be changed later)
ID provider application, with optional configuration settings.
Permissions - specifies who can manage and access the ID provider

ID provider applications must be installed before you can select them.

Setting up an ID provider from the Users admin tool

System ID provider

XP ships with a special ID provider that cannot be removed or renamed. It is called the System ID provider.

When accessing the XP admin console for the first time in a fresh installation, you will see the login screen of System ID provider.

The purpose of the System ID provider is to store system users, for example su(the Super User) and anonymous (the default user when no other user is specified).

Users in the System ID provider that are not system users are called Service Accounts.

Prior to XP , users added to the System ID provider were treated as regular users with username-password credentials. Users with username-password credentials in the System ID provider are still supported, but strongly discouraged. Instead, use service accounts with JWT tokens. See Service Accounts for more details.

Avoid adding real users to the System ID provider, rather create a new ID provider instead.

Service Accounts

A service account is a special kind of user used by remote applications and services to authenticate with XP. Service accounts are not meant to be used by humans. Service accounts are managed by XP Users app.

Each Service Account may (but not required to) have one or several Service Account keys. Using Service Account Key is beneficial for security reasons:

It allows to authenticate without transferring the password over the network.
Multiple Shared Account Keys allow rotation of Public-Private key-pairs without service interruption.
Stored Public key is not a hash of a password, so it is not possible to reverse-engineer the password from the public key.

Service accounts keys are used to make an authorized call to:

Management Endpoint
any other XP service port endpoint that supports authentication and is configured to use the System ID provider. See Virtual Hosts for more details.

Requests are authenticated by JWT token in the Authorization header.

Content of the header should look like the following:

Authorization: Bearer <token>

A JWT token must follow the following rules:

it must be a valid RFC-7519 JWT token.
alg header parameter must be set to RS256.
kid header parameter must be set to ID of the public key that corresponds to the private key used to sign the token.
sub claim must be set to ID of the service account, for instance, user:system:user_id.
exp claim must be set to expiration time of the token. The token will be rejected if it is expired.
iat claim must be set to issue time of the token. The token will be rejected if it was issued in the future.

Private key from Public-Private key pair is stored only on the client side and must not be shared with the XP server.

Public key from Public-Private key pair is stored in the XP server and is used to verify signature of the token.

Service account keys are a security risk if not managed correctly. Make sure to rotate keys regularly and keep them safe. If you suspect that your keys have been compromised, you can revoke them in the Users app. Whenever possible use other ID providers instead, such as OIDC ID provider.

JWT header example

{
  "kid": "51a29c2ab5ebf945f6a5ddac8935bf8b",
  "typ": "JWT",
  "alg": "RS256"
}

JWT payload example

{
  "sub": "user:system:user_id",
  "exp": 1692787396,
  "iat": 1692787366
}

ID provider apps

In order for an ID provider to work, it must be associated with an ID provider application that handles the authentication process.

You may install ID providers from Enonic Market, or build your own for a fully customized experience.

Standard ID provider app

Enonic XP is shipped with an app called the "Standard ID provider". This is also the app that is being used by the System ID provider

Built-in roles

Enonic XP is shipped with several built-in roles (described below) which grant certain permissions when applied to users. New roles can be created by users with Administrators and Users Administrator roles.

Permissions for every role can be overridden by Administrator or Content Manager Administrator on the content level.

Administrator Users with the Administrator role have full access to all content and admin tools through the user interface.

Administration Console Login Users with this role can log in to the administration console. These users will also require a role for each of the admin tools that the users need access to.

Content Manager Administrator

This role allows full access to Content Studio, including ability to create and delete content projects.

Content Manager Expert

This role gives members ability to view and modify source code in the rich text editor.

Content Manager App

Give users to access to the legacy default project in Content Studio. Users with this role can see content and sites, but cannot create new sites or any new content in the project.

As of v7.3, XP supports creation of custom content projects. These offer project-specific roles that automatically provide access to both Content Studio and the project itself.

Users App

Provides view-only access to the Users admin tool.

Users Administrator

Grants full access to the Users admin tool, including create/edit/delete for ID providers, users, roles, and groups.

Authenticated

Users automatically get this role when they are logged into the platform, regardless of ID provider.

Everyone

A special role that both authenticated users, and visitors (Anonymous user) all have in common. The role is for instance used to grant read permissions to publicly available content projects.

Schemas Administrator

Grants permissions to manipulate virtual applications and schemas.

NOTE: If you are using Content Projects, your project will have a set of project-specific roles in addition to the built-in ones.

Identity and access management (IAM)

Contents

Introduction

IAM Concepts

Principals

Permissions

Identity providers

Creating an ID provider

System ID provider

Service Accounts

ID provider apps

Standard ID provider app

Built-in roles

Contents

Contents