| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| configuration:oauth2_oidc [2022/09/13 09:36] – emaijala | configuration:oauth2_oidc [2023/05/12 07:13] (current) – [Testing] emaijala |
|---|
| ====== OAuth2 and OpenID Connect Authorization Server ====== | ====== OAuth2 and OpenID Connect Authorization Server ====== |
| |
| :!: Available from VuFind 9.0. | :!: 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 [[https://openid.net/connect/|OpenID Connect]] for more information on how OIDC works. | 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 [[https://openid.net/connect/|OpenID Connect]] for more information on how OIDC works. |
| |
| Recommended read: [[https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1|OpenID Connect Primer]] | Recommended read: [[https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1|OpenID Connect Primer]] |
| ===== Available User Information ===== | ===== 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 ([[https://vufind.org/wiki/development:plugins:ils_drivers#getmyprofile|getMyProfile]] method) can be added into a scope that a client can request. | 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 ([[development:plugins:ils_drivers#getmyprofile|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. |
| |
| ===== Prerequisites ===== | ===== Prerequisites ===== |
| |
| ===== Configuration ===== | ===== Configuration ===== |
| | |
| | ==== 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. | :!: 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. |
| ''Clients'' contains settings for all known clients that should be allowed to use the authorization service. | ''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. | ''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. | ''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. | Finally, ''Grants'' allows fine-tuning life times of different tokens. These can typically be left as the defaults. |
| | |
| | ===== Endpoints ===== |
| | |
| | The following endpoints are available: |
| | |
| | * Authorization: /OAuth2/Authorize |
| | * Tokens: /OAuth2/Token |
| | * OIDC user info: /OAuth2/UserInfo |
| | * Server's public keys: /OAuth2/jwks |
| | |
| | ===== Testing ===== |
| | |
| | [[https://gitlab.com/guenoledc-perso/idp-oidc-tester|idp-oidc-tester]] is a very useful tool for testing the OIDC provider. Example to run it with docker: |
| | <code> |
| | docker run --rm --name idp-oidc-tester -p 8080:80 registry.gitlab.com/guenoledc-perso/idp-oidc-tester:latest |
| | </code> |
| | 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 | |
| ---- struct data ---- | ---- struct data ---- |
| properties.Page Owner : emaijala | properties.Page Owner : emaijala |
| ---- | ---- |
| |
