Download the PHP package wernerdweight/api-auth-bundle without Composer

ApiAuthBundle

Symfony bundle providing API authentication and authorization.

Installation

1. Download using composer

2. Enable the bundle

Enable the bundle in your kernel:

Configuration

Only client configuration is mandatory, default values are mentioned in comments.

Target controllers

All controllers that implement WernerDweight\ApiAuthBundle\Controller\ApiAuthControllerInterface will be targeted automatically (no configuration required).

If you can't modify the controller (e.g. it's vendor code), you can specify an interface implemented by the vendor controller (be aware that it may also be implemented by some other controllers), or specify the class of the controller itself.

If you want to target all controllers, use * as configuration value for target_controllers.

Firewall

Configure your firewall:

ApiClient

You need to create an entity that implements ApiClientInterface. The easiest option is to extend the existing AbstractApiClient entity like so:

You can also directly implement the WernerDweight\ApiAuthBundle\Entity\ApiClientInterface if you want to avoid inheritance.

ApiUser

OPTIONAL: If you want to restrict certain actions within your API to certain users (see 'on behalf' access mode below), create an entity that implements ApiUserInterface and another one that implements ApiUserTokenInterface. The easiest option is to extend AbstractApiUser and AbstractApiUserToken entities like so:

WARNING: If you implement custom UserRepository (doctrine entity repository for your entity that implements ApiUserInterface), you must extend AbstractApiUserRepository or implement ApiUserRepositoryInterface!

Usage

General usage

You simply have to include respective client id and secret in requests that require authentication.

Scope access

You can optionally enable scope checking (via api_auth.client.use_scope_access_model or api_auth.user.use_scope_access_model configuration settings).

If enabled, the authenticator will also (apart from api credentials) check the defined client/user scope using configured checker (if no checker is explicitly configured (api_auth.client.access_scope_checker or api_auth.user.access_scope_checker) the default RouteChecker is used). This way, different ApiClients/Users can have different privileges.

The scope is generally a JSON column on ApiClient/ApiUser entities. You can store any information in that column and then use any checker you want to read and evaluate the stored information.

The default RouteChecker expects a structure like this:

ApiAuthBundle also by default includes a checker for DoctrineCrudApiBundle, that expects this structure:

You can also implement custom checker (don't forget to tag your checker with api_auth.access_scope_checker):

on-behalf access mode

If the ApiClient/ApiUser scope is configured to be checked (see above) and the 'on-behalf' value is set in the scope, another authentication is required.

The request must then contain the X-Api-User-Token header with a valid token. To obtain the token, the user must login using Basic Auth - the request should look as follows:

The response contains the token and scope (and optionally any other information returned from your user entity via json serialization):

WARNING: If you overload the default jsonSerialize method, don't forget to include the parent return value:

You can then use the obtained token in requests that require the 'ob-behalf' access mode like this:

FYI: The 'on-behalf' value only makes sense for client scope. If you set 'on-behalf' as value inside the user scope, the value is interpreted in the same way as true.

Events

The following events are dispatched, so you can hook in the process. For general info on how to use events, please consult the official Symfony documentation.

ApiClientCredentialsCheckedEvent (wds.api_auth_bundle.api_client_credentials_checked) \ Issued after the client credentials have been checked. Contains the client and credentials being checked. You can call setValid on the event to change the check result.

ApiUserAuthenticatedEvent (wds.api_auth_bundle.api_user_authenticated) \ Issued after the user has been authenticated using the authenticate endpoint. Contains the authenticated user.

ApiUserTokenCheckedEvent (wds.api_auth_bundle.api_user_token_checked) \ Issued after the 'on-behalf' token check. Contains the user and token being checked. You can call setValid on the event to change the check result.

ApiUserTokenRefreshEvent (wds.api_auth_bundle.api_user_token_refresh) \ Issued during the 'on-behalf' token is generated. Contains the user and generated token. You can call setToken on the event to change the token.

License

This bundle is under the MIT license. See the complete license in the root directiory of the bundle.