Transition from API Key to OAuth 2.0 client credential-based flow for BDRS Integration

[nitin-vavdiya]

What

Transition the authentication mechanism for BDRS integration from API Key to OAuth 2.0 client credential-based flow for management APIs.

Why

To ensure consistency in how we call other services from the portal backend and enhance security.

Reference: Eclipse Tractus-X SIG Release Issue #959

How

We have two options to implement this transition:

Option 1

• Validate the token using the auth-delegated extension instead of auth-tokenbased.

Option 2

• Validate the token using auth-delegated and perform a role-based validation against the Keycloak client. We need to implement this functionality in upstream(eclipse EDC auth-delegated extension) first or we can go with custom development.

Note: The current implementation of auth-delegated does not support role-based authorization.

---

Further Notes

I wanted to open discussion instead of creating an issue, but discussion is not enabled for this repository.

@paullatzelsperger @evegufy @lgblaumeiser @wolf4ood @jimmarino
Please share your thoughts on which option we should choose.

[paullatzelsperger]

The upstream DelegatedAuthenticationService only does authentication, as the name suggests, and that is by design, as EDC does not have a concept of a user. The effort in designing and implementing a generic (!) role-based access control mechanism would be disproportionate to the value it would provide.

So theoretically, your options are:

1) If you are fine with just authentication

basically your option 1

2) If you must have authorization

Implement a custom AuthenticationService, e.g. named AccessControlService that performs the claim evaluation and register it for BDRS's management API.

However, ...

I would strongly question both the general need for authorization, since you mentioned a technical user, i.e. a machine. If it's only ever going to be portal that calls BDRS Management APIs, authentication should be enough. Secondly, and even more importantly, I also dispute the notion of building this into the BDRS application itself. In fact, I strongly advise against doing that. Authorization and authentication, particularly against a third party IdP, should be handled out-of-band by dedicated specialist infrastructure like API gateways or proxies. They typically are specifically designed for this purpose, are quite mature in terms of security and can do other things too, like auditing, rate-limiting, etc.

NB:

• All of the above is obviously only true for BDRS's Management API as the Directory API is secured with a VP token.
• OIDC might not be the correct choice, because you mentioned a technical user, which precludes user consent. UC is an integral part of OIDC.

TL;DR

• the upstream auth-delegated extension does not - nor will it ever - support authz
• do not build authz into the BDRS app, use an API gateway for this

[jimmarino]

I am unclear about the scope of this issue. Is it authentication to the Management API and, therefore, involves the connection between the onboarding portal and the BDRS? Or. are you suggesting the verification and validation of the Membership credential presented by EDC clients be changed to use a central identity provider?

If it is the latter, that would go against the decentralized architecture we are trying to promote, which involves removing all vestiges of central identity providers and "technical" users for dataspace interactions. A concept of a technical user may remain for interactions between portal and various systems. However, all EDC interactions must be migrated from central identity providers if the decentralized architecture is to be realized.

[nitin-vavdiya]

@jimmarino
Yes, This is for management APIs only and use keycloak token generated using client_id and client_secret(by portal backend).

@paullatzelsperger
Thanks for providing input.

At Cofinity-X, we have implemented role-based access control. For the BDRS application, we defined a Keycloak private client (Cl25-CX-BDRS) and set up roles such as create_bpndidrecord, delete_bpndidrecord, etc. These roles have been assigned to the service account.

In the future, if there is a need to grant read-only permissions to an operator user, this can be achieved easily by assigning appropriate roles.

At the current stage, if JWT token validation (authentication using auth-delegation) is deemed sufficient, we can proceed with this approach.

[paullatzelsperger]

In the future, if there is a need to grant read-only permissions to an operator user, this can be achieved easily by assigning appropriate roles.

Even then, OIDC might not be the way to go, because it is built around user consent, which is not available if the client system is a machine (i.e. portal). Authorizing a human client (=operator) can still be achieved with OAuth2 flows.

Again, I can't stress enough that directly building this into BDRS's API stack is strongly discouraged. For reference, check out this section in EDC's Security Best Practices.

[nitin-vavdiya]

Thank you for sharing your insights.

To address sig-release 959, we propose implementing authentication alone, without incorporating role-based access control for the management API at this stage.

Do we agree with this approach, or should we retain the existing key-based authentication?

[paullatzelsperger]

Do we agree with this approach, or should we retain the existing key-based authentication?

No, I disagree with the idea of letting BDRS directly handle outward-facing authn/authz. As I said, that should be handled centrally by an API gateway, ingress controller or similar.

That said, if you choose to go against that recommendation, the delegated-auth module might work.

[evegufy]

I just wanted to clarify that the approach would be changing from API Key to technical user/service account with OAuth 2.0's Client Credentials Grant. A technical user authentication with OIDC is not and was never in place.

[paullatzelsperger]

A technical user authentication with OIDC is not and was never in place.

this makes sense to me, since OIDC is geared towards user (i.e. human) consent, which is not applicable here. Conversely, Client Credentials grants can also be used if the user is in fact human.
However it does not change my recommendation towards letting specialized software like an API gateway handle authn/authz in a central and easily maintainable way.

[nitin-vavdiya]

Apologies for any confusion caused by including OIDC. As @evegufy mentioned, it is applicable only for the client credential OAuth flow. I have updated the title and description accordingly.

[jimmarino]

To further @paullatzelsperger's point, why would this be built into BDRS when specialized solutions exist, such as API gateways?

These solutions provide all of the required RBAC features. They also abstract security across all services into a common layer that can be centrally managed and dynamically reconfigured. IMO, this approach is a much better architectural direction since it avoids reinventing the wheel, provides more features, and eliminates the need (and risk) to replicate critical security code into all services.

[evegufy]

Changing from an API Key to OAuth 2.0 Client Credentials Grant and adding an API Gateway are complementary steps rather than mutually exclusive. While I fully support the use of an API Gateway, I also believe that transitioning from an API Key to OAuth 2.0 Client Credentials Grant would independently represent an improvement.

[jimmarino]

Adding an API Gateway will take care of handling the client credentials grant as well as any RBAC, auditing, and other features (e.g., throttling). The questions are:

1. Why re-invent the wheel?
2. Why not provide a security layer that can be dynamically re-configured (i.e., at runtime) and centrally managed rather than duplicating security code in each service?

[evegufy]

I wouldn't frame it as "reinventing the wheel" as using OAuth 2.0 Client Credentials Grant alongside an API Gateway is a common approach to securing applications. OAuth 2.0 Client Credentials Grant is not a duplication of security code but rather a common security standard that complements an API Gateway.

[jimmarino]

Of course, but the API Gateway can do this. Putting RBAC-related code in BDRS and handling the OAuth flow there will cause a duplication of code since all services will have to do this. Just have the API gateway (or a proxy) enforce this.

[paullatzelsperger]

OAuth 2.0 Client Credentials Grant is not a duplication of security code

no, but the code to evaluate and match roles and claims would be, and this is getting even worse if that code has to be reimplemented in various languages. This gets exacerbated by enterprise concepts like hierarchical roles, role groups etc.

We're not arguing against using Client Credentials flow, only against implementing this entire logic in BDRS.

[hkny]

Hello,
I would like to add a bit of context for why this is a feature request.

Currently, we have a single user for the ManagementAPI, which is the Core Service B provider. However, when we are talking about having multiple issuers within the same network, the necessity arrives for another issuer to be able to use the ManagementAPI.

To do so though, we have worked on a separate API in the BDRS called the allowListAPI, which enables the Core Service B provider to add another organization to create, update, and delete BPN:DID mappings. After the new issuer is added to the allowList, they can do CUD operations for BPN:DID mappings. However, they are not allowed to use the allowListAPI. They also cannot manipulate any BPN:DID mapping that wasn't created by them.

For those reasons a role-based access control and thus this issue was created. I hope the context helps to make a decision on moving forward.

[jimmarino]

Thanks, can we setup a meeting to discuss this and go through the options and requirements?

[lgblaumeiser]

Had to think a bit about this proposal. I have some doubts that you want to extend the management api to be available for use outside of an organization, as it is meant to organize your operated service. The use case, that different operating companies should access the api to manage mappings is imho the wrong approach. Actually, from a dataspace concept perspective, I would assume, that we use ssi means for exchanging data between OpCos as well.

What does this mean, imho, the exchange of mapping data between companies should be based on the directory api. It would make sense to extend that api to have also some CUD methods that would require a special operation company credential to be available. This would prevent the strange mixture of identies used between independent entities.

I would also propose to make the BDRS a core service A. It could be a federated service, every OpCo or issuer would operate its own BDRS. The BDRS build a network of services, that exchange their mapping data with an appropriate distributed algorithm. This way, OpCos would only use their management api to manage the data in their operated service and the services build a network of trust to exchange the data. This would improve availability of the service and strengthen the decentralized approach. It would be even possible for participants and enablement service providers to also run the service locally as a read-only copy. It might sound as too much, but this would improve decentralization and would follow the principles of Catena-X.

With that target in mind, the right solution here would be to use option 1, only add authentication as I still think, that OAuth is better than an api-key for an inner company management of technical identities.

[jimmarino]

@lgblaumeiser We had a discussion today about this along similar lines to what you outlined above:

• One option is to develop a scheme for BPN generation where each OpCo generates BPNs within a partition. If this option is adopted, no replication is needed since EDCs can have a list of BDRS services they cache from. This can be extremely efficient and avoid a single point of failure. Secondary nodes could cache the primary OpCo BDRS, providing an extra layer of redundancy.

• Another option is to develop a replication protocol. This should be built on append-only messages in a different context from the management API. At least two problems would need to be solved. First, some global locking mechanism (or service) is needed to guarantee BPN uniqueness if a partition scheme is not used, creating another single point of failure. Second, either a centralized authorization server would need to be setup and managed for every OpCo with cross-accounts, or DID registries could be configured for authorization. Either way, this is complicated and involves a lot of configuration.

What would not be good is if another OpCo relies on an existing OpCo to fulfill its primary mission of registering members by requiring updates to a specific BDRS instance. I think the first option is much simpler, more scalable, and can be made fault-tolerant with less effort.

[lgblaumeiser]

@jimmarino Yes, the way, how BPNs are generated needs a special distribution scheme so that they can be generated locally. That is not rocket science, and I would also prefer something along your first proposal. That typically depends on the size of the identifier, as you have to assign range budgets to OpCos and that requires sufficient buffers in the size of the identifier. Unlike in the ip4 case, where the size is simply too small.

My point was more that I think it necessary to separate between the operator of a BDRS service, who must have access to the management api, as this is the way for him to manage his service. This has to be separated from other companies who access the BDRS service. This should be only possible by the directory api and ssi based authentication mechanisms. I.e., the directory api would need an extension so that other companies, i.e., OpCos can add, change and remove entries in the BDRS.

My further proposal was, that instead of companies accessing the directory API for this use case, it should be a federated network of BDRS services. Each OpCo would operate their own BDRS service and would add BPN to DID mappings they are creating according to the BPN creation algorithm standardized for OpCos. The BDRS services would then exchange their internal data using the directory api and a certain credential that authenticates them as BDRS service. There are standard algorithms which organize such networks, so that they can handle additions and network separations. This would add a substantial amount of fault tolerance to the system.

[jimmarino]

As I mentioned, this can be handled very simply using a BPN partition scheme. The client can cache BDRS entries from multiple BDRS servers. There is no need to federate data between BDRS servers and no need for any type of consensus between them.

If option 2 is chosen, consensus is also not required. However, that setup is still complex and a single point of failure since there needs to be a another service which guarantees global uniqueness for BPNs.

[lgblaumeiser]

Ok, I think we stumble again accross terms. Let me try again to phrase my proposal. I think, BDRS should be a core service A that is operated as an instance by an issuer in the future. As participants should not need to know all issuer, the BDRS services of all issuers build one virtual, distributed service, i.e., they exchange their mappings, so that after a short period of time a new mapping is shared between all operated BDRS services. Each participant only needs to know its issuers BDRS service to resolve between the two identifiers.

The problem we talk about is, that in a Multi-Issuance situation, all issuers might need to add mappings to the BDRS service of the data space. And the proposal given here, that multiple unrelated organizations are allowed to manipulate the BDRS database by accessing the management api using different credentials and different authorizations is imho not leading in the right direction. The management api is an api that is used by the company that operates the service, and every exchange between different companies should be done based on SSI authentication and authorization.

As a consequence, concerning this item here, simple authorization is sufficient for the BDRS service. That is my point. Authorization is only needed for the directory api based on credentials a caller has. I do not see, that we need contracts, so no connector is needed, but identification by signed credentials should be the base principle for interactions in the dataspace between any kind of participant.

[jimmarino]

We need to be careful about conflating concepts here:

• A dataspace authority (Catena-X) delegates to an operating company (e.g., Cofinity-X) to handle participant onboarding
• An issuer is an entity that asserts claims about one or more subjects by issuing a Verifiable Credential to a Holder (dataspace participant).
• Both issuers and operating companies function as trust anchors in the dataspace.

The operating company and issuer are not the same roles, although Cofinity-X may function in both roles. All participants must always be "aware" (i.e., trust) of all issuers. Otherwise, the dataspace will not function.

The BDRS does not need to be run as a centralized service, and no replication protocol is needed. BDRS endpoints can be discovered similar to the way the issuer list is. I also think having one operating company managing a "special" BDRS instances does not make sense from a business standpoint since it requires one operating company to be dependent on another. For example, an operating company outside the EU would probably not accept that type of relationship.

[nitin-vavdiya]

As per discussion, this feature needs more refinement and can be done after the multi-issuer or multi-operator concept is finalised.

Closing this ticket

[lgblaumeiser]

I have to admit, that I do not get this conclusion out of the discussion. The outcome, imho is, that changing the authentication makes sense, but that there was no use case described where authorization on the management api makes sense. The management api is not meant as an api to be used from outside of the company that operates the BDRS service, so authorization requires a use case that is driven by different roles within the company that operates the service. As it is an api that is basically used from portal in a homogeneous way, I do not see that use case.

The further discussion was about topologies of the service in a multi-issuer environment. This discussion went beyond the original issue, I admit.