Identityserver4: Features needed for full support of token exchange

[amadard]

This is a continuation of #2310, describing the features needed to add full support to IdentityServer4 for token exchange as defined by IETF Token Exchange. Most of these features are directly from the specification, but some are suggestions based on real world usage needs that I included for consideration.

1. Token exchange can be either "delegation" or "impersonation", where impersonation results in a token that is indistinguishable from a token generated for the subject, while delegation results in a token that has the rights of the subject, but the token includes information about the actor's identity.
   1.1.  Because impersonation has less information in the result, I suggest a default implementation that does not allow impersonation, and a new property in the IdentityServerOptions to enable impersonation.
2. Token exchange requires a new grant type, "token-exchange" Completed in IdentityModel.GrantTypes
3. Token exchange has specific requirements for the token request parameters.  TokenRequestValidator needs to be updated to implement these new requirements for this grant type, in addition to existing validation checks.
   3.1. subject_token is a valid security token that contains the sub that will be impersonated or acted on behalf of.
   3.2. subject_token_type is the token type of the subject_token
   3.3. actor_token is an optional parameter, that is a valid security token that has the identity of the sub that is acting on behalf of the subject.  This parameter is optional for impersonation, required for delegation.
   3.4. actor_token_type is an optional parameter that is the token type of the actor_token.  This is required is actor_token is present, it must not be included if actor_token is missing.
4. Token exchange requires a valid subject_token that contains the identity of the user or client being impersonated, or acted on behalf of.  If that subject is "logged in", their existing token may be used for the subject_token.  A workflow needs to be identified, by which an actor ([email protected]), may request a valid token for the subject ([email protected]) for the purposes of token exchange, without the actor needing the subject's credentials, nor interaction by the subject at time of the token exchange.
   4.1. It may be beneficial to have a consent process for a user to give permission for an actor to request tokens on their behalf prior to the actor having permission to request tokens for that user.  This could be a per actor configuration, so that specific clients/roles/users would be "required actors", not allowing permission to be denied, while other actors would be "optional actors", following a full consent workflow. There is also the potential of "required and hidden actors", that would be required, and not displayed through the consent workflow.
5. The token generated by the token-exchange may include the "act" claim, which provides the identity of the actor for informational purposes.  When the exchange is delegation, this information could come from the actor_token, while when impersonating the only identity available is the client requesting the token.
   5.1. The act claim is a JSON object, which may be modeled by a class.  Standard properties could be:
   5.1.1. Identity and identity type (e.g. sub/user, clientid/client)
   5.1.2. Previous act claims
   5.1.3. Properties Key/Value pairs to allow additional information to be included.
   5.2. The TokenResponseGenerator needs to be updated to add the act claim as appropriate.
   5.3. The act claim may provide additional information about the actor.  This should have an override-able default implementation, with an interface to allow a custom implementations.
   5.4. The act claim may be nested, providing information on a chain of delegation.  If the actor_token includes an act claim, that claim should be embedded in the act claim of the new token.
   5.5. The size of a custom implementation of the act claim may become very large, so the size should be restricted through the settings.
6. The "may_act" claim  may be part of the subject_token to provide information to the TokenRequestValidator to determine if the client or identity in the actor_token are authorized to perform token-exchange for the subject_token's subject.
   6.1. A workflow needs to be identified by which IdentityServer knows when the TokenResponseGenerator should include the may_act claim.  Token-exchange is not going to be used in every situation, so it is not necessary to include may_act in every token.
   6.2. A workflow needs to be identified by which IdentityServer knows which users/roles/clients should be included in the may_act claim.  This may be properties of the user or client.
   6.3. The may_act claim is a JSON object, which may be modeled by a class.
   6.4. The may_act claim may also include additional information about the authorized actor, so this should have an override-able default implementation, with an interface to allow a custom implementations. 
   6.5.  The size of the may_act claim may become very large, so the size should be restricted through the settings.
7. The TokenRequestValidator needs to validate the client or actor_token identity against the subject_token identity to determine if the client AND actor_token (if present) are authorized for impersonation/delegation.  This should start with the may_act claim, then check against the user/client store.
8. To prevent abuse, it may be beneficial to require the scope claim in the request and mitigate some of the potential security risk.

Edit 12/27/19 - Adding:

1. It may be beneficial to add an interface to check if impersonation is allowed. The global flag would allow/restrict impersonation across the board, so having this interface would allow situation specific blocking of impersonation with a minor customization. E.g. client_1 is allowed to impersonate, but client_2 is not. The TokenRequestValidator would allow impersonation, then check against the collection of "IImpersonationValidator", much like how ExtensionGrantValidator has the collection of registered grant type validators. All registered implementations of "IImpersonationValidator" would need to pass to allow impersonation.

[leastprivilege]

Thanks for the detailed write-up. We will discuss it.

[amadard]

Edited the original post to add number 9, suggesting IImpersonationValidator.

[amadard]

I was thinking through how Identity would know if [email protected] is allowed to be an actor for [email protected], but I realized that is talking authority not identity, and so that workflow would fall under a separate service, like PolicyServer.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[amadard]

Adding a comment to keep alive during review.

[leastprivilege]

Since token exchange offers so many options, it almost feels like it requires a "mini-framework" for it. I currently don't see that being part of the core IS4 work.

My real question would be - is there anything missing in IS4 that would prohibit creating this hypothetical framework based on the current extensibility points?

[amadard]

@leastprivilege I will review if there is anything I can see that is missing.

[amadard]

@leastprivilege Based on my review, I think this could be a separate "mini-framework" project that is optionally added to IS4. Below are each of my above bullet points reviewed:

1. This can be a framework configuration option.
2. Already resolved
3. This can be a derived class of TokenRequestValidator
4. This can be a derived class of TokenRequestValidator. The consent process can be stored via the existing Persistent Grants.
5. This can be a derived class of TokenResponseGenerator
6. This can be a derived class of TokenResponseGenerator
7. This can be a derived class of TokenRequestValidator
8. This can be a derived class of TokenRequestValidator
9. This can be a derived class of TokenRequestValidator

[pedrotiagopontes]

Hi @amadard, I'm also interested in this feature.
Did you started the development of any framework or are you planning to do so in the near future?
After reading the RFC I believe it could be implemented using the extension grants, by creating a new grant type with the new parameters and a custom response. I believe you also analysed this, did you found any blockers in implementing this using extension grants?

[leastprivilege]

I just did an implementation of some use cases using the standard extension grant validator. I did not hit any blockers.

I think everything is fine for now.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.
Questions are community supported only and the authors/maintainers may or may not have time to reply. If you or your company would like commercial support, please see here for more information.

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.