:PROPERTIES:
:ID:       6b389575-42a7-4f0d-a7eb-e9bf6795a718
:END:
#+Title: XDR Monetization
#+Author: Yann Esposito
#+Date: [2023-07-12]

* Intro

** What?

- *Entitlements*: What the customer is paying for.
- *Access Rules*: What services should allow, restrict.

** Example

*** Entitlements:

- Tier: Essentials for 1000 /users/ (number of [[https://cisco.sharepoint.com/sites/SecurityPersonas/SitePages/prime-employee.aspx?csf=1&web=1&e=LcTwTp][Lees]]).
- Extra Data Retention "add-on": 180 /days/
- Extra Ingest "add-on": 2 /GB/

*** Access Rule example:

- *Total Ingest*: 4000GB (1000 user × (2GB + 2GB))
- *Time to Keep Data*: 180 days (yes, *extra* might not mean what we could expect)

ref: https://wwwin-github.cisco.com/cisco-sbgidm/docs/blob/master/provisioning/xdr/xdr-ga.md#entitlements

** How?

Entitlement represent what the customer pays for.
PIAM creates and updates them.

#+begin_src plantuml :file xdr-monetization-piam-entitlements.png
PIAM -> IROH : enterprise_id,Entitlements
Any -> IROH : /iroh/profile/entitlements
IROH -> Any : Entitlements
PIAM -> IROH : update Entitlements
Any -> IROH : /iroh/profile/entitlements
IROH -> Any : Entitlements
#+end_src

#+RESULTS:
[[file:xdr-monetization-piam-entitlements.png]]

** Also Entitlement Summary

IROH exposes an API to retrieve an ~EntitlementSummary~.
A data structure easier to consume than the list of entitlements.

#+begin_src plantuml :file xdr-monetization-piam-entitlement-summary.png
PIAM -> IROH : enterprise_id,Entitlements
Any -> IROH : /iroh/profile/whoami
IROH -> Any : enterprise_id,EntitlementSummary
PIAM -> IROH : update Entitlements
Any -> IROH : /iroh/profile/whoami
IROH -> Any : enterprise_id,EntitlementSummary
#+end_src

#+RESULTS:
[[file:img/piam-entitlement-summary.png]]

* Entitlements (technically)

Example of a list of ~Entitlements~ sent by PIAM to IROH:

** Just the Tier, no add-on:

#+begin_src js
[{"name" "tier",
  "value" "advantage",
  "quantity" {"value" 1000, "unit" "users"},
  "enforce-quantity" true}]
#+end_src


** Tier with add-ons

#+begin_src js
[{"name":"tier",
  "value":"essentials",
  "quantity":{"value":1000, "unit":"users"},
  "enforce-quantity":true},
 {"name":"extra_ingest",
  "value":"",
  "quantity":{"value":2, "unit":"GB"},
  "enforce-quantity":true},
 {"name":"extra_data_retention",
  "value":"",
  "quantity":{"value":180, "unit":"days"},
  "enforce-quantity":true}]
#+end_src

** PIAM Doc

From [[https://wwwin-github.cisco.com/cisco-sbgidm/docs/blob/master/provisioning/xdr/xdr-ga.md#entitlements][Paul Chichonski's doc]]

https://wwwin-github.cisco.com/cisco-sbgidm/docs/blob/master/provisioning/product-spec.md#multi-valued-attributes

*** Entitlements

- ~entitlements~ -- A list of entitlements the tenant is allowed to use. Each item in
  the list is an object with the following fields:

#+begin_src js
[{"name":"tier",
  "value":"essentials",
  "quantity":{"value":1000, "unit":"users"},
  "enforce-quantity":true},
 {"name":"extra_ingest",
  "value":"",
  "quantity":{"value":2, "unit":"GB"},
  "enforce-quantity":true}]
#+end_src

*** name

- ~name~ -- The name of the entitlement (defined as part of the entitlement
  controlled vocabulary between PIAM and the product)

*** value

- ~value~ -- Some entitlements will have a string value that serves to qualify the
  entitlement. For example an entitlement with ~name=tier~ may have three
  different manifestations if there are three different tiers (e.g., ~{"name":
  "tier", "value": "essentials"}~, ~{"name": "tier", "value": "primary"}~,
   ~{"name": "tier", "value": "advantage"}~)

*** quantity

- ~quantity~ -- Some entitlements will have numeric quantity associated with the
  entitlement, this represents the amount of this entitlement the tenant is
  permitted to consume. Each quantity field will contain an object with the
  following values:
    - ~value~ - The number holding the actual quantity.
    - ~unit~ - A string representing what unit to use when interpreting the quantity.

*** quantity_enforced

- ~quantity_enforced~ -- A boolean field, if ~true~ it means that the product
  should enforce the allocated quantity of the entitlement for this tenant. It
  is up to the product to determine how to do this. Cases where this will be
  ~false~ are if the customer purchased via a buying program that supports a
  "pay as you go" pricing model.

* Entitlement Summary

The Entitlement Summary provides a data-structure easier to consume
than the entitlements list.

- A JSON Object instead of list.
- Additional technically useful entries.

** Structure

The main structure of the ~EntitlementSummary~ is:

#+begin_src
{<entitlement-name>: <entitlement-details>}
#+end_src

Where ~<entitlement-details>~ looks like:

#+begin_src js
{"title": "something", // <- optional instead of value:""
 "quantity": Integer,
 "unit": "human-readable-unit",
 "enforce?": Boolean}
#+end_src
** Tier-only Entitlement

When PIAM send this list of ~Entitlements~:

#+begin_src  js
[{"name" : "tier",
  "value" : "advantage",
  "quantity" : {"value" : 32000,
                "unit" : "users"},
  "enforce-quantity" : true}]
#+end_src

** The ~EntitlementSummary~ will look like this:

#+begin_src js
{"tier" : {"title" : "advantage",
           "quantity" : 32000,
           "unit" : "users",
           "enforce?" : true}}
#+end_src

** With Add-ons

If PIAM send a list of ~Entitlements~ with add-ons:

#+begin_src js
[ {"name" : "tier",
   "value" : "premier",
   "quantity" : {"value" : 1000, "unit" : "users"},
   "enforce-quantity" : true},
  {"name" : "extra_ingest",
   "value" : "",
   "quantity" : {"value" : 2, "unit" : "GB"},
   "enforce-quantity" : true},
  {"name" : "extra_data_retention",
   "value" : "",
   "quantity" : {"value" : 180, "unit" : "days"},
   "enforce-quantity" : true}]
#+end_src

** The ~EntitlementSummary~ will be:

#+begin_src js
{"tier": {"title": "premier",
          "quantity": 1000,
          "unit": "users",
          "enforce?": true},
 "extra_data_retention": {"quantity": 180,
                          "unit": "days",
                          "enforce?": true},
 "extra_ingest": {"quantity": 2,
                  "unit": "GB",
                  "enforce?": true}}
#+end_src

** ~Entitlements~ consumption in js

#+begin_src js
function get_entitlement_tier (entitlements) {
    for (entitlement in org.entitlements) {
        if (entitlement.name == "tier") {
            return entitlement.title;
        }
    }
}
let tier =  get_entitlement_tier (entitlements);
#+end_src

** EntitlementSummary consumption in js

#+begin_src js
let tier = whoami.org["entitlement-summary"].tier.title;
#+end_src

** More to come

*** IROH Internal

But we plan to add more technical specific values so it helps every Entitlement consumer.
That way it would make possible to share between product specific technical values.

For example, we plan to add:
- a list of allowed modules.
- an optional list of additional scopes
- rate limits

*** XDR global values

If you want us to add some information, so we could centralize some logic
related to entitlement into IROH just ask us to add it.
Ideally, this should only contain data that could be shared between different modules.
For example:

- allowed workflows, or allowed properties for workflows
- specific limitations for a specific module (read-only, etc…)

*** Example

#+begin_src js
{"tier": {"title": "premier",
          "quantity": 1000,
          "unit": "users",
          "enforce?": true},
 "extra_data_retention": {"quantity": 180,
                          "unit": "days",
                          "enforce?": true},
 "extra_ingest": {"quantity": 2,
                  "unit": "GB",
                  "enforce?": true},
 // ---- SUMMARY OF TECHNICAL LIMITS
 "summary" {...}}
#+end_src

*** Summary


#+begin_src js
{// ---- SUMMARY OF TECHNICAL LIMITS
 "summary" {
     // PIAM Logic
     "data-retention-in-days": 180, // use extra_data_retention + tier
     "data-maximal-size-in-GB": 4000, // use extra_ingest + tier quantity
     // IROH Internal
     "additional-scopes": [ ... ],  // depends on the tier
     "allowed-modules": [ ... ],    // depends on the tier
     // XDR Shared Global Rules
     "restricted-workflows": [...], // depends on the tier (or something else)
     "rate-limits": // can change depending on the tier
         {"sca": {"queries-per-minutes": "100"},
          "sxo": {"queries-per-minutes": "80"},
          "csc": ...},
     ...
 }
}
#+end_src

* Conclusion

- tier?  ~GET /iroh/profile/whoami~
  then ~whoami.org["entitlement-summary"].tier.title~
- Summary only: ~GET /iroh/profile/entitlement-summary~
- raw entitlements: ~GET /iroh/profile/entitlements~