flush out some more details related to SAML option

1 files changed, 41 insertions, 12 deletions

diff --git a/doc/authz/SAML.md b/doc/authz/SAML.md
index d503dab..df51f6a 100644
--- a/doc/authz/SAML.md
+++ b/doc/authz/SAML.md
@@ -8,38 +8,33 @@ current set or permissions.
 
 E.g.
 
+This is an incomplete example with many attributes removed to make it easier to
+`consume`. (See what I did there?)
 
 ```xml
 <?xml version="1.0"?>
-<Response xmlns="urn:oasis:names:tc:SAML:2.0:protocol" ID="_4ca277e1-1fd9-4264-a02a-fab4fc99b6e1" Version="2.0" IssueInstant="2022-03-30T18:50:39Z" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" Destination="https://tfcdev-82d111f9.ngrok.io/sso/saml/samlconf-BYk3Pj4iYG6WCHFTiUSaRKHAKm7yyp/acs" InResponseTo="_44b5198d-dae0-4df7-a44b-f22ea06b1a9b">
-  <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://id.terraform.io/metadata.xml</Issuer>
+<Response Version="2.0" Destination="https://app.terraform.io/sso/saml/acs">
+  <Issuer>https://id.terraform.io/metadata.xml</Issuer>
   <Status>
     <StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
   </Status>
-  <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="_7b3914b0-ad9f-4ba8-9b0a-b4022387fb82" IssueInstant="2022-03-30T18:50:39Z" Version="2.0">
+  <Assertion Version="2.0">
     <Issuer>https://idp.terraform.io/metadata.xml</Issuer>
     <Subject>
       <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">mo.khan@hashicorp.com</NameID>
-      <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
-        <SubjectConfirmationData
-          InResponseTo="_44b5198d-dae0-4df7-a44b-f22ea06b1a9b"
-          Recipient="https://app.terraform.io/sso/saml/metadata"
-          NotOnOrAfter="2022-03-30T18:55:39Z">
-      </SubjectConfirmationData>
-      </SubjectConfirmation>
     </Subject>
     <Conditions NotBefore="2022-03-30T18:50:39Z" NotOnOrAfter="2022-03-30T21:50:39Z">
       <AudienceRestriction>
         <Audience>https://app.terraform.io/sso/saml/metadata</Audience>
       </AudienceRestriction>
     </Conditions>
-    <AuthnStatement AuthnInstant="2022-03-30T18:50:39Z" SessionIndex="_7b3914b0-ad9f-4ba8-9b0a-b4022387fb82">
+    <AuthnStatement AuthnInstant="2022-03-30T18:50:39Z">
       <AuthnContext>
         <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
       </AuthnContext>
     </AuthnStatement>
     <AttributeStatement>
-      <Attribute Name="Permission">
+      <Attribute Name="Permissions">
         <AttributeValue>terraform.teams.create</AttributeValue>
         <AttributeValue>terraform.teams.read</AttributeValue>
         <AttributeValue>terraform.workspaces.read</AttributeValue>
@@ -49,22 +44,56 @@ E.g.
 </Response>
 ```
 
+The general idea is that the SAML assertion will include a `Permissions`
+attribute that can align with the permissions naming scheme from HCP that can be
+used for authorizing access to resources for the current session. Terraform
+Cloud will need to maintain this list of permissions and associate it with the
+current session token (i.e. cookie, api key, etc).
+
 ## TFE Approach
 
 <!-- In this idea, how do we prevent TFE customers from being hurt? -->
 
+In TFE mode, the Terraform rails app will act as both the SAML Service Provider
+and SAML Identity Provider by default. Organizations can override the default
+SAML Identity Provider by setting up their own. In that scenario, the SAML
+Assertion will not contain a list of permissions and can fall back to the
+existing authz policies.
+
 ## Coupling Assessment
 
 <!-- In this idea, how coupled is TFC to HCP at runtime? -->
 
+TFC will be coupled to the SAML `Permissions` attribute if it is present.
+If it is not present then access falls back to the current users role and
+permissions are assigned based on todays implicit mapping of role to
+permission/claim.
+
 ## Expected Benefits
 
 <!-- Not exhaustive, but what makes this compelling? -->
 
+This minimizes the effort involved by utilizing a feature that is available
+today but enables it by default to point to HCP as the SAML Idp.
+
 ## Expected Downsides
 
 <!-- Not exhaustive, but what are some initial concerns? -->
 
+SAML. The SAML Assertion Consumer Service endpoint is an attack vector that
+needs to be hardened by ensuring we:
+
+* rate limit
+* prevent reusing assertions.
+* prevent golden SAML style attacks that abuse XML parsers.
+
 ## 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? -->
+
+Spike out a flow where Permissions are delivered as attributes and mapped to
+existing roles. I would want to list out the current TFC roles and then compile
+a list of discrete permissions using the permission naming scheme suggested in
+[HCP-104: Permission Naming Convention][1]
+
+[1]: https://docs.google.com/document/d/1ZKBRVBKqZU_l4WcKLugYgY_IUACM4SGHWpnJAuWUf70