From adb2af442a88b88452cd8aee2d064c906d4eb9ec Mon Sep 17 00:00:00 2001 From: Giuseppe Graziano Date: Tue, 30 Jul 2024 21:04:05 +0200 Subject: [PATCH] Move token exchange documentation to guides (#31707) Closes #31334 Signed-off-by: Giuseppe Graziano Signed-off-by: Marek Posolda Co-authored-by: Marek Posolda --- docs/documentation/securing_apps/topics.adoc | 3 - .../images/exchange-idp-apply-policy.png | Bin .../images/exchange-idp-client-policy.png | Bin .../images/exchange-idp-permission-set.png | Bin .../images/exchange-idp-permission-setup.png | Bin .../images/exchange-idp-permission-unset.png | Bin ...ge-target-client-exchange-apply-policy.png | Bin .../exchange-target-client-permission-set.png | Bin ...xchange-target-client-permission-setup.png | Bin ...xchange-target-client-permission-unset.png | Bin .../images/exchange-target-client-policy.png | Bin .../images/exchange-users-apply-policy.png | Bin .../images/exchange-users-client-policy.png | Bin .../images/exchange-users-permission-set.png | Bin .../exchange-users-permission-setup.png | Bin .../exchange-users-permission-unset.png | Bin .../securing-apps}/token-exchange.adoc | 96 +++++++++++------- 17 files changed, 57 insertions(+), 42 deletions(-) rename docs/{documentation/securing_apps => guides}/images/exchange-idp-apply-policy.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-idp-client-policy.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-idp-permission-set.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-idp-permission-setup.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-idp-permission-unset.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-target-client-exchange-apply-policy.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-target-client-permission-set.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-target-client-permission-setup.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-target-client-permission-unset.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-target-client-policy.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-users-apply-policy.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-users-client-policy.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-users-permission-set.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-users-permission-setup.png (100%) rename docs/{documentation/securing_apps => guides}/images/exchange-users-permission-unset.png (100%) rename docs/{documentation/securing_apps/topics/token-exchange => guides/securing-apps}/token-exchange.adoc (91%) diff --git a/docs/documentation/securing_apps/topics.adoc b/docs/documentation/securing_apps/topics.adoc index 8429e04ba0..bacdcda71f 100644 --- a/docs/documentation/securing_apps/topics.adoc +++ b/docs/documentation/securing_apps/topics.adoc @@ -14,7 +14,4 @@ include::topics/saml/java/java-adapters-product.adoc[] endif::[] include::topics/saml/saml-errors.adoc[] -ifeval::[{project_community}==true] -include::topics/token-exchange/token-exchange.adoc[] -endif::[] diff --git a/docs/documentation/securing_apps/images/exchange-idp-apply-policy.png b/docs/guides/images/exchange-idp-apply-policy.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-idp-apply-policy.png rename to docs/guides/images/exchange-idp-apply-policy.png diff --git a/docs/documentation/securing_apps/images/exchange-idp-client-policy.png b/docs/guides/images/exchange-idp-client-policy.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-idp-client-policy.png rename to docs/guides/images/exchange-idp-client-policy.png diff --git a/docs/documentation/securing_apps/images/exchange-idp-permission-set.png b/docs/guides/images/exchange-idp-permission-set.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-idp-permission-set.png rename to docs/guides/images/exchange-idp-permission-set.png diff --git a/docs/documentation/securing_apps/images/exchange-idp-permission-setup.png b/docs/guides/images/exchange-idp-permission-setup.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-idp-permission-setup.png rename to docs/guides/images/exchange-idp-permission-setup.png diff --git a/docs/documentation/securing_apps/images/exchange-idp-permission-unset.png b/docs/guides/images/exchange-idp-permission-unset.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-idp-permission-unset.png rename to docs/guides/images/exchange-idp-permission-unset.png diff --git a/docs/documentation/securing_apps/images/exchange-target-client-exchange-apply-policy.png b/docs/guides/images/exchange-target-client-exchange-apply-policy.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-target-client-exchange-apply-policy.png rename to docs/guides/images/exchange-target-client-exchange-apply-policy.png diff --git a/docs/documentation/securing_apps/images/exchange-target-client-permission-set.png b/docs/guides/images/exchange-target-client-permission-set.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-target-client-permission-set.png rename to docs/guides/images/exchange-target-client-permission-set.png diff --git a/docs/documentation/securing_apps/images/exchange-target-client-permission-setup.png b/docs/guides/images/exchange-target-client-permission-setup.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-target-client-permission-setup.png rename to docs/guides/images/exchange-target-client-permission-setup.png diff --git a/docs/documentation/securing_apps/images/exchange-target-client-permission-unset.png b/docs/guides/images/exchange-target-client-permission-unset.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-target-client-permission-unset.png rename to docs/guides/images/exchange-target-client-permission-unset.png diff --git a/docs/documentation/securing_apps/images/exchange-target-client-policy.png b/docs/guides/images/exchange-target-client-policy.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-target-client-policy.png rename to docs/guides/images/exchange-target-client-policy.png diff --git a/docs/documentation/securing_apps/images/exchange-users-apply-policy.png b/docs/guides/images/exchange-users-apply-policy.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-users-apply-policy.png rename to docs/guides/images/exchange-users-apply-policy.png diff --git a/docs/documentation/securing_apps/images/exchange-users-client-policy.png b/docs/guides/images/exchange-users-client-policy.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-users-client-policy.png rename to docs/guides/images/exchange-users-client-policy.png diff --git a/docs/documentation/securing_apps/images/exchange-users-permission-set.png b/docs/guides/images/exchange-users-permission-set.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-users-permission-set.png rename to docs/guides/images/exchange-users-permission-set.png diff --git a/docs/documentation/securing_apps/images/exchange-users-permission-setup.png b/docs/guides/images/exchange-users-permission-setup.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-users-permission-setup.png rename to docs/guides/images/exchange-users-permission-setup.png diff --git a/docs/documentation/securing_apps/images/exchange-users-permission-unset.png b/docs/guides/images/exchange-users-permission-unset.png similarity index 100% rename from docs/documentation/securing_apps/images/exchange-users-permission-unset.png rename to docs/guides/images/exchange-users-permission-unset.png diff --git a/docs/documentation/securing_apps/topics/token-exchange/token-exchange.adoc b/docs/guides/securing-apps/token-exchange.adoc similarity index 91% rename from docs/documentation/securing_apps/topics/token-exchange/token-exchange.adoc rename to docs/guides/securing-apps/token-exchange.adoc index bfedd9fcec..2d74fcb90e 100644 --- a/docs/documentation/securing_apps/topics/token-exchange/token-exchange.adoc +++ b/docs/guides/securing-apps/token-exchange.adoc @@ -1,11 +1,27 @@ +<#import "/templates/guide.adoc" as tmpl> +<#import "/templates/links.adoc" as links> -[[_token-exchange]] - -== Using token exchange +<@tmpl.guide +title="Using token exchange" +priority=40 +summary="Configuring and using Token exchange with {project_name}"> :tech_feature_name: Token Exchange :tech_feature_id: token-exchange -include::../templates/techpreview.adoc[] + +[NOTE] +==== +{tech_feature_name} is +*Preview* +and is not fully supported. This feature is disabled by default. + +To enable start the server with `--features=preview` +ifdef::tech_feature_id[] +or `--features={tech_feature_id}` +endif::[] + +{tech_feature_name} is *Technology Preview* and is not fully supported. +==== [NOTE] ==== @@ -13,7 +29,7 @@ To use more than the <<_internal-token-to-internal-token-exchange,Internal Token For details, see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}. ==== -=== How token exchange works +== How token exchange works In {project_name}, token exchange is the process of using a set of credentials or token to obtain an entirely different token. A client may want to invoke on a less trusted application so it may want to downgrade the current token it has. @@ -41,7 +57,7 @@ Public clients specify their client identifier as a form parameter. Confidentia to pass their client id and secret, Basic Auth, or however your admin has configured the client authentication flow in your realm. -==== Form parameters +=== Form parameters client_id:: _REQUIRED MAYBE._ This parameter is required for clients using form parameters for authentication. If you are using @@ -81,7 +97,7 @@ scope:: NOTE: We currently only support OpenID Connect and OAuth exchanges. Support for SAML based clients and identity providers may be added in the future depending on user demand. -==== Responses from a token exchange request +=== Responses from a token exchange request A successful response from an exchange invocation will return the HTTP 200 response code with a content type that depends on the `requested-token-type` and `requested_issuer` the client asks for. OAuth requested token types will return @@ -124,7 +140,7 @@ For simplicity's sake, let's call a token minted by the current realm as an _int an external realm or identity provider as an _external_ token. [[_internal-token-to-internal-token-exchange]] -=== Internal token to internal token exchange +== Internal token to internal token exchange With an internal token to token exchange you have an existing token minted to a specific client and you want to exchange this token for a new one minted for a different target client. Why would you want to do this? This generally happens @@ -134,20 +150,20 @@ need to perform a "permission downgrade" where your app needs to invoke on a les to propagate your current access token. [[_client_to_client_permission]] -==== Granting permission for the exchange +=== Granting permission for the exchange Clients that want to exchange tokens for a different client need to be authorized in the Admin Console. You need to define a `token-exchange` fine grain permission in the target client you want permission to exchange to. .Target Client Permission -image:images/exchange-target-client-permission-unset.png[Target Client Permission] +image::exchange-target-client-permission-unset.png[Target Client Permission] .Procedure . Toggle *Permissions Enabled* to *On*. + .Target Client Permission -image:images/exchange-target-client-permission-set.png[Target Client Exchange Permission Set] +image::exchange-target-client-permission-set.png[Target Client Exchange Permission Set] + That page displays a *token-exchange* link. @@ -156,7 +172,7 @@ That page displays a *token-exchange* link. This setup page displays. + .Target Client Exchange Permission Setup -image:images/exchange-target-client-permission-setup.png[Target Client Exchange Permission Setup] +image::exchange-target-client-permission-setup.png[Target Client Exchange Permission Setup] . Click *Client details* in the breadcrumbs at the top of the screen. . Define a policy for this permission. @@ -166,20 +182,20 @@ image:images/exchange-target-client-permission-setup.png[Target Client Exchange . Create a *Client* Policy by clicking *Create policy* button. + .Client Policy Creation -image:images/exchange-target-client-policy.png[Client Policy Creation] +image::exchange-target-client-policy.png[Client Policy Creation] . Enter in the starting client that is the authenticated client that is requesting a token exchange. . After you create this policy, go back to the target client's *token-exchange* permission and add the client policy you just defined. + .Apply Client Policy -image:images/exchange-target-client-exchange-apply-policy.png[Apply Client Policy] +image::exchange-target-client-exchange-apply-policy.png[Apply Client Policy] Your client now has permission to invoke. If you do not do this correctly, you will get a 403 Forbidden response if you try to make an exchange. [[_internal_internal_making_request]] -==== Making the request +=== Making the request When your client is exchanging an existing token for a token targeting another client, you use the `audience` parameter. This parameter must be the client identifier for the target client that you configured in the Admin Console. @@ -218,7 +234,7 @@ the client making the request to successfully complete the exchange. } ---- -=== Internal token to external token exchange +== Internal token to external token exchange You can exchange a realm token for an external token minted by an external identity provider. This external identity provider must be configured within the `Identity Provider` section of the Admin Console. Currently only OAuth/OpenID Connect based external @@ -237,19 +253,19 @@ If the account is not linked, the exchange response will contain a link you can discussed more in the <<_internal_external_making_request, Making the Request>> section. [[_grant_permission_external_exchange]] -==== Granting permission for the exchange +=== Granting permission for the exchange Internal to external token exchange requests will be denied with a 403, Forbidden response until you grant permission for the calling client to exchange tokens with the external identity provider. To grant permission to the client, you go to the identity provider's configuration page to the *Permissions* tab. .Identity Provider Permission -image:images/exchange-idp-permission-unset.png[Identity Provider Exchange Permission] +image::exchange-idp-permission-unset.png[Identity Provider Exchange Permission] .Procedure . Toggle *Permissions Enabled* to *On*. + .Identity Provider Permission -image:images/exchange-idp-permission-set.png[Identity Provider Exchange Permission Set] +image::exchange-idp-permission-set.png[Identity Provider Exchange Permission Set] + The page displays *token-exchange* link. @@ -258,26 +274,26 @@ The page displays *token-exchange* link. This setup page appears. + .Identity Provider Exchange Permission Setup -image:images/exchange-idp-permission-setup.png[Identity Provider Exchange Permission Setup] +image::exchange-idp-permission-setup.png[Identity Provider Exchange Permission Setup] . Click *Client details* in the breadcrumbs at the top of the screen. . Click *Policies* tab to create a client policy. + .Client Policy Creation -image:images/exchange-idp-client-policy.png[Client Policy Creation] +image::exchange-idp-client-policy.png[Client Policy Creation] . Enter the starting client that is the authenticated client that is requesting a token exchange. . Return to the identity provider's *token-exchange* permission and add the client policy you just defined. + .Apply Client Policy -image:images/exchange-idp-apply-policy.png[Apply Client Policy] +image::exchange-idp-apply-policy.png[Apply Client Policy] Your client now has permission to invoke. If you do not do this correctly, you will get a 403 Forbidden response if you try to make an exchange. [[_internal_external_making_request]] -==== Making the request +=== Making the request When your client is exchanging an existing internal token to an external one, you provide the `requested_issuer` parameter. The parameter must be the alias of a configured identity provider. @@ -324,7 +340,7 @@ so that the client can perform link:{developerguide_link}[Client Initiated Accou providers require linking through browser OAuth protocol. With the `account-link-url` just add a `redirect_uri` query parameter to it and you can forward browsers to perform the link. -=== External token to internal token exchange +== External token to internal token exchange You can trust and exchange external tokens minted by external identity providers for internal tokens. This can be used to bridge between realms or just to trust tokens from your social provider. It works similarly to an identity provider @@ -343,7 +359,7 @@ These types of changes required a configured identity provider in the Admin Cons NOTE: SAML identity providers are not supported at this time. Twitter tokens cannot be exchanged either. -==== Granting permission for the exchange +=== Granting permission for the exchange Before external token exchanges can be done, you grant permission for the calling client to make the exchange. This permission is granted in the same manner as <<_grant_permission_external_exchange, internal to external permission is granted>>. @@ -352,7 +368,7 @@ If you also provide an `audience` parameter whose value points to a different cl must also grant the calling client permission to exchange to the target client specific in the `audience` parameter. How to do this is <<_client_to_client_permission, discussed earlier>> in this section. -==== Making the request +=== Making the request The `subject_token_type` must either be `urn:ietf:params:oauth:token-type:access_token` or `urn:ietf:params:oauth:token-type:jwt`. If the type is `urn:ietf:params:oauth:token-type:access_token` you specify the `subject_issuer` parameter and it must be the @@ -395,21 +411,21 @@ an example JSON response you get back from this call. ---- -=== Impersonation +== Impersonation For internal and external token exchanges, the client can request on behalf of a user to impersonate a different user. For example, you may have an admin application that needs to impersonate a user so that a support engineer can debug a problem. -==== Granting permission for the exchange +=== Granting permission for the exchange The user that the subject token represents must have permission to impersonate other users. See the link:{adminguide_link}[{adminguide_name}] on how to enable this permission. It can be done through a role or through fine grain admin permissions. -==== Making the request +=== Making the request Make the request as described in other chapters except additionally specify the `requested_subject` parameter. The value of this parameter must be a username or user id. @@ -427,7 +443,7 @@ curl -X POST \ http://localhost:8080{kc_realms_path}/myrealm/protocol/openid-connect/token ---- -=== Direct Naked Impersonation +== Direct Naked Impersonation You can make an internal token exchange request without providing a `subject_token`. This is called a direct naked impersonation because it places a lot of trust in a client as that client can impersonate any user in the realm. @@ -438,7 +454,7 @@ is able to authenticate users itself, but not able to obtain a token. WARNING: It is very risky to enable direct naked impersonation for a client. If the client's credentials are ever stolen, that client can impersonate any user in the system. -==== Granting permission for the exchange +=== Granting permission for the exchange If the `audience` parameter is provided, then the calling client must have permission to exchange to the client. How to set this up is discussed earlier in this chapter. @@ -452,12 +468,12 @@ Additionally, the calling client must be granted permission to impersonate users . Click the *Permissions* tab. + .User Permissions -image:images/exchange-users-permission-unset.png[User Permissions] +image::exchange-users-permission-unset.png[User Permissions] . Toggle *Permissions Enabled* to *On*. + .Identity Provider Permission -image:images/exchange-users-permission-set.png[Users Impersonation Permission Set] +image::exchange-users-permission-set.png[Users Impersonation Permission Set] + The page displays an *impersonate* link. . Click that link to start defining the permission. @@ -465,14 +481,14 @@ The page displays an *impersonate* link. This setup page displays. + .Users Impersonation Permission Setup -image:images/exchange-users-permission-setup.png[Users Impersonation Permission Setup] +image::exchange-users-permission-setup.png[Users Impersonation Permission Setup] . Click *Client details* in the breadcrumbs at the top of the screen. . Define a policy for this permission. . Go to the *Policies* tab and create a client policy. + .Client Policy Creation -image:images/exchange-users-client-policy.png[Client Policy Creation] +image::exchange-users-client-policy.png[Client Policy Creation] . Enter the starting client that is the authenticated client that is requesting a token exchange. @@ -480,7 +496,7 @@ image:images/exchange-users-client-policy.png[Client Policy Creation] defined. + .Apply Client Policy -image:images/exchange-users-apply-policy.png[Apply Client Policy] +image::exchange-users-apply-policy.png[Apply Client Policy] Your client now has permission to impersonate users. If you do not do this correctly, you will get a 403 Forbidden response if you try to make this type of exchange. @@ -488,7 +504,7 @@ try to make this type of exchange. NOTE: Public clients are not allowed to do direct naked impersonations. -==== Making the request +=== Making the request To make the request, simply specify the `requested_subject` parameter. This must be the username or user id of a valid user. You can also specify an `audience` parameter if you wish. @@ -503,14 +519,14 @@ curl -X POST \ http://localhost:8080{kc_realms_path}/myrealm/protocol/openid-connect/token ---- -=== Expand permission model with service accounts +== Expand permission model with service accounts When granting clients permission to exchange, you don't necessarily manually enable those permissions for each and every client. If the client has a service account associated with it, you can use a role to group permissions together and assign exchange permissions by assigning a role to the client's service account. For example, you might define a `naked-exchange` role and any service account that has that role can do a naked exchange. -=== Exchange vulnerabilities +== Exchange vulnerabilities When you start allowing token exchanges, there are various things you have to both be aware of and careful of. @@ -527,3 +543,5 @@ Direct naked exchanges are quite dangerous. You are putting a lot of trust in t its client credentials. If those credentials are leaked, then the thief can impersonate anybody in your system. This is in direct contrast to confidential clients that have existing tokens. You have two factors of authentication, the access token and the client credentials, and you're only dealing with one user. So use direct naked exchanges sparingly. + +