:PROPERTIES:
:ID:       97cfc6a5-3522-4ebc-99c6-704740ea97e8
:END:
#+TITLE: Token Exchange in IROH-Auth
#+Author: Yann Esposito
#+Date: [2022-04-26]
- tags :: [[id:91f33b35-6e4e-4213-b214-972ee20722df][Cisco]] [[id:299643a7-00e5-47fb-a987-3b9278e89da3][Auth]]
- source ::

- Token Exchange RFC :: https://www.rfc-editor.org/rfc/rfc8693.html

* Token Exchange

Token Exchange RFC describe an OAuth2 extension to support Token Exchanges.
With that RFC you could exchange an access token with another one.

It would immediately be useful to support the following features:

- provide impersonate ability to trusted clients

The RFC propose to use the existing ~/token~ endpoint.

Here would be an example for account switching:

#+begin_src http :pretty
POST /iroh/oauth2/token
Authorization: Basic XXXXXXXXXXXXX
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
 &subject_token=JWT_WHERE_SUB_IS_USER_ID
 &subject_token_type=
  urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token
 &audience=iroh
 &scope=profile
#+end_src

The call takes:

- Authorization contain the info about the Client (id + secret)
- Some JWT signed by the client containing some SecureX ~user-id~
- optionally a list of scopes
- optionally some audience

And should return an access token of this user.
So we could provide a client that would just need to know some user-id to
be able to get a JWT of this user.
* Token Exchange support Okta tokens

The end goal is to provide a mechanism for a team that support Okta login to
retrieve tokens from SecureX for the User's accounts.

*** Introduction

The terminology used in the Authentication/Authorization context are often
fuzzy, and even worse, ambiguous depending on which side you are looking into
them.
A *user* in not the same entity when looked from an Okta engineer from a SecureX
engineer, from another Cisco team perspective. So here is an explicit list of
meaning for each word restricted to this document:

- IROH => the main API that powers Threat Response and SecureX
- IROH-Auth => the

- /SecureX user/ or simply /user/ => a SecureX user belongs to a known org
- /SecureX org/ or simply /org/ => The org in SecureX, can be assimilated to the tenant
- /SecureX account/ or simply /account/ => a couple SecureX user with its associated SecureX org
- /User Identity/ or /IdP User/ or /Okta User/ => a user identified via an IdP. Such a user can reach
  potentially multiple SecureX accounts.
- /tenant/ => can be assimilated to SecureX org in this document
- /client/ => the client of the OAuth2 IROH-Auth Provider, an entity making HTTP
  requests to IROH-Auth
- /client object/ or /client entity/ => the OAuth2 clients entity that could be
  created, and configured in IROH-Auth.
- /token/ => A token is a string that could be used to retrieve user information
  (/id_token/), access some API (/access_token/) or retrieve new tokens (/refresh_token/).
  In this document, most token will be JWT (JSON Web Token)

*** Use cases

We would like that a team, which is integrated with SXSO can retrieve tokens from IROH-Auth.