Add access management: grants, groups, and org data sources

README.md

@@ -6,6 +6,10 @@ Terraform provider for managing SplitSecure SAML2 resources via service-account
 
 - **`splitsecure_saml2_identity_provider`** — SAML IdP on a SplitSecure team. Computed `metadata_xml` is suitable as the `saml_metadata_document` input for `aws_iam_saml_provider`.
 - **`splitsecure_saml2_service_provider`** — SAML SP bound to an IdP, supporting all 17 saml2v2 integration variants (AWS, Cloudflare, Okta, GCP, etc.).
+- **`splitsecure_grant`** — per-resource permission grant `(resource, grantee) → view/use/edit` so the resources above are visible/usable to org members, not just their creator. Plain RPCs, not proposal-gated. Tiers control visibility and permission management; resource mutations stay proposal/voter-gated regardless of tier.
+- **`splitsecure_group`** — locally-managed principal group with an authoritative member list, used as a grant target. Group mutations require the provider's service account to hold the org **admin** role; grants alone work with the default member role (the creating service account receives `edit` on resources it creates).
+
+Data sources: **`splitsecure_organization`** (org info incl. the "Everyone" group S2R for org-wide grants), **`splitsecure_principal`** (principal S2R by console email — resolves both users and service accounts), **`splitsecure_org_member`** (user S2R by email), **`splitsecure_group`** (existing group by its `group_s2r`).
 
 Generated reference docs live in [`docs/`](./docs); per-resource attribute tables, validators, and example blocks are kept in sync via `tfplugindocs` (`make docs`).
 

docs/data-sources/group.md

@@ -0,0 +1,36 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "splitsecure_group Data Source - SplitSecure"
+subcategory: ""
+description: |-
+  Resolves an org group by its stable group_s2r, exposing its current name and source. Lookup is by group_s2r only: a group's name is mutable and not unique server-side, so it is not a stable key. The system Everyone group is not a regular group; read everyone_group_s2r from the splitsecure_organization data source instead.
+---
+
+# splitsecure_group (Data Source)
+
+Resolves an org group by its stable group_s2r, exposing its current name and source. Lookup is by group_s2r only: a group's name is mutable and not unique server-side, so it is not a stable key. The system Everyone group is not a regular group; read everyone_group_s2r from the splitsecure_organization data source instead.
+
+## Example Usage
+
+```terraform
+# Resolve a group by its stable group_s2r, exposing its current name and
+# source (e.g. to assert its source before granting on it). A group's
+# name is mutable and not unique server-side, so group_s2r is the only
+# lookup key. To use a group as a grant grantee you can also reference
+# its s2r directly, without this data source.
+data "splitsecure_group" "sre" {
+  group_s2r = "s2r:us:group:01HX.../01HY..."
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `group_s2r` (String) Group s2r URI to resolve. Also usable directly as a grant grantee.
+
+### Read-Only
+
+- `name` (String) Current group name. Mutable server-side, so do not treat it as an identifier.
+- `source` (String) Where the group is managed: "local", "scim", or "system".

docs/data-sources/org_member.md

@@ -0,0 +1,34 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "splitsecure_org_member Data Source - SplitSecure"
+subcategory: ""
+description: |-
+  Looks up a single org member by email (case-insensitive). Errors if no member or more than one member matches.
+---
+
+# splitsecure_org_member (Data Source)
+
+Looks up a single org member by email (case-insensitive). Errors if no member or more than one member matches.
+
+## Example Usage
+
+```terraform
+# Resolve an org member by email to the user S2R used as a grant or
+# group-member target. Errors if the email matches zero or multiple
+# members.
+data "splitsecure_org_member" "alice" {
+  email = "alice@example.com"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `email` (String) Email address of the member to look up. Matched case-insensitively.
+
+### Read-Only
+
+- `display_name` (String) Human-readable display name of the member.
+- `user_s2r` (String) User s2r URI of the member. Usable as a grant grantee or a group member principal.

docs/data-sources/organization.md

@@ -0,0 +1,29 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "splitsecure_organization Data Source - SplitSecure"
+subcategory: ""
+description: |-
+  The organization the provider is configured against. Takes no arguments; the org comes from the provider's org_s2r.
+---
+
+# splitsecure_organization (Data Source)
+
+The organization the provider is configured against. Takes no arguments; the org comes from the provider's org_s2r.
+
+## Example Usage
+
+```terraform
+# The provider-configured org. everyone_group_s2r is the grantee for
+# org-wide grants; the "Everyone" group is a system group and is not
+# returned by group listings.
+data "splitsecure_organization" "current" {}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Read-Only
+
+- `everyone_group_s2r` (String) S2R of the org's system Everyone group -- the grantee to use for org-wide grants. System groups are NOT returned by group listings (including the splitsecure_group data source); this attribute is the way to obtain it.
+- `id` (String) Org s2r URI.
+- `name` (String) Human-readable organization name.

docs/data-sources/principal.md

@@ -0,0 +1,41 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "splitsecure_principal Data Source - SplitSecure"
+subcategory: ""
+description: |-
+  Resolves an org principal (user or service account) to its s2r by the email shown in the console. Use the s2r as a group member or grant grantee.
+---
+
+# splitsecure_principal (Data Source)
+
+Resolves an org principal (user or service account) to its s2r by the email shown in the console. Use the s2r as a group member or grant grantee.
+
+## Example Usage
+
+```terraform
+# Resolve an org principal (user or service account) to its s2r by the email
+# shown in the console. Use the s2r as a group member or grant grantee.
+
+# A human user.
+data "splitsecure_principal" "alice" {
+  email = "alice@example.com"
+}
+
+# A service account (email is the one displayed in the console).
+data "splitsecure_principal" "ci_bot" {
+  email = "kQ7...@abc123.serviceaccount.us.splitsecure.com"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `email` (String) Email of the principal, copy-pasted from the console. Matched case-insensitively.
+
+### Read-Only
+
+- `display_name` (String) Display name (user) or name (service account).
+- `kind` (String) Principal kind: "user" or "service_account".
+- `s2r` (String) Principal s2r URI (usr: for users, sa: for service accounts). Usable as a group member or grant grantee.

docs/index.md

@@ -39,7 +39,25 @@ provider "splitsecure" {
 
 ## Full Example
 
-End-to-end wiring: a SplitSecure team with a SAML2 IdP, mirrored as `aws_iam_saml_provider` on the AWS side, with admin and readonly IAM roles and a single SP allowing federation into both. Lives at [`examples/full/main.tf`](https://github.com/splitsecure/terraform-provider-splitsecure/tree/main/examples/full) in the repo.
+End-to-end wiring: a SplitSecure team with a SAML2 IdP, mirrored as `aws_iam_saml_provider` on the AWS side, with admin and readonly IAM roles and a single SP allowing federation into both. Lives at [`examples/full`](https://github.com/splitsecure/terraform-provider-splitsecure/tree/main/examples/full) in the repo.
+
+```terraform
+variable "org_s2r" {
+  type        = string
+  description = "Org s2r URI hosting the team below. Used by the provider to spawn the proposal-scoped managed enclave on every Create / Delete."
+}
+
+variable "team_s2r" {
+  type        = string
+  description = "Team s2r URI that owns the IdP and SP. Voters on this team approve every Create / Delete proposal."
+}
+
+variable "operator_emails" {
+  type        = list(string)
+  default     = []
+  description = "Emails (as shown in the console) of users / service accounts allowed to operate the AWS federation SP."
+}
+```
 
 ```terraform
 terraform {
@@ -60,16 +78,6 @@ provider "splitsecure" {
 
 provider "aws" {}
 
-variable "org_s2r" {
-  type        = string
-  description = "Org s2r URI hosting the team below. Used by the provider to spawn the proposal-scoped managed enclave on every Create / Delete."
-}
-
-variable "team_s2r" {
-  type        = string
-  description = "Team s2r URI that owns the IdP and SP. Voters on this team approve every Create / Delete proposal."
-}
-
 data "aws_caller_identity" "current" {}
 
 locals {
@@ -203,4 +211,34 @@ output "aws_readonly_role_arn" {
   value       = aws_iam_role.readonly.arn
   description = "ARN of the readonly role users assume via SAML."
 }
+
+# --- Access -------------------------------------------------------
+# Terraform-managed permissions on the SP. Without grants, only org
+# owners/admins (and the creating service account) can see it.
+
+data "splitsecure_organization" "current" {}
+
+# Resolve each console email to its principal s2r (users and service
+# accounts alike), so callers paste emails rather than raw s2rs.
+data "splitsecure_principal" "operators" {
+  for_each = toset(var.operator_emails)
+  email    = each.value
+}
+
+resource "splitsecure_group" "operators" {
+  name    = "aws-federation-operators-${local.account_id}"
+  members = [for p in data.splitsecure_principal.operators : p.s2r]
+}
+
+resource "splitsecure_grant" "operators_use" {
+  resource_s2r = splitsecure_saml2_service_provider.main.id
+  grantee_s2r  = splitsecure_group.operators.group_s2r
+  tier         = "use"
+}
+
+resource "splitsecure_grant" "org_view" {
+  resource_s2r = splitsecure_saml2_service_provider.main.id
+  grantee_s2r  = data.splitsecure_organization.current.everyone_group_s2r
+  tier         = "view"
+}
 ```

docs/resources/grant.md

@@ -0,0 +1,46 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "splitsecure_grant Resource - SplitSecure"
+subcategory: ""
+description: |-
+  Permission grant giving a principal (user, service account, or group) a tier on a resource. Keyed by (resource, grantee) within the provider-configured org; only the tier can change in place.
+---
+
+# splitsecure_grant (Resource)
+
+Permission grant giving a principal (user, service account, or group) a tier on a resource. Keyed by (resource, grantee) within the provider-configured org; only the tier can change in place.
+
+## Example Usage
+
+```terraform
+# Grants authorize a principal (user, service account, or group) to act
+# on one resource at a tier: view < use < edit. PutGrant semantics are
+# upsert, so changing tier updates the grant in place; changing the
+# resource or grantee replaces it.
+#
+# Org owners and admins hold the edit tier on every resource implicitly;
+# grants matter for plain members.
+
+# Grant a group access to a SAML2 service provider.
+resource "splitsecure_grant" "sre_use" {
+  resource_s2r = splitsecure_saml2_service_provider.main.id
+  grantee_s2r  = data.splitsecure_group.sre.group_s2r
+  tier         = "use"
+}
+
+# Grant every org member visibility via the system "Everyone" group.
+resource "splitsecure_grant" "org_view" {
+  resource_s2r = splitsecure_saml2_service_provider.main.id
+  grantee_s2r  = data.splitsecure_organization.current.everyone_group_s2r
+  tier         = "view"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `grantee_s2r` (String) s2r URI of the principal receiving access: a user, service account, or group.
+- `resource_s2r` (String) s2r URI of the resource being shared.
+- `tier` (String) Access tier. One of: view, use, edit.

docs/resources/group.md

@@ -0,0 +1,51 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "splitsecure_group Resource - SplitSecure"
+subcategory: ""
+description: |-
+  Locally-managed principal group in the provider-configured organization. Terraform is authoritative over the member set; SCIM- and system-managed groups cannot be managed by this resource.
+---
+
+# splitsecure_group (Resource)
+
+Locally-managed principal group in the provider-configured organization. Terraform is authoritative over the member set; SCIM- and system-managed groups cannot be managed by this resource.
+
+## Example Usage
+
+```terraform
+# Groups are named sets of principals used as grant targets. Terraform
+# manages locally-sourced groups only: SCIM groups are owned by the
+# IdP and the system "Everyone" group is implicit. The members list is
+# authoritative — principals added out of band are removed on the next
+# apply.
+#
+# Group mutations require the service account behind the provider to
+# hold the org admin role.
+#
+# Members are referenced by the email shown in the console; the
+# splitsecure_principal data source resolves each to its s2r (users and
+# service accounts alike).
+resource "splitsecure_group" "sre" {
+  name = "SRE"
+  members = [
+    data.splitsecure_principal.alice.s2r,  # a user
+    data.splitsecure_principal.ci_bot.s2r, # a service account
+  ]
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) Human-readable group name. Changing it updates the group in place.
+
+### Optional
+
+- `members` (Set of String) Authoritative set of member principal s2r URIs (users or service accounts). Principals not listed here are removed on apply. Leave unset for an empty group.
+
+### Read-Only
+
+- `group_s2r` (String) Group s2r URI. Stable identifier; also the import ID.
+- `source` (String) Where the group is managed from: "local", "scim", or "system". Always "local" for Terraform-managed groups.

examples/data-sources/splitsecure_group/data-source.tf

@@ -0,0 +1,8 @@
+# Resolve a group by its stable group_s2r, exposing its current name and
+# source (e.g. to assert its source before granting on it). A group's
+# name is mutable and not unique server-side, so group_s2r is the only
+# lookup key. To use a group as a grant grantee you can also reference
+# its s2r directly, without this data source.
+data "splitsecure_group" "sre" {
+  group_s2r = "s2r:us:group:01HX.../01HY..."
+}

examples/data-sources/splitsecure_org_member/data-source.tf

@@ -0,0 +1,6 @@
+# Resolve an org member by email to the user S2R used as a grant or
+# group-member target. Errors if the email matches zero or multiple
+# members.
+data "splitsecure_org_member" "alice" {
+  email = "alice@example.com"
+}

examples/data-sources/splitsecure_organization/data-source.tf

@@ -0,0 +1,4 @@
+# The provider-configured org. everyone_group_s2r is the grantee for
+# org-wide grants; the "Everyone" group is a system group and is not
+# returned by group listings.
+data "splitsecure_organization" "current" {}

examples/data-sources/splitsecure_principal/data-source.tf

@@ -0,0 +1,12 @@
+# Resolve an org principal (user or service account) to its s2r by the email
+# shown in the console. Use the s2r as a group member or grant grantee.
+
+# A human user.
+data "splitsecure_principal" "alice" {
+  email = "alice@example.com"
+}
+
+# A service account (email is the one displayed in the console).
+data "splitsecure_principal" "ci_bot" {
+  email = "kQ7...@abc123.serviceaccount.us.splitsecure.com"
+}