deft/notes/cisco_ft_securex_registration.org

:PROPERTIES:
:ID:       1208f09c-d37d-4e6b-9110-151f3c6b7d34
:END:
#+TITLE: Cisco FT SecureX Simplified Registration
#+Author: Yann Esposito
#+Date: [2021-12-07]

- tags :: [[id:299643a7-00e5-47fb-a987-3b9278e89da3][Auth]]
- source :: https://github.com/advthreat/response/issues/821
- dashboard :: https://github.com/advthreat/iroh/projects/32

* Table of Content :TOC_3:QUOTE:
#+BEGIN_QUOTE
- [[#functional-spec][Functional Spec]]
- [[#technical-plan][Technical Plan]]
  - [[#support-private-email-vs-public-emails][Support private email vs public emails]]
    - [[#canceled-support-allow-list-exceptions-for-some-cisco-user][CANCELED Support allow-list exceptions for some Cisco user.]]
  - [[#support-search-admin-with-same-email-domain][Support, search admin with same email domain]]
  - [[#new-ui-sync][New UI Sync]]
    - [[#new-auth-apis][New Auth APIs]]
    - [[#new-api-jwt-middleware][New API JWT middleware]]
    - [[#new-iroh-auth-crud-services][New IROH-Auth CRUD Services]]
    - [[#new-iroh-auth-api][New IROH-Auth API]]
    - [[#new-iroh-auth-login-process][New IROH-Auth login process.]]
  - [[#email-notification-of-org-request-accesses][Email Notification of Org Request Accesses]]
    - [[#notes][Notes]]
  - [[#org-requests-crud-api-for-admins-of-the-orgs][Org Requests CRUD API for Admins of the Orgs]]
    - [[#list][List]]
    - [[#read][Read]]
    - [[#patch-the-org-access][Patch the Org Access]]
#+END_QUOTE

* Functional Spec

Response issues:
- https://github.com/advthreat/response/issues/821

Figma: https://www.figma.com/file/Bz3m25kpWXpdct7AnhmNsW/SXSO-Registeration?node-id=759%3A5926

* Technical Plan
** DONE Support private email vs public emails

*DONE*
+/Estimate: 1 release cycles after the list is provided./+

The solution is to use a blacklist of domains where any user could create
multiple email accounts pseudo-anonymously.

Details: https://github.com/advthreat/response/issues/979

*** CANCELED Support allow-list exceptions for some Cisco user.
:LOGBOOK:
- State "CANCELED"   from "HOLD"       [2022-01-17 Mon 10:57] \\
  This only concern new account creation. User with gmail account could still login.
:END:

/Estimate: 1 release cycles after the list is provided./

Typically we should allow some users with an email like =some-user+XXX@gmail.com=

** Support, search admin with same email domain

/Estimate: 1 release cycle./
Note: *Work in progress*

We should be able given an email from a user, to find all the orgs for
which at least one of its admin has a matching domain name.

1. Most efficient: add an invisible field =email-domain= to all users. This
   should be lower-case, and we will need a migration.
   Doing this we could have a faster match than using string related queries.

Problems, users can login in the same user, with the same public email with
different emails.
This should be rare.

2. Search via text match.


The algorithm should look a bit like:

#+begin_src clojure

;; only when this is an unknown user
;; so a single approval will prevent the user to see this page.
(let [user-email ,,,
      domain (string/replace user-email #".*@" "")
      users (matching-admins domain) ;; returns a potentially big list of admin users
      indexed-orgs (group-by :org-id users)]
  (vals indexed-orgs))
#+end_src


Once this list of orgs is found.
We should also check the list of pending or rejected OrgAccessRequest for this user in
order to prevent the user to request access multiple time.

** New UI Sync

/Estimate: 9 release cycles/

We should find a way to hand the UI work to the UI team.
Right now, the page are all generated in IROH.

To reach that ideally we should sync the source code as a jar in IROH.

In order to give the UI the ability to make a front-end application, we
should create news APIS that support a new UserIdentity-level JWT

*** New Auth APIs

Continue to use the =/code= route of iroh-auth.
But instead of returning a Session Token, it will return a UserIdentity Token.
This is a JWT with the important data from the IdP:

- idp-id
- user-identity-id
- user-email
- etc…

When the user is redirected to an HTML generated page, we should add the
=code= in the anchor parameter of the route so the UI will be able to use
that code to retrieve a UserIdentity Token.

*** New API JWT middleware

/Estimate: 1 release cycle/

We need to change the configuration of the check JWT middleware to support
UserIdentity Token instead. And use this configuration for this new API.

The =user-identity-jwt= should contain enough data to retrieve:
- =idp-mapping=
- =user-email=
- all other metas, as user-name, user-nick, etc…
*** New IROH-Auth CRUD Services
**** OrgAccessRequest

/Estimate: 5 release cycles/

This new service should be mostly a CRUD service on top of TKStore with the
following schema:

#+begin_src clojure
(s/defschema OrgAccessRequestStatus
  (s/enum :pending :accepted :rejected))

(s/defschema OrgAccessRequest
  (st/merge
   {:id UUID
    :idp-mapping IdPMapping
    :user-email s/Str
    :org-id s/Str
    :status OrgAccessRequestStatus
    :created-at DateTime}
   (st/optional-keys
    {:user-name s/Str
     :user-nick s/Str
     :role-granted Role ;; the role granted if the request is accepted
     :approver-id UserId
     :approver-email UserEmail ;; email of the approver
     :updated-at DateTime
     })))
#+end_src

#+begin_src clojure
(defprotocol OrgAccessRequestService
  "See iroh-auth.registration.org-access-request.schemas/ServiceFns for schemas."
  :extend-via-metadata true

  ;; User filtered CRUD+Search for REST API related methods
  (search-org-access-requests-for-user-identity
    [this user-identity filter-map pagination-params]
    "Search all OrgAccessRequest made by this user identity accross all orgs.
     This should only be visible via the registration page on the new API accepting
     user-identity JWT")

  ;; User filtered CRUD+Search for REST API related methods
  (search-org-access-requests-for-org
    [this request-identity filter-map pagination-params]
    "Search all OrgAccessRequest of the org of the user of the request-identity")

  (get-org-access-request
    [this request-identity org-access-request-id]
    "Return the OrgAccessRequest for a user using the org-access-request-id")

  (patch-org-access-request
    [this request-identity org-access-request-id org-access-request-patch]
    "Change the status of an OrgAccessRequest to grant/reject it.
     Note user creation could be a side effect.")

  ;; Internal CRUD+Search
  (raw-search-org-access-requests
    [this filter-map pagination-params]
    "Search all OrgAccessRequest grants")

  (raw-get-org-access-request
    [this org-access-request-id]
    "Return the OrgAccessRequest grant")

  (raw-patch-org-access-request
    [this org-access-request-id org-access-request-patch]
    "Update the status of an OrgAccessRequest."))
#+end_src

**** UserIdentity

/Estimate: 1 release cycle/

Should look a lot like a user but instead of a =user-id= it should have a
=user-identity-id= and should not have any =org-id= value.

It should also contain a field containing a set of hidden org-ids that will
be the orgs not to display on the registration webpages.

#+begin_src clojure
(s/defschema UserIdentity
  (ist/open-schema-any-keys
   {:id s/Str
    :email
    :name
    :nickname
    :last-logged-in [,,,]
    }))
#+end_src

*** New IROH-Auth API

/Estimate: 2 release cycle/
/Depends: IROH-Auth CRUD Service/

This new API should only work with UserIdentity JWT.

#+begin_src
POST /iroh/registration/org-access/:org-id ;; request access to a matching org
POST /iroh/registration/hide-org/:org-id ;; ability to hide an org-access
GET  /iroh/registration/matching-accounts ;; list all the matching accounts
GET  /iroh/registration/matching-orgs ;; list all the matching orgs
GET  /iroh/registration/pending-invites ;; list all the pending invites
GET  /iroh/registration/registration-view ;; helper to make a single http call
#+end_src

**** Request Org Access

We need to create another store with another Entity for access request to an Org.

#+begin_src clojure
(s/defschema OrgAccessRequest
  (st/merge
   {:id UUID
    :idp-mapping IdPMapping
    :user-email s/Str
    :org-id s/Str
    :status (s/enum :pending :accepted :rejected)
    :created-at DateTime}
   (st/optional-keys
    {:user-name s/Str
     :user-nick s/Str
     :approver-id UserId
     :approver-email UserEmail ;; email of the approver
     :updated-at DateTime
     })))
#+end_src

When a user request access to an organization.
We should create this object in DB.


#+begin_src
POST  /iroh/registration/org-access/:org-id ;; request access to a matching org
#+end_src

#+begin_src http
POST /iroh/registration/org-access/:org-id

Accept: application/json
Content-Type: application/json
User-Agent: ob-http
Authorization: Bearer ${user-identity-jwt}
#+end_src

With this, and if every check matches:

1. There is a known active admin of this org with an email with the same domain name
2. The org is active

We should:

1. create a new =OrgAccessRequest= object in DB.
2. Send emails (see the [[*Email Notification of Org Request Accesses]] section)

**** Hide Org

#+begin_src http
POST /iroh/registration/hide-org/:org-id

Accept: application/json
Content-Type: application/json
User-Agent: ob-http
Authorization: Bearer ${user-identity-jwt}
#+end_src

Should save in the user identity store a new org-id to hide.
This impacts the call to `matching-orgs` such that orgs marked as hidden
should not be displayed when calling the `matching-org` route.

**** List Matching Accounts

#+begin_src http
GET  /iroh/registration/matching-accounts

Accept: application/json
Content-Type: application/json
User-Agent: ob-http
Authorization: Bearer ${user-identity-jwt}
#+end_src

It should return a list of object with the following schema sorted by last
logged in time by the user:

#+begin_src clojure
{:user User
 :org Org
 :last-login-date DateTime
 :relative-last-login s/Str
 :org-created-at DateTime
 :relative-org-created-at s/Str
 :activated? s/Bool
 :org-nb-users s/Int}
#+end_src

**** List Matching Orgs

#+begin_src http
GET  /iroh/registration/matching-orgs
#+end_src

Should return a list of objects with the following schema (sort to be defined):

#+begin_src clojure
{:org Org
 :org-nb-users s/Int
 :org-request-access-status OrgRequestAccessStatus}
#+end_src

Note this is not a straightforward route.
We should list all current matching org, as well as listing all current
=OrgRequestAccess= made by this =UserIdentity=.
And also retrieve the hidden orgs in the =UserIdentity= in DB.

Then, return a list of orgs, with the current status and remove from the
list the hidden orgs from the =UserIdentity=.

**** List Pending Invites
#+begin_src http
GET  /iroh/registration/pending-invites
#+end_src

Here is an example value:

#+begin_src clojure
{:role "admin",
 :org-id "org-1",
 :expires-in-nb-days 7,
 :status "pending",
 :invitee-email "chuck@example.org",
 :inviter-user-id "org-1-admin-1"}
#+end_src

**** Registration View
GET  /iroh/registration/registration-view

Should return the same result as the union of the calls to
=matching-accounts=, =matching-orgs= and =pending-invites=.

#+begin_src clojure
{:matching-accounts [,,,]
 :matching-orgs [,,,]
 :pending-invites [,,,]}
#+end_src
*** New IROH-Auth login process.

Every-time a users successfully login via an IdP we should synchronize the
=UserIdentity= value in our DB accordingly.
It should occurs not only during the account registration, but also for
every new login.

** Email Notification of Org Request Accesses

/Estimate: 4 release cycle after email+html templates/

1. List all the admins of the requested org.
2.a. If there is fewer admins than a number that could be configured in the
     node configuration. Then we send an email to all admins.
2.b. If there are more admins than this specific number, then we randomly
     chose this maximal number of admins and send them an email notification.



*TODO* Have an email template (both HTML and Text)
*** Notes

Need to be able to trigger a new request to join after 7 days.

** Org Requests CRUD API for Admins of the Orgs

/Estimate: 3 release cycle after mail templates + text/

There should be a CRUD API restricted to the ~admin/user-mgmt/org-requests~ scope:

- ~GET  /iroh/user-mgmt/org-requests~ list pending org access requests
- ~GET  /iroh/user-mgmt/org-requests/<id>~ read a single org access request
- ~POST /iroh/user-mgmt/org-requests/<id>/accept~ Grant the access
- ~POST /iroh/user-mgmt/org-requests/<id>/reject~ Reject the access

*** List

~GET  /iroh/user-mgmt/org-requests~

If no parameter is provided, only list pending =OrgAccessRequests= of the org
of the caller.
Otherwise we could pass the query-parameter =status= with the following
value(s):

- =pending=
- =accepted=
- =rejected=

Note we should probably support duplicate statuses.
Ex:

~GET /iroh/user-mgmt/org-requests?status=accepted&status=pending~

*** Read

~GET /iroh/user-mgmt/org-requests/org-request-id~

Should returns a 404 if not found or the single Org Access Request object.

*** Patch the Org Access

~PATCH /iroh/user-mgmt/org-requests/<id>~ Grant/Reject the access

The body should be a JSON Object with:
- an optional field =role= whose value could be either =admin= or =user= (default
  to =user=)
- a mandatory =status= field whose value could be either =accepted= or =rejected=.

A few examples of valid values:

#+begin_src js
{"role":"admin"
 "status":"accepted"}
#+end_src

#+begin_src js
{"status":"accepted"}
#+end_src

#+begin_src js
{"status":"rejected"}
#+end_src

During the call we should:

1. Create a new user with:

#+begin_src clojure
{:user-id (gen-uuid)
 :org-id (:org-id org-access-request)
 :user-email (:user-email org-access-request)
 :idp-mappings [(:idp-mapping org-access-request)]
 :user-name (:user-name org-access-request)
 :user-nick (:user-nick org-access-request)
 :role (get-in request [:body :role])
 :enabled? true
 }
#+end_src

2. Send an email to user confirming his access was granted.

*TODO* have an email template + text.