Common Library

Security Model

common holds the security vocabulary and the pieces that are not specific to one application. How the engine applies them is described in Security Implementation.

Roles

common/security/Constants.kt defines the role names and the identity provider claim names:

Constant Value

Constant	Value
`ROLE_ADMIN`, `ROLE_OWNER`, `ROLE_VIEWER`, `ROLE_MANAGER`, `ROLE_DESIGNER`, `ROLE_CONSUMER`	The role vocabulary; `allRoles` is the full set.
`REALM_ACCESS_CLAIM`, `ROLES_CLAIM`	The Keycloak token claims the roles are read from (`realm_access.roles`).

ROLE_ADMIN, ROLE_OWNER, ROLE_VIEWER, ROLE_MANAGER, ROLE_DESIGNER, ROLE_CONSUMER

The role vocabulary; allRoles is the full set.

REALM_ACCESS_CLAIM, ROLES_CLAIM

The Keycloak token claims the roles are read from (realm_access.roles).

security/Constants.kt additionally defines the API key transport names: the X-Api-Key header and the apiKey query parameter.

API Keys

data class ApiKey(val key: String, val roles: List<String>, val enabled: Boolean)

SecurityProperties maps the promethist.security prefix — enableApiKey and the apiKeys map, where each entry names a key, its roles and whether it is active. Keys are therefore configuration, not data, and are granted roles from the same vocabulary as users.

Authentication Helpers

Element Purpose

Element	Purpose
`SimplePrincipal`	A minimal `java.security.Principal`, used where an identity has a name but no credentials — the telephony and Slack channels, and API key authentication.
`Authentication.roles`	Extension reading the granted roles off an authentication.
`reactiveCurrentAuthentication`	The current authentication from the reactive security context, which is how services and pipeline components read the caller identity without it being passed down explicitly.
`UnauthorizedException`	Exception annotated with `401`, thrown where an operation requires an identity.

SimplePrincipal

A minimal java.security.Principal, used where an identity has a name but no credentials — the telephony and Slack channels, and API key authentication.

Authentication.roles

Extension reading the granted roles off an authentication.

reactiveCurrentAuthentication

The current authentication from the reactive security context, which is how services and pipeline components read the caller identity without it being passed down explicitly.

UnauthorizedException

Exception annotated with 401, thrown where an operation requires an identity.

Access Control

AccessControlList (see Domain Model) grants a role on a tenant or project, either to an internal user ID or to an external identity — an identity provider ref plus an optional external role. AclService reads those records and is enabled with promethist.acl-service.enabled.

Matching an external identity rather than a user ID is what allows enterprise access to be granted by role before the user has ever signed in.

Device Authentication

component/DeviceAuthenticator is the contract for authenticating a device or session; KeycloakDeviceAuthenticator implements it against Keycloak. It covers the case where the client is a device rather than a person.

Digests

lib provides Digest (SHA-1 and related helpers), used for derived identifiers — for example the default tracking ref of an outbound call, derived from the caller number rather than stored.