Identity and Access Management

Content owner: christian.blumenroehr@roche.com, connolly.sean@gene.com
Authentication (AuthN) is the process of verifying someone (or application) claimed identity. It’s like proving you are who you say you are. Authorization (AuthZ) determines what a user can access. It does this after verifying them through authentication.
A general guideline is to separate authentication (who are you?) from authorisation (what can you do?).

Principles for authentication (AuthN)

Recommended Authentication Protocol: OAuth2/OIDC

We recommend OAuth2/OpenID Connect (OIDC) over SAML for several reasons that improve security, user experience, and developer efficiency

  • Modern Framework: OIDC is built on OAuth2, offering a flexible approach suitable for modern software development.

  • Optimized for Modern Apps: It provides streamlined flows for mobile and single-page applications (SPAs).

  • Standardized Identity: OIDC offers a well-defined method for obtaining verifiable user identity alongside resource authorization.

  • Simplified Development: The clear separation of authentication and authorization reduces misconfiguration risks.

  • Strong Ecosystem: OIDC benefits from vast community support and open-source tools, making integration easier than the often proprietary implementations required by SAML.

Note on SAML: While OIDC is preferred, some enterprise or third-party applications still use SAML. While this can complicate interoperability, these systems often do not require deep API integration.

Recommended Token Issuers

We equally recommend PingFederate (PingFed) and Janus (AWS Cognito) as token issuers:

  • PingFed: Historically used by pRED (D&A).

  • Janus: Historically used by gRED (gCS).

We are currently working with RDT to implement and support token exchange mechanisms between these token issuer environments. Furthermore we acknowledge that also tokens from the Google and Microsoft (EntraID) ecosystems are being used and we aim to support corresponding token exchange mechanisms in the future as well.

The following decision tree can help to decide which token issuer to be used:

graph TD
    A["Is OAuth2/OIDC<br/>being used?"] --> |No| B["✓ Use PingFed"]
    A --> |Yes| C{"Cross-RED<br/>application?"}
    C --> |Yes| D["✓ Ideally support both<br/>until token exchange<br/>is largely applied *"]
    C --> |No| E{"Deep AWS integration<br/>or gRED-facing?"}
    E --> |Yes| F["✓ Use Janus"]
    E --> |No| G["✓ Use PingFed"]

    style B fill:#90EE90
    style D fill:#FFD700
    style F fill:#87CEEB
    style G fill:#90EE90

*See token exchange. Besides the technical realization of the token exchange process in both Janus and PingFed (which are already done), there is also the fact that it is not yet largely applied. So while cross-RED applications can use either PingFed or Janus for their UI, they might need to accept tokens from both issuers in their APIs.

In addition this comparison might help:

Feature Janus PingFederate

SAML Support

✗

✓

OIDC Support

✓

✓

  • Authorization Code Grant

✓

✓

  • Implicit Grant

✓

✓

  • Client Credentials

✓

✓

  • PKCE

✓

✓

  • Device Authorization

✓

✓

  • Resource Owner Password Credentials

✗

✓

  • Decode Janus tokens

✓

✓

  • Decode PingFed tokens

✓

✓

AWS Integration

✓

✗

Developer Experience

✓

(✓)

  • GitOps Self-Service

✓

✗

  • Slack Support

✓

✗

  • gChat Support

✗

✓

  • Pipeline Status Viewing

✓

✗

  • Service Now Support

✗

✓

  • Service Now Provisioning

✗

✓

Concise & Up-to-date Documentation

✓

✓

SDKs, Example Integrations, Code Snippets

✓

(✓)

Supported Authentication Flows

As described in RFC 6749 several authentication flows are supported:

Authorization Code Grant Type: standard flow supported by PingFed. It is strongly encouraged to enhance it using PKCE (Proof Key for Code Exchange) by protecting the token exchange process.

Device Authorization Grant Type: preferred flow for cases without web application (e.g. command line interfaces). A separate device (e.g. phone) can be used for the authentication or you can also copy and paste the URL into your browser in order to authenticate.

ROPC (Resource Owner Password Credential): this flow is discouraged and only allowed in those cases when the normal authentication flows are not possible to implement. This might be the case for rich client applications that cannot handle redirects or when user tokens for generic users need to be created.

Client Credentials: this flow is an option for machine-to-machine integration where no end user is involved. It does not include the identity of a user (but only includes the information about the client application). Therefore this flow is basically comparable to using an API-key and its usage must be limited to cases where no end user is involved and where no user-based authorisation is needed.

The below image shows the standard way to secure a basic web application. Users authenticate into a web frontend through Roche SSO, and the app uses the user’s temporary access token to authenticate calls to its own API.

Key security points: - Token is from a trusted Roche issuer (iss) - Token is used by the intended audience (aud) - Token is sent by an identified client application (client_id) - Token is for minimal scopes (openid)

We recommend to use the "aud" claim in all SSO clients (PingFed, Janus) by default.

This was not yet the case so far, as e.g. the pRED standard token structure does not contain it. This will be changed soon and thus most of the pRED tokens will contain an "aud" claim.

authentication

Token handling

JSON Web Tokens (JWTs) are a compact, URL-safe means of representing claims to be transferred between two parties. They consist of three parts: Header, Payload, and Signature.

  • Header: Typically consists of two parts: the type of token (JWT) and the signing algorithm used (e.g., HMAC SHA256).

  • Payload: Contains claims, which are statements about an entity (typically, the user) and additional data. Standard claims include issuer (iss), subject (sub), expiration (exp), etc.

  • Signature: Ensures the integrity and authenticity of the token. The signature is created by signing the header and payload with a secret key using the specified algorithm.

The following types of Tokens in OAuth2/OIDC exist:

ID Tokens:

  • Audience: The Client Application.

  • Purpose: The primary function of the ID token is to verify the identity of the user. It is intended for the client application (relying party) to authenticate the user and typically includes claims about the authentication event.

  • Content: ID tokens are JWTs that contain claims such as the user’s unique identifier, issuer, etc.

  • Usage: ID tokens are used locally by the client application and are not used for accessing resources; instead, they are used to prove that the user has authenticated.

  • TTL (time to live): by default 2 hours for PingFed tokens and 1 hour for Janus tokens.

The ID token MUST NOT be used for authentication in APIs.

Access Tokens:

  • Audience: The Resource Server (APIs).

  • Purpose: Access tokens in OIDC are used to authorize access to protected resources.

  • Content: Contains claims relevant to resource access.

  • Usage: Access tokens are presented to resource servers to gain access to the user’s resources. They carry sufficient information (claims) for the resource server to determine the authorization level of the request.

  • TTL (time to live): by default 2 hours for PingFed tokens and 1 hour for Janus tokens.

OAuth2 access tokens must be passed to the API clients as "Bearer" tokens. The clients calling the APIs are bearers of the identity of a user for the request made. Users delegate the handling of their identity to the client. The standard way of submitting access tokens is via the “Authorization” header. This is the default and should be assumed by every API implementation as well as by every API integration.

Refresh Tokens:

  • Purpose: Used to obtain new access and ID tokens without requiring the user to re-authenticate. Also a new refresh token is issued.

  • TTL (time to live): by default 2 days for PingFed tokens and 30 days for Janus tokens.

Claims

While the ID token is a key innovation of OIDC, specifically designed to prove that a user has been successfully authenticated by the Authorization Server (Identity Provider), OIDC also influences the structure and content of access tokens. By supporting JWT format for access tokens, OIDC allows these tokens to carry user-related claims that can assist resource servers in making authorization decisions.

To ensure interoperability, a standardized set of claims should be included particularly in the Access tokens which are propagated to other systems.

While it is optional to add identity related claims into the Access Token JWT it is commonly done to simplify the work the API needs to do to handle the request after validating the token. In this case the token can use the user information for the purpose of authorization (not authentication), e.g. by checking if the user is in the group of allowed users to receive the requested resource. Note that it is up to the API to use the identifying information or not, but if the API needs the users id and it is missing this information in the token in the right and agreed claim it can’t handle the request, which would be an issue for the integration.

Alternatively, the userinfo endpoint could be called to fetch the user’s ID token, but also here an agreed upon standard will be needed.

Standardized claims are:

  • iss (Issuer): Identifies the principal that issued the JWT (e.g., https://wam.roche.com). This tells the recipient who created the token.

  • client_id: Identifies the specific application that requested the token. While not a standard JWT registered claim, it’s ubiquitous in OAuth2/OpenID Connect flows.

  • aud (Audience): Identifies the intended recipients of the JWT. If the service receiving the token isn’t in this list, it should reject the token.

  • sub (Subject): The unique identifier for the user. This is the "who" the token represents. There is a difference between PingFed and Janus tokens. While PingFed tokens contain here the Roche user ID, Janus tokens contain an AWS Cognito UUID for the user.

  • preferred_username: Contains the Roche user ID in Janus tokens ("sub" and "username" contain other information due to AWS Cognito).

  • groups: A custom or OIDC-extension claim listing the security groups or roles the user belongs to, often used for authorization (RBAC). For PingFed tokens it is discouraged to use this claim (no nested groups are supported) and authorization should be separated from authentication.

  • exp: The exact timestamp when the token becomes invalid. Crucial for security.

  • scope: The specific permissions granted (e.g., openid profile, read:profile, write:orders).

Scopes

To be added

Token Validation

Tokens must always be validated. Access Tokens are issued as JWTs (see jwt.io for details), these JWTs can be decoded and interpreted easily. However the payload of a JWT can also be changed as easily (e.g. changing the expiration date or the user ID). Therefore proper validation is required.

Token Exchange

Please have a look at the dedicated Token Exchange page.

Technical information and knowledge base

Please have a look at How to: PingFed and How to: Janus for further information.

Principles for authorization (AuthZ)

This section is still a work in progress and will be updated to provide a holistic view of the CS CoE.

See also the Knowledge Base article for more detailed information.

Membership in CIDM/AD groups

Access to applications or resources in general is often granted upon membership in dedicated groups. These can be managed in CIDM and are reflected in Active Directory. Besides manually maintained groups, there is also the possibility to define groups which are automatically updated based on some AD filter (see template in RoSE).

See the Knowledge Base on information about possibilities to check a user’s group membership.

Project-based access management (PBAM)

While the previous approach works for general access to an application more fine-grained and row-level access management is needed when data from different projects (or other categories like studies) are accessed. In pRED D&A we introduced RedPanda (UI, API) as a tactical solution for managing access to data belonging to portfolio project.

As part of the RDE WS7 project PBAM (project-based access management) RedPanda has been formalized as the Single Source of Truth for cross-portfolio project metadata. Therefore all systems currently sourcing project metadata from MRHub, RDP or other related systems should migrate from these systems to RedPanda. Systems connected to MAPS can stay as is, as we are still working on the positioning of MAPS regarding RedPanda and the integration of the two systems. As part of this activity the implementation of PBAM can also be performed using the RedPanda API.

Policy-based access control (PBAC)

While PBAM is focused on project data, PBAC is a more generic approach to consistently and securely control the access to arbitrary data based on policies. These policies are based on metadata from the accessing user and the protected resource and define rules about who can access what and when.

In the context of RDE WS7 Data Foundations PBAC has been introduced as a general concept and the PBAC platform of PlainID has been identified as the strategic solution. The new PBAC platform will be introduced during 2026 and project-based access management (PBAM) will be onboarded as one of the first use cases. Afterwards (timeline still to be decided), applications currently using RedPanda to decide about the access to projects by users can switch to the APIs provided by the PBAC platform. However, RedPanda will still be needed to get the project metadata.