Once authentication is enabled, ServiceControl can additionally enforce authorization: restricting what each authenticated user is allowed to do based on the roles assigned to them in the identity provider. This is known as role-based access control (RBAC).
Authentication answers who is calling; authorization answers what they are allowed to do. Authorization requires authentication to be enabled first.
Role-based authorization is disabled by default. When it is disabled — but authentication is enabled — every authenticated user is granted full access. Enable authorization to restrict actions per user.
How it works
When authorization is enabled, ServiceControl reads the user's roles from their access token and, for each request, allows or denies the action based on those roles. ServicePulse adapts its interface to match, hiding or disabling the actions a user is not permitted to perform.
Built-in roles
Access is granted through three built-in roles. Assign one or more of these role names to users in the identity provider:
| Role | Access |
|---|---|
reader | Read-only access to everything. |
admin | Everything reader can do, plus managing the configuration and administration areas (licensing, notifications, retry redirects, throughput, and connections). |
writer | Full access, including message actions such as retry, edit, archive, and restore. |
The roles are cumulative: writer is the highest level and can do everything admin and reader can, and admin can do everything reader can. Role names are matched case-insensitively, and a user with none of these roles has no access to the affected areas.
Only reader, admin, and writer grant access. Custom role names are not supported, so provider-side roles must be named to match.
How to enable role-based access control
Upgrade to ServiceControl 6.18.0 or later and ServicePulse 2.9.0 or later.
Enable authentication if it is not already enabled. Authorization has no effect without it.
In the identity provider, create roles named
reader,admin, andwriter, and assign them to users. Ensure the roles are included in the access token — see reading roles from the token for where different providers place them.On every ServiceControl instance (Primary, Audit, and Monitoring), set the following configuration keys:
Restart all ServiceControl instances.
Each instance authorizes its own requests, so all instances must have authorization enabled. For the app config keys and environment variables of every instance type, see Primary, Audit, and Monitoring configuration.
Enable authorization consistently across all instances. If one instance is left with RoleBasedAuthorizationEnabled set to false while the others have it enabled, that instance grants every authenticated user full access to its endpoints, and ServicePulse will show those actions as available. Apply the same setting to Primary, Audit, and Monitoring.
Reading roles from the token
Identity providers place roles in different claims and shapes. Use the Authentication. setting to tell ServiceControl where to find them. Both a flat claim name (for example roles) and a dotted path into a nested JSON object claim (for example realm_access.) are supported.
| Identity provider | Typical RolesClaim value | Notes |
|---|---|---|
| Keycloak (realm roles) | realm_access. | Roles are nested inside the realm_access object; a dotted path reaches them. |
| Keycloak (with a realm-role mapper) / generic | roles | A flat top-level array of role strings. |
| Microsoft Entra ID (app roles) | roles | Configure app roles named reader, admin, or writer and assign them to users. |
| AWS Cognito (groups) | cognito:groups | Name the Cognito groups reader, admin, or writer. |
The value at the configured path may be a single string or an array of strings; both are accepted.
Authorization audit log
Every authorization decision — both allowed and denied — is written to a dedicated audit log so access can be reviewed and retained for compliance. Entries are emitted under the log category ServiceControl. and formatted as Elastic Common Schema (ECS) JSON, so they can be ingested into Elastic/Kibana or most SIEM (Security Information and Event Management) systems without custom mapping. Allowed decisions are logged at Information level and denied decisions at Warning level.
Where the audit log is written
ServiceControl routes the ServiceControl. category to a dedicated destination automatically; no additional logging configuration is required. Each entry is a single ECS JSON object on its own line, kept separate from the operational log so the two streams do not mix.
- Running as a Windows service (not in a container): entries are written to an
audit.file in the instance's log directory, alongside the console. The file rotates daily and when it exceeds 30 MB, retaining up to 14 archived files.json - Running in a container: entries are written to standard output only, for the container's log driver or log aggregator to collect; no
audit.file is produced.json
The audit trail is captured from Information upward independently of the operational log level, so reducing operational verbosity never drops audit entries, and audit entries never appear in the operational log.
Audit identity claims
The audit log identifies the caller using two token claims, configurable per instance:
Authentication.— a stable identifier for the user (defaultSubjectIdClaim sub).Authentication.— a human-readable display name (defaultSubjectNameClaim preferred_username).
If either claim is missing from the token, the request is rejected. A missing claim usually means the identity provider is not configured to emit it; correct the provider or point these settings at claims the token does contain.
Disabling authorization
To keep authentication (require a valid token) but grant every authenticated user full access, leave Authentication. set to false (the default). In this mode roles are not consulted.