Table of Contents
OAuth2 and OpenID Connect Authorization Server
Available from VuFind® 9.0.
VuFind® provides an OAuth2 and OpenID Connect (OIDC) authorization server (provider) that allows external services to request authorization and user information from VuFind® while allowing the user to manage the consent and see the user information that is being passed to the external service. See OpenID Connect for more information on how OIDC works.
Recommended read: OpenID Connect Primer
Available User Information
OIDC allows a client to request any set (i.e. scope) of user attributes. VuFind® allows the OIDC client to request user attributes stored in VuFind®'s user account as well as attributes available from a library catalog. If the client requests attributes that require a catalog connection, the user is prompted for a library card if necessary. Any field that is returned from the ILS driver (getMyProfile method) can be added into a scope that a client can request.
The default scope and claim configuration contains the scopes defined in the OIDC specification and several VuFind specific ones. You should keep the predefined ones available for interoperability, but you can choose what else to support.
The PHP extension
ext-sodium is required for correct functionality. Please ensure it is installed and loaded before configuring the service.
Apache + PHP-FPM Configuration
If you are using PHP-FPM, you need to ensure that the
Authorization header is passed through from Apache. See the sample config/vufind/httpd-vufind.conf for an example.
It is recommended to have basic understanding of how OAuth2 and OIDC work to ensure proper configuration, though it's possible to just change the sample settings accordingly.
The OAuth2/OIDC configuration resides in OAuth2Server.yaml. See the file for comments on the settings. You should copy the file from config/vufind to your local configuration directory (e.g. local/config/vufind/OAuth2Server.yaml) and make changes there.
Server configuration contains settings for cryptography. Ensure that you use good random strings for
Clients contains settings for all known clients that should be allowed to use the authorization service.
Scopes contain definitions for sets of claims (user attributes) that can be requested from the user. These will not need changes for basic operation. Note that OIDC defines some sets that should contain predefined claims. These are marked with appropriate comments in the configuration and should not be changed. Supported claims can come from user's account in VuFind® as well as from the profile information from a library catalog.
ClaimMappings map the claims in scopes to the actual user attributes in VuFind®. These will not need changes for basic operation.
Grants allows fine-tuning life times of different tokens. These can typically be left as the defaults.
idp-oidc-tester is a very useful tool for testing the OIDC provider. Example to run it with docker:
docker run --rm --name idp-oidc-tester -p 8080:80 registry.gitlab.com/guenoledc-perso/idp-oidc-tester:latest
Access the service by pointing your browser to http://localhost:8080.
Make sure that the OIDC client in Docker can access token, jwks and user info endpoints of VuFind. E.g. if you run VuFind locally with Mac, use http://docker.for.mac.localhost/vufind/OAuth2/token or similar depending on what VuFind base url is.