OpenFGA Relationship Tuple

Deploys a relationship tuple into an existing OpenFGA store. A relationship tuple is the fundamental unit of authorization data in OpenFGA, representing that a specific user (or userset) has a particular relation to an object. Together with an authorization model, tuples determine access decisions at check time. All tuple fields are immutable — changing any field replaces the tuple. This component requires Terraform/Tofu as the provisioner; no Pulumi provider is available.

What Gets Created

When you deploy an OpenFgaRelationshipTuple resource, OpenMCF provisions:

• Relationship Tuple — an openfga_relationship_tuple resource that writes a single authorization tuple (user, relation, object) into the specified OpenFGA store

Prerequisites

• OpenFGA server — a running OpenFGA instance (self-hosted or cloud-hosted)
• OpenFGA credentials configured via environment variables: FGA_API_URL (required), plus either FGA_API_TOKEN for token-based auth or FGA_CLIENT_ID, FGA_CLIENT_SECRET, and FGA_API_TOKEN_ISSUER for client credentials auth
• An existing OpenFGA store — provide the store ID directly or reference an OpenFgaStore resource via valueFrom
• An authorization model — the store must contain a model that defines the types and relations used in the tuple
• Terraform/Tofu — this component has no Pulumi provider; set the provisioner label to tofu

Quick Start

Create a file tuple.yaml:

apiVersion: openfga.openmcf.org/v1
kind: OpenFgaRelationshipTuple
metadata:
  name: anne-views-budget
  labels:
    openmcf.org/provisioner: tofu
spec:
  storeId:
    value: "01HXYZ..."
  user:
    type: user
    id:
      value: anne
  relation: viewer
  object:
    type: document
    id:
      value: budget-2024

Deploy:

openmcf apply -f tuple.yaml

This creates a relationship tuple granting user anne the viewer relation on document:budget-2024.

Configuration Reference

Required Fields

Optional Fields

Examples

Grant a User Access to a Document

A minimal tuple granting a single user viewer access to a specific document, using direct values for all fields:

apiVersion: openfga.openmcf.org/v1
kind: OpenFgaRelationshipTuple
metadata:
  name: anne-views-budget
  labels:
    openmcf.org/provisioner: tofu
spec:
  storeId:
    value: "01HXYZ..."
  user:
    type: user
    id:
      value: anne
  relation: viewer
  object:
    type: document
    id:
      value: budget-2024

Group Membership with Userset

Add a user to a group using the userset format (group:engineering#member). Other tuples can then reference this group membership to grant indirect access:

apiVersion: openfga.openmcf.org/v1
kind: OpenFgaRelationshipTuple
metadata:
  name: anne-member-engineering
  labels:
    openmcf.org/provisioner: tofu
spec:
  storeId:
    value: "01HXYZ..."
  user:
    type: user
    id:
      value: anne
  relation: member
  object:
    type: group
    id:
      value: engineering

A second tuple grants all members of the engineering group editor access to a folder, using the userset relation field on the user:

apiVersion: openfga.openmcf.org/v1
kind: OpenFgaRelationshipTuple
metadata:
  name: engineering-edits-reports
  labels:
    openmcf.org/provisioner: tofu
spec:
  storeId:
    value: "01HXYZ..."
  user:
    type: group
    id:
      value: engineering
    relation: member
  relation: editor
  object:
    type: folder
    id:
      value: reports

Conditional Tuple with Foreign Key References

A tuple that uses foreign key references to resolve the store and model IDs from other OpenMCF resources, and includes a condition that restricts access to a set of allowed IP ranges. The condition must be defined in the authorization model:

apiVersion: openfga.openmcf.org/v1
kind: OpenFgaRelationshipTuple
metadata:
  name: bob-edits-roadmap-conditional
  labels:
    openmcf.org/provisioner: tofu
spec:
  storeId:
    valueFrom:
      kind: OpenFgaStore
      name: prod-authz
      field: status.outputs.id
  authorizationModelId:
    valueFrom:
      kind: OpenFgaAuthorizationModel
      name: rbac-model
      field: status.outputs.id
  user:
    type: user
    id:
      value: bob
  relation: editor
  object:
    type: document
    id:
      value: roadmap-2025
  condition:
    name: in_allowed_ip_range
    contextJson: '{"allowed_ips": ["192.168.1.0/24", "10.0.0.0/8"]}'

Stack Outputs

After deployment, the following outputs are available in status.outputs:

Related Components

• OpenFgaStore — provides the store where relationship tuples are written
• OpenFgaAuthorizationModel — defines the types, relations, and conditions that govern how tuples are evaluated