Modular Models

Authorization is application-specific. In an organization with multiple teams building different applications or modules, each team should be able to define and evolve their authorization policies independently.

Modular models allows splitting your authorization model across multiple files and modules, improving upon some of the challenges that may be faced when maintaining an authorization model within a company, such as:

A model can grow large and difficult to understand.
As more teams begin to contribute to a model, the ownership boundaries may not be clear and code review processes might not scale.

With modular models, a single model can be split across multiple files in a project and organized in a way that makes sense for the project or teams collaborating on it. For example, modular models allows ownership for reviews to be expressed using a feature like GitHub's, GitLab's or Gitea's code owners.

note

To use modular models you need to use FGA CLI to maintain authorization models. The Auth0 FGA dashboard will not let you update an authorization model that uses modular models.

Key Concepts

`fga.mod`

The fga.mod file is the project file for modular models. It specifies the schema version for the final combined model and lists the individual files that make up the modular model.

Property	Description
`schema`	The schema version to be used for the combined model
`contents`	The individual files that make up the modular model

Modules

Auth0 FGA modules define the types and relations for a specific application module or service.

Modules are declared using the module keyword in the DSL, and a module can be written across multiple files. A single file cannot have more than one module.

Type Extensions

As teams implement features, they might find that core types they are dependent upon might not contain all the relations they need. However, it might not make sense for these relations to be owned by the owner of that type if they aren't needed across the system.

Modular models solves that problem by allowing individual types to be extended within other modules to to share those relations.

The following are requirements for type extension:

The extended type must exist
A single type can only be extended once per file
The relations added must not already exist, or be part of another type extension

Example

The following example shows how an authorization model for a SaaS compny with a issue tracking and wiki software can implement modular models.

Core

If there is a core set of types owned by a team that manages the overall identity for the company, the following provides the basics: users, organizations and groups that can be used by each product area.

module core

type user

type organization
  relations
    define member: [user]
    define admin: [user]

type group
  relations
    define member: [user]

Issue tracking

The issue tracking software separates out the project- and issue-related types into separate files. Below, we also extend the organization type to add a relation specific to the issue tracking feature: the ability to authorize who can create a project.

module issue-tracker

extend type organization
  relations
    define can_create_project: admin

type project
  relations
    define organization: [organization]
    define viewer: member from organization

module issue-tracker

type ticket
  relations
    define project: [project]
    define owner: [user]

Wiki

The wiki model is managed in one file until it grows. We can also extend the organization type again to add a relation tracking who can create a space.

module wiki

extend type organization
  relations
    define can_create_space: admin


type space
  relations
    define organization: [organization]
    define can_view_pages: member from organization

type page
  relations
    define space: [space]
    define owner: [user]

`fga.mod`

To deploy this model, create the fga.mod manifest file, set a schema version, and list the individual module files that comprise the model.

schema: '1.2'
contents:
  - core.fga
  - issue-tracker/projects.fga
  - issue-tracker/tickets.fga
  - wiki.fga

Putting it all together

With individual parts of the modular model in place, write the model to Auth0 FGA and run tests against it. Below is an example of what to run in the CLI:

fga model write --store-id=$FGA_STORE_ID --file fga.mod

This model can now be queried and have tuples written to it, just like a singular file authorization model.

const options = {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA",
};

await fgaClient.write({
  writes: [
      {"user":"user:anne","relation":"admin","object":"organization:acme"},
      {"user":"organization:acme","relation":"organization","object":"space:acme"},
      {"user":"organization:acme","relation":"organization","object":"project:acme"}
  ],
}, options);

options := ClientWriteOptions{
    AuthorizationModelId: openfga.PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientWriteRequest{
    Writes: []ClientTupleKey{
        {
             User: "user:anne",
             Relation: "admin",
             Object: "organization:acme",
        },         {
             User: "organization:acme",
             Relation: "organization",
             Object: "space:acme",
        },         {
             User: "organization:acme",
             Relation: "organization",
             Object: "project:acme",
        }, 
    }, 
}

data, err := fgaClient.Write(context.Background()).
    Body(body).
    Options(options).
    Execute()

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

_ = data // use the response

var options = new ClientWriteOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
       new() {
                  User = "user:anne",
                  Relation = "admin",
                  Object = "organization:acme"
              },
       new() {
                  User = "organization:acme",
                  Relation = "organization",
                  Object = "space:acme"
              },
       new() {
                  User = "organization:acme",
                  Relation = "organization",
                  Object = "project:acme"
              }
  },
};
var response = await fgaClient.Write(body, options);

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}
body = ClientWriteRequest(
        writes=[
                ClientTuple(
                    user="user:anne",
                    relation="admin",
                    object="organization:acme",
                ),
                ClientTuple(
                    user="organization:acme",
                    relation="organization",
                    object="space:acme",
                ),
                ClientTuple(
                    user="organization:acme",
                    relation="organization",
                    object="project:acme",
                ),
        ],
)

response = await fga_client.write(body, options)

var options = new ClientWriteOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientWriteRequest()
        .writes(List.of(
                new ClientTupleKey()
                        .user("user:anne")
                        .relation("admin")
                        ._object("organization:acme"),
                new ClientTupleKey()
                        .user("organization:acme")
                        .relation("organization")
                        ._object("space:acme"),
                new ClientTupleKey()
                        .user("organization:acme")
                        .relation("organization")
                        ._object("project:acme")
        ));

var response = fgaClient.write(body, options).get();

fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:anne admin organization:acme  
fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA organization:acme organization space:acme  
fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA organization:acme organization project:acme  

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/write \
  -H "Authorization: Bearer $FGA_API_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{
  "writes": {
    "tuple_keys": [
      {
        "user": "user:anne",
        "relation": "admin",
        "object": "organization:acme"
      },
      {
        "user": "organization:acme",
        "relation": "organization",
        "object": "space:acme"
      },
      {
        "user": "organization:acme",
        "relation": "organization",
        "object": "project:acme"
      }
    ]
  },
  "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}'

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
const { CredentialsMethod, OpenFgaClient } = require('@openfga/sdk'); // OR import { CredentialsMethod, OpenFgaClient } from '@openfga/sdk';

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

const fgaClient = new OpenFgaClient({
    apiUrl: process.env.FGA_API_URL,
    storeId: process.env.FGA_STORE_ID,
    authorizationModelId: process.env.FGA_MODEL_ID,
    credentials: { // Credentials are not needed if connecting to the Playground API
      method: CredentialsMethod.ClientCredentials,
      config: {
        apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER,
        apiAudience: process.env.FGA_API_AUDIENCE,
        clientId: process.env.FGA_CLIENT_ID,
        clientSecret: process.env.FGA_CLIENT_SECRET,
      },
    },
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:anne',
    relation: 'can_create_space',
    object: 'organization:acme',
  }, {
    authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
import (
    "os"

    openfga "github.com/openfga/go-sdk"
    . "github.com/openfga/go-sdk/client"
    "github.com/openfga/go-sdk/credentials"
)

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

func main() {
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), 
        StoreId:              os.Getenv("FGA_STORE_ID"),
        AuthorizationModelId: os.Getenv("FGA_MODEL_ID"),
        Credentials: &credentials.Credentials{ // Credentials are not needed if connecting to the Playground API
            Method: credentials.CredentialsMethodClientCredentials,
            Config: &credentials.Config{
                ClientCredentialsClientId:       os.Getenv("FGA_CLIENT_ID"),
                ClientCredentialsClientSecret:   os.Getenv("FGA_CLIENT_SECRET"),
                ClientCredentialsApiAudience:    os.Getenv("FGA_API_AUDIENCE"),
                ClientCredentialsApiTokenIssuer: os.Getenv("FGA_API_TOKEN_ISSUER"),
            },
        },
    })

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

options := ClientCheckOptions{
    AuthorizationModelId: openfga.PtrString("01HVMMBCMGZNT3SED4Z17ECXCA"),
}

body := ClientCheckRequest{
    User:     "user:anne",
    Relation: "can_create_space",
    Object:   "organization:acme",
}

data, err := fgaClient.Check(context.Background()).
    Body(body).
    Options(options).
    Execute()

// data = { allowed: true }

Initialize the SDK

// Checkout the "How to Setup the SDK Client" page for more details.
using OpenFga.Sdk.Client;
using OpenFga.Sdk.Client.Model;
using OpenFga.Sdk.Model;
using Environment = System.Environment;

namespace Example;

// Ensure the environment variables are set
// FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

class MyProgram {
    static async Task Main() {
        var configuration = new ClientConfiguration() {
            ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"),
            StoreId = Environment.GetEnvironmentVariable("FGA_STORE_ID"),
            AuthorizationModelId = Environment.GetEnvironmentVariable("FGA_MODEL_ID"),
            Credentials = new Credentials() { // Credentials are not needed if connecting to the Playground API
                Method = CredentialsMethod.ClientCredentials,
                Config = new CredentialsConfig() {
                    ApiTokenIssuer = Environment.GetEnvironmentVariable("FGA_API_TOKEN_ISSUER"),
                    ApiAudience = Environment.GetEnvironmentVariable("FGA_API_AUDIENCE"),
                    ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
                    ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
                }
            }
        };
        var fgaClient = new OpenFgaClient(configuration);
    }
}

var options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA"
};
var body = new ClientCheckRequest {
    User = "user:anne",
    Relation = "can_create_space",
    Object = "organization:acme",
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Initialize the SDK

# Checkout the "How to Setup the SDK Client" page for more details.

import os
import openfga_sdk
from openfga_sdk.client import OpenFgaClient, ClientConfiguration
from openfga_sdk.credentials import Credentials, CredentialConfiguration

# FGA_API_URL = 'https://api.us1.fga.dev' // 'https://api.eu1.fga.dev' for EU and 'https://api.au1.fga.dev' for AU
# FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
# FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
# FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
# FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
# FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
# FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

async def main():
    credentials = Credentials(
      method='client_credentials',
      configuration=CredentialConfiguration(
          api_issuer= os.environ.get('FGA_API_TOKEN_ISSUER'),
          api_audience= os.environ.get('FGA_API_AUDIENCE'),
          client_id= os.environ.get('FGA_CLIENT_ID'),
          client_secret= os.environ.get('FGA_CLIENT_SECRET'),
      )
    )

    configuration = ClientConfiguration(
        api_url = os.environ.get('FGA_API_URL'), # required, e.g. 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()

asyncio.run(main())

options = {
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA",
}
body = ClientCheckRequest(
    user="user:anne",
    relation="can_create_space",
    object="organization:acme",
)

response = await fga_client.check(body, options)

# response.allowed = true

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import dev.openfga.sdk.api.client.OpenFgaClient;
import dev.openfga.sdk.api.configuration.ClientConfiguration;
import dev.openfga.sdk.api.configuration.ClientCredentials;
import dev.openfga.sdk.api.configuration.Credentials;

// FGA_API_URL = 'https://api.us1.fga.dev' for Dev Preview and Early Access / 'https://api.playground.fga.dev' for the FGA Playground
// FGA_STORE_ID = 'YOUR_STORE_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
// FGA_MODEL_ID = 'YOUR_MODEL_ID' - optional, can be overridden per request, helps reduce latency
// FGA_API_TOKEN_ISSUER = 'auth.fga.dev' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' for Dev Preview and Early Access / not needed for the FGA Playground
// FGA_CLIENT_ID = 'YOUR_CLIENT_ID' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground
// FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' - Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page / not needed for the FGA Playground

public class Example {
  public static void main(String[] args) throws Exception {
      var config = new ClientConfiguration()
              .apiUrl(System.getenv("FGA_API_URL")) // If not specified, will default to "https://localhost:8080"
              .storeId(System.getenv("FGA_STORE_ID")) // Not required when calling createStore() or listStores()
              .authorizationModelId(System.getenv("FGA_MODEL_ID")) // Optional, can be overridden per request
              .credentials(new Credentials(
                  new ClientCredentials()
                          .apiTokenIssuer(System.getenv("FGA_API_TOKEN_ISSUER"))
                          .apiAudience(System.getenv("FGA_API_AUDIENCE"))
                          .clientId(System.getenv("FGA_CLIENT_ID"))
                          .clientSecret(System.getenv("FGA_CLIENT_SECRET"))
              ));

      var fgaClient = new OpenFgaClient(config);
  }
}

var options = new ClientCheckOptions()
        .authorizationModelId("01HVMMBCMGZNT3SED4Z17ECXCA");

var body = new ClientCheckRequest()
        .user("user:anne")
        .relation("can_create_space")
        ._object("organization:acme");

var response = fgaClient.check(body, options).get();

// response.getAllowed() = true 

Set the environment variables according to the "How to get your API keys"

Set the required environment variables
# For all environments
export FGA_STORE_ID = 'YOUR_STORE_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_MODEL_ID = 'YOUR_MODEL_ID' # optional, can be overridden per request, helps reduce latency

export FGA_API_URL = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
export FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_CLIENT_ID = 'YOUR_CLIENT_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:anne can_create_space organization:acme

# Response: {"allowed":true}

Set the environment variables according to the "How to get your API keys"

Set the required environment variables
# For all environments
export FGA_STORE_ID = 'YOUR_STORE_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_MODEL_ID = 'YOUR_MODEL_ID' # optional, can be overridden per request, helps reduce latency

export FGA_API_URL = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_API_TOKEN_ISSUER = 'auth.fga.dev'
export FGA_API_AUDIENCE = 'https://api.us1.fga.dev/' // 'https://api.eu1.fga.dev/' for EU and 'https://api.au1.fga.dev/' for AU
export FGA_CLIENT_ID = 'YOUR_CLIENT_ID' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page
export FGA_CLIENT_SECRET = 'YOUR_CLIENT_SECRET' # Get this from your store settings in the dashboard, refer to the "How to get your API Keys" page

curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/check \
  -H "Authorization: Bearer $FGA_API_TOKEN" \ # Not needed if service does not require authorization
  -H "content-type: application/json" \
  -d '{
    "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA",
    "tuple_key": {
      "user": "user:anne",
      "relation": "can_create_space",
      "object": "organization:acme"
    }
  }'

# Response: {"allowed": true}

check(
  user = "user:anne", // check if the user `user:anne`
  relation = "can_create_space", // has an `can_create_space` relation
  object = "organization:acme", // with the object `organization:acme`
);

Reply: true

is user:anne related to organization:acme as can_create_space?

# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`

Viewing the model

When using the CLI to view the combined model DSL with fga model get --store-id=$FGA_STORE_ID, the DSL is annotated with comments defining the source module and file for types, relations and conditions.

For example, the organization type shows that the type is defined in the core.fga file as part of the core module, the can_create_project relation is defined in issue-tracker/projects.fga as part of the issuer-tracker module, and the can_create_space relation is defined in the wiki.fga file as part of the wiki module.

type organization # module: core, file: core.fga
  relations
    define admin: [user]
    define member: [user] or admin
    define can_create_project: admin # extended by: module: issue-tracker, file: issue-tracker/projects.fga
    define can_create_space: admin # extended by: module: wiki, file: wiki.fga

Key Concepts​

fga.mod​

Modules​

Type Extensions​

Example​

Core​

Issue tracking​

Wiki​

fga.mod​

Putting it all together​

Viewing the model​

Have Feedback?

Key Concepts

`fga.mod`

Modules

Type Extensions

Example

Core

Issue tracking

Wiki

`fga.mod`

Putting it all together

Viewing the model