About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools

Warning: This page has not been updated in over over a year and may be outdated or deprecated.

OAuth2 and OpenID Connect Authorization Server

Page Owneremaijala

:!: 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.

VuFind Configuration

:!: 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.

The Server configuration contains settings for cryptography. Ensure that you use good random strings for encryptionKey and hashSalt.

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.

Finally, Grants allows fine-tuning life times of different tokens. These can typically be left as the defaults.


The following endpoints are available:

  • Authorization: /OAuth2/Authorize
  • Tokens: /OAuth2/Token
  • OIDC user info: /OAuth2/UserInfo
  • Server's public keys: /OAuth2/jwks


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 macOS, use http://docker.for.mac.localhost/vufind/OAuth2/token or similar depending on what VuFind base url is. Here are example settings when running macOS and VuFind in http://localhost/vufind:

Setting Value
Discover url (leave empty)
Authorize url http://localhost/vufind/OAuth2/authorize
Token endpoint http://docker.for.mac.localhost/vufind/OAuth2/token
JWKS endpoint http://docker.for.mac.localhost/vufind/OAuth2/jwks
Issuer https://docker.for.mac.localhost
Instrospection endpoint (leave empty)
User info endpoint http://docker.for.mac.localhost/vufind/OAuth2/userinfo
End session endpoint http://docker.for.mac.localhost/vufind/OAuth2/logout
Register as redirect_uri http://localhost:8080/session/callback
Client id tester
Client secret secret
Scopes openid profile address block_status
configuration/oauth2_oidc.txt · Last modified: 2023/05/12 07:13 by emaijala