docs: updated documentation on authentication

docs/architecture.md

@@ -122,9 +122,34 @@ Authentication and authorization are critical components of the APEx Dispatch AP
 In this scenario, all jobs are executed on the external platforms using a generic APEx service account that has access to them. This means that each job or upscaling task triggered through the API is executed on the platform under the APEx account, rather than the actual user’s identity. However, the Dispatch API maintains the link between the platform job ID and the user who initiated the request in its database.
 
 ```mermaid
-flowchart LR
-    C["Alice"] -- Request job---> D["APEx Dispatch API"]
-    D--Launch job as user APEx -->P1[Platform ]
+sequenceDiagram
+    participant UI as Client (UI)
+    box APEx
+        participant APEX_KEYCLOAK as APEx Keycloak
+        participant API as APEx Dispatch API
+    end
+    box Platform
+        participant EXTERNAL_KEYCLOAK as Platform Keycloak
+        participant EXTERNAL_API as Platform API
+    end
+
+    %% Flow
+    Note over UI,APEX_KEYCLOAK: Step 1 — User Authentication
+    UI->>APEX_KEYCLOAK: Authenticate user (OIDC login)
+    APEX_KEYCLOAK-->>UI: Return APEx user access token
+
+    Note over UI,API: Step 2 — Call APEx API with token
+    UI->>API: Request (Authorization: Bearer user_token)
+
+    Note over API,EXTERNAL_KEYCLOAK: Step 3 — Token Exchange
+    API->>APEX_KEYCLOAK: Initiate token exchange
+    APEX_KEYCLOAK->>EXTERNAL_KEYCLOAK: Request platform access token (via token exchange)
+    EXTERNAL_KEYCLOAK-->>APEX_KEYCLOAK: Return platform access token
+    APEX_KEYCLOAK-->>API: Return platform access token
+
+    Note over API,EXTERNAL_API: Step 4 — Access Platform Resource
+    API->>EXTERNAL_API: Invoke job (Authorization: Bearer platform_token)
+    EXTERNAL_API-->>API: Job accepted/response
 ```
 
 **Pros:**
@@ -156,4 +181,34 @@ flowchart LR
 **Cons:**
 
 * Propagating user identity across platforms is a technical challenge and currently lacks a proven, ready-to-use solution.
-* May require modifications on the target platform to support user impersonation, depending on the chosen implementation strategy.
+* May require modifications on the target platform to support user impersonation, depending on the chosen implementation strategy.
+
+
+#### Implementation: OIDC Token Exchange via APEx Keycloak
+The APEx Dispatch API implements user impersonation by utilising the OpenID Connect (OIDC) Token Exchange flow, which is facilitated through the APEx Keycloak instance. In this scenario, APEx Keycloak serves as an OIDC broker, interacting with external OIDC instances to enable secure and seamless user authentication across multiple platforms.
+
+To start, users authenticate via the standard login process through the APEx Keycloak. Leveraging the provided tools or scripts, the user’s APEx Keycloak access token is used to submit requests to the APEx Dispatch API by including their access token within the request headers. When the Dispatch API needs to interact with an external API, such as GEP’s OGC API - Process API or CDSE’s openEO API, it triggers a token exchange operation with the APEx Keycloak instance.
+
+```mermaid
+flowchart LR
+    C["Alice"] -- Request job---> D["APEx Dispatch API"]
+    D--Launch job as user APEx -->P1[Platform ]
+```
+
+Through this process, the APEx Keycloak uses the submitted user access token to issue an exchanged token corresponding to the external Identity Provider (IdP) of the target platform (e.g., GEP or CDSE). The resulting token functions as an external access token, recognised by the respective external platform and including the identity of the original requester. This token is then returned to the APEx Dispatch API.
+
+Upon receiving the exchanged token, the APEx Dispatch API proceeds to authenticate with the external API by presenting the external access token. This mechanism ensures that the external system accurately identifies the user, thereby maintaining continuity and integrity in user access and identity management across various platforms.
+
+##### Prerequisites
+The implementation of the Token Exchange process requires the following:
+
+* Every platform needs to be set up as an external IdP in APEx Keycloak, which includes creating a client on the external platform. 
+* The client used by the APEx Dispatch API must be authorised to perform token exchanges for the IdPs associated with supported platforms. This can be managed within the APEx Keycloak environment. 
+* For user token exchange, the user's account must be linked via the platform's IdP. Users can link their accounts through the APEx account dashboard or by signing into APEx with the corresponding external IdP.
+
+##### Considerations
+The following considerations should be noted in this scenario:
+
+* This scenario requires the user to possess a valid account on the platform with appropriate authorisation to access various resources.
+* Each platform must be onboarded individually as an external identity provider.
+* The association between the user's account and the external platform is subject to expiration, requiring the user to periodically re-link their account.

docs/contributing.md

@@ -42,4 +42,20 @@ class OGCAPIProcessPlatform(BaseProcessingPlatform):
 
 The processing type, defined by `ProcessTypeEnum`, is the unique identifier for the platform implementation. It is used to distinguish between different platform implementations in the system. This value is used by the different request endpoints to determine which platform implementation to use for processing the request. To add a new platform implementation, you will need to define a new `ProcessTypeEnum` value in the `app/schemas/enum.py` file. This value should be unique and descriptive of the platform you are implementing.
 
-Once you have completed the above steps, the new platform implementation will be registered automatically and made available for use in the APEx Dispatch API. You can then proceed to implement the specific functionality required for your platform.
+Once you have completed the above steps, the new platform implementation will be registered automatically and made available for use in the APEx Dispatch API. You can then proceed to implement the specific functionality required for your platform.
+
+### Best Practices
+
+#### Usage of dedicated client libraries
+
+When implementing a new platform, it is highly recommended to use dedicated client libraries for interacting with external services. This approach offers several advantages:
+- **Simplicity**: Client libraries often provide a higher-level abstraction over raw HTTP requests, making it easier to interact with the service.
+- **Error Handling**: Many client libraries come with built-in error handling mechanisms, reducing the need to implement custom error handling logic.
+- **Performance**: Client libraries may include optimizations for performance, such as connection pooling and efficient data serialization.
+- **Maintenance**: Using a well-maintained client library can reduce the maintenance burden, as updates and bug fixes are handled by the library maintainers.
+
+#### Dependency Management
+
+When adding new dependencies to the project, please ensure that they are declared in the `requirements.txt` file of the project. 
+This practice helps maintain a clear record of all dependencies required for the project and ensures that anyone working on the project can easily install the necessary packages.
+Additionally, this list of dependencies is used in the deployment process to set up the environment correctly.