Move token exchange documentation to guides (#31707)

Closes #31334


Signed-off-by: Giuseppe Graziano <g.graziano94@gmail.com>
Signed-off-by: Marek Posolda <mposolda@gmail.com>
Co-authored-by: Marek Posolda <mposolda@gmail.com>

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::[]
 

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]]
+<@tmpl.guide
-
+title="Using token exchange"
-== 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.
+
+</@tmpl.guide>