Agency Auth Bundle

This bundle enables agency ("library") authentication against the Open Platform (Shared API for danish public libraries). In order to use this bundle you must have a CLIENT_ID / CLIENT_SECRET pair from DBC.

The bundle validates agency access tokens against the Open Platform introspection endpoint. If a supplied token is valid a User object with ROLE_OPENPLATFORM_AGENCY will be available from Symfony's security component.

Note

If you need user ("personal") authentication you should use danskernesdigitalebibliotek/oauth2-adgangsplatformen

Installation

Use Composer to install the bundle: composer require danskernesdigitalebibliotek/agency-auth-bundle

Bundle Configuration

Add a config/packages/ddb_agency_auth.yaml file:

ddb_agency_auth:
    # Your client id supplied by DBC
    openplatform_id: '%env(OPENPLATFORM_ID)%'
    
    # Your client secret supplied by DBC
    openplatform_secret: '%env(OPENPLATFORM_SECRET)%'
    
    # The introspection URL to query against
    openplatform_introspection_url: 'https://login.bib.dk/oauth/introspection'
    
    # A comma separated allow list of CLIENT_IDs. An empty list allows all.
    openplatform_allowed_clients: '%env(OPENPLATFORM_ALLOWED_CLIENTS)%'

    # [Optional] A service id for the cache service to use for caching token/user pairs 
    auth_token_cache: token.cache

    # [Optional] A service id for the logger to use for error logging.
    auth_logger: logger

In your .env add:

###> Openplatform ###
OPENPLATFORM_ID=myId
OPENPLATFORM_SECRET=mySecret
OPENPLATFORM_INTROSPECTION_URL=https://login.bib.dk/oauth/introspection
OPENPLATFORM_ALLOWED_CLIENTS=''
###< Openplatform ###

Then set the actuel values in your .env.local. (See configuration based on environment variables)

Security Configuration

Configure firewalls, access control and roles according to your needs in your config/packages/security.yml. The bundle provides a TokenAuthenticator you can use as a custom authenticator and a OpenPlatformUserProvider you can use as a custom user provider. If authenticated it will return a self validating passport with a User with the ROLE_OPENPLATFORM_AGENCY. You can use Symfonys hierarchical roles to map this role to your applications roles.

A working security configuration could be:

security:
    # https://symfony.com/doc/current/security.html#where-do-users-come-from-user-providers
    providers:
        openplatform_provider:
            id: DanskernesDigitaleBibliotek\AgencyAuthBundle\Security\OpenPlatformUserProvider
    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false
        main:
            stateless: true
            custom_authenticators:
                - DanskernesDigitaleBibliotek\AgencyAuthBundle\Security\TokenAuthenticator

    access_control:
        # Allows accessing the Swagger UI
        - { path: '^/api/docs', roles: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: '^/api', roles: ROLE_API_USER }

    role_hierarchy:
        ROLE_OPENPLATFORM_AGENCY: [ROLE_API_USER, ROLE_ENTRY_READ]

Development Setup

A docker-compose.yml file with a PHP 7.4 image is included in this project. To install the dependencies you can run

docker compose up -d
docker compose exec phpfpm composer install

Unit Testing

A PhpUnit setup is included in this library. To run the unit tests:

docker compose exec phpfpm composer install
docker compose exec phpfpm ./vendor/bin/simple-phpunit

Psalm static analysis

We are using Psalm for static analysis. To run psalm do

docker compose exec phpfpm composer install
docker compose exec phpfpm ./vendor/bin/psalm

Check Coding Standard

The following command let you test that the code follows the coding standard for the project.

• PHP files (PHP-CS-Fixer)

  docker compose exec phpfpm composer check-coding-standards

• Markdown files (markdownlint standard rules)

  docker run -v ${PWD}:/app itkdev/yarn:latest install
  docker run -v ${PWD}:/app itkdev/yarn:latest check-coding-standards

Apply Coding Standards

To attempt to automatically fix coding style

• PHP files (PHP-CS-Fixer)

  docker compose exec phpfpm composer apply-coding-standards

• Markdown files (markdownlint standard rules)

  docker run -v ${PWD}:/app itkdev/yarn:14 install
  docker run -v ${PWD}:/app itkdev/yarn:14 apply-coding-standards

CI

Github Actions are used to run the test suite and code style checks on all PR's.

If you wish to test against the jobs locally you can install act. Then do:

act -P ubuntu-latest=shivammathur/node:latest pull_request

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the AGPL-3.0 License - see the LICENSE.md file for details