yogsototh/deft
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
deft/notes/scc_integration_piam_option_1.org
Yann Esposito (Yogsototh) 9f0200c13d
update
2024-06-27 11:09:53 +02:00

20 KiB
Raw Permalink Blame History

SCC Integration

tags
cisco
source

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

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

Then the customer buy XDR in NAM in PlatformGroup_1

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

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

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

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

"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"
]

For <<Enterprise_1>>

"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"
]

For <<Enterprise_2>>

"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"
]

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

Org Flags:

  • scc
  • xdr
  • secure-client
  • sx

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

Detailled Tasks

Unfixed Vocabulary:

  • headless org, common org

PIAM ⇒ IROH token

From PIAM Access Control Doc

The PIAM token will look like:

{
  "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"
}

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:

  1. the role specified in the value for XDR product in the security-cloud claim will always be admin.

OR

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

    1. 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)
    2. 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.

(s/defschema AllowedApplications
  (s/enum :scc :xdr :sx))

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

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

Jyoti question

  1. Disable XDR functionality when XDR license expires (Yann)
  1. Change the org mode back to `common`
  2. Disable SXO, DAP, SAC tenants

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.

    1. 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)
    2. 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.