2022-04-26 14:03:46 +00:00
|
|
|
:PROPERTIES:
|
|
|
|
:ID: 97cfc6a5-3522-4ebc-99c6-704740ea97e8
|
|
|
|
:END:
|
|
|
|
#+TITLE: Token Exchange in IROH-Auth
|
|
|
|
#+Author: Yann Esposito
|
|
|
|
#+Date: [2022-04-26]
|
2022-04-26 14:06:11 +00:00
|
|
|
- tags :: [[id:91f33b35-6e4e-4213-b214-972ee20722df][Cisco]] [[id:299643a7-00e5-47fb-a987-3b9278e89da3][Auth]]
|
2022-04-26 14:03:46 +00:00
|
|
|
- source ::
|
2022-04-26 14:06:11 +00:00
|
|
|
|
|
|
|
- Token Exchange RFC :: https://www.rfc-editor.org/rfc/rfc8693.html
|
2022-04-26 14:07:23 +00:00
|
|
|
|
|
|
|
* Token Exchange
|
|
|
|
|
2022-06-01 08:37:10 +00:00
|
|
|
The end goal is to provide a mechanism for a team that support Okta login to
|
2022-06-01 08:38:41 +00:00
|
|
|
retrieve tokens from SecureX for the User's accounts.
|
2022-06-01 08:40:25 +00:00
|
|
|
|
2022-06-01 08:55:03 +00:00
|
|
|
*** 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
|
2022-06-01 09:53:28 +00:00
|
|
|
engineer, from another Cisco team perspective.
|
|
|
|
This is why at the bottom of this document there is a Terminology section.
|
2022-06-01 09:32:38 +00:00
|
|
|
|
|
|
|
*** Using SXSO tokens vs SXSO User Identity
|
|
|
|
|
|
|
|
SXSO support both OpenID Connect and SAML v2.0.
|
2022-06-01 09:34:08 +00:00
|
|
|
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~.
|
2022-06-01 09:35:35 +00:00
|
|
|
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~.
|
|
|
|
|
2022-06-01 09:31:37 +00:00
|
|
|
*** Exchange an SXSO User Identity for a SecureX user tokens
|
2022-06-01 08:42:34 +00:00
|
|
|
|
2022-06-01 08:58:38 +00:00
|
|
|
We would like that a team, which is integrated with SXSO can retrieve tokens from IROH-Auth.
|
2022-06-01 09:04:49 +00:00
|
|
|
The main issue is that there is not a 1-1 relationship between an SXSO User
|
|
|
|
Identity and a SecureX user.
|
2022-06-01 09:07:48 +00:00
|
|
|
|
|
|
|
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~)
|
2022-06-01 09:09:14 +00:00
|
|
|
- some OAuth2 Client credentials
|
2022-06-01 09:10:20 +00:00
|
|
|
|
|
|
|
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.
|
2022-06-01 09:16:30 +00:00
|
|
|
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
|
|
|
|
|
2022-06-01 09:11:47 +00:00
|
|
|
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.
|
2022-06-01 09:12:59 +00:00
|
|
|
|
|
|
|
Once the subject is selected, the client could then use the Token Exchange with:
|
|
|
|
|
2022-06-01 09:17:37 +00:00
|
|
|
- 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.
|
2022-06-01 09:19:57 +00:00
|
|
|
- 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.
|
2022-06-01 09:29:13 +00:00
|
|
|
|
|
|
|
If IROH-Auth can verify that the actor token comes from a trusted source we
|
2022-06-01 09:49:21 +00:00
|
|
|
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~.
|
2022-06-01 09:29:13 +00:00
|
|
|
|
2022-06-01 09:42:26 +00:00
|
|
|
**** Notes
|
2022-06-01 09:29:13 +00:00
|
|
|
|
|
|
|
- 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.
|
2022-06-01 09:31:37 +00:00
|
|
|
- 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.
|
2022-06-01 09:42:26 +00:00
|
|
|
- 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.
|
2022-06-01 09:35:35 +00:00
|
|
|
|
2022-06-01 09:47:07 +00:00
|
|
|
*** Tasks
|
2022-06-01 09:37:21 +00:00
|
|
|
|
2022-06-01 09:51:16 +00:00
|
|
|
- Expose the Account selection API (merged but still subject to change)
|
2022-06-01 09:37:21 +00:00
|
|
|
- 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
|
2022-06-01 09:53:28 +00:00
|
|
|
|
|
|
|
|
|
|
|
*** Terminology
|
|
|
|
|
|
|
|
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/.
|