Admin API Authorization Service

Overview

The Admin Authorization Service is the central component responsible for Role-Based Access Control (RBAC) within the Admin API. It determines a principal's (user's) role for each incoming request and verifies if that role has sufficient permissions to access the requested endpoint.

This service solves the problem of enforcing granular access control across all Admin API endpoints. It acts as a gatekeeper, ensuring that principals can only view data and perform actions appropriate for their assigned role.

For every HTTP request to the Admin API, an authorization filter invokes this service. The service resolves the principal's identity, determines their role and special capabilities, and attaches this information to the request as an AuthContext for use by downstream components. Its sources of truth for authorization decisions are database role bindings, bootstrap configuration from environment variables, and claims within the product license.

How it Works

The service evaluates authorization for each request in a multi-step process, which includes resolving the principal's role, determining special capabilities like "Platform Operator" status, and checking against endpoint-specific permission requirements. The system employs several layers of caching to ensure high performance.

Request Authorization Flow

1. Identity Resolution: The service first resolves the principal's identity from the incoming HttpServletRequest using the IdentityResolver component. This provides a verified email address for the acting user.
2. Role Resolution: The service determines the principal's role. This follows a specific order of precedence, detailed in the diagram below. A key feature is "Pristine Mode," where the first authenticated user in a new deployment is automatically pro<customer>ed to the ADMIN role.
3. Capability Assessment: Beyond the standard role, the service assesses two special boolean capabilities:
   • platformOperator: true if the principal is authorized to manage the platform itself, such as tenant lifecycles in a multi-tenant environment.
   • dataAccess: true if the principal is permitted to view tenant-specific data. A restricted platform operator might have platformOperator=true but dataAccess=false.
4. Context Creation: The resolved role, principal email, correlation ID, and capability flags are packaged into an AuthContext object. This context is then attached to the request via attributes for other parts of the application to use.

Role Resolution Logic

The service resolves a principal's role by checking several sources in a specific order. The first source to grant a role wins.

flowchart TD
    A[Principal's Email] --> B{Is system in Pristine Mode?};
    B -- Yes --> C[Pro<customer>e principal to ADMIN<br>Flip system to Protected Mode];
    C --> Z(Role is ADMIN);
    B -- No --> E{Resolve from sources};
    subgraph E [Role Resolution Sources]
        direction TD
        E1[1. Check DB Role Bindings (Cache)] -- Found --> E_OUT(Role Assigned);
        E1 -- Not Found --> E2[2. Check Bootstrap Principals];
        E2 -- Found --> E_OUT;
        E2 -- Not Found --> E3[3. Check Bootstrap Groups];
        E3 -- Found --> E_OUT;
        E3 -- Not Found --> E4[Role is NONE];
        E4 --> E_OUT;
    end
    E --> Z;

Special Authorization Modes

Open Mode

If the system has zero active Identity Providers (IdPs) configured, it enters "Open Mode."

• Behavior: In this mode, RBAC is effectively disabled. Every request is treated as if it were made by a principal with the ADMIN role.
• Detection: The service checks for active IdP configurations via idpConfigRepository.countActive(). This check is cached for 30 seconds.
• Logging: When a request is processed in Open Mode, the service emits a throttled warning log message to alert operators that the system is running without authentication enforcement. The message is S2R-ADM-AUTH OPEN_MODE — no active IdP configured; every request is treated as ADMIN... and is logged at most once per minute.

Pristine Mode

For new deployments, the system starts in pristine mode.

• Behavior: The first authenticated principal to make a request is automatically granted the ADMIN role. The system then atomically transitions from pristine to protected mode. All subsequent role resolutions follow the standard logic.
• Pro<customer>ion: The pro<customer>ion is an atomic operation handled by authModeRepository.pro<customer>eIfPristine to prevent race conditions. The new admin is granted full platformOperator and dataAccess capabilities for their initial request.

Platform Operator

A Platform Operator is a privileged role designed for managing the platform infrastructure, particularly in multi-tenant deployments. This is distinct from a tenant's own ADMIN.

• Resolution: A principal is considered a Platform Operator if their email is found in any of these sources:
  1. The s2r.admin.bootstrap.platform-operator-emails environment variable.
  2. An admin or operator role binding in the database under the special __platform__ tenant.
  3. The meta.platform_operators claim within the signed product license.
• Enforcement: Certain API endpoints, like those for managing tenants (/admin/v1/tenants) or tenant API keys (/admin/v1/tenant-api-keys), require Platform Operator status. An attempt by a non-platform operator (even a tenant ADMIN) to access these endpoints is denied with error S2R-ADM-0407.

Data Access Wall for Restricted Operators

To support platform operators who should manage infrastructure without accessing tenant data, the service implements a "data access wall."

• Behavior: A principal identified as a restricted platform operator (platformOperator=true, dataAccess=false) is denied access to all Admin API endpoints except for a minimal, explicit allow-list. Access to any other endpoint is denied with error S2R-ADM-0408.
• Allowed Paths: The allow-list (isPlatformOperatorAllowedPath) includes infrastructure-management surfaces:
  • /health/**
  • /admin/v1/eula/**
  • /admin/v1/license/**
  • /admin/v1/tenants/**
  • /admin/v1/tenant-api-keys/**
  • /admin/v1/me
  • /admin/v1/ping
  • /admin/v1/saas/region
  • /admin/v1/settings/install-profile

Caching

To optimize performance, the service heavily caches authorization data. All caches are invalidated when relevant data changes.

Configuration Reference

The service can grant roles to principals at startup using environment variables. This is useful for bootstrapping the first users or for integrating with an external identity system that provides group information. These variables accept a list of emails or group identifiers, separated by commas, semicolons, or whitespace.

Service Contract

The service exposes several public methods used by the authorization filter and other internal components. It also sets specific attributes on the HttpServletRequest for downstream consumption.

Request Attributes

The following attributes are set on the HttpServletRequest object after successful authorization.

Endpoint Authorization Rules

The service maintains a detailed, explicit list of rules that map API endpoints to the minimum role required for access. The path used for matching is a canonicalized "routed path," which is resilient to URL encoding and other forms of obfuscation.

No Role Required (Public Access)

These endpoints are accessible to any authenticated principal, regardless of role.

• /health/**
• /admin/v1/eula/**

READER Role

• All GET requests not explicitly requiring a higher role.
• /admin/v1/ping
• /admin/v1/assistant/** (In-product documentation assistant)

DEVELOPER Role

This role is required for actions related to service definition and lifecycle management.

• GET /admin/v1/services/.../unconstrained-string-fields
• POST /admin/v1/services (Create service)
• DELETE /admin/v1/services/{serviceId}
• POST /admin/v1/services/{serviceId}/versions (Create version)
• Any path containing :activate or :rollback actions.
• Any path containing :generate-openapi action.
• Any path containing :apply-string-regexes, :set-boolean-handling, :set-upstream-failure-status, :set-null-handling, :set-fault-detail-exposure, :set-mtom-request, :set-datetime-handling, :set-array-collapse, :set-numeric-handling, :set-whitespace-handling, :set-binary-handling, :set-duration-handling, :set-required-handling, :set-header-propagation, :set-field-casing, :set-envelope-wrap, :set-error-shape, :set-xsi-type-handling, or :set-field-ordering.
• PUT /admin/v1/operations/{opId}/mapping
• POST /admin/v1/operations/{opId}/mapping:regenerate
• POST /admin/v1/services/{serviceId}/mapping:regenerate
• POST /admin/v1/services/{serviceId}/versions/{versionId}/mapping-synthesis:apply
• /admin/v1/wsdl/** (WSDL import)
• /admin/v1/openapi/import/** (OpenAPI import)

OPERATOR Role

This role is required for operational tasks, service configuration, and diagnostics.

• GET /admin/v1/services/.../spec-refinement
• POST /admin/v1/services/.../spec-refinement:apply
• Non-GET requests to /admin/v1/debug/capture/**
• GET /admin/v1/debug/capture/.../download
• PATCH /admin/v1/operations/{opId}
• PATCH /admin/v1/services/{serviceId}
• Any path containing :set-validation-regex
• All methods on /admin/v1/operations/{opId}/field-encodings and /admin/v1/operations/{opId}/transform-rules
• /admin/v1/services:bulk-action
• All methods on /admin/v1/services/{serviceId}/backend-profiles, /synthetic-monitor, and /test-datasets
• All methods on /admin/v1/backend-profiles/** (except DELETE, which is ADMIN)
• DELETE /admin/v1/test-datasets/{id}
• All methods on /admin/v1/datapower/**, /admin/v1/f5/instances/**, /admin/v1/discovery/vendor-enablement, /admin/v1/discovery/environments, /admin/v1/learned-example-error-markers
• PUT /admin/v1/master-discovery/rows/{id}/alert
• All methods on /admin/v1/async-executions/**
• /admin/v1/soap-to-json/preview, /admin/v1/soap-to-json/preview-with-overrides, /admin/v1/roundtrip/replay/**
• /admin/v1/license/request, /admin/v1/specaria/license-request

ADMIN Role

This role is required for system-wide configuration, security-sensitive operations, and any unclassified write operations.

• All non-GET requests to /admin/v1/settings/**
• All non-GET requests to /admin/v1/permission-bindings/**
• All non-GET requests to /admin/v1/updates/**
• All non-GET requests to /admin/v1/topology/**
• All non-GET requests to /admin/v1/support-consent/**
• All non-GET requests to /admin/v1/specaria/telemetry/**
• All methods on /admin/v1/idp-config/**
• All non-GET requests to /admin/v1/connectors/**
• All non-GET requests to /admin/v1/agents/**
• All non-GET requests to /admin/v1/tenants/** (also requires Platform Operator)
• All non-GET requests to /admin/v1/tenant-api-keys/** (also requires Platform Operator)
• GET /admin/v1/settings/conversion-defaults:preview
• GET /admin/v1/updates/deployment-id
• GET /admin/v1/updates/notifications
• POST /admin/v1/license and /admin/v1/license/upload
• All methods on /admin/v1/trusted-proxy-declarations/**
• All methods on /admin/v1/services/.../consumer-ip-grants/**
• DELETE /admin/v1/backend-profiles/{id}
• Any path containing :regenerate-all, :rehydrate-wsdl-artifacts, or :create-wsdl-artifacts-from-discovery.

Troubleshooting

See Also

• Identity Provider Configuration
• Identity Resolution
• License Management

All SOAP-to-REST docs