Entitlements V2 standard implementation for all providers

Status

Context & Scope

Currently the only service that does not follow the implementation pattern of sharing a common interface and business logic layer and implementing the common SPI is Entitlements.

This has lead to a divergence in the interface and behavior of the service between providers. For instance few implementations do not have hierarchical groups and do not support the concept of group owners vs members.

This ADR is proposing a standard Entitlements service implementation to enforce the interface and behavior between providers. The Entitlements V2 implementation will keep the interface of V1 but will also add a couple of missing APIs from the original spec e.g. delete group.

Consequences

Adopting the common service will make sure all implementations are compliant. Once CSP adopts the common service it also needs to provide a way to migrate the data from Entitlements V1 to the new V2. Each Entitlements V1 service has potential gaps in behavior a common migration script cannot be provided for all providers.

Authentication and identity resolution has been extracted from Entitlements service in this implementation. This is a provider specific implementation. Therefore the service expects the identity to be provided to it in the requests. Therefore some part of the CSPs specific implementation e.g. Service mesh, API gateway, different service needs to provide the identity in a secure way to Entitlements to use this implementation. This also makes it convenient to dynamically add support for multiple IdPs (and token issuers) to OSDU instance without the need to make code changes or even redeploy the Entitlements service.

The common implementation does support nested groups and concept of group owners vs members.

Tradeoff Analysis - Input to decision

Clients of the OSDU expect a common interface between provider implementations. Here we have a divergence from this expectation.

This is currently being felt inside the OSDU by teams looking at policy based Entitlements. They are finding gaps between the different implementations which is making building a common policy system on top extremely challenging.

This is also felt by application teams including inside the OSDU where Infosys are making a Admin UI for the OSDU and managing users in this app will not be possible in a common way due to the divergence in functionality.

One of the blockers for original adoption of a common Entitlements service was the initial GCP implementations coupling with Google native technologies like GSuite as an IdP and how it handled identity.

The new V2 implementation extracts the discovery of identity away from the service so that the identity is expected to be provided to it. Jwt validation has also been extracted out of the service.

The service is now only responsible for storing a relationship between users, groups and permissions non specific to any IdP. This allows for an SPI layer to be implemented where each provider can choose how to store this information and then also how to provide the identity information to the service.

The x-user-identity header is an expected parameter on the requests into the service. This header provides the identity of the user to use on the request. In the Azure and GCP implementation this is provided by the infrastructure which handles jwt validation from the IdP and provides identity information based on the respective claim. The service itself is completely free of any specific IdP logic.

We could ask each provider to fix the issues related to their implementation but this will not solve the issue of possible further divergence in the future and the amount of work needed in some instances deemed a re-write necessary and so putting the effort into a potential shared implementation made more sense.

Edited Apr 19, 2021 by Matt Wise