deft/notes/scc_integration_piam_option_1.org

:PROPERTIES:
:ID:       e32045d1-4f6b-491d-b83a-6fa1511e2229
:END:
#+title: SCC Integration
#+Author: Yann Esposito
#+Date: [2024-03-06]

- tags :: [[id:ce893df9-32a4-44e0-9eb5-b9817141ee6a][cisco]]
- source ::

* [[https://github.com/advthreat/iroh/issues/9060][EPIC]]
⚠️  **DRAFT**

- ⚠: during the JIT user provisioning we will only have the user-email. As such
  common fields such as the user name, user nick, will be empty. Some product
  and in particular some UI rely on these user field to exists.

** SCC Integration

identified tasks
<https://airtable.com/appZKQe0zXhVMepC8/shrdGCDFRzqZoIIFc/tblP6J2lMHF942Emq>

*** Functional Requirements

We plan on using part of the XDR UI inside another Web application SCC.
SCC is in charge of centralizing customer products and users. The SCC UI
session will be handled via a /PIAM token/[^1].

*** Specification

**** PIAM Terminology and concepts

An Enterprise can access to different regions.
Into each region, we can have "Platform Group".
Within each Platform Group, you can have at most 1 IROH headless org.
Or if the org upgrade to XDR 1 IROH and 1 XDR with the exact same tenant-id.

Example from PIAM doc; PIAM Enterprise Structure

#+NAME: Enterprise_0
#+begin_src mermaid :file scc_integration_piam_enterprise_structure_0.png
flowchart TB;
    Enterprise_3443 --> NAM
    Enterprise_3443 --> APJC
    NAM --> PlatformGroup_1
    APJC --> PlatformGroup_2
    NAM --> SecureAccess_49b9
    PlatformGroup_1 --> IROH_f122b
    PlatformGroup_1 --> SSX_358e
    APJC --> CDO_193a
    PlatformGroup_2 --> IROH_57db
    PlatformGroup_2 --> SSX_9dc5
#+end_src

Then the customer buy XDR in NAM in =PlatformGroup_1=

#+NAME: Enterprise_1
#+begin_src mermaid :file scc_integration_piam_enterprise_structure_1.png
flowchart TB;
    Enterprise_3443 --> NAM
    Enterprise_3443 --> APJC
    NAM --> PlatformGroup_1
    APJC --> PlatformGroup_2
    NAM --> SecureAccess_49b9
    PlatformGroup_1 --> IROH_f122b
    PlatformGroup_1 --> XDR_f122b
    PlatformGroup_1 --> SSX_358e
    APJC --> CDO_193a
    PlatformGroup_2 --> IROH_57db
    PlatformGroup_2 --> SSX_9dc5
#+end_src


Then the customer buy a new XDR in NAM, they need to create a new Platform Group:

#+NAME: Enterprise_2
#+begin_src mermaid :file scc_integration_piam_enterprise_structure_2.png
flowchart TB;
    Enterprise_3443 --> NAM
    Enterprise_3443 --> APJC
    NAM --> PlatformGroup_1
    APJC --> PlatformGroup_2
    NAM --> PlatformGroup_3
    NAM --> SecureAccess_49b9
    PlatformGroup_1 --> IROH_f122b
    PlatformGroup_1 --> XDR_f122b
    PlatformGroup_1 --> SSX_358e
    PlatformGroup_3 --> IROH_1234
    PlatformGroup_3 --> XDR_1234
    APJC --> CDO_193a
    PlatformGroup_2 --> IROH_57db
    PlatformGroup_2 --> SSX_9dc5
#+end_src

***** PIAM Tokens

A PIAM Token is a JWT signed and issued by PIAM.

A client can request PIAM to issue a token. Depending on the requested scopes
and the identity of the client and parameter of the request different PIAM Token
could be generated.

For this specific work we are interested in two different kind of tokens.

- Tokens for SCC audience.
- Tokens for some Application (for example DI)

In both cases, for this feature we are interested in the following claims:
- ~sub~: the PIAM identity which is an *email* and not an unique identifier, AN EMAIL!
- ~security-cloud~ claim which contain a list of strings. Each of this string is
  intended to be parsed to represent a "Product Access".
  For example the string
  ="security:iroh:integration-admin:e0b9859c-3bdd-4e6c-87de-c7fb8caf122b"=
  represent the fact that this token can give access to the product /iroh/ with
  the role /integration-admin/ for the /tenant id/ =e0b9859c-3bdd-4e6c-87de-c7fb8caf122b=.
  :warning:
  IT IS NOT FIXED WHAT /tenant id/ WILL BE, FOR NOW, THIS IS THE IROH ORG-ID.
  BUT IT IS PLANNED TO BE A /product tenant id/ GENERATED BY PIAM AND SAVED IN PIAM.

For the three different states shown for <<Enterprise_0>>, <<Enterprise_1>> and
<<Enterprise_2>>, the ~security-cloud~ , for a token dedicated to use the SCC UI will contain:

For <<Enterprise_0>>

#+begin_src
"security-cloud": [
  "security:enterprise:member:2a715451-c4c2-4d46-b3e3-69d8b53b3443",
  "security:iroh:integrations-admin:e0b9859c-3bdd-4e6c-87de-c7fb8caf122b",
  "security:iroh:integrations-admin:61ad26da-bf66-44f3-9648-738704b957db"
]
#+end_src

For <<Enterprise_1>>

#+begin_src
"security-cloud": [
  "security:enterprise:member:2a715451-c4c2-4d46-b3e3-69d8b53b3443",
  "security:iroh:integrations-admin:e0b9859c-3bdd-4e6c-87de-c7fb8caf122b",
  "security:iroh:integrations-admin:61ad26da-bf66-44f3-9648-738704b957db"
]
#+end_src

For <<Enterprise_2>>

#+begin_src
"security-cloud": [
  "security:enterprise:member:2a715451-c4c2-4d46-b3e3-69d8b53b3443",
  "security:iroh:integrations-admin:e0b9859c-3bdd-4e6c-87de-c7fb8caf122b",
  "security:iroh:integrations-admin:61ad26da-bf66-44f3-9648-738704b957db"
  "security:iroh:integrations-admin:12345678-ae36-1afb-3633-acf7147db123"
]
#+end_src


** Tasks

- Create Token Exchange API (still working on gathering technical details)
- JIT user sync between PIAM and IROH (still need a few details)
- New module auth in IROH to support PIAM Auth (cc @msprunck)
- Create new role for PIAM Administrators within XDR (to be defined by PM)
- Role mapping with SCSO (to be defined by PM)
- SecureX Orgs migration to Common Orgs @yogsototh: should be handled via
  Brownfield attach API effort, otherwise there is no known way to send the IROH
  tenant ID to PIAM/SCC. As such this should be customer driven, and the related
  work has not yet started for Q3.
- Licence Restriction in XDR based on module capability (cc @msprunck)
- Disable XDR functionality from IROH when XDR license expires (see another
  comment expect about 1 to 2 releases of dev work, 1 to 2 releases of team
  sync, perhaps more depending on the other team)

*[Update 2024-03-14]: new tasks discovered after PIAM sync*:

- Universal PIAM API with different onboard rules:
  - creating an headless IROH Org
  - creating an XDR Org
  - upgrading an headless IROH Org to an XDR Org
  - downgrading an XDR Org to an headless IROH Org
- Add a new Middleware to support PIAM token, we should also look for a header
  containing a ~product-tenant-id~ in order to be able to transform this request
  with a valid IROH user request-identity.
- Update the Universal PIAM API to keep track of the ~product-tenant-id~.
- Create a migration script to attach the PIAM ~product-tenant-id~ to existing IROH ~org-id~.

*[Update 2024-03-18]: need to support Secure Client UI*

- secure-client flag in the Org
- init flag of Orgs using Secure Access team to set
- Add secure-client flag during the provisioning
- Handle Invite flow target URL
- Show the Org flags (labels, applications) in the Registration UI

#+begin_quote
Org Flags:
  - scc
  - xdr
  - secure-client
  - sx
#+end_quote

[^1]: [PIAM Token Doc (+ tenant, user, rbac)](https://wwwin-github.cisco.com/cisco-sbgidm/docs/blob/master/access-control/index.md)

** Detailled Tasks

#+begin_quote
Unfixed Vocabulary:

- headless org, common org
#+end_quote

*** PIAM ⇒ IROH token

From [[https://wwwin-github.cisco.com/cisco-sbgidm/docs/blob/master/access-control/index.md#example][PIAM Access Control Doc]]

The PIAM token will look like:

#+begin_src js
{
  "ver": 1,
  "jti": "AT.zWFQnc9MVJQ9wtjFgzzCK88lqTNS3OshQJdQCOeCTHs",
  "iss": "https://sso-staging.test.security.cisco.com/oauth2/aus3uzfwpumAvDegH357",
  "aud": "api://preprod-mercury",
  "iat": 1701291945,
  "exp": 1701295545,
  "cid": "0oa9sca662IshmWh1357",
  "uid": "00udtubj15dIiqKti357",
  "scp": [
    "email",
    "openid",
    "profile",
    "security-cloud",
    "security:xdr",
    "security:cdo",
    "security:ssx"
  ],
  "auth_time": 1701291942,
  "sub": "rhofschn@cisco.com",
  "security-cloud": [
    "security:enterprise:member:2a715451-c4c2-4d46-b3e3-69d8b53b3443",
    "security:xdr:admin:e0b9859c-3bdd-4e6c-87de-c7fb8caf122b",
    "security:cdo:read-only:5dbd3bb4-0e67-4379-a231-068c930a6e41",
    "security:ssx:create-device:4ed0c951-4027-43e0-846f-b1b12789358e",
  ],
  "client-product": "xdr"
}
#+end_src

Expectations:

1. The PIAM token `security-cloud` claim will contain one and only one value
   starting with `security:xdr:`.
2. PIAM will know the target region to call the correct XDR region URL.

We will expose an endpoint:

- ~POST /iroh/cisco-piam/token~ that given a PIAM token in the ~Authorization~
  header as Bearer token will:
  1. Look up for:
     - user-email = sub claim of PIAM token
     - org-id = TENANT_ID part of the ~security:xdr~ block
  2. If no org is found ⇒ return a 400 error
     If the org is found ⇒ tag that org as an headless-compatible org
  3. If no user found; Create the new User and return a couple (IROH Session
     Token/Session Refresh Token)
     If user if found; optionally update the user (role) if necessary and return
     a couple IROH Session Token/Session Refresh Token).
  4. Notes;
     - User created via this JIT should have a specific flag to mark they were created via PIAM
     - The token will have a specific audience

*** Just In Time User sync

We will only synchronize user on user login. No service to service
synchronization mechanism. For example, if a user is deleted from PIAM server
this user will never be deleted from IROH server.

*Expectations*:
a. the role specified in the value for XDR product in the ~security-cloud~ claim
   will always be ~admin~.
OR
b. the role specified in the value for XDR product in the ~security-cloud~ claim
   will always be a valid, known XDR role id (~admin~, ~user~ or ~sat~ , for now).

User will created or updated upon calls to retrieve an IROH token from a PIAM
Token only.

Invitations as well as Organization Access Requests will still be handled by IROH.
This mean that a user login into SCC could create a user in an XDR tenant.
BUT, a user having access to this XDR tenant will not necessarily have an SCC account.

In order to improve any future decision, we need to flag Users object to
determine if they only access XDR via SCC portal or if they login directly in
XDR or both.

**** Subtasks

- [ ] Add a flag when a user login into XDR so we will be able to know if user
  logged in only via SCC, only via XDR or both. I suggest adding a field
  ~{:login-product #{(s/enum :scc :xdr :sx :ctr :orbital :internal)}}~ and using
  the ~allowed-login-origins~ to add a tag of the login product.
  Ideally we could then support adding the login origin in the ~aud~ of the JWT.

*** DELEGATED New module Auth in IROH to support PIAM token (cc @msprunck)
*** DELEGATED Role mapping with SCSO (to be defined by PM probably all admin)
*** SX Org migration (Brownfield attach mechanism enough?) YES
*** DELEGATED License Restriction in XDR based on module capability (cc @msprunck)
*** Disable XDR Functionalities when XDR license expires

**** Change the org mode back to ~common~ (1 to 2 releases)

Expectations:

- The common org should already be tagged as ~common~.
- Every common org should have an ~enterprise-id~.

Changes:

Currently we have a single /scopes matrix/  with a "fake role" to simulate
admin user from inactive Orgs.
This need to be changed by a function that given an Org and its Entitlements
returns a /scopes matrix/. (Ideally sharing the same lines).
More precisely we will only need 3 scopes matrix in total:

- a scopes matrix for XDR orgs
- a scopes matrix for inactive XDR orgs
- a scopes matrix for inactive XDR Org which are also a common Org

Sub tasks:

1. Make a decision about the list of scopes for the two new matrix, perhaps
   there will be a need to have different matrices before and after SX EOL.
   a. after SX EOL, unactivated and non common org are fully disabled (I don't
      think that's the case to continue to support SE / Orbital for example)
   b. after SX EOL, there will be an UI that should work for all possible
      "scopes set". We are talking about 1 scopes-set per role per matrix.
      Currently 6 scopes set (admin, user, sat).

I would expect the scopes choice to be done in a few days, and about 1 to 2 releases
(2 to 4 weeks for the code change).

**** Disabling Products
***** SXO (0 release, should already be supported)

We could immediately remove the ~ao~ scope and it should be enough to prevent
Automation usage.

SXO is already consuming Entitlement changes events and thus could detect and
Org becomes inactive and could therefore do the necessary tasks inside SXO.

***** DAP / SCA (1 to 2 releases about team syncing, close to 0 dev effort)

We need to configure a new hook on ~EntitlementSummary~ changes so this could
trigger a decommission.

It should be a matter of adding a webhook with some configuration. So here we
mostly need time to sync with the dev teams to configure the webhooks.
Creating a new webhook should be easy but we will probably need a few days to
gather all necessary data to create this configuration.

*** Org Schema change

IROH will be an API that will be used for two different Applications.
SCC and XDR.
Notice IROH is already used as API for many different applications;
- CTR,
- SecureX,
- XDR,
- Orbital,
- Registration UI,
- Tactical Portal.
- IROH-Admin,
- SecureX UI Dev Env

So SCC will be one more to add, but this time the login method will be different.
Also while all other existing cases are mostly synchronous, we should start to
enforce a lot better the application accessible or not.

Regarding the functionality I suggest not to be too precise and only mention
SCC, XDR and SecureX.

#+begin_src clojure
(s/defschema AllowedApplications
  (s/enum :scc :xdr :sx))
#+end_src

This should probably not be used to enforce anything from the backend yet, but
should be useful for the UI and will help have a better data structure internally.
Currently we create a view with ~xdr-enabled?~, ~sx-enabled?~ etc…
It will be nice to transform this set to add many flags, the new one will be ~scc-enabled?~.

With the current plan, every XDR org will be ~scc-enabled~, but some might not be
~xdr-enabled~, and all will have ~sx-enabled~ set to false. And we need to planify a
time where ~sx~ app will be removed.

*** User Schema change
When we receive a token exchange to generate an IROH token with a PIAM token
containing in the ~security-cloud~ claim a value starting with ~security:iroh:~ then
we should mark that user to be an scc user.

When we receive a token exchange or when a user login as usual, we should mark
that user to be an xdr user.

*** Update Universal Provisioning

Add a query parameter to the Universal Provisioning API (typically ~&headless=true~).
If the provisioning occurs with this parameter then: only onboard DI and SCC.
Keep track of the onboarding state somewhere (perhaps just looking for existing
module instances)

If a provisioning occurs without this parameter then onboard DI, SCC, SXO & SCA.
If we receive an update:
   onboard the missing product (looking at module instances) SXO & SCA.

*** PIAM token support middleware

We need a middleware that provide the ability to translate a PIAM token to an
IROH identity.
We already have a mechanism that depending on the JWT issuer returns a different user-identity.

We should have a mechanism so that an API could accept PIAM token for both cases:

- we just have the PIAM token, this API is not IROH tenant scoped.
- we have the PIAM token as well as a tenant-id (either PIAM product-tenant-id
  or IROH org-id) and the API will be tenant scoped

*** Update Universal Provisioning to track PIAM product-tenant-id
*** Create a migration script to attach the PIAM product-tenant-id to existing IROH org-id

For every org provisioned before we keep track of the product-tenant-id we
should attach a product-tenant-id to the org.

* Official Tasks

[[https://airtable.com/appZKQe0zXhVMepC8/shrdGCDFRzqZoIIFc/tblP6J2lMHF942Emq][Airtable list]]

- create a token exchange API
- JIT user sync between PIAM and IROH
- New module auth in IROH to support PIAM Auth
- Create new role for PIAM Administrators within XDR
- Role Mapping with Security Cloud Sign-on
- SX Orgs migration to Common Orgs
- License Restriction in XDR based on module capability
- Disable XDR functionality from IROH when XDR license expires

Unknown:

- PM how to handle SCC user vs XDR invited users
* Questions to [[webexteams://im?space=f4791010-c534-11ee-a02f-8b2b472f9d7c][channel]]
** User Session

Hello All!

I have a few technical questions for which I would like some clarifications.

The plan as I understood would be to integrate some external UI to the SCC UI.
And this external UI will need to "exchange" the session of the user logged into
SCC into a user in IROH.

As such, I would like to understand how is the session saved in the SCC UI.
Is it a cookie session? If it is, does the session contain a JWT?
If it is a JWT, is it a PIAM token?

If we want to create a valid token in IROH out of such session we will need at least:

A ~user-email~, an ~enterprise-id~ and an SCC user role (from my understanding there
are only two SCC roles, which should roughly be admin and user).

More straight to the point, what would be a secure way to expose an API in IROH
that the integrated UI in SCC could use to exchange an SCC session to an IROH
user token?
If this is a JWT signed by PIAM which contain just an ~user-email~ and an
~enterprise-id~ then this should be fine as I will be able to search for the
single IROH tenant with this ~enterprise-id~ (as I understood we decided to keep
this constraint of preventing multi-XDR tenancy relatively to SCC tenancy).

Also, let me know if my understanding that we will need to manage different type
of token is true?
I think what we call a _PIAM Token_ is an *access token* which is also a *JWT* that
will contain a list from which we could deduce the user-id and its role for
every product. Like: `<PRODUCT>:<USER_ROLE>:<USER-ID-IN-PRODUCT>`.
I don't think the session in SCC is maintained using such token, could you
confirm this?

I also have another question related to the PIAM tokens.
Should we support multiple entries for the same product in the list in the JWT
containing the user-id and role in the external products?

Thanks!
* Sizing
** [[webexteams://im?space=b62bf8f0-6062-11ed-9564-a57f2c094899&message=c82ce020-db43-11ee-8e37-799ed57689d0][Jyoti question]]
#+begin_quote
2. Disable XDR functionality when XDR license expires (Yann)
	a. Change the org mode back to `common`
	b. Disable SXO, DAP, SAC tenants
#+end_quote

*** Disable XDR Functionalities when XDR license expires

**** Change the org mode back to ~common~ (1 to 2 releases)

Expectations:

- The common org should already be tagged as ~common~.
- Every common org should have an ~enterprise-id~.

Changes:

Currently we have a single /scopes matrix/  with a "fake role" to simulate
admin user from unactivated Orgs.
This need to be changed by a function that given an Org and its Entitlements
returns a /scopes matrix/. (Ideally sharing the same lines).
More precisely we will only need 3 scopes matrix in total:

- a scopes matrix for XDR orgs
- a scopes matrix for unactivated XDR orgs
- a scopes matrix for unactivated XDR Org which are also a common Org

Sub tasks:

1. Make a decision about the list of scopes for the two new matrix, perhaps
   there will be a need to have different matrices before and after SX EOL.
   a. after SX EOL, unactivated and non common org are fully disabled (I don't
      think that's the case to continue to support SE / Orbital for example)
   b. after SX EOL, there will be an UI that should work for all possible
      "scopes set". We are talking about 1 scopes-set per role per matrix.
      Currently 6 scopes set (admin, user, sat).

I would expect the scopes choice to be done in a few days, and about 1 to 2 releases
(2 to 4 weeks for the code change).
**** Disabling Products
***** SXO (0 release, should already be supported)

We could immediately remove the ~ao~ scope and it should be enough to prevent
Automation usage.

SXO is already consuming Entitlement changes events and thus could detect and
Org becomes inactive and could therefore do the necessary tasks inside SXO.

***** DAP / SCA (1 to 2 releases about team syncing, close to 0 dev effort)

We need to configure a new hook on EntitlementSummary changes so this could
trigger a decomission.

It should be a matter of adding a webhook with some configuration. So here we
mostly need time to sync with the dev teams to configure the webhooks.
Creating a new webhook should be easy but we will probably need a few days to
gather all necessary data to create this configuration.