: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 component of IROH focused on Authorization, Authentication,
  User and Org (Tenant) management. It provides a full OAuth2 and OpenID Connect
  provider, as well as an OAuth2 and OpenID Connect client. It exposes API to
  manage Orgs, Users and OAuth2 clients.
- /SXSO/ => The IdP which is powered via Okta. It is mostly seen in this document
  as an OpenID Connect provider, but it also has the ability to be a SAML provider.

- /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.
- /client credentials/ => both an OAuth2 Client object ~client_id~ and
  ~client_secret~. This is used to identify the /client/.
- /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)

- /subject/ => in the terminology used in the Token Exchange RFC, a subject would
  be a /SecureX user id/.

*** Use cases

We would like that a team, which is integrated with SXSO can retrieve tokens from IROH-Auth.
The main issue is that there is not a 1-1 relationship between an SXSO User
Identity and a SecureX user.

So in order to close the gap, we need to provide an API that would help
pre-select the "tenancy" (the /SecureX account/).
So given a token that would provide:

- an SXSO User Identity Id (for example: ~0oaox2ch79pg6fyWZ0h7~)
- some OAuth2 Client credentials

This API should return a list of *subjects* ideally with a short list of metas
that would help the client to select one to choose.
So this first selection should most probably be interactive so the end user (the
real person) could select which tenant they would like to link to the product.