Skip to content

ADR: GCZ Authorization in OSDU with Entitlements

Status

  • Proposed
  • Trialing
  • Under review
  • Approved
  • Retired

Context & Scope

In the OSDU framework, a uniform approach to authentication and authorization (AuthN/Z) is paramount across all services. The Entitlements service is a crucial, non-bypassable component of this process, authenticating the principal's identity using one of its supported modes (considering either a token or an "x-user-id" header depending on the mode), and providing the roles assigned to the principal for subsequent authorization.

The journey of principals seeking to access OSDU typically involves:

  • Receiving tokens from an Identity Provider (IDP) specific to each OSDU instance, or getting a user ID via an 'identity aware proxy' to be used in the "x-user-id" header (depending on the authentication mode used).
  • The OSDU's Entitlements service independently validates either the provided token against the IDP or the user ID from the "x-user-id" header, confirming the principal's authenticity in every interaction.
  • Post-authentication, the service cross-checks if the authenticated principal exists within the OSDU's Role-Based Access Control (RBAC) database, retrieves the roles linked to the principal, and forwards them to the originating service.
  • Consequently, the originating service relies on these returned roles to conduct authorization checks.

Despite this framework-wide norm, the Geo Consumption Zone (GCZ) services, comprising the Transformer and Provider, currently do not adhere to this process.

Transformer & Provider: At present, these services utilize their independent AuthN/Z structures. However, they fail to comply with the defined OSDU AuthN/Z standards, prompting a necessary revision of their current AuthN/Z systems.

This ADR aims to align the Transformer and Provider services with OSDU's AuthN/Z protocol by proposing suitable AuthN/Z mechanisms, thereby ensuring OSDU-compliance.

Decision

In an effort to meet OSDU's AuthN/Z standards, a robust revision is planned for the Geo Consumption Zone (GCZ) services - Transformer and Provider.

Our strategy includes:

  • Removing native built-in AuthN/Z features in both services to prevent potential security risks.
  • Mandating all inbound calls in both services to pass authentication through the Entitlements service. This means that any incoming user tokens or "x-user-id" headers, depending on the mode, will be validated using the Entitlements service.
  • To access APIs in either the Transformer or the Provider, principals must hold one of these roles: service.gcz.viewer, service.gcz.creator, or service.gcz.admin.
  • The Transformer will include Access Control Lists (ACLs) into the Ignite DB during data ingestion. This information will later serve as a reference for filtering records based on roles of the authenticated users.
  • The Provider will apply filtering to only return records that align with the roles of authenticated users, as specified in the record's ACLs.

Specific adjustments include:

Transformer:

  • As it is a Java Spring service, it will have common AuthN/Z code and interfaces added directly, with the specifics managed by CSP modules.
  • To accommodate its background operations and the Entitlements service modes, the use of service account (system users) credentials, and IDP-clients for token generation, and extraction of user ID from token when necessary, are proposed.

Provider:

  • Based on Koop.js, the Provider will be equipped with a newly introduced "osdu-auth" plugin for AuthN/Z management and Koop.js will be reconfigured to utilize this plugin, supporting both token and "x-user-id" header based authentication modes.

The overall goal of this decision is to ensure that the AuthN/Z mechanisms of the Transformer and Provider services comply with OSDU's standards, irrespective of the CSP in use.

The following diagram shows the target resulting state of the GCZ component image

Rationale

Adopting a consistent and secure AuthN/Z protocol across GCZ services to comply with OSDU standards requires consideration of user roles as part of the access control. Specifically, access to both Transformer and Provider APIs necessitates the assignment of particular roles: service.gcz.viewer, service.gcz.creator, or service.gcz.admin. This role-based authorization ensures that only principals with the necessary permissions can interact with the APIs.

  • Transformer:

    • The Transformer will utilize service account credentials and Identity Provider (IDP) clients for token generation.
    • It will also have the capability to extract the user ID from the token when necessary, aligning with the modes of the Entitlements service.
    • In addition it will include the record ACLs during data ingestion into Ignite DB.

  • Provider:

    • Given the existing AuthN/Z inadequacies, the introduction of an "osdu-auth" authentication plugin for Koop.js is necessary.
    • This will enable it to enforce the AuthN/Z rules effectively, in adherence with the modes of the Entitlements service and the role-based access.
    • Alongside necessary AuthN/Z enhancements, the Provider will restrict data returned to users based on ACLs associated with each record - essentially returning only those records that contain at least one role which matches those of the authenticated user.

In essence, this approach aims to standardize the Transformer and Provider services' AuthN/Z mechanisms, ensure role-based access control and extend their compatibility to multiple CSPs.

Consequences

With the implementation of the proposed changes, the GCZ services can expect:

  • Enhanced security due to alignment with OSDU's secure AuthN/Z standards.
  • Seamless functionality across different cloud platforms as a result of multi-CSP compatibility.
  • Possible technical challenges could arise during the implementation or maintenance of the CSP-specific modules for the Transformer service.
  • Upon implementation, any services interacting with GCZ's Transformer and Provider services will be required to follow the new, multi-CSP compatible AuthN/Z protocols that are compliant with the Entitlements service modes.

Through careful planning and execution, this implementation will align the GCZ services with the OSDU's AuthN/Z protocol, ensuring a secure and efficient GCZ platform.

When to revisit

Tradeoff Analysis

Pros:

  • Improved security and OSDU compliance.
  • Multi-CSP operation ensures smooth functionality across platforms.

Cons:

  • Increased complexity due to implementation of CSP-specific modules and new plugins.
  • Maintenance effort and costs could rise due to increased complexity.
  • Possible updates needed if OSDU's AuthN/Z protocol or specific CSP changes.

Overall, the proposed changes offer significant security and standardization benefits, but warrant consideration for potential complexity and maintenance implications.

Alternatives and implications

  • Maintaining Status Quo: Services continue using their current AuthN/Z mechanisms.

  • Partial Adoption of OSDU's AuthN/Z Protocol: Services adopt some aspects of OSDU's AuthN/Z, while maintaining elements of their current systems.

  • Fully Customized AuthN/Z Mechanisms: Design of a custom AuthN/Z mechanism mirroring OSDU's protocol.

Each of these choices comes with its own challenges. The proposed solution of revising the AuthN/Z mechanisms for the GCZ services to align with the OSDU's protocol, while also accommodating CSP-specific requirements, aligns the trade-offs most effectively.

Decision Criteria and Trade-offs

The decision for this AuthN/Z revision focused on three primary criteria: security alignment with OSDU's standards, seamless multi-CSP operation, and future extensibility.

The trade-offs considered in the proposal include:

  • Security vs. Complexity: Enhancing security by adopting OSDU's robust AuthN/Z protocol introduces complexity in both the Transformer and Provider services. However, the security enhancement is deemed worthy of the increased complexity.

  • Multi-CSP Operation vs. Maintenance Effort: Designing CSP-extendable GCZ services ensures CSP interoperability and future flexibility but may increase the maintenance effort due to CSP-specific modules in the Transformer.

  • OSDU Compliance vs. Customization: Although a fully customized AuthN/Z mechanism can provide complete control and potential customization, it may fall out of sync with OSDU's evolving standards and entail more overhead.

Given these trade-offs, adopting OSDU's AuthN/Z protocol in the GCZ services, while extending the token generation in the Transformer for multi-CSP compatibility, is identified as the most balanced and suitable approach.

Decision timeline

[TBD]

Edited by Rostislav Dublin (EPAM)