Management API: add delegating authentication service

[paullatzelsperger]

Feature Request

Currently, we have two implementation of the AuthenticationService: a BasicAuthenticationService which was deprecated in version 0.6.5, and the TokenBasedAuthenticationService, which lacks some key features, such as token rotation, token invalidation, etc.

Thus, another implementation will be added that delegates the authentication decision to a third-party Identity Provider (IdP).

Management API clients must obtain a JSON Web token from that third-party IdP system and attach it to the request's Authorization header as Bearer token. The connector then resolves the IdP's public key and verifies the token.

NB: The abbreviation dac stands for "delegated access control" and is used only to better group config values.

Limitations

• We will only implement verification of OAuth2 tokens (JWT format).
• No evaluation of claims, i.e. no authorization.
• Only JWS are supported, i.e. no encrypted tokens (JWEs)
• Public keys must be provided as JWK or in PEM format. If JWK, then the expected format is JWKS

Initially, this system will be deployed for the Management API context, but in the future it could be used for other API contexts as well.

Which Areas Would Be Affected?

Management API

Why Is the Feature Desired?

to have a more production-grade security solution for the Management API

Solution Proposal

• Both the TokenBasedAuthenticationService extension and the DelegatingAuthenticationService extension will be loaded at runtime. The DelegatingAuthenticationService will be registered in the ServiceExtensionContext if - and only if - all config parameters it requires are provided. Otherwise, we fall back to the TokenBasedAuthenticationService, which will be registered as default provider.

• By default, the DelegatingAuthenticationService only verifies the JWT, plus some basic plausibility verification:

  • nbf if present, nbf must be before the current time (allowing for some epsilon)
  • exp if present, exp must be after the current time (allowing for some epsilon)

• additional token validation can be contributed to the TokenValidationRuleRegistry using extensions using the management-api context string.

• Required configuration values

  • edc.api.auth.dac.key.url: URL of the IdP where the connector can download the public key(s) (JWK or PEM format).

• Optional configuration values

  • edc.api.auth.dac.cache.validty: time (in milliseconds) that the public key(s) of the IdP should be cached. Set to <= 0 to disable the cache.

• to allow for some backwards compatibility, the DelegatingAuthenticationService will also evaluate the x-api-key header and log a warning. After the usual deprecation period of two milestones this will be removed.

[edit 1]: removed optional header configuration
[edit 2]: added JWKS requirement
[edit 3]: renamed config property to be more generic

[paullatzelsperger]

\CC @lgblaumeiser

[lgblaumeiser]

Thanks, @paullatzelsperger,

that reflects our discussion very well. Only one point, I think, that could be clarified a bit better. In your description, you define the config parameter: edc.api.auth.dac.header to allow a configuration of the header to be used. This defaults to "Authorization". My understanding is, that here you change that to the existing use of the "x-api-key" header instead. From our discussion, my understanding was, that this is a feature of the edc to handle both instead of the configured one.

Both could be fine, but for the ease of handling, I would favor supporting both headers at the same time. The reasoning is, that an EDC owner could make use of different tools for managing the EDC. In the case, that these tools use the headers not uniquely, the usage of this combination is blocked. The security risk imho is minimal, if two different header keys are applicable.

[paullatzelsperger]

clarification: to provide some client backwards compatibility, the x-api-key header will also be evaluated by the DelegatingAuthenticationService, but a deprecation warning will be logged.

Specifically:

• if the new DelegatedAuthenticationService is configured properly, it will take either an Authorization header or the x-api-key header. Either must contain an OAuth2 Bearer token. That means, for a transitional period, either Authorization or x-api-key headers can be used interchangeably. Supplying an API Key instead of an OAuth2 Bearer token will result in an error!!
• if the x-api-key is used in that constellation, a deprecation warning will be logged on the connector
• if the DeletagedAuthenticationService is not configured (i.e. the edc.api.auth.dac.key.url property is omitted), it will not be used at runtime and the system will fall back to using the TokenBasedAuthenticationService. There, it will also take an x-api-key header, but it must contain an API Key (not an OAuth2 token!).

[paullatzelsperger]

We will implement support for JWKS only at first, and - if needed - provide support for PEM keys later