README

A Symfony bundle to set up an IdentityProvider with OpenID Connect implemented

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

Applications that use Symfony Flex

Open a command console, enter your project directory and execute:

$ composer require coddin-web/idp-openid-connect-bundle

Applications that don't use Symfony Flex

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

$ composer require coddin-web/idp-openid-connect-bundle

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the config/bundles.php file of your project:

// config/bundles.php

return [
    // ...
    Coddin\IdentityProvider\CoddinIdentityProviderBundle::class => ['all' => true],
    // ...
];

Please note that this bundle can provide default configuration for other bundles (like doctrine and messenger). To make this work this bundle should be registered before other bundles.

This bundle also comes with a fully configured security config. Please make sure this does not conflict with your own security configuration or skip using the provided config and manually import what you need.

Configuring this bundle

Step 1: Include routes

This bundle provides routes needed for the OpenIDConnect flow to work, you can import them like so:

# config/routes.yaml
idp:
  resource: "@CoddinIdentityProviderBundle/config/routes.yaml"
  prefix: /

Step 2: Include default configs:

Note: this step can be skipped if you decide to configure certain bundles (like DoctrineBundle and SecurityBundle, etc) yourself.

# config/packages/coddin_identity_provider.yaml
imports:
  - { resource: "@CoddinIdentityProviderBundle/config/config.yaml" }

Please note that when including this configuration you need to remove your application security.yaml file.

Or you could import the individual configuration files like so:

# config/packages/coddin_identity_provider.yaml
imports:
  # ...
  - { resource: "@CoddinIdentityProviderBundle/config/packages/messenger.yaml" }

Step 3: Templates

The templates need the assets provided by the bundle, they can be installed via:

bin/console assets:install --symlink

Step 4: Database

This bundle needs specific tables to exist for the OAuth flow to work. They can either be "brute forced" in your application by running bin/console doctrine:schema:update --force (which I do not recommend) or within your application you can run bin/console doctrine:migrations:diff to create the needed migrations to update your application with the needed tables.

Step 5: Cache

The Symfony cache needs to be cleared before this module will be fully operational. This can be done with bin/console cache:clear If errors keep popping up try removing the cache by hand rm -rf var/cache/*

Please be careful when doing this in a production environment

Step 6: Environment variables

This bundle uses environment variables to configure certain aspects:

Variable	Description
`IDP_ENCRYPTION_KEY`	This variable is used as the encryption key for signing the requests <br/><br/>this key should be generated with `./vendor/bin/generate-defuse-key`
`IDP_PUBLIC_KEY_PATH`	A public and private key are needed for the OAuth2 Server
`IDP_PRIVATE_KEY_PATH`	A public and private key are needed for the OAuth2 Server
`IDP_JWKS_PATH`	This variable should point to a file (e.g.) `jwks.json` that contains the public key information for the `.well-known` endpoint <br/><br/>The contents of this file can be generated with the command `bin/console coddin:jwk:generate`
`IDP_HOST_URL`	This variable is used by the router to determine the default host (e.g. for e-mail templates)
`IDP_SCHEME`	This variable is used by the router to determine the default scheme (which should be `https`, which is also the default)
`TRUSTED_HOSTS`	This variable is used to protect the introspect endpoint
`COMPANY_NAME`	This variable is used to customize the default templates
`IDP_MAIL_FROM`	This variable is used as the global "from" header for emails
`MAILER_DSN`	This is needed for the password reset and general mailing within the application
`MESSENGER_TRANSPORT_DSN`	This is needed for the asynchronous processes this bundle uses

NB: The public / private and jwk paths are relative to the project directory

OAuth2 keys

This bundle comes with keys (which are needed by OAuth2 to sign the requests) located in the config/openidconnect/keys directory of the bundle. DO NOT use these keys on a production environment but replace them during your build.

For a new (production) server these keys can be generated by running two openssl commands.

openssl genrsa -out private.key 2048
openssl rsa -pubout -in private.key -out public.key

!! Setting up these files in the ENV is important (see Environment variables)

Message Queue / Supervisor

This bundle uses asynchronous events to not block the end-user with possible hiccups of certain processes. Therefor it is needed to run a message queue. It is recommended to use e.g. supervisor to run Symfony's Messenger queue like so: bin/console messenger:consume async

By importing this bundle's configuration (see Step 2) the Messages will be configured for you.

Debugging / unexpected errors

On a Macbook unexpected errors could occur when using LibreSSL insteadof OpenSSL.

MacOS comes with LibreSSL pre-installed, but it can be replaced by installing openssl with Homebrew.

Supported languages

Out of the box this module supports detection of the locale via the browser.

Two languages are supported: Dutch and English

Feel free to contribute other languages by submitting a Pull Request!

Testing

This bundle uses PHPUnit for unit and integration tests.

It can be run standalone by composer phpunit or within the complete checkup by composer checkup

NB The integration tests need a database to be run against. See the .env.test (which can be overruled by .env.test.local) for the needed configuration.

Checkup

The above-mentioned checkup runs multiple analyses of the bundle's code. This includes Squizlab's Codesniffer, PHPStan and a coverage check.

Continuous Integration

GitHub actions are used for continuous integration. Check out the configuration file if you'd like to know more.

Changelog

See the project changelog

Contributing

Contributions are always welcome. Please see CONTRIBUTING.md and CODE_OF_CONDUCT.md for details.

License

The MIT License (MIT). Please see License File for more information.

Credits

This code is principally developed and maintained by Marius Posthumus for usage by several clients of Coddin

Additional Resources

https://github.com/steverhoades/oauth2-openid-connect-server - The core of this bundle

https://github.com/thephpleague/oauth2-server - The base of the OpenIDConnect server library

https://tailwindcss.com/ - Used as base for of the default templates

coddin-web / idp-openid-connect-bundle

Maintainers

Details