deft/notes/customer_manager.org

:PROPERTIES:
:ID:       99fd9444-ae5d-4d51-a295-a936fc01928a
:END:
#+TITLE: Customer Manager
#+Author: Yann Esposito
#+Date: [2021-10-15]

- tags :: [[id:91f33b35-6e4e-4213-b214-972ee20722df][Cisco]]
- source :: 

* Table of Content :TOC_3:
- [[#customer-manager][Customer Manager]]
  - [[#questions][Questions]]
  - [[#remarks][Remarks]]
  - [[#quick-wins-along-the-way][Quick wins along the way]]
    - [[#q2-cross-region-links][[Q2] Cross region links]]
    - [[#q2-local-account-switch-tenancy-switching][[Q2?] Local Account Switch (Tenancy Switching)]]
    - [[#done-backend-to-backend-oauth2-tokens-exchange][[DONE] backend-to-backend OAuth2 tokens exchange]]
    - [[#q3-org-level-credentials][[Q3?] org-level credentials]]
  - [[#intermediate-steps-optional][Intermediate steps (optional)]]
    - [[#-cross-region-account-switching][[?] Cross region Account switching]]
    - [[#-organization-managements-once-we-have-a-deployed-a-global-node-that][[?] Organization managements Once we have a deployed a global node that]]
    - [[#-customer-selection-][[?] Customer Selection (?)]]
    - [[#-customer-invitations][[?] Customer Invitations]]
    - [[#-tenant-management][[?] Tenant management]]

* Customer Manager

Note this document is still a work in progress.

** Questions

One supposition is not entirely unambiguous in the Customer Manager document.
Can we assume that a /user identity/ (login via SXSO) can have at most a
single /customer/?

Where should be the source of truth?

- Does SXSO select the customer at user login?
- Does the customer is associated in the customer manager after the user
  authentication via SXSO?

** Remarks

An important remark that might be missing is about user management and in
particular removing users.

If we push for our customer to integrate their own IdP, they will probably
be under the impression that removing/changing the role of user in their
system will be replicated inside SXSO/Customer Manager/SecureX.

Note that once a user could use SecureX, they can authorize many clients.
And thus, even if they are no more able to login inside SecureX, their
clients will still work until their account is disable inside SecureX.

** Quick wins along the way
*** [Q2] Cross region links

One easy problem to solve (probably for Q2) is to provide a region
switching mechanism backed by an API.
That way the UI will be able to provide a mechanism to help the user switch
from one region to another.

*** [Q2?] Local Account Switch (Tenancy Switching)

The API will provide two new routes:

- =GET /iroh/session/accounts=
 => returns a list of accounts + URLs
- =POST /iroh/session/switch-account=
  => revoke current JWT / returns a new access and refresh token for the
  new account

The clients (UI) could use these endpoint to:
- list the accounts
- switch the account

The tenant/session is still  local to the domain name/application (SecureX/CTR/Orbital)

**** Notes

The call to switch account should revoke the JWT to prevent a bug in the UI
that will continue to use an older access token from the wrong org/tenant.

*** [DONE] backend-to-backend OAuth2 tokens exchange

> *code already delivered, not deployed*

Idea, give other teams a trusted client.
With this client and a user-id the team could get tokens for this user-id.

This is a probably safer mechanism than Webhooks that do not involve any =client-secret=.
Ideally the webhooks should only provide user ids, and the other team will
be able to retrieve credential tokens for this user via this
backend-to-backend token delivery route.

One major advantage is also that the tokens scopes (and many other properties)
will be managed in a centralized client.

Ideally every Cisco team that integrate within IROH should have a single client.

This new API should solve many points mentioned in the /Application - SecureX Integrations/
part of the document:

#+begin_quote
- Clients can acquire tokens, possibly from the Customer Manager, to access SecureX APIs for a target SecureX Organization
- Access is pre-authorized, and tokens can be acquired without user consent
- Achievable using the OAuth Client Credentials Grant using a confidential client with a client secret or
certificate. Source application tenant is provided as part of the token request.
#+end_quote

*** [Q3?] org-level credentials

We simulate the existence of an org-level user.
We do not create a new entry in the DB, instead, we simply add a logic in
=get-user= function such that if the name matches something like
=admin-<org-id>= we retrieve an admin user data.

This way this should not break the existing mechanism of security regarding
authorizations and OAuth2.

Then in order to detach an entity to the org-level (typically a client or
an application grant) we could simply change the =user-id= to match this
=admin-<org-id>=.

It looks like this could work, but this need to be tested first as we might
miss a technical detail making this difficult.

This with the previous backend-to-backend route should solve the following entry:

#+begin_quote
- These tokens provide access on behalf of the source application tenant and not on behalf of a user
#+end_quote


**** TODO Tasks
SCHEDULED: <2021-10-18 Mon>

- [ ] handle re-ownership
- [ ] interactive OAuth2 grant
- [ ] scope to access the admin entities as a user

** Intermediate steps (optional)
*** [?] Cross region Account switching

The goal of this step is to deploy a new single global application API + UI
that will help the user select their account across regions.
The user will be able to see the list of accounts per region and should be
able to directly login to the selected account.

This could be the occasion to make a new global deployment.
A specific node with credentials that could be used to call all IROH nodes.

This could be challenging to have this in a few weeks, but this open the
notion of /Customer Manager Session/ at the User-Identity level.

**** Tasks

- [ ] Support sub-routes in IROH using another public key for JWT.
  Also the claims will be different.
  The claims will not contain any =user-id= nor =org-id=, but only
  =user-identity-id= and probably =idp-id= (not sure).
- [ ] Support login via SXSO-only but returning a non IROH JWT, but a
  Customer Manager JWT. This is the biggest work to be done. Currently the
  code to login takes great care at checking some claims in the JWTs.
  We need to support User-Identity session instead of User session.
- [ ] Support login to a pre-selected account. This is also not a trivial
  task, there are multiple solutions. One is just to force a new login,
  another one more direct would be to take advantage of the trust-relation
  between the Customer Manager and the IROH nodes to prevent a redirect to
  login via SXSO.
- [ ] Create a new set of services in IROH that will be the future Customer
  Manager. And see with the ops how we could deploy it.
  I would guess deploy this on NAM, and the node will call the 3 IROH nodes.
  This will be the occasion to test the latency between nodes and see if this
  is not problem.
*** [?] Organization managements Once we have a deployed a global node that

could makes call to all IROH nodes.

We could start to think about providing more and more API accesses.

Typically one step could be a way to control the orgs from this centralized
node.
Typically, see all your orgs across all regions and disable/rename the orgs.
*** [?] Customer Selection (?)

If we have a global node deployed where users could login

At this step we could also imagine that a User-Identity might belongs to
multiple Customers. This would probably also be the right moment to provide
APIs managing these.


**** Tasks

- [ ] Design a user-identity and customer schema
- [ ] New stores to create: =customers= and =user-identities=.
  This change might force a DB Migration of the =users= DB in all IROH nodes.

*** [?] Customer Invitations

We could probably reuse the SecureX invitation API to invite people into a
=Customer= in the Customer Manager. This invitation will probably be a lot
simpler as it will not involve SecureX org selection and a single region.

*** [?] Tenant management

- At this step we should be able to login user at their User Identity level (SXSO login).
- The User Identity should be linked to a single Customer(?).
- The IROH nodes should support new APIs that could be called using the
  tokens from the customer manager node.

Now we could be able to create/update/move across orgs/move across regions
module-instances (tenants).