Auth

The CipherMail Gateway back end exposes a REST API that is used by both the web-based user interface and the command-line (CLI) tool to configure and manage the system. To call the REST API, you must sign in with an admin account. Admin accounts and their credentials are created and maintained with the CLI tool.

Access to the REST API is controlled by roles and permissions:

  • A permission grants access to a specific capability or set of endpoints in the API.

  • Permissions are grouped into roles.

  • Roles are assigned to admin accounts.

An admin can only use an API endpoint if their assigned roles include the required permission. This design ensures least-privilege access: administrators only see and do what their roles allow.

Permissions

Access to each capability or property requires a specific permission.

The gateway uses a comprehensive permission model with approximately 1700 distinct permissions. For every property, there are separate permissions to get and to set values at three scopes: global, domain, and user.

To list all available permissions, use the following cli command:

ciphermail-cli auth permissions all

To get a list of all permissions assigned to an admin, use the following cli command:

ciphermail-cli auth permissions effective --name <admin>

Roles

Permissions are granted to roles rather than directly to users. Roles can inherit other roles, allowing you to build reusable role sets. The system includes a default role named admin; it is created or updated each time the back end starts and is automatically granted all available permissions.

Note

In a standard installation, there is typically another role called portal. This role is assigned to the portal administrator and is used by the portal back end.

Use the following CLI commands to manage roles (see CLI Commands for all role related commands)

Create a role

NAME
       auth role create - Create new role

SYNOPSIS
       auth role create --name <string>

OPTIONS
       --name <string>
       name of new role
       [Mandatory]

Add permissions

NAME
       auth role permissions add - Add permissions to a role

SYNOPSIS
       auth role permissions add --name <string> --permissions <string-list>

OPTIONS
       --name <string>
       name of role
       [Mandatory]

       --permissions <string-list>
       permissions to add
       [Mandatory]

Delete a role

NAME
       auth role delete - Delete role

SYNOPSIS
       auth role delete --name <string>

OPTIONS
       --name <string>
       name of role to delete
       [Mandatory]

Inherit roles

NAME
       auth role inherited set - Set inherited roles for a role

SYNOPSIS
       auth role inherited set --name <string> --inherited-roles <string-list>

OPTIONS
       --name <string>
       name of role
       [Mandatory]

       --inherited-roles <string-list>
       inherited roles
       [Mandatory]

Admins

To use the REST API or the web interface, you must sign in with a valid administrator account. For added security, administrator access can be restricted to specific IP addresses or ranges.

Hint

In a standard installation, two administrator accounts are created: cli and portal. These accounts can be accessed only from the local host (127.0.0.1). The cli account has the admin role and therefore full permissions. The portal account has a restricted portal role that grants only the minimum permissions required by the portal backend.

To add a new admin using password authentication with full permissions, execute the following cli commands:

To create a new administrator account with full privileges using password-based authentication, run the following CLI commands:

ciphermail-cli auth admin add --name <admin> --authentication-type username-password
ciphermail-cli auth admin password --name <admin> --password <password>
ciphermail-cli auth admin roles set --name <admin> --roles admin

Use the following CLI commands to manage admin credentials (see CLI Commands for all admin related commands)

Add admin

NAME
       auth admin add - Add new admin

SYNOPSIS
       auth admin add --name <string> --authentication-type <username-password | oidc>

OPTIONS
       --name <string>
       name of new admin
       [Mandatory]

       --authentication-type <username-password | oidc>
       [Mandatory]

Hint

In most setups, set --authentication-type to username-password. Use oidc only if OpenID Connect is configured in your environment (for example, with Entra ID).

Delete admin

NAME
       auth admin delete - Delete admin

SYNOPSIS
       auth admin delete --name <string>

OPTIONS
       --name <string>
       name of the admin to delete
       [Mandatory]

Set password

NAME
       auth admin password - Set admin password

SYNOPSIS
       auth admin password --name <string> --password <string>

OPTIONS
       --name <string>
       name of admin
       [Mandatory]

       --password <string>
       password for the admin
       [Mandatory]

Set Roles

NAME
       auth admin roles set - Set roles for an admin

SYNOPSIS
       auth admin roles set --name <string> --roles <string-list>

OPTIONS
       --name <string>
       name of admin
       [Mandatory]

       --roles <string-list>
       roles for the admin
       [Mandatory]

Get all admins

NAME
       auth admin get all - List all admins

SYNOPSIS
       auth admin get all

Set authorized IP addresses

NAME
       auth admin ip-addresses set - Set authorized IP addresses for an admin

SYNOPSIS
       auth admin ip-addresses set --name <string> [--ip-addresses <string-list>]

OPTIONS
       --name <string>
       name of admin
       [Mandatory]

       --ip-addresses <string-list>
       IP addresses for the admin
       [Mandatory]

EntraID Pro/Ent only

This section guides you through setting up authentication with Microsoft Entra ID (formerly Azure Active Directory).

Before you start, make sure you have administrator access to your Entra ID tenant and know which users or groups should be allowed to sign in.

At a high level, you will register or use an existing application in Entra ID, configure redirect and logout URLs, generate client credentials, assign the appropriate permissions, and then copy the tenant ID, client ID, and client secret into the product’s authentication settings.

To set up Microsoft Entra ID authentication, complete the steps below.

  1. Create an App Registration on the Entry ID page

  2. Create a client secret

  3. Create an Ansible override file

  4. Run the playbook

  5. For every admin, add an admin with authentication type set to oidc

Create App Registration

Sign in to the Microsoft Azure portal and open the Microsoft Entra ID service. Find your Tenant ID and make a note of it, as you will need it in the next steps.

EntraID overview

Open the “App registrations” page and click New registration

  1. Set a “user-facing display name”

  2. Select “Accounts in this organizational directory only”

  3. Under “Redirect URI” Select “Web” and set the URL to https://<hostname>:8443/api/login/oauth2/code/entraid where <hostname> should be replaced by the fgqdn of the CipherMail gateway

  4. Click Register to add the new app registration

Hint

If you operate multiple CipherMail Gateways (for example, in a high-availability cluster), configure a separate “Redirect URI” for each gateway instance.

EntraID registrater application

Create a Client Secret

On the App Registration page, click Certificates & Secrets, then Client secrets and click New client secret.

Enter a descriptive name, choose an expiration date, and select Add. The “Certificates & secrets” page will then display the newly created secret.

Attention

The secret value is displayed only once. Copy it now, as you will need it in the next steps.

EntraID add client secret

Create Ansible override file

To enable EntraID, you need to create an ansible override file:

  1. Create the file using the Cockpit File Browser (or use an SSH client)

    /etc/ciphermail/ansible/group_vars/all/entraid.yml

    Paste the following configration.

    ---
ciphermail_entraid__enabled: true

# must be set to your Azure Tenant ID
ciphermail_entraid__azure_tenant_id: '<tennant-id>'

# must be set to the client id
ciphermail_entraid__client_id: '<client-id>'

# must be set to the client secret
ciphermail_entraid__client_secret: '<client-secret>'

    Replace <tennant-id> with your tenant ID, <client-id> with the client ID (which can be found on the “App registration overview page”) and <client-secret> with the client secret value (from the previous step)

  2. Login the shell using Cockpit Terminal (or use an SSH client)

  3. Run the ansible playbook

    sudo cm-run-playbook

    Hint

    the sudo command might ask for your Unix account password.

Add OIDC admin

With the CipherMail gateway, OIDC is only used for authenticating the admin, not for authorization. The main reason for this is that the gateway permission model is not compatible with the OIDC permission model. To allow OIDC login, an admin account with authentication type set to oidc should be added.

ciphermail-cli auth admin add --name <email> --authentication-type oidc
ciphermail-cli auth admin roles set --name <email> --roles admin

Replace <email> with your EntraID email account.

Login with EntraID

When you open the admin UI login page, you will see a Login with Entra ID option on the login page. Selecting this option starts the OpenID Connect (OIDC) sign-in process.

EntraID Login

Hint

If sign-in fails, verify that the redirect URL exactly matches what is configured in Entra ID, that time is synchronized on all systems, that the user has the required role or group membership and that the authentication-type of the admin is set to oidc.

Attention

During startup, the gateway contacts Entra ID to retrieve the provider’s configuration (endpoints and supported features) from a well-known JSON discovery URL. If this connection fails, startup is terminated and the gateway will not start.

To allow the gateway to start when Entra ID is unavailable:

  • Create an administrative user with a password.

  • Disable Entra ID by setting ciphermail_entraid__enabled to false.

  • Run the playbook to apply the changes.