Identity & Access Control =========================== The LEXIS Platform separates **authentication**, **authorisation**, and **credential management** into distinct services. Keycloak establishes the authenticated user identity and issues OpenID Connect tokens through connected identity federations such as MyAccessID. UserOrg applies platform-specific authorisation rules using the LEXIS Platform Project and resource abstraction model. Expirio service manages credentials and external-service tokens that must remain available securely for long-running or automated workflows and for external services. Authentication & Federated Identities --------------------------------------- The LEXIS Platform uses **Keycloak** as its central authentication service and OpenID Connect (OIDC) provider. User-facing applications and platform APIs rely on Keycloak-issued access tokens rather than maintaining independent login sessions or password databases. Keycloak acts as an **identity broker** between the LEXIS Platform and external identity providers. A user authenticates with a supported federation, while LEXIS Platform services receive a consistent OIDC identity and token format from Keycloak. The LEXIS Platform supports delegated authentication through established research and education identity services, including: * **MyAccessID**, which provides access to federated academic and research identities, including identities available through eduGAIN and related infrastructures; * **EUDAT B2ACCESS**, which provides federated authentication for European research and data services; * additional identity providers configured through Keycloak where required. The authentication path is conceptually:: User | v LEXIS Portal / APIs / Services (Login) | v External Identity Federation (MyAccessID / B2ACCESS / other IdP) | v Keycloak (Identity Brokering & Authentication) | v OIDC Access Token | v LEXIS Portal / APIs / Services (Entry) Keycloak is therefore the trust boundary for validating user authentication. It normalises identities from different federations and exposes them to LEXIS Platform services through standard OIDC and OAuth 2.0 mechanisms. Various multi-factor (MFA) authentication policies enforced by the federated identity providers remain in place, as Keycloak issues the token only if the upstream service authenticates the user successfully. Authentication does not by itself grant access to a project, dataset, workflow, or computing resource. A valid Keycloak token establishes **who the user is**; platform authorisation determines **what that user is allowed to do**. Authorisation & UserOrg RBAC ------------------------------ Platform authorisation is handled separately from authentication. The LEXIS Platform uses a custom **role-based access control (RBAC) matrix** implemented in the **UserOrg** backend service. UserOrg maintains the platform relationships required for authorisation, including: * LEXIS Platform Projects and project memberships; * user roles within projects; * providers and computing resources; * application management on project level; * mappings between LEXIS Platform Projects, users, provider allocations, and resources. A request to a protected service normally contains a JWT Bearer token. The authenticated identity is extracted from the token, while the requested operation is evaluated against UserOrg's RBAC and project/resource relationships. Conceptually: .. code-block:: text Keycloak Authenticated Identity | v LEXIS Platform Service | +----> UserOrg RBAC matrix Project Membership Resource Mappings | | | v +<---- Allow / Deny | v Requested Operation This separation allows identity federation to evolve independently of the LEXIS Platform authorisation model. Keycloak does not need to encode all project, resource, and workflow permissions into federation identities or long-lived token roles. UserOrg remains the authoritative source for application-level authorisation decisions that depend on LEXIS Platform entities. This model does not replace the local resource provider policies; it merely abstracts the common way in which HPC or Cloud resources are provided to users through allocations granted by various national or European bodies. The LEXIS Platform provides an additional layer on top of local provider policies, allowing uniform addressing of similar computing resources operated by different entities. Typical authorisation questions include: * Is the user a member of the selected LEXIS Platform Project? * Does the user's project role allow the requested operation? * May the project access the selected dataset or workflow? * Is the selected computing resource allocation assigned to the project? * Does the project map to an appropriate provider-side compute allocation? * May the user manage other project members or project-level resources? The resulting model separates responsibilities as follows: .. list-table:: Identity and authorisation responsibilities :header-rows: 1 :widths: 25 75 * - Component - Responsibility * - Keycloak - Authentication, identity brokering, OIDC/OAuth 2.0 token issuance, and validation of the authenticated user identity. * - UserOrg - LEXIS Platform-specific RBAC, project membership, project and resource mappings, and application-level authorisation decisions. * - Resource provider - Final enforcement of provider-side allocations, scheduler policies, quotas, and infrastructure-specific permissions. Projects as the Access Context ------------------------------ The central organisational entity is the **LEXIS Platform Project**. A project defines the collaboration and authorisation context in which users access datasets, workflows, applications, and computing resource allocations. A project context handles the following areas: * project membership; * user roles and permissions; * access to project datasets and workflows; * access to one or more computational allocations; * ownership and visibility boundaries for workflow executions and results, including logs from HPC batch jobs; The LEXIS Platform distinguishes between platform-level authorisation and provider-level resource allocation. .. code-block:: text User | v LEXIS Platform Project | v Resource Allocation | v Provider Allocation Users should distinguish between: * **Identity** -- who performs an operation; * **Project Membership** -- in which collaboration context the operation is performed; * **Role** -- which actions the user may perform in that project; * **Resource Authorisation** -- which computing resources the project can access; * **Compute Allocation** -- which provider-side allocation is charged for execution; * **Data Permissions** -- which datasets the user or project can access. This separation allows the LEXIS Platform to provide a common project and authorisation model while preserving the accounting and enforcement mechanisms of each infrastructure provider. Expirio & Secure Credential Lifecycle --------------------------------------- **Expirio** provides secure handling of tokens, credentials, and secrets that are required by workflows but should not be stored directly in workflow definitions, Airflow DAGs, task parameters, or user scripts. Its role is complementary to Keycloak. A Keycloak access token authenticates the user to LEXIS Platform services, while workflows may also need credentials for external systems such as repositories, remote APIs, data services, or other infrastructure that uses a separate authentication domain. Expirio covers two main use cases: * **External-Service Tokens** -- credentials obtained when a user authorises the LEXIS Platform to access an external service on the user's behalf; * **User-Defined Secrets** -- passwords, API tokens, URLs, keys, or other sensitive configuration values explicitly stored for later workflow use. For token-based external integrations, Expirio provides a controlled token lifecycle boundary. The platform can retain the credentials required to continue using an authorised external service without exposing refresh tokens or equivalent long-lived credentials to workflow definitions. Where supported by the external service, token renewal can be handled through the stored authorisation material so workflows consume a usable credential rather than implementing token refresh themselves. The conceptual flow is:: User Authorisation | v External Service | v Access / Refresh Credentials | v Expirio Secure Vault | +----> Token Lifecycle Handling | v Workflow Task Receives Credential only when Required | v External Service API Secrets are referenced logically by workflows instead of being embedded in workflow source. This is particularly important for reusable LWD definitions and workflows stored in a shared catalogue, where executable logic can be shared without distributing the credentials of the workflow author. Examples include: * access and refresh tokens for external APIs; * repository or data-service credentials; * passwords for encrypted input or output data; * API keys required by a workflow application; * connection parameters and other protected configuration values. The intended security boundary is:: Workflow Definition Contains Reference | v Secret Identifier | v Expirio Secure Storage | v Authorised Retrieval | v Workflow Task Workflow components should treat credentials obtained through Expirio as short-lived execution inputs and avoid persisting them in task logs, workflow metadata, generated datasets, or other user-visible artifacts. Together, Keycloak, UserOrg, and Expirio form three separate security functions: .. code-block:: text Keycloak UserOrg Expirio -------- ------- ------- Which external Who are you? What may you do? credentials may this workflow use? OIDC Authentication RBAC and Project Secret vault Identity Federation Authorisation Token lifecycle Access Tokens Resource mappings This separation keeps federated identity, platform authorisation, and external credential handling independently manageable while presenting a unified security model to LEXIS Platform users and workflows. Identity Mapping to HPC Accounts with HEAppE -------------------------------------------- LEXIS Platform users are authenticated using institutional identity through the identity federation services, while an HPC system normally executes jobs under a local operating-system account. HEAppE provides the mapping between these two identity domains. The mapping is associated with a particular LEXIS Platform Resource and its underlying provider allocation. The same external user can therefore be mapped to different local identities on different Resources. Identity mapping is separate from authorisation. UserOrg determines whether the user is allowed to access the LEXIS Platform Project, Computational Project, and Resource. HEAppE subsequently resolves the authorised external identity to the local identity under which the job is executed. Conceptually:: External Identity | | authenticated by Keycloak v LEXIS Platform User | | authorised by UserOrg v LEXIS Platform Project | v Resource Allocation | | identity mapping by HEAppE v Local HPC Identity | v Scheduler / Compute Nodes Service Account per Resource Allocation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the service-account model, multiple external users authorised to use the same resource allocation are mapped to a common functional account created specifically for that allocation. For example:: External User A --\ \ External User B ----> LEXIS Platform Project / | External User C --/ v Resource Allocation | v HEAppE | v svc_lexis_project123 | v HPC Scheduler The service account belongs to the provider-side project or accounting allocation and is normally valid only for the lifetime and scope of that allocation. This strategy avoids the requirement to create a local HPC account for every LEXIS Platform user. It is particularly useful for resources exposed primarily through LEXIS Platform APIs and workflows, where users are not expected to log in directly to the cluster. The main properties of this model are: * the local account represents an allocation rather than an individual user; * all authorised users of the allocation can execute through the same account; * scheduler accounting is associated with the provider allocation; * user-level identity remains available in the LEXIS Platform and HEAppE audit information; * filesystem ownership is typically shared at the service-account level; * project workspaces and DDI staging locations should be preferred over user-specific home directories. Because the operating system sees the shared service account, traceability of individual users must be maintained by the higher layers. The LEXIS Platform and HEAppE should therefore preserve the originating external identity, workflow execution, job identifier, and project context in their audit information. The service account does not grant access by itself. A user must first be authorised for the corresponding Computational Project and Resource before HEAppE can use the mapped account for job execution. One-to-One Mapping to Local User Accounts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the one-to-one model, each external identity is mapped to the existing local HPC identity of the same person. For example:: Federated Identity user@example.org | v Keycloak | v LEXIS Platform User | v HEAppE | | identity mapping v Local User jsmith | v Provider Allocation | v HPC Scheduler The local account must exist at the provider and must have access to the provider-side project or allocation corresponding to the LEXIS Platform Computational Project. This strategy preserves the site's traditional user model. Jobs execute under the same local identity that would be used if the user accessed the HPC system through other supported interfaces. The main properties of this model are: * each external identity maps to a distinct local operating-system identity; * filesystem ownership remains attributable to the individual user; * existing local quotas, policies, and accounting mechanisms can be reused; * provider-side audit information directly identifies the local user; * users can use existing project and home directories where permitted; * local account provisioning and deprovisioning must be coordinated with external identity lifecycle. The mapping should preferably use a stable external identifier rather than a mutable property such as a display name. Depending on the identity federation, this can be an immutable subject identifier or another persistent identifier provided by the federation. A mapping is local to a site and Resource. The LEXIS Platform does not require a user's local account name to be identical at every provider. For example:: External identity: 12345678@federation Resource A -> local user: jsmith Resource B -> local user: john.smith Resource C -> service account: lexis_proj42 Different sites can therefore apply different mapping strategies to the same LEXIS Platform identity. Choosing an Identity Mapping Strategy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The appropriate mapping strategy is determined by the resource provider. The service-account model is suitable when: * compute access is provided primarily through workflows and APIs; * allocations are assigned to projects or teams; * per-user local account provisioning should be minimised; * users do not require direct interactive access to the cluster. The one-to-one model is suitable when: * the provider requires an individual local account for every user; * filesystem ownership must identify individual users; * existing site accounting or audit policies require local user identities; * users also access the same allocation through provider-native interfaces. A site can support both models. The mapping strategy may be selected independently for different Resources or allocations. Identity & Authorisation Boundaries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The identity chain should be understood as a sequence of independent responsibilities:: Identity Federation | v Keycloak Authentication | v UserOrg Authorisation / RBAC | v LEXIS Platform Resource & Allocation | v HEAppE Identity Mapping | v Local HPC Account | v Scheduler Authorisation Keycloak establishes who the user is. UserOrg determines which LEXIS Platform Projects, Computational Projects, and Resources the user is authorised to use. HEAppE translates the authorised external identity and resource context into the local execution identity required by the HPC infrastructure. The local scheduler finally applies provider-specific allocation, queue, partition, quota, and accounting rules. Identity mapping therefore does not extend a user's authorisation. It only determines the local execution identity used after access to the corresponding LEXIS Platform Resource has already been authorised.