terraform-provider-openfga

README

Terraform provider for OpenFGA

This is a Terraform/OpenTofu provider for OpenFGA. It enables managing the state of OpenFGA resources with code. for more details, check the provider documentation.

Table of Contents

• About OpenFGA
• Resources
• Installation
• Getting Started
  • Initializing the Provider
  • Using the Provider
    • Stores
      • Create Store
      • Get Store
      • List Stores
    • Authorization Models
      • Authorization Model Documents
      • Create Authorization Model
      • Get Authorization Model
      • Get Latest Authorization Model
      • List Authorization Models
    • Relationship Tuples
      • Create Relationship Tuple
      • Get Relationship Tuple
      • List Relationship Tuples
      • Query Relationship Tuples
    • Relationship Queries
      • Check
      • List Objects
      • List Users
• Contributing
• Author
• License

About

OpenFGA is an open source Fine-Grained Authorization solution inspired by Google's Zanzibar paper. It was created by the FGA team at Auth0 based on Auth0 Fine-Grained Authorization (FGA), available under a permissive license (Apache-2) and welcomes community contributions.

OpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate fine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a high scale.

Resources

• OpenFGA Documentation
• OpenFGA API Documentation
• Twitter
• OpenFGA Community
• Zanzibar Academy
• Google's Zanzibar Paper (2019)

Installation

To install, add the provider to your configuration:

terraform {
  required_providers {
    openfga = {
      source  = "openfga/openfga"
      version = ">=0.4.0"
    }
  }
}

Then run terraform init:

terraform init

Getting Started

Initializing the Provider

After installation, configure the provider to connect to your OpenFGA server.

No Credentials

provider "openfga" {
  api_url = "http://openfga:8080" # or use FGA_API_URL
}

API Token

provider "openfga" {
  api_url   = "http://openfga:8080" # or use FGA_API_URL
  api_token = var.api_token         # or use FGA_API_TOKEN
}

OAuth2 Client Credentials

provider "openfga" {
  api_url          = "http://openfga:8080" # or use FGA_API_URL
  client_id        = "..."                 # or use FGA_CLIENT_ID
  client_secret    = var.client_secret     # or use FGA_CLIENT_SECRET
  api_token_issuer = "http://example.com"  # or use FGA_API_TOKEN_ISSUER
  api_audience     = "..."                 # or use FGA_API_AUDIENCE
  api_scopes       = "..."                 # or use FGA_API_SCOPES
}

Environment Variables

You can also use environment variables to configure the provider. In this case, you can leave the provider block empty. If both environment variable and provider config a specified, the provider config takes precedence.

provider "openfga" {}

The available environment variables are:

• FGA_API_URL
• FGA_API_TOKEN
• FGA_CLIENT_ID
• FGA_CLIENT_SECRET
• FGA_API_SCOPES
• FGA_API_AUDIENCE
• FGA_API_TOKEN_ISSUER

Using the Provider

Stores

Create Store

Create and initialize a store.

Terraform Documentation

resource "openfga_store" "example" {
  name = "FGA Demo"
}

Get Store

Get information about a store by ID.

Terraform Documentation

data "openfga_store" "example" {
  id = "01FQH7V8BEG3GPQW93KTRFR8JB"
}

List Stores

Get a list of stores.

Terraform Documentation

data "openfga_stores" "example" {}

Authorization Models

Authorization Model Documents

Create a stable JSON representation of an authorization model.

Terraform Documentation

This data source takes authorization models in different formats as an input and produces a semantiaclly equal JSON output for the use in a openfga_authorization_model resource. The output of this data source will only change if there are semantic changes to a model (i.e., the output won't change for formatting changes, etc.)

Note: To learn how to build your authorization model, check the Docs at https://openfga.dev/docs.

Learn more about the OpenFGA configuration language.

data "openfga_authorization_model_document" "dsl" {
  dsl = file("path/to/model.fga")
}

data "openfga_authorization_model_document" "json" {
  json = file("path/to/model.json")
}

data "openfga_authorization_model_document" "mod" {
  mod_file_path = "path/to/fga.mod"
}

data "openfga_authorization_model_document" "model" {
  model = {
    schema_version = "1.1"
    type_definitions = [{
      type = "user"
    }]
  }
}

Create Authorization Model

Create a new authorization model.

Terraform Documentation

Note: You should use the openfga_authorization_model_document data source when when creating an authoriuation model.

resource "openfga_authorization_model" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"

  model_json = data.openfga_authorization_model_document.example.result
}

Get Authorization Model

Get an authorization model in a store by ID.

Terraform Documentation

data "openfga_authorization_model" "specific" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"

  id = "01GXSA8YR785C4FYS3C0RTG7B1"
}

Get Latest Authorization Model

Get latest authorization model in a store.

Terraform Documentation

data "openfga_authorization_model" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"
}

List Authorization Models

Get a list of authorization models in a store.

Terraform Documentation

data "openfga_authorization_models" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"
}

Relationship Tuples

Create Relationship Tuple

Create a new relationship tuple.

Terraform Documentation

resource "openfga_relationship_tuple" "example" {
  store_id               = "01FQH7V8BEG3GPQW93KTRFR8JB"
  authorization_model_id = "01GXSA8YR785C4FYS3C0RTG7B1" # optional

  user     = "user:81684243-9356-4421-8fbf-a4f8d36aa31b"
  relation = "viewer"
  object   = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
}

Get Relationship Tuple

Get a relationship tuple in a store by attributes.

Terraform Documentation

data "openfga_relationship_tuple" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"

  user     = "user:81684243-9356-4421-8fbf-a4f8d36aa31b"
  relation = "viewer"
  object   = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
}

List Relationship Tuples

Get all relationship tuple in a store.

Terraform Documentation

data "openfga_relationship_tuples" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"
}

Query Relationship Tuples

Get a list of relationship tuple in a store based on a query.

Terraform Documentation

data "openfga_relationship_tuples" "query" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"

  query = {
    user     = "user:81684243-9356-4421-8fbf-a4f8d36aa31b"
    relation = "viewer"
    object   = "document:"
  }
}

Relationship Queries

Check

Check if a user has a particular relation with an object.

Terraform Documentation

data "openfga_check_query" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"

  user     = "user:81684243-9356-4421-8fbf-a4f8d36aa31b"
  relation = "viewer"
  object   = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
}

You can also add contextual tuples and context to the query.

data "openfga_check_query" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"

  user     = "user:81684243-9356-4421-8fbf-a4f8d36aa31b"
  relation = "viewer"
  object   = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"

  contextual_tuples = [
    {
      user     = "user:81684243-9356-4421-8fbf-a4f8d36aa31b"
      relation = "viewer"
      object   = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
    }
  ]

  context_json = jsonencode({
    time = timestamp()
  })
}

List Objects

List the objects of a particular type a user has access to.

Terraform Documentation

data "openfga_list_objects_query" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"

  user     = "user:81684243-9356-4421-8fbf-a4f8d36aa31b"
  relation = "viewer"
  type     = "document"
}

You can also add contextual tuples and context to the query.

data "openfga_list_objects_query" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"

  user     = "user:81684243-9356-4421-8fbf-a4f8d36aa31b"
  relation = "viewer"
  type     = "document"

  contextual_tuples = [
    {
      user     = "user:81684243-9356-4421-8fbf-a4f8d36aa31b"
      relation = "viewer"
      object   = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
    }
  ]

  context_json = jsonencode({
    time = timestamp()
  })
}

List Users

List the users who have a certain relation to a particular type.

Terraform Documentation

data "openfga_list_users_query" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"

  type     = "user"
  relation = "viewer"
  object   = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
}

You can also add contextual tuples and context to the query.

data "openfga_list_users_query" "example" {
  store_id = "01FQH7V8BEG3GPQW93KTRFR8JB"

  type     = "user"
  relation = "viewer"
  object   = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"

  contextual_tuples = [
    {
      user     = "user:81684243-9356-4421-8fbf-a4f8d36aa31b"
      relation = "viewer"
      object   = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
    }
  ]

  context_json = jsonencode({
    time = timestamp()
  })
}

Contributing

See CONTRIBUTING.

Author

OpenFGA, Maurice Ackel

This provider was created by Maurice Ackel, and then donated to the OpenFGA team, and Maurice stayed on as a maintainer.

Versions <v0.4.0 can be found at: https://registry.terraform.io/providers/mauriceackel/openfga, licensed as MIT.

License

This project is licensed under the Apache-2.0 license. See the LICENSE file for more info.