Authentication

Authentication

Welcome to the Authentication guide of the PHYLOViZ Web Platform documentation! Here, we provide an overview of the authentication process and components used within the platform. Authentication plays a crucial role in securing access to the platform and its resources, ensuring that only authorized users can interact with the system.

The authentication sequence is depicted in the following image:

Keycloak

For user authentication, the PHYLOViZ Web Platform utilizes the Keycloak server. Keycloak is an open-source software product that enables single sign-on with Identity and Access Management capabilities. It is configured to use the OpenID Connect protocol.

Keycloak serves as the Identity and Access Management (IAM) solution for the platform, providing authentication, authorization, and user management features. It supports various protocols such as OAuth2, OpenID Connect, and SAML.

In the context of the PHYLOViZ Web Platform, Keycloak acts as the OpenID identity provider. It authenticates users and issues access tokens, which are used to access protected resources.

Gateway

The platform uses Spring Cloud Gateway as an OpenID client. Spring Cloud Gateway leverages Keycloak's OIDC capabilities to authenticate users. Once a user is authenticated, Spring Cloud Gateway utilizes the received access token from Keycloak to forward requests to the appropriate microservice.

Microservices

The microservices in the platform act as OpenID resource servers. They validate the access token received from Spring Cloud Gateway to ensure that the user is authorized to access the requested resource.

Authentication Process

The authentication process follows these high-level steps:

1. The user sends a request to access a protected resource.
2. Spring Cloud Gateway intercepts the request and redirects the user to Keycloak's login page.
3. The user enters their credentials on Keycloak's login page and submits the form.
4. Keycloak authenticates the user and generates an access token, which contains the user's identity and authorization information.
5. Keycloak sends the access token back to Spring Cloud Gateway through User-Agent redirection.
6. Spring Cloud Gateway receives the access token and stores it in a session cookie.
7. Spring Cloud Gateway forwards the request, along with the access token, to the appropriate microservice.
8. The microservice receives the request and validates the access token through introspection, ensuring that the user is authorized to access the requested resource.
9. If the access token is valid, the microservice processes the request and sends a response back to Spring Cloud Gateway.
10. Spring Cloud Gateway receives the response and forwards it back to the user.

Configuration

To configure the authentication components, follow these steps:

Configure the Keycloak Server:

1. Log in to the Keycloak server administration console (localhost:8082) with username admin and password admin.
2. Navigate to the "phyloviz-web-platform" realm, in the dropdown menu above manage.
3. Click on "Clients" in the left-hand menu.
4. Select the "phyloviz-web-platform-client" client.
5. In the "Credentials" tab, click "Save", "Regenerate Secret", and then copy the "Secret" value to your clipboard.

Configure the Spring Gateway and Microservices:

Replace the client-secret with your Keycloak client Secret from your clipboard after keycloak configuration:

1. In src/backend/microservices/shared/src/main/resources/application-shared.yml:

   spring:
     security:
       oauth2:
         resourceserver:
           opaquetoken:
             client-secret: YOUR_CLIENT_SECRET_HERE

2. In src/backend/microservices/gateway/src/main/resources/application.yml:

   spring:
     security:
       oauth2:
         client:
           registration:
             phyloviz-web-platform-client:
               client-secret: YOUR_CLIENT_SECRET_HERE

By following these configuration steps, you will ensure the proper setup of the Keycloak server, Spring Cloud Gateway, and microservices for authentication within the PHYLOViZ Web Platform.

Please note that the repository includes a Keycloak configuration file containing the required client and provider configurations. However, you must configure the secrets yourself, as they are not included in the repository.

Ensure that you properly secure the secrets and follow best practices for managing sensitive information.