add diagram with high level protocol flow

1 files changed, 99 insertions, 2 deletions

diff --git a/doc/authz/OAUTH.md b/doc/authz/OAUTH.md
index 3c0de9e..de71c1b 100644
--- a/doc/authz/OAUTH.md
+++ b/doc/authz/OAUTH.md
@@ -3,12 +3,72 @@
 Use OAuth 2.0 as the framework for Authz and extend it with OpenID Connect for
 Authn.
 
+```plaintext
+Protocol Flow
+
+    +--------+                               +---------------+
+    |        |--(A)- Authorization Request ->|   Resource    |
+    |        |                               |     Owner     |
+    |        |<-(B)-- Authorization Grant ---|               |
+    |        |                               +---------------+
+    |        |
+    |        |                               +---------------+
+    |        |--(C)-- Authorization Grant -->| Authorization |
+    | Client |                               |     Server    |
+    |        |<-(D)----- Access Token -------|               |
+    |        |                               +---------------+
+    |        |
+    |        |                               +---------------+
+    |        |--(E)----- Access Token ------>|    Resource   |
+    |        |                               |     Server    |
+    |        |<-(F)--- Protected Resource ---|               |
+    +--------+                               +---------------+
+```
+
+* Client:
+  * Terraform Cloud Ember.js
+  * Terraform Agent
+  * Terraform CLI
+  * Agent Job
+  * Agent Pool
+  * Task Result
+* Resource Owner
+  * User
+  * Team
+* Authorization Server: [Cloud IDP][4]
+
+* [RFC-6749 - OAuth 2.0][5]
+
+The `AccessToken` and/or `IDToken` will use the [JWT][] scheme with the some of
+the standard claims. The `scope` claim will include a space delimited list of
+permissions that the current subject is entitled to.
+
+For example:
+
+```json
+{
+  "scope": "terraform.teams.read terraform.teams.write",
+  "sub": "<uuid-of-principal> | or Global ID representation of Subject. .e.g <User:1> | <Team:3> etc",
+  "aud": "https://app.terraform.io",
+  "iss": "https://idp.terraform.io",
+  "exp": "unix-timestamp-expires-at",
+  "iat": "unix-timestamp-issued-at"
+}
+```
+
+If an `IDToken` is provided as part of an OpenID Connect transaction then this
+token can be used to fetch any profile information update from the OpenID user
+profile endpoint to stay in sync with any profile changes that occur in HCP.
+
 ## TFE Approach
 
 <!-- In this idea, how do we prevent TFE customers from being hurt? -->
 
 In TFE, Terraform Cloud can act as both the resource server and authorization
-server (openid connect provider).
+server (openid connect provider) and utilize [devise][6] just like it does today.
+This step might be redundant but by maintaining the same authz flow for TFE as
+we do in cloud we can limit the cognitive overhead of needing to remember the
+differences and attempting to maintain parity.
 
 TFE customers could plug in their own OpenID Connect server if they choose to
 but would have to make sure that the standard set of "permissions" align with
@@ -27,6 +87,37 @@ against the HCP authorization server. Instead it can choose to check the
 validity of a token and it's permissions by periodically checking the
 disposition of the provided token against the [token introspection endpoint][1].
 
+Request:
+
+```plaintext
+POST /introspect HTTP/1.1
+Host: idp.terraform.io
+Accept: application/json
+Content-Type: application/json
+
+{
+  "token": "mF_9.B5f-4.1JqM",
+  "token_type_hint": "access_token"
+}
+```
+
+Response:
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "active": true,
+  "scope": "terraform.teams.read terraform.teams.write",
+  "sub": "<uuid-of-principal> | or Global ID representation of Subject. .e.g <User:1> | <Team:3> etc",
+  "aud": "https://app.terraform.io",
+  "iss": "https://idp.terraform.io",
+  "exp": "unix-timestamp-expires-at",
+  "iat": "unix-timestamp-issued-at"
+}
+```
+
 If when permissions/policy changes are changed in HCP this will be propagated to
 the Terraform OpenID Connect server so that it can provide the current claims
 for a token when the Terraform API makes a token introspection check for a given
@@ -55,9 +146,15 @@ which could impact some of the existing [Pundit Policies][3].
 
 ## Investigation Goal
 
-What do we need to do to understand this better? Is it feedback from others, is it a technical spike, is it a document?
+<!-- What do we need to do to understand this better? Is it feedback from others, is it a technical spike, is it a document? -->
+
+List out the different Authz flows and model them through sequence diagrams to
+understand the interface between services and how they can be extended/attacked.
 
 [1]: https://datatracker.ietf.org/doc/html/rfc7662#section-2
 [2]: https://github.com/hashicorp/atlas/blob/c060b88f91aeca9cf30b7d890445a8701f7eba82/app/models/authentication_token.rb#L96-L112
 [3]: https://github.com/hashicorp/atlas/tree/c060b88f91aeca9cf30b7d890445a8701f7eba82/app/policies
 [4]: https://github.com/hashicorp/cloud-idp
+[5]: https://datatracker.ietf.org/doc/html/rfc6749
+[6]: https://rubygems.org/gems/devise
+