User Groups

To add users to groups and grant groups access to an object using OpenFGA.

When to use

Relationship tuples can specify that an entire group has a relation to an object, which is helpful when you want to encompass a set of users with the same relation to an object. For example:

Grant viewer access to a group of engineers in roadmap.doc
Create a block_list of members who can't access a document
Sharing a document with a team
Granting viewer access to a photo to followers only
Making a file viewable for all users within an organization
Restricting access from or to users in a certain locale

Before you start

Familiarize yourself with the OpenFGA Concepts.

Assume you have the following authorization model.
: you have an object called document that users can relate to as an editor.

model
  schema 1.1

type user

type document
  relations
    define editor: [user]

In addition, you will need to know the following:

Direct Access

You need to know how to create an authorization model and a relationship tuple to grant a user access to an object. To learn more, see direct access.

OpenFGA Concepts

A Type: a class of objects that have similar characteristics.
A User: an entity in the system that can be related to an object.
A Relation: a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system.
An Object: represents an entity in the system. Users' relationships to it can be defined with relationship tuples and the authorization model.
A Relationship Tuple: a grouping consisting of a user, a relation and an object stored in OpenFGA.

Step By Step

There are possible use cases where a group of users have a certain role on or permission to an object. For example, members of a certain team could have an editor relation to a certain document.

To represent this in OpenFGA:

Introduce the concept of a team to the authorization model. →
Add users as members to the team. →
Assign the team members a relation to an object. →
Check an individual member's access to the object. →

01. Introduce the concept of a team to the authorization model

First, define the object team in your authorization model. In this use case, a team can have members, so you make the following changes to the authorization model:

model
  schema 1.1

type user

type document
  relations
    define editor: [team#member]

type team
  relations
    define member: [user]

02. Add users as members to the team

You can now assign users as members of teams. Create a new relationship tuple that states user:alice is a member of team:writers.

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({
  apiUrl: process.env.FGA_API_URL, // required, e.g. https://api.fga.example
  storeId: process.env.FGA_STORE_ID,
  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
});

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

await fgaClient.write({
  writes: [
      {"user":"user:alice","relation":"member","object":"team:writers"}
  ],
}, options);

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. 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: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

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

body := ClientWriteRequest{
    Writes: []ClientTupleKey{
        {
             User: "user:alice",
             Relation: "member",
             Object: "team:writers",
        }, 
    }, 
}

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

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

_ = data // use the response

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() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. 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 options = new ClientWriteOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
       new() {
                  User = "user:alice",
                  Relation = "member",
                  Object = "team:writers"
              }
  },
};
var response = await fgaClient.Write(body, options);

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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 = ClientWriteRequest(
        writes=[
                ClientTuple(
                    user="user:alice",
                    relation="member",
                    object="team:writers",
                ),
        ],
)

response = await fga_client.write(body, options)

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import dev.openfga.sdk.api.client.OpenFgaClient;
import dev.openfga.sdk.api.configuration.ClientConfiguration;

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

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

var body = new ClientWriteRequest()
        .writes(List.of(
                new ClientTupleKey()
                        .user("user:alice")
                        .relation("member")
                        ._object("team:writers")
        ));

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

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

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

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:alice",
        "relation": "member",
        "object": "team:writers"
      }
    ]
  },
  "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}'

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

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

fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:alice member team:writers  

write([
    {
      "user":"user:alice",
      "relation":"member",
      "object":"team:writers"
    }
], authorization_model_id="01HVMMBCMGZNT3SED4Z17ECXCA")

03. Assign the team members a relation to an object

To represent groups, use the type:object_id#relation format, which represents the set of users related to the type:object_id as a certain relation. For example, team:writers#members represents the set of users related to the team:writers object as members.

In order to assign members of a team a relation to a document, create the following relationship tuple stating that members of team:writers are editors of document:meeting_notes.doc.

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({
  apiUrl: process.env.FGA_API_URL, // required, e.g. https://api.fga.example
  storeId: process.env.FGA_STORE_ID,
  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
});

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

await fgaClient.write({
  writes: [
      // Set of users related to 'team:writers' as 'member'
      {"_description":"Set of users related to 'team:writers' as 'member'","user":"team:writers#member","relation":"editor","object":"document:meeting_notes.doc"}
  ],
}, options);

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. 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: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

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

body := ClientWriteRequest{
    Writes: []ClientTupleKey{
        {
             // Set of users related to 'team:writers' as 'member'
             User: "team:writers#member",
             Relation: "editor",
             Object: "document:meeting_notes.doc",
        }, 
    }, 
}

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

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

_ = data // use the response

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() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. 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 options = new ClientWriteOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA",
};
var body = new ClientWriteRequest() {
    Writes = new List<ClientTupleKey>() {
    // Set of users related to 'team:writers' as 'member'
       new() {
                  User = "team:writers#member",
                  Relation = "editor",
                  Object = "document:meeting_notes.doc"
              }
  },
};
var response = await fgaClient.Write(body, options);

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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 = ClientWriteRequest(
        writes=[
                ClientTuple(
                    # Set of users related to 'team:writers' as 'member'
                    user="team:writers#member",
                    relation="editor",
                    object="document:meeting_notes.doc",
                ),
        ],
)

response = await fga_client.write(body, options)

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import dev.openfga.sdk.api.client.OpenFgaClient;
import dev.openfga.sdk.api.configuration.ClientConfiguration;

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

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

var body = new ClientWriteRequest()
        .writes(List.of(
                // Set of users related to 'team:writers' as 'member'
                new ClientTupleKey()
                        .user("team:writers#member")
                        .relation("editor")
                        ._object("document:meeting_notes.doc")
        ));

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

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

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

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": "team:writers#member",
        "relation": "editor",
        "object": "document:meeting_notes.doc"
      }
    ]
  },
  "authorization_model_id": "01HVMMBCMGZNT3SED4Z17ECXCA"
}'

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

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

fga tuple write --store-id=${FGA_STORE_ID} --model-id=01HVMMBCMGZNT3SED4Z17ECXCA team:writers#member editor document:meeting_notes.doc  

write([
    // Set of users related to 'team:writers' as 'member'
    {
      "user":"team:writers#member",
      "relation":"editor",
      "object":"document:meeting_notes.doc"
    }
], authorization_model_id="01HVMMBCMGZNT3SED4Z17ECXCA")

04. Check an individual member's access to an object

Now that you have:

a relationship tuple indicating that alice is a member of team:writers
a relationship tuple indicating that members of team:writers are editors of document:meeting_notes.doc

The *check\ is alice an editor of document:meeting_notes.doc returns the following:

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({
  apiUrl: process.env.FGA_API_URL, // required, e.g. https://api.fga.example
  storeId: process.env.FGA_STORE_ID,
  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
});

// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:alice',
    relation: 'editor',
    object: 'document:meeting_notes.doc',
  }, {
    authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Initialize the SDK

// ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.
import (
    "os"

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

func main() {
    // Initialize the SDK with no auth - see "How to setup SDK client" for more options
    fgaClient, err := NewSdkClient(&ClientConfiguration{
        ApiUrl:               os.Getenv("FGA_API_URL"), // required, e.g. 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: os.Getenv("FGA_MODEL_ID"),  // Optional, can be overridden per request
    })

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

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

body := ClientCheckRequest{
    User:     "user:alice",
    Relation: "editor",
    Object:   "document:meeting_notes.doc",
}

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

// data = { allowed: true }

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() {
          ApiUrl = Environment.GetEnvironmentVariable("FGA_API_URL"), ?? "http://localhost:8080", // required, e.g. 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 options = new ClientCheckOptions {
    AuthorizationModelId = "01HVMMBCMGZNT3SED4Z17ECXCA"
};
var body = new ClientCheckRequest {
    User = "user:alice",
    Relation = "editor",
    Object = "document:meeting_notes.doc",
};
var response = await fgaClient.Check(body, options);

// response.Allowed = true

Initialize the SDK

# ApiTokenIssuer, ApiAudience, ClientId and ClientSecret are optional.

import asyncio
import os
import json
from openfga_sdk.client import ClientConfiguration, OpenFgaClient

async def main():
    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:alice",
    relation="editor",
    object="document:meeting_notes.doc",
)

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;

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_AUTHORIZATION_MODEL_ID")); // Optional, can be overridden per request

      var fgaClient = new OpenFgaClient(config);
  }
}

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

var body = new ClientCheckRequest()
        .user("user:alice")
        .relation("editor")
        ._object("document:meeting_notes.doc");

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

// response.getAllowed() = true 

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

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

fga query check --store-id=$FGA_STORE_ID --model-id=01HVMMBCMGZNT3SED4Z17ECXCA user:alice editor document:meeting_notes.doc

# Response: {"allowed":true}

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

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

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:alice",
      "relation": "editor",
      "object": "document:meeting_notes.doc"
    }
  }'

# Response: {"allowed": true}

check(
  user = "user:alice", // check if the user `user:alice`
  relation = "editor", // has an `editor` relation
  object = "document:meeting_notes.doc", // with the object `document:meeting_notes.doc`
   authorization_id = "01HVMMBCMGZNT3SED4Z17ECXCA"
);

Reply: true

is user:alice related to document:meeting_notes.doc as editor?

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

The chain of resolution is:

alice is member of team:writers
members of team:writers are editors of document:meeting_notes
therefore, alice is editor of document:meeting_notes

caution

Note: When creating relationship tuples for OpenFGA, use unique ids for each object and user in your application domain. This example uses first names and simple ids as a suggested example.

Managing Group Membership

Learn how to add and remove users from groups

Modeling Google Drive

See how User Groups can be used to share documents within a domain in the Google Drive use-case.

Modeling GitHub

Granting teams permissions to a repo in the GitHub use-case.

Before you start​

Direct Access​

OpenFGA Concepts​

Step By Step​

01. Introduce the concept of a team to the authorization model​

02. Add users as members to the team​

03. Assign the team members a relation to an object​

04. Check an individual member's access to an object​

Related Sections​

Before you start

Direct Access

OpenFGA Concepts

Step By Step

01. Introduce the concept of a team to the authorization model

02. Add users as members to the team

03. Assign the team members a relation to an object

04. Check an individual member's access to an object

Related Sections