deft/notes/2021-04-16--12-27-13Z--iroh_auth_presentation.org

:PROPERTIES:
:ID:       a92ff371-3ece-489c-a6cc-34810458f660
:END:
#+TITLE: IROH Auth Presentation
#+Author: Yann Esposito
#+Date: [2021-04-16]

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

* IROH Auth                                                          :ATTACH:
:PROPERTIES:
:ID:       dc5070c0-9040-4175-9a67-c85a21f65f35
:END:


[[attachment:_20210416_150439Screenshot%202021-04-16%20at%2015.04.30.png]]

Yann Esposito <yaesposi@cisco.com>

* Plan

1. Introduction, History
2. Login
3. OAuth2/OIDC Provider
4. Specific Usages Cisco

* 1 - Introduction
* When did you interacted with IROH-Auth?

- *Login* in SecureX
- *Login* in CTR
- *Login* in Orbital
- *Authorized* the Ribbon
- *Invited* someone to your Org
- *Cross Launch* with SSE
- Dealing with JWT
- Changed the role of some user
- When you investigate in CTR (via CTIA's module)
- Created an OAuth2 client

* What is IROH-Auth? (overview)

This is a software subcomponent of /IROH/[fn:iroh] taking care of:

+ *Authentication*
  - provide a user unique identifier
+ *Authorization*
  - decide what user can or cannot do
+ *User Data Model*
+ *Tenancy (Org) Management*
+ *API Clients Management*
+ *OAuth2*, *OpenID Connect* provider (half of IROH-Auth dedicated to this)

[fn:iroh]: *IROH* The software serving the API behind SecureX, CTR, Ribbons, integrations...
* What is IROH-Auth? (technical)

/IROH-Auth/ is a set of /Services/ within /IROH/ some of them exposing
HTTP APIs.

- Login
  + Login (core service + web API)
  + Org (service)
  + User (service + web API)
  + Scopes (service)
  + Auth Management (core service)
  + Invite (core service + web API)
  + Session (web API)
  + Profile (web API, =/whoami=)
  + SCIM Client (service)
  + IdP Migrate  (core service + web API) /deprecated a few months ago/
  + Provision (service + web API) /used instead of IdP Migrate/

- OAuth2
  + OAuth2 (core service + web API)
  + OAuth2 Clients (core service + web API)
  + OAuth2 Clients Presets (service)
  + Grant Service (User's client authorizations)

- Admin
  + Auth Management (web API)
  + OAuth2 Clients Management (web API)

* History: IROH/Visibility (1/?)                                     :ATTACH:
:PROPERTIES:
:ID:       dab23b61-a766-4eda-a1e9-1d39258ef5c0
:END:

Login using AMP SAML (generate JWT)
Worked with Guillaume.

Use AMP as an *IdP*[fn:idp]

After the dance of their people AMP provides:
- user-id
- org-id
- role (admin/user)

*No DB of users!*

[fn:idp] Idp: Identity Provider

* History: IROH/Visibility - SAML (2/?)                              :ATTACH:
:PROPERTIES:
:ID:       07dabe43-9563-430c-a729-87b5154d6d18
:END:

Doc & Libs

> It's bad.
> It's really bad.
> It's like eating a hot circle of garbage...
>        Kevin

[[attachment:_20210416_152516.jpeg]]

* History: IROH/Visibility (3/?)

2nd goal: Support OAuth2 (become an OAuth2 provider)
3rd goal: Support AMP and Threatgrid login (OpenID Connect)

Become both an OAuth2 client and provider.

Need Clients/Users/Orgs in DB!!!

OAuth2 RFC => OAuth2 GRANTS

- Authorization Code Grant (the classic)
- Client Grant (for scripts)
- Implicit Grant (for Single Page Applications, now deprecated)

* History: IROH/Visibility (4/?)

4rd goal: Support Account Activation => SCIM[fn:scim] Client

Call a SCIM server.
Check if the account is part from an activated Org inside AMP.

- Become an OpenID Connect provider, made before the start of SecureX.
- OpenID Connect with SSE (we are the IdP now)

[fn:scim] *SCIM*: System for Cross-domain Identity Management
* History: CTR (IDB SSE)                                             :ATTACH:
:PROPERTIES:
:ID:       83c6d508-003a-4c81-8385-b9fa13137b92
:END:
To integrate with SSE (devices) we have to use an SSE hosted IdP provider:
the *IDB*

The *IDB* stand for *Identity Broker*.
This is a *Ping Federate Identity Provider*.
*Ping Federate* is a server from PingIdentity a company specialized in
Identity Providers and Management.

Since then we only use OpenID Connect
=> IROH-Auth SAML support start to rot and is now probably completely deprecated

[[attachment:_20210416_155119Yesssss--meme-40935.jpg]]

* History: SecureX (5/?)

From =idp-mapping= to =idp-mappings=

From Idp managing Orgs to IdP providing only a User Identity Id.
=> generate random user-id/org-id and stop using the the one given by the IdP.

Lot of DB migrations ensues.

* 2 - Login

Lot of IROH-Auth services dedicated just for *Login*

* IROH-Auth Login

Generally: enter your username & password => set a cookie with an id of the
user of the user

Not in IROH-Auth.
The first goal was (and still is) not to take care of user's credentials.

*There are no user password in IROH Auth.*

The password security is handled by external *IdPs*.
Currently SXSO, CSA & TG.

* IROH-Auth Login Dance (1/?)                                        :ATTACH:
:PROPERTIES:
:ID:       e12ca021-c030-47f8-a9e5-4fb815a88735
:END:

So the dance of login via IROH-Auth

[[attachment:_20210416_154054Screenshot%202021-04-16%20at%2015.38.37.png]]

1. Login page => Select an IdP (all buttons are just links)
2. When a user click on the link:
   - generate and save an unique Id
   - redirect the user to the IdP with that unique Id as parameter
3. Wait for the user to come back to =/iroh/iroh-auth/:idp/answer= with
   - =code= query parameter
   - =state= query paramter that should be equal to the generate unique Id
4. We check our DB for that unique Id
   then call the IdP with the =code= and a secret shared between IROH-Auth
   and the IdP only.
5. The IdP returns an =id_token= with all user's information.


After this first dance, we have:

1. A Users's Identity Id (the id of the user in the IdP)
2. The user email
* IROH-Auth Login Dance (2/?)

After the "Login Workflow" we know:

- The user IdP
- /User Identity id/
- the user's email

Depending on the IdP we can also have an associated Org-id.

So login now? no.

* IROH-Auth Login Dance: Check the IdP configuration (3/?)

   #+begin_example clojure
   {:id "idb-amp" <- idp-id
    :name "Cisco Security Account" <- to display on the login page
    :msg "For existing Threat Response & AMP users." <- ???
    :position 1 <- position on the login page
    :legacy true <- old?
    :auth-kind :oidc <- SAML or OpenId Connect?
    :user-namespace "idb-amp" <- if legacy, user-id will be (str user-namespace "-" user-identity-id)
    :authorize-uri "https://staging-sse.cisco.com/providers/sse/services/ident/as/authorization.oauth2"
    :token-uri     "https://staging-sse.cisco.com/providers/sse/services/ident/as/token.oauth2"
    :idp-account-url "https://console.qa1.immunet.com/users/current"
    :idp-logout-url "https://console.qa1.immunet.com/logout"
    :grant-type    :code <- OAuth2 detail
    ;; Correlation table how to transform the `id_token` claims
    :correlation-table {:org-id [:companyId]
                        :org-name [:companyName]
                        :user-name [:user_name]
                        :user-email [:email]
                        :role [:role]}
    :scopes ["profile" "email"] <- asked to the IdP OIDC provider
    :client-id "mylocalamp" <- client-id on the IdP provider
    :allow-all-role-to-login false <- default allow non-admin to login
    :client-secret "******"
    :additional-authorize-query-params {:selector "amp"} <- ping fed magic
    :scim-id :qa1} <- SCIM server id (refer to another part in the conf)
   #+end_example

* IROH-Auth Login Dance: For Legacy IdPs

We consider the IdP will manage the org (give an org-id, provide an user
   role, etc...)
   If that's the case we update our users inside IROH-Auth everytime the
   user login.
   There is no mechanism to push user's change from IdP directly in
   IROH-Auth.
   With CSA Migraiton should be deprecated.

* IROH-Auth Login Dance: For SXSO
:PROPERTIES:
:ID:       dc5070c0-9040-4175-9a67-c85a21f65f36
:END:

We generate the =idp-mapping= out of the =id_token=.
The =idp-mapping= contain:

- The idp-id
- The /User Identity Id/ (the user id in the IdP not in IROH)

We search for the user's email.
If we find multiple users with the same email, we add (if not already exists)
the idp-mapping to all thoses users.

Then we search the DB for matches of the idp-mappings:

1. 0 occurence, this is a new unknown user => Present Org's creation page
   => create the org and the user.
2. 1 occurence, directly login the user to it's single known account
3. >1 occurence, display the account selection page

[[attachment:_20210416_150439Screenshot%202021-04-16%20at%2015.04.30.png]]

* 3 - OAuth2 / OpendID Connect Provider
* OAuth2 Provider

From the RFC:

>  The OAuth 2.0 authorization framework enables a third-party
>  application to obtain limited access to an HTTP service, either on
>  behalf of a resource owner by orchestrating an approval interaction
>  between the resource owner and the HTTP service, or by allowing the
>  third-party application to obtain access on its own behalf.

3 involved entities:

- an API (Service Provider, IROH)
- an IROH-Auth user
- an Application that would like to access the API on behalf of the user (Ribbon)

* OAuth2 Provider: Supported Grants

RFC Grants

*Authorization Code Grant*
secrets:
- 1 secret between IROH-Auth/Application (client secret)
- 1 secret between Application/User and IROH-Auth/User (refresh token)
  => involve user-agent workflow

*Client Credential Grant*
- 1 shared secret between IROH-Auth/Application/User (client secret)
  => involve copy/paste

* Authorization Code Grant

#+begin_quote
4.1.  Authorization Code Grant

   The authorization code grant type is used to obtain both access
   tokens and refresh tokens and is optimized for confidential clients.
   Since this is a redirection-based flow, the client must be capable of
   interacting with the resource owner's user-agent (typically a web
   browser) and capable of receiving incoming requests (via redirection)
   from the authorization server.

     +----------+
     | Resource |
     |   Owner  |
     |          |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier      +---------------+
     |         -+----(A)-- & Redirection URI ---->|               |
     |  User-   |                                 | Authorization |
     |  Agent  -+----(B)-- User authenticates --->|     Server    |
     |          |                                 |               |
     |         -+----(C)-- Authorization Code ---<|               |
     +-|----|---+                                 +---------------+
       |    |                                         ^      v
      (A)  (C)                                        |      |
       |    |                                         |      |
       ^    v                                         |      |
     +---------+                                      |      |
     |         |>---(D)-- Authorization Code ---------'      |
     |  Client |          & Redirection URI                  |
     |         |                                             |
     |         |<---(E)----- Access Token -------------------'
     +---------+       (w/ Optional Refresh Token)

   Note: The lines illustrating steps (A), (B), and (C) are broken into
   two parts as they pass through the user-agent.

                     Figure 3: Authorization Code Flow
#+end_quote

* Client Credential Grant

#+begin_quote
4.4.  Client Credentials Grant

   The client can request an access token using only its client
   credentials (or other supported means of authentication) when the
   client is requesting access to the protected resources under its
   control, or those of another resource owner that have been previously
   arranged with the authorization server (the method of which is beyond
   the scope of this specification).
   The client credentials grant type MUST only be used by confidential
   clients.

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(A)- Client Authentication --->| Authorization |
     | Client  |                                  |     Server    |
     |         |<--(B)---- Access Token ---------<|               |
     |         |                                  |               |
     +---------+                                  +---------------+

                     Figure 6: Client Credentials Flow

   The flow illustrated in Figure 6 includes the following steps:

   (A)  The client authenticates with the authorization server and
        requests an access token from the token endpoint.

   (B)  The authorization server authenticates the client, and if valid,
        issues an access token.
#+end_quote

* Clients

Client mandatory fields:

- =id= the unique id of the client accross all Threat Response,
- =name= a name for the client that will be user facing,
- =client-type= can be either =confidential= or =public=,
- =grants= a list that could contain =auth-code= or =client-creds=,
- =redirects= a set of URIs,
- =scopes= a set of scopes,
- =enabled?= a boolean, this field is editable by admin users,
- =approved?= a boolean, editable only by Threat Response admins.

Client optional fields:

- =description=, a long description of the client that could be presented to the
  users during client authorization,
- =owner-id=, the user id of the client's owner,
- =org-id=, the org id of the client's owner,
- =enabled-by=, the user id of the admin that enabled the client,
- =disabled-by=, the user id of the admin that disabled the client,
- =password=, also known as the "client's secret", public clients don't
  have a password,
- =access-token-lifetime-in-sec=, access token lifetime this client provides,
- =refresh-token-lifetime-in-sec=, refresh token lifetime this client provides,
- =availability=, can be =user=, =org= or =everyone=. This filters the user that
  can grant access to this client:
  + =user= only the owner
  + =org= only org's members
  + =everyone= any Threat Response user
- =approval-status=, possible values are =waiting= =rejected= =approved=. During
  client creation some criteria will need an Threat Response Admin's approval,
- =approver-id=, the user id of the user (a Threat Response admin) that approved the client
- =approval-message=, a message left for the user.
- =client-preset-id=, a Client Preset ID. Client Presets are explained in [[#client-presets]].

+ advanced fields

- =allow-partial-user-scopes?= If true, a user without all the requested
  scopes from the Client can still authorize the client. The refresh and
  access tokens will only have the intersection of both scopes.
- =audiences=

* 4 - Specifc Cisco Usage

- Orbital
- AMP
- SSE