Configure Authorization Model for a Store

This article explains how to configure an authorization model for a store in an OpenFGA server.

Before You Start

Node.js

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have installed the SDK, created the store and setup the SDK client.
3. You have loaded FGA_STORE_ID and FGA_API_HOST as environment variables.

Go

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have installed the SDK, created the store and setup the SDK client.
3. You have loaded FGA_STORE_ID and FGA_API_HOST as environment variables.

.NET

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have installed the SDK, created the store and setup the SDK client.
3. You have loaded FGA_STORE_ID and FGA_API_HOST as environment variables.

Python

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have installed the SDK, created the store and setup the SDK client.
3. You have loaded FGA_STORE_ID and FGA_API_HOST as environment variables.

CLI

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have installed the CLI, created the store and setup your environment variables.
3. You have loaded FGA_STORE_ID and FGA_SERVER_URL as environment variables.

curl

1. Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_HOST and, if needed, FGA_API_TOKEN.
2. You have created the store and have loaded FGA_STORE_ID and FGA_API_HOST as environment variables.

Step By Step

Assume that you want to configure your store with the following model.

DSL

model
  schema 1.1
type user
type document
  relations
    define reader: [user]
    define writer: [user]
    define owner: [user]

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "document",
      "relations": {
        "reader": {
          "this": {}
        },
        "writer": {
          "this": {}
        },
        "owner": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "reader": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "owner": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
}

To configure authorization model, we can invoke the write authorization models API.

Node.js

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
const { OpenFgaClient } = require('@openfga/sdk');

// Initialize the SDK with no auth - see "How to setup SDK client" for more options
const fgaClient = new OpenFgaClient({
  apiScheme: process.env.FGA_API_SCHEME, // Either "http" or "https", defaults to "https"
  apiHost: process.env.FGA_API_HOST, // required, define without the scheme (e.g. api.fga.example instead of https://api.fga.example)
  storeId: process.env.FGA_STORE_ID,
  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
});

const { authorization_model_id: id } = await fgaClient.writeAuthorizationModel({
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "document",
      "relations": {
        "reader": {
          "this": {}
        },
        "writer": {
          "this": {}
        },
        "owner": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "reader": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "owner": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    }
  ]
});
// id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"

Go

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    . "github.com/openfga/go-sdk/client"
    "os"
)

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiScheme:            os.Getenv("FGA_SCHEME"), // Either "http" or "https", defaults to "https"
        ApiHost:              os.Getenv("FGA_API_HOST"), // required, define without the scheme (e.g. api.fga.example instead of https://api.fga.example)
        StoreId:              os.Getenv("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
        AuthorizationModelId: openfga.PtrString(os.Getenv("FGA_MODEL_ID")),  // Optional, can be overridden per request
    })

    if err != nil {
    // .. Handle error
    }
}

  var writeAuthorizationModelRequestString = "{\"schema_version\":\"1.1\",\"type_definitions\":[{\"type\":\"user\"},{\"type\":\"document\",\"relations\":{\"reader\":{\"this\":{}},\"writer\":{\"this\":{}},\"owner\":{\"this\":{}}},\"metadata\":{\"relations\":{\"reader\":{\"directly_related_user_types\":[{\"type\":\"user\"}]},\"writer\":{\"directly_related_user_types\":[{\"type\":\"user\"}]},\"owner\":{\"directly_related_user_types\":[{\"type\":\"user\"}]}}}}]}"
  var body WriteAuthorizationModelRequest
  if err := json.Unmarshal([]byte(writeAuthorizationModelRequestString), &body); err != nil {
      t.Errorf("%v", err)
      // .. Handle error
      return
  }

  data, response, err := fgaClient.OpenFgaClient.WriteAuthorizationModel(context.Background()).Body(body).Execute()
  if err != nil {
      // .. Handle error
  }

  // data.AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"
  

.NET

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
// import the SDK
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

class Example {
    public static async Task Main() {
        // Initialize the SDK with no auth - see "How to setup SDK client" for more options
        var configuration = new ClientConfiguration() {
          ApiScheme = Environment.GetEnvironmentVariable("FGA_API_SCHEME"), // Either "http" or "https", defaults to "https"
          ApiHost = Environment.GetEnvironmentVariable("FGA_API_HOST"), // required, define without the scheme (e.g. api.fga.example instead of https://api.fga.example)
          StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"), // optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
          AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"), // Optional, can be overridden per request
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

  var modelJson = "{\"schema_version\":\"1.1\",\"type_definitions\":[{\"type\":\"user\"},{\"type\":\"document\",\"relations\":{\"reader\":{\"this\":{}},\"writer\":{\"this\":{}},\"owner\":{\"this\":{}}},\"metadata\":{\"relations\":{\"reader\":{\"directly_related_user_types\":[{\"type\":\"user\"}]},\"writer\":{\"directly_related_user_types\":[{\"type\":\"user\"}]},\"owner\":{\"directly_related_user_types\":[{\"type\":\"user\"}]}}}}]}";
  var body = JsonSerializer.Deserialize<OpenFga.Sdk.Model.WriteAuthorizationModelRequest>(modelJson);

  var response = await fgaClient.WriteAuthorizationModel(body);
  // response.AuthorizationModelId = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"

Python

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import os
import json
import openfga_sdk
from openfga_sdk.client import OpenFgaClient

configuration = openfga_sdk.ClientConfiguration(
    api_scheme = os.environ.get('FGA_API_SCHEME'), # Either "http" or "https", defaults to "https"
    api_host = os.environ.get('FGA_API_HOST'), # required, define without the scheme (e.g. api.fga.example instead of https://api.fga.example)
    store_id = os.environ.get('FGA_STORE_ID') # optional, not needed for `CreateStore` and `ListStores`, required before calling for all other methods
    authorization_model_id = os.environ.get('FGA_MODEL_ID'), # Optional, can be overridden per request
)

# Enter a context with an instance of the OpenFgaClient
async with OpenFgaClient(configuration) as fga_client:
    api_response = await fga_client.read_authorization_models()
    await fga_client.close()

# from openfga_sdk.models.write_authorization_model_request import WriteAuthorizationModelRequest

async def write_authorization_model():
    body_string = "{\"schema_version\":\"1.1\",\"type_definitions\":[{\"type\":\"user\"},{\"type\":\"document\",\"relations\":{\"reader\":{\"this\":{}},\"writer\":{\"this\":{}},\"owner\":{\"this\":{}}},\"metadata\":{\"relations\":{\"reader\":{\"directly_related_user_types\":[{\"type\":\"user\"}]},\"writer\":{\"directly_related_user_types\":[{\"type\":\"user\"}]},\"owner\":{\"directly_related_user_types\":[{\"type\":\"user\"}]}}}}]}"
    response = await fga_client_instance.write_authorization_model(json.loads(body))
    # response.authorization_model_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw"

CLI

Set FGA_SERVER_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_SERVER_URL according to the service you are using (e.g. https://api.fga.example)

fga model write --store-id=${FGA_STORE_ID} {"schema_version":"1.1","type_definitions":[{"type":"user"},{"type":"document","relations":{"reader":{"this":{}},"writer":{"this":{}},"owner":{"this":{}}},"metadata":{"relations":{"reader":{"directly_related_user_types":[{"type":"user"}]},"writer":{"directly_related_user_types":[{"type":"user"}]},"owner":{"directly_related_user_types":[{"type":"user"}]}}}}]}

curl

Set FGA_SERVER_URL according to the service you are using (e.g. https://api.fga.example)

Set FGA_SERVER_URL according to the service you are using (e.g. https://api.fga.example)

curl -X POST $FGA_SERVER_URL/stores/$FGA_STORE_ID/authorization-models \
  -H "Authorization: Bearer $FGA_API_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{"schema_version":"1.1","type_definitions":[{"type":"user"},{"type":"document","relations":{"reader":{"this":{}},"writer":{"this":{}},"owner":{"this":{}}},"metadata":{"relations":{"reader":{"directly_related_user_types":[{"type":"user"}]},"writer":{"directly_related_user_types":[{"type":"user"}]},"owner":{"directly_related_user_types":[{"type":"user"}]}}}}]}'

The API will then return the authorization model ID.

Note

The OpenFGA API only accepts an authorization model in the API's JSON syntax.

To convert between the API Syntax and the friendly DSL, you can use the syntax transformer or Auth0 FGA's Playground.

Related Sections

Take a look at the following sections for more information on how to configure authorization model in your store.

Getting Started with Modeling

Read how to get started with modeling.

• More

Modeling: Direct Relationships

Read the basics of modeling authorization and granting access to users.

• More