The aim of this effective summary is to underline key points in updates to existing Cochrane authentication system.
Please follow the link for the full description of OAuth 2.0 authentication in Keycloak.
Cochrane's authentication system is based on the OAuth 2.0 authorization framework to enable 3rd-party applications (clients) to obtain limited access to a service on behalf of resource owner (end user). As OAuth 2.0 is just a framework, it required specific implementation. Originally, in Cochrane's ecosystem OAuth was implemented through Archie's functionality, i.e. Arhcie was the authentication server which was providing access token to clients.
In the setup described above Archie plays two main roles - authentication server and central point for managing people, documents and editorial process. This means that Archie is overwhelmed with responsibilites, which has negative impact on whole system operation: for example, when Archie is restarted users are logged out of the system and have to log in again.
The main objective of the inititative is to separate concerns by dividing components involved in authentication and management of user accounts and managmement of editorial process into different systems. In the new setup Archie will only be responsible for managing people, documents, and editorial process. This will allow to develop and operate both systems - Archie and the authentication system - independently.
Key parts to be separated from Archie are:
To fit project aims the best out-of-the-box solution was selected - Keycloak, an open-source identity and access management system. Major features from Keycloak which are utilized in the new SSO system are:
Key attributes of the user profile have been moved from Archie to Keycloak. This includes family and given name, email addresses, and country of residence. More information on fields moved can be found there.
Registration of the client (before start using the system) is done using standard Keycloak administration tools. More information can be found there.
Important! The Archie “Person ID” (i.e. “Cochrane ID”) has to be used to be able to identify the users by external systems.
| Environment | KEYCLOAK_BASEURL |
|---|---|
| test | https://test-login.cochrane.org/ |
| training | https://training-login.cochrane.org/ |
| production | https://login.cochrane.org/ |
Endpoints are changed to Keycloak endpoints - Authorization and Token endpoints:
The authorization endpoint performs authentication of the end-user. This is done by redirecting the user agent to this endpoint.
${KEYCLOAK_BASEURL}/auth/realms/cochrane/protocol/openid-connect/authThe token endpoint is used to obtain tokens. Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used. The token endpoint is also used to obtain new access tokens when they expire.
${KEYCLOAK_BASEURL}/auth/realms/cochrane/protocol/openid-connect/tokenNon-standard secondary endpoints such as token information and token revoking endpoints were decomissioned. As JWT (JSON Web Tokens) is used, information about access token is embedded in the token itself.
For token revocation token expiration setting should be used. More information can be found there.
Important! A new permissions endpoint was implemented in Archie to replace the "permissions=true" functionality of the decomissioned tokeninfo endpoint. More information can be found there.
Non-standard token validation used in Archie is changed to standard OAuth 2.0 validation mechanism in Keycloak. There are two options to validate token - using Introspection Endpoint and validating tokens locally. More information can be found there.
Keycloak produces JSON Web tokens (JWT) with configured data sets (JWT claims) so token length is not fixed. If token needs to be saved in the system / database, 4000 characters length is recommended for both access token and refresh token.