Documentation for swapping authentication types

[crismsx]

A common scenario I'm running into is to proxy a request for the sole reason of swapping the authentication token.

In particular, the use case involves the swapping of 2 OAuth2 tokens. The client has access to one IdentityServer and the resource server to a different IdentityServer. The proxy in between is the only component that has access to both IdentityServers and is able to swap the access tokens. The swap should work only for specific (configured) routes.

Consider adding documentation that covers this authentication scenario.

[Tratcher]

See this discussion: #375

As this is a flow that's likely require a lot of customization I don't know that we'll be able to provide more than general guidance and docs. We'll have to wait and see what the most common patterns are. (Triage, I recommend backlog awaiting additional feedback.)

[karelz]

Triage: We can make it an example of adding a header based on the incoming user - likely related to #60

[macsux]

We've been using HTTP Headers to do Auth/Authz at the proxy and propagate identity downstream as HTTP headers. This implies there is implicit transport security between proxy and final destination provided by the infrastructure, but this is now increasingly common with SDN, K8S, and use of reverse proxies in sidecar scenarios. I believe this is also a model that is applied by Azure AppService (they auto inject HTTP module to reconstruct .NET Principal from authentication headers). Consider offering this out of the box as it greatly simplifies downstream services processing identity without having to deal with any security blocks. We've been using this to offload Kerberos validation to the sidecar. The identity is extracted and 2 headers are sent downstream:

X-Identity: someuser\domain
X-Roles: User,SomeGroup
Alternatively repackaging identity into JWT can provide greater flexibility as it allows for the much richer expression of principal than plaintext headers above. For this option, it would be useful to have the ability to send both signed and unsigned tokens. Unsigned JWT tokens would lessen the burden of dealing with managing JWK that proxy would need to expose and downstream having to configure.

Signed JWT should also be supported by exposing a JWK url at the proxy. This is to facilitate scenarios where security between proxy and destination cannot be enforced at the transport infrastructure level. Also, some JWT libraries don't support unsigned JWT tokens.

There's also the concept of identity delegation. Consider downstream service wanting to make further downstream calls on behalf of user. OAuth2 supports this via token-exchange where the original incoming token is exchanged to acquire extract claims that the downstream service is implicitly authorized for without requiring user consent. Kerberos also supports this by either delegating TGT of the user (unconstrained delegation) or via similarly constrained delegation which is very similar to oauth2. In all of these cases, there is a desire to propagate the original token/ticket downstream for further use.