add proposal for OAuth 2.0

2 files changed, 84 insertions, 0 deletions

diff --git a/.github/ISSUE_TEMPLATE/idea.md b/.github/ISSUE_TEMPLATE/idea.md
new file mode 100644
index 0000000..cd79dd0
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/idea.md
@@ -0,0 +1,22 @@
+# Idea Name
+
+Description of the idea
+
+## TFE Approach
+
+In this idea, how do we prevent TFE customers from being hurt?
+
+## Coupling Assessment
+
+In this idea, how coupled is TFC to HCP at runtime?
+
+## Expected Benefits
+
+Not exhaustive, but what makes this compelling?
+
+## Expected Downsides
+Not exhaustive, but what are some initial concerns?
+
+## 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?
diff --git a/doc/authz/OAUTH.md b/doc/authz/OAUTH.md
new file mode 100644
index 0000000..fc9d1c7
--- /dev/null
+++ b/doc/authz/OAUTH.md
@@ -0,0 +1,62 @@
+# OAuth 2.0
+
+Use OAuth 2.0 as the framework for Authz and extend it with OpenID Connect for
+Authn.
+
+## 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).
+
+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
+the Terraform Cloud permissions.
+
+## Coupling Assessment
+
+<!-- In this idea, how coupled is TFC to HCP at runtime? -->
+
+In Terraform Cloud, (cloud-idp)[https://github.com/hashicorp/cloud-idp] will act
+as the intermediary between Terraform and HCP. All Authz permissions (claims)
+for a given Principal (Resource Owner) will be included in a stateless OpenID
+Connect ID Token that can be used by the Terraform Cloud API (Resource Server)
+to authorize actions. Terraform Cloud will not perform runtime checks directly
+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].
+
+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
+Resource Owner.
+
+## Expected Benefits
+
+<!-- Not exhaustive, but what makes this compelling? -->
+
+This allows Terraform Cloud to delegate authorization using a standard protocol
+that can be replaced by other implementations that adhere to the protocols
+without needing to directly couple to HCP. It will also also the upgrade of the
+Terraform Cloud token scheme to slowly align with the permissions scheme devised
+by HCP. Existing Authn/Authz enforcement can remain and be upgraded gradually
+until all old tokens are eventually expired.
+
+## Expected Downsides
+
+<!--  Not exhaustive, but what are some initial concerns? -->
+
+This path requires knowledge/education of the OAuth 2.0 protocol flow and
+accepting JWT as the ID Token format for OpenID Connect Authn schemes.
+
+This change may require hooking into how we look up the [Authenticateable Resource][2]
+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?
+
+[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