: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

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/.


*** Using SXSO tokens vs SXSO User Identity

SXSO support both OpenID Connect and SAML v2.0.
If we were to support direct tokens from SXSO, it would still mean the product
need to provide its own client credentials.
Also it would need IROH-Auth to integrate a complex system to verify and trust
these external tokens.

Instead this proposal only need to use IROH-Auth signed tokens.
The only work to be done by the product would be to extract the SXSO ~User Identity Id~
from either the ~id_token~ or the ~SAMLResponse~.
Which should be trivial.

If this is difficult, we could most probably add a layer inside IROH-Auth later
to check the authenticity of the ~id_token~ and/or the ~SAMLResponse~ and return the
~User Identity Id~.

*** Exchange an SXSO User Identity for a SecureX user tokens

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.
Along with the subjects list there should also be a list of ~subject_token~.
Concretely, the response should look like:

#+begin_src js
[{"user":{"user-id" : "42", "user-name": "John Doe", "user-email": "..."}
  "org" :{"name":"Cisco", ...}
  "subject_token":"eYjj....."},
 {"user":{"user-id" : "43", "user-name": "John Doe", "user-email": "..."}
  "org" :{"name":"Pepsi", ...}
  "subject_token":"eYjj....."}]
#+end_src

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.

Once the subject is selected, the client could then use the Token Exchange with:

- a ~subject_token~ retrieved from the previous call. This should be a JWT signed
  by IROH-Auth. I think it would be safe to have an infinite or at least very
  long lifetime for these JWT.
- an ~actor_token~ ; this is an ~access_token~ generated from the client object
  handled to the client. This way IROH-Auth could authenticate that the request
  is made by a know client.

If IROH-Auth can verify that the actor token comes from a trusted source we
could return new tokens. The response will always return an /access_token/ but
could optionally return an /id_token/ as well as a /refresh_token/.

**** Notes

- We could restrict the access token so much that only the ~id_token~ is useful.
  This is useful when the client does not intend to use IROH API, but only
  retrieve a SecureX user.
- Most of the time the client will request both an access token and a refresh token.
  Once given, the refresh token could be used call IROH API on behalf of the user.
- We should probably never use the user email as a safe user identity as this
  could change, also the OIDC RFC is quite clear that we could only use the ~sub~
  claim of the ~id_token~ to use as user identity id.

*** Tasks

- Expose the Account selection API (done, but still fresh)
- Optionally add ~subject_token~ to the account selection API, probably depending
  on some scope and/or some audience of the token making the call
- Add support for Token Exchange RFC