anzusystems / auth-bundle
Anzu authorization services
Package info
github.com/anzusystems/auth-bundle
Type:symfony-bundle
pkg:composer/anzusystems/auth-bundle
Requires
- php: >=8.5
- ext-json: *
- ext-redis: *
- anzusystems/common-bundle: ^12.1
- lcobucci/clock: ^3.0
- lcobucci/jwt: ^5.5
- symfony/console: ^7.3|^8.0
Requires (Dev)
- doctrine/doctrine-bundle: ^2.11|^3.0
- doctrine/orm: ^2.13|^3.0
- nelmio/api-doc-bundle: ^5.9
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^2.1
- phpstan/phpstan-doctrine: ^2.0
- phpstan/phpstan-symfony: ^2.0
- slevomat/coding-standard: 8.20.0
- symfony/http-client: ^7.3|^8.0
- symfony/test-pack: ^1.0
- symplify/easy-coding-standard: ^13.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 08:01:24 UTC
README
Provides authorization functionality among Anzusystems' projects.
Installation
From within container execute the following command to download the latest version of the bundle:
$ composer require anzusystems/auth-bundle --no-scripts
Step 3: Use the Bundle
Configure the AnzuAuthBundle in config/anzu_systems_auth.yaml:
anzu_systems_auth: cookie: domain: .anzusystems.localhost secure: false # use true for PROD environment! jwt: audience: anz algorithm: ES256 # enum (ES256|RS256), default "ES256" public_cert: '%env(base64:AUTH_JWT_PUBLIC_CERT)%' # string representation of a public certificate private_cert: '%env(base64:AUTH_JWT_PRIVATE_CERT)%' # string representation of a private certificate authorization: enabled: true refresh_token: storage: redis: service_id: SharedTokenStorageRedis # service id of \Redis instance auth_redirect_default_url: http://admin-dam.anzusystems.localhost auth_redirect_query_url_allowed_pattern: '^https?://(.*)\.anzusystems\.localhost(:\d{2,5})$' type: json_credentials
Configure the SecurityBundle in config/security.yaml:
security: providers: app_user_provider_email: entity: class: App\Entity\User property: email auth: pattern: ^/api/auth/ stateless: true provider: app_user_provider_email json_login: check_path: auth_login success_handler: AnzuSystems\AuthBundle\Security\AuthenticationSuccessHandler failure_handler: AnzuSystems\AuthBundle\Security\AuthenticationFailureHandler logout: path: auth_logout access_control: - { path: ^/api/auth/, roles: PUBLIC_ACCESS }
Configure routing:
$routes ->import('@AnzuSystemsAuthBundle/Controller/Api/JsonCredentialsAuthController.php', type: 'attribute') ->prefix('/api/auth/');
Personal access tokens
Opt-in personal access token (PAT) authentication: an sha256-hashed bearer token bound to a user, with optional expiration, revocation, expiry notifications and management API. Disabled by default — a project that does not enable it needs no schema or configuration changes after a bundle upgrade.
Enable it by subclassing the mapped superclass and pointing the config to it:
use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository; use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken; use Doctrine\ORM\Mapping as ORM; #[ORM\Entity(repositoryClass: PersonalAccessTokenRepository::class)] #[ORM\Table(name: 'personal_access_token')] #[ORM\Index(name: 'IDX_revokedAt_expiresAt', fields: ['revokedAt', 'expiresAt'])] class PersonalAccessToken extends AbstractPersonalAccessToken { }
anzu_systems_auth: personal_access_token: enabled: true entity_class: App\Domain\PersonalAccessToken\Entity\PersonalAccessToken
The user relation targets AnzuSystems\Contracts\Entity\AnzuUser — make sure doctrine
resolve_target_entities maps it to the project user class. Add the doctrine mapping for the bundle's Entity
namespace and generate the migration with doctrine:migrations:diff. The user class comes from the common-bundle
settings.user_entity_class. The entity relies on constructor-less proxies, so use doctrine/orm 3 (lazy ghosts);
the ORM 2 legacy proxy strategy conflicts with the final entity constructor.
Wire the authenticator into a firewall protecting the API that accepts the tokens:
security: firewalls: mcp: pattern: ^/api/mcp stateless: true provider: app_user_provider_id entry_point: AnzuSystems\AuthBundle\Security\Authentication\PersonalAccessTokenAuthenticator custom_authenticators: - AnzuSystems\AuthBundle\Security\Authentication\PersonalAccessTokenAuthenticator
Management API routes (list/create/revoke/tools/update tools) are provided by
AnzuSystems\AuthBundle\Controller\Api\PersonalAccessTokenController attribute routes — import them with a prefix:
$routes ->import('@AnzuSystemsAuthBundle/Controller/Api/PersonalAccessTokenController.php', type: 'attribute') ->prefix('/api/adm/v1');
Authorization uses the auth_personalAccessToken_(create|createWithWriteTools|read|revoke) permissions (see
AnzuSystems\AuthBundle\Security\PersonalAccessTokenPermission); creation additionally requires the role
configured via create_role (default ROLE_MCP). A request authenticated by a personal access token never manages
tokens, a super admin included: all four permissions are denied, so a scoped token cannot create a wider one.
PUT <prefix>/personal-access-token/{id}/tools is guarded by the same permissions as creation:
auth_personalAccessToken_create with the create_role, and auth_personalAccessToken_createWithWriteTools when
writeTools is not empty. The owner of the token or a super admin may change it.
Declare these permissions in the host's common-bundle permission config (anzu_systems_common.permissions.config),
together with their translations, so the admin can grant them. Without the declaration the admin cannot grant them,
and auth_personalAccessToken_createWithWriteTools stays with super admins, who hold every permission checked through
AbstractVoter implicitly:
anzu_systems_common: permissions: config: auth_personalAccessToken: read: create: createWithWriteTools: revoke: translation: subjects: auth_personalAccessToken: en: Personal access token sk: Osobný prístupový token actions: createWithWriteTools: en: Create with write tools sk: Vytvor so zápisovými nástrojmi revoke: en: Revoke sk: Zruš
Add read and create to translation.actions as well if the host does not translate them yet.
Every token says which MCP tools it may use, set at creation and replaceable later, in three separate lists:
writeTools(AbstractPersonalAccessToken::getWriteTools()): the write tools, stored in the nullable JSON columnwrite_tools. An empty list is a read-only token, and so isNULLin the column.readTools(getReadTools()): the read tools, stored in the nullable JSON columnread_tools.nullkeeps every read tool the user may use, also ones added later, and[]gives none. A tool declared with#[AsMcpTool(explicitGrant: true)]is never a part of this list,nullincluded.explicitReadTools(getExplicitReadTools()): the read tools declared with#[AsMcpTool(explicitGrant: true)], each by name, stored in the nullable JSON columnexplicit_read_tools. An empty list gives none, and so doesNULLin the column. The list does not depend onreadTools, so a token can keep every read tool and one of these.
A token never gets more than its user: the tool permission is checked again on every call. An MCP preview tool
(#[AsMcpTool(previewOf: …)]) is never listed: a token gets it together with its write tool.
Every name must be a tool of the right kind in the common-bundle MCP configuration and may be listed once, otherwise
creation and a change of the tools fail validation on that field: an explicitGrant tool in readTools fails, and so
does another read tool in explicitReadTools. In an application without MCP enabled every name fails. The anzu:personal-access-token:create command relies on this check only and does not look at the user's
permissions.
The management API also checks the creator: POST <prefix>/personal-access-token (PersonalAccessTokenFacade::createGranted())
answers 422 on readTools, explicitReadTools or writeTools for a tool whose mapped permission the creator does not
hold. A missing explicitReadTools is read as []. A token with at
least one write tool additionally requires auth_personalAccessToken_createWithWriteTools, which super admins hold
implicitly, otherwise the answer is 403. GET <prefix>/personal-access-token/tools (allowed with
auth_personalAccessToken_create) returns the tools the current user may grant as
[{"name": "example_read", "writeTool": false, "category": "examples", "explicitGrant": false}, …], so a
creation form can offer them. A tool with explicitGrant: true reaches a token only through explicitReadTools, so a
form offers it apart from the other read tools. category is the
category of the tool from #[AsMcpTool(category: …)], camelCase, so a client can build a translation key from it; the items come in the order of McpToolAccessChecker::getPermittedToolNames(), not grouped by category.
PUT <prefix>/personal-access-token/{id}/tools (PersonalAccessTokenFacade::updateTools()) replaces the three lists
at once; the name, the expiration and the token value stay. writeTools is required (422 error_field_empty), a
missing readTools is read as null, so such a body gives the token every read tool, and a missing
explicitReadTools is read as []. A revoked token answers 422 on
revokedAt and an expired one 422 on expiresAt. Every name must be a tool whose mapped permission the owner of the
token holds, also when a super admin changes the token, otherwise the answer is 422 on readTools,
explicitReadTools or writeTools. A change of the tools applies from the next request. The
MCP server does not announce it, so a connected client sees an added tool only after it reconnects; a removed tool is
refused at once.
The authenticator puts a common-bundle McpToolScope on the security token
(PersonalAccessTokenAuthenticator::TOOL_SCOPE_ATTRIBUTE, with explicitReadTools as its explicitToolNames), and
PersonalAccessTokenToolScopeProvider is registered as common-bundle's McpToolScopeProviderInterface, so the MCP
server hides and refuses the other tools. A JWT or session has no scope, so it gets no write tool, a super admin
included.
Deleting a user: call PersonalAccessTokenFacade::deleteByUser($user) before removing the user entity — it deletes the
user's tokens in one flush. The user join column also declares onDelete: CASCADE,
but that is best-effort only: the created_by/modified_by columns of the user's own tokens still reference the user, so
the explicit deleteByUser() call is the contract.
Console commands:
anzu:personal-access-token:create <userId> --name=<label> [--expires-at=...] [--never-expires] [--write-tool=<name> ...] [--read-tool=<name> ... | --no-read-tools] [--explicit-read-tool=<name> ...]— prints the plaintext token once.--never-expirescreates a token withexpiresAt = NULL(skipped by the expiry notifications, mutually exclusive with--expires-at). It is command-only — the management API never sets it, so a never-expiring token can only be issued deliberately for a system user (e.g. a service integration).--write-toolis repeatable, one write tool per option; without it the token is read only.--read-toolis repeatable too; without it the token keeps every read tool its user may use except theexplicitGrantones, and--no-read-toolsgives it none.--explicit-read-toolis repeatable and grants oneexplicitGrantread tool per option, whatever the other read tool options say. The command prints the granted tools.anzu:personal-access-token:list <userId>— lists a user's tokens with id, status, dates and tools, never the token itself.anzu:personal-access-token:revoke <id>— revokes a token of any user, it stops working at once. A token already revoked stays as it is.anzu:personal-access-token:update-tools <id> [--write-tool=<name> ...] [--read-tool=<name> ... | --no-read-tools | --all-read-tools] [--explicit-read-tool=<name> ...]— replaces the three tool lists of a token of any user. With any tool option it needs exactly one of--read-tool,--no-read-toolsand--all-read-tools, otherwise it saves nothing and fails: the new lists replace the old ones, so an operator who adds a write tool must also say which read tools stay.--all-read-toolssetsreadToolstonull, so it is the only option needed for a token with every read tool and nothing else. Without--explicit-read-toolthe token loses itsexplicitGranttools, without--write-toolit becomes read only. Unlikecreateit checks the permissions of the owner of the token, and it refuses a revoked or expired token. It prints the previous and the new tools. Run in a terminal without any of these options, it shows the token, offers the tools the owner may grant and asks for the read tools (all,selectedornone), the explicit read tools and the write tools, with the current choice as the default answer. A list is answered with numbers or names separated by a comma,nonefor an empty one. A tool the token holds and the owner may no longer grant is listed and removed when saved. The command shows the change and saves it after a confirmation. Run without any of these options where it cannot ask (--no-interaction, or no terminal, such as a cron job), it saves nothing and fails with a message that names the options; with--quietit fails without the message. Answers piped to it are read like answers typed in a terminal.anzu:personal-access-token:notify-expiring— daily cron; notifies owners of tokens expiring in 7 days or 1 day throughPersonalAccessTokenExpiryNotifierInterface(no-op by default — alias your own implementation). The final-notice windows of consecutive runs overlap, so the implementation must be idempotent per (token, daysRemaining) pair — e.g. dispatch under an event name containing both.
When migrating from an app-level PAT implementation, rename existing permission grants to the
auth_personalAccessToken_* keys — grants stored under the old keys stop matching silently.