Skip to main content

Modeling Authorization for Slack with OpenFGA

This tutorial explains how to model permissions for a communication platform like Slack using OpenFGA.

What you will learn
  • How to indicate relationships between a group of users and an object.
    Used here to indicate that all members of a slack workspace can write in a certain channel.
    See Modeling User Groups for more.
  • How to Model concentric relationship to have a certain relation on an object imply another relation on the same object.
    Used here to indicate that legacy admins have all the permissions of the more granular channels admin.
    See Modeling Concentric Relationships for more.
  • How to use the union operator condition to indicate that a user might have a certain relation with an object if they match any of the criteria indicated.

Before you start​

In order to understand this guide correctly you must be familiar with some OpenFGA concepts and know how to develop the things that we will list below.

OpenFGA concepts​

It would be helpful to have an understanding of some concepts of OpenFGA before you start.

Direct access​

You need to know how to create an authorization model and create a relationship tuple to grant a user access to an object. Learn more →

Modeling concentric relationships​

You need to know how to update the authorization model to allow having nested relations such as all writers are readers. Learn more →

Concepts & configuration language​

What you will be modeling​

Slack is a messaging app for businesses that connects people to the information they need. By bringing people together to work as one unified team, Slack transforms the way organizations communicate. (Source: What is Slack?)

In this tutorial, you will build a subset of the Slack permission model (detailed below) in OpenFGA, using some scenarios to validate the model.

As reference, you can refer to Slack's publicly available docs:

Note: For brevity, this tutorial will not model all of Slack's permissions. Instead, it will focus on modeling the scenarios outlined below.

Requirements​

This tutorial will focus on the following sections (this is a partial list of Slack's roles):

Workspace Roles:

  • Guest: This type of user is limited in their ability to use Slack, and is only permitted to see one or multiple delegated channels.
  • Member: This is the base type of user that does not have any particular administrative abilities, but has basic access to the organization's Slack workspaces. When an administrative change needs to be made, these users need the support of admins and owners to make the changes.
  • Legacy Admin: This type of user is the basic administrator of any organization, and can make a wide variety of administrative changes across Slack, such as renaming channels, archiving channels, setting up preferences and policies, inviting new users, and installing applications. Users with this role perform the majority of administrative tasks across a team.

System Roles:

  • Channels Admin: This type of user has the permission to archive channels, rename channels, create private channels, and convert public channels into private channels.

Channel Settings:

  • Visibility:
    • Public: Visible to all members and open to join
    • Private: Visible to admins and invited members
  • Posting Permissions:
    • Open: Anyone can post
    • Limited: Only allowed members can post

Defined scenarios​

Use the following scenarios to be able to validate whether the model of the requirements is correct.

There will be the following users:

  • Amy
  • Bob
  • Catherine
  • David
  • Emily

These users will interact in the following scenarios:

  • You will assume there is a Slack workspace called Sandcastle
  • Amy is a legacy admin of the Sandcastle workspace
  • Bob is a member of the Sandcastle workspace with a channels admin role (Read more about system roles at Slack here)
  • Catherine and Emily are normal members of the Sandcastle workspace, they can view all public channels, as well as channels they have been invited to
  • David is a guest user with only view and write access to #proj-marketing-campaign, one of the public channels in the Sandcastle workspace
  • Bob and Emily are in a private channel #marketing-internal in the Sandcastle workspace which only they can view and post to
  • All members of the Sandcastle workspace can view the general channel, but only Amy and Emily can post to it

Image showing requirements

caution

In production, it is highly recommended to use unique, immutable identifiers. Names are used in this article to make it easier to read and follow.

Modeling workspaces & channels​

The goal by the end of this post is to ask OpenFGA: Does person X have permission to perform action Y on channel Z? In response, you want to either get a confirmation that person X can indeed do that, or a rejection that they cannot. E.g. does David have access to view #general?

The OpenFGA is based on Zanzibar, a Relation Based Access Control system. This means it relies on objects and user relations to perform authorization checks.

Setting aside the permissions, you will start with the roles and learn how to express the requirements in terms of relations you can feed into OpenFGA.

The requirements stated:

  • Amy is a legacy admin of the Sandcastle workspace
  • Bob is a channels admin of the Sandcastle workspace
  • Catherine and Emily are a normal members of the Sandcastle workspace
  • David is a guest user

Here is how you would express than in OpenFGA's authorization model: You have a type called "workspace", and users can be related to it as a legacy_admin, channels_admin, member and guest

model
  schema 1.1

type user

type workspace
  relations
    define legacy_admin: [user]
    define channels_admin: [user]
    define member: [user]
    define guest: [user]
info

Objects of type workspace have users related to them as:

  • Legacy Admin (legacy_admin)
  • Channels Admin (channels_admin)
  • Member (member)
  • Guest (guest)

Direct relationship type restrictions indicate that a user can have a direct relationship with an object of the type the relation specifies.

01. Individual permissions​

To keep things simple and focus on OpenFGA rather than Slack complexity, we will model only four roles (legacy_admin, channels_admin, member, guest).

At the end of this section we want to have the following permissions represented

UserRelationObject
amylegacy_adminworkspace:sandcastle
bobchannels_adminworkspace:sandcastle
catherinememberworkspace:sandcastle
davidguestworkspace:sandcastle
emilymemberworkspace:sandcastle

To represent permissions in OpenFGA we use relations. For workspace permissions we need to create the following authorization model:

model
  schema 1.1

type user

type workspace
  relations
    define legacy_admin: [user]
    define channels_admin: [user]
    define member: [user]
    define guest: [user]

The OpenFGA service determines if a user has access to an object by checking if the user has a relation to that object. Let us examine one of those relations in detail:


type workspace
  relations
    define member: [user]
info

The snippet above indicates that objects of type workspace have users related to them as "member" if those users belong to the userset of all users related to the workspace as "member".

This means that a user can be directly related as a member to an object of type "workspace"

If we want to say amy is a legacy_admin of workspace:sandcastle we create this relationship tuple

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
});

await fgaClient.write({
  writes: [
      // Amy is a Legacy Admin in the Sandcastle workspace
      {"_description":"Amy is a Legacy Admin in the Sandcastle workspace","user":"user:amy","relation":"legacy_admin","object":"workspace:sandcastle"}
  ],
}, {
  authorization_model_id: "01HVMMBCMGZNT3SED4Z17ECXCA" 
});

We can now ask OpenFGA "is amy a legacy_admin of workspace:sandcastle?"

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:amy',
    relation: 'legacy_admin',
    object: 'workspace:sandcastle',
  }, {
  authorization_model_id: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

We can also say that catherine is a member of workspace:sandcastle:

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
});

await fgaClient.write({
  writes: [
      // Catherine is a Member in the Sandcastle workspace
      {"_description":"Catherine is a Member in the Sandcastle workspace","user":"user:catherine","relation":"member","object":"workspace:sandcastle"}
  ],
}, {
  authorization_model_id: "01HVMMBCMGZNT3SED4Z17ECXCA" 
});

And verify by asking OpenFGA

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:catherine',
    relation: 'member',
    object: 'workspace:sandcastle',
  }, {
  authorization_model_id: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Catherine, on the other hand, is not a legacy_admin of workspace:sandcastle.

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:catherine',
    relation: 'legacy_admin',
    object: 'workspace:sandcastle',
  }, {
  authorization_model_id: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = false

Repeat this process for the other relationships

[
  {
    // Bob is a Channels Admin in the Sandcastle workspace
    user: 'user:bob',
    relation: 'channels_admin',
    object: 'workspace:sandcastle',
  },
  {
    // David is a guest in the Sandcastle workspace
    user: 'user:david',
    relation: 'guest',
    object: 'workspace:sandcastle',
  },
  {
    // Emily is a Member in the Sandcastle workspace
    user: 'user:emily',
    relation: 'member',
    object: 'workspace:sandcastle',
  },
]
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
});

await fgaClient.write({
  writes: [
      // Bob is a Channels Admin in the Sandcastle workspace
      {"_description":"Bob is a Channels Admin in the Sandcastle workspace","user":"user:bob","relation":"channels_admin","object":"workspace:sandcastle"},
      // David is a guest in the Sandcastle workspace
      {"_description":"David is a guest in the Sandcastle workspace","user":"user:david","relation":"guest","object":"workspace:sandcastle"},
      // Emily is a Member in the Sandcastle workspace
      {"_description":"Emily is a Member in the Sandcastle workspace","user":"user:emily","relation":"member","object":"workspace:sandcastle"}
  ],
}, {
  authorization_model_id: "01HVMMBCMGZNT3SED4Z17ECXCA" 
});

Verification​

To verify, we can issue check request to verify it is working as expected.

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:amy',
    relation: 'legacy_admin',
    object: 'workspace:sandcastle',
  }, {
  authorization_model_id: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Let's try to verify the followings:

UserObjectRelationQueryRelation?
amyworkspace:sandcastlelegacy_adminis amy related to workspace:sandcastle as legacy_admin?Yes
davidworkspace:sandcastlelegacy_adminis david related to workspace:sandcastle as legacy_admin?No
amyworkspace:sandcastleguestis amy related to workspace:sandcastle as guest?No
davidworkspace:sandcastleguestis david related to workspace:sandcastle as guest?Yes
amyworkspace:sandcastlememberis amy related to workspace:sandcastle as member?No
davidworkspace:sandcastlememberis david related to workspace:sandcastle as member?No

02. Updating The workspace Authorization Model With Implied Relations​

Some of the queries that you ran earlier, while returning the correct response, do not match reality. One of which is:

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:amy',
    relation: 'member',
    object: 'workspace:sandcastle',
  }, {
  authorization_model_id: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = false

As you saw before, running this query will return amy is not a member of workspace:sandcastle, which is correct based on the data you have given OpenFGA so far. But in reality, Amy, who is a legacy_admin already has an implied channels_admin and member relations. In fact anyone (other than a guest) is a member of the workspace.

To change this behavior, we will update our system with a concentric relationship model.

With the following updated authorization model, you are informing OpenFGA that any user who is related to a workspace as legacy_admin, is also related as a channels_admin and a member .

model
  schema 1.1

type user

type workspace
  relations
    define legacy_admin: [user]
    define channels_admin: [user] or legacy_admin
    define member: [user] or channels_admin or legacy_admin
    define guest: [user]

We can then verify amy is a member of workspace:sandcastle.

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:amy',
    relation: 'member',
    object: 'workspace:sandcastle',
  }, {
  authorization_model_id: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

We can check for other users and relationships.

UserObjectRelationQueryRelation?
amyworkspace:sandcastlelegacy_adminis amy related to workspace:sandcastle as legacy_admin?Yes
davidworkspace:sandcastlelegacy_adminis david related to workspace:sandcastle as legacy_admin?No
amyworkspace:sandcastleguestis amy related to workspace:sandcastle as guest?No
davidworkspace:sandcastleguestis david related to workspace:sandcastle as guest?Yes
amyworkspace:sandcastlememberis amy related to workspace:sandcastle as member?Yes
davidworkspace:sandcastlememberis david related to workspace:sandcastle as member?No

03. Updating the authorization model to include channels​

So far, you have modeled the users' relations to the workspace itself. In this task you will expand the model to include the relations concerning the channels.

By the end of it, you will run some queries to check whether a user can view or write to a certain channel. Queries such as:

  • is david related to channel:general as viewer? (expected answer: No relation, as David is a guest user with only a relation to #proj-marketing-campaign)
  • is david related to channel:proj_marketing_campaign as viewer? (expected answer: There is a relation, as there is a relation between David and #proj-marketing-campaign as a writer)
  • is bob related to channel:general as viewer? (expected answer: There is a relation, as Bob is a member of the Sandcastle workspace, and all members of the workspace have a viewer relation to #general)

The requirements are:

  • Amy, Bob, Catherine and Emily, are normal members of the Sandcastle workspace, they can view all public channels, in this case: #general and #proj-marketing-campaign
  • David, a guest user, has only view and write access to the #proj-marketing-campaign channel
  • Bob and Emily are the only ones with either view or write access to the #marketing-internal channel
  • Amy and Emily are the only ones with write access to the #general channel

The possible relations to channels are:

  • Workspace includes the channel, consider the relation that of a parent workspace
  • A user can be a viewer and/or writer on a channel

The authorization model already has a section describing the workspace, what remains is describing the channel. That can be done by adding the following section to the configuration above:


type channel
  relations
    define parent_workspace: [workspace]
    define writer: [user, workspace#legacy_admin, workspace#channels_admin, workspace#member, workspace#guest]
    define viewer: [user, workspace#legacy_admin, workspace#channels_admin, workspace#member, workspace#guest]
info

The configuration snippet above describes a channel that can have the following relations:

  • workspaces related to it as parent_workspace
  • users related to it as writer
  • users related to it as viewer

Implied relation​

There is an implied relation that anyone who can write to a channel can also read from it, so the authorization model can be modified to be:


type channel
  relations
    define parent_workspace: [workspace]
    define writer: [user, workspace#legacy_admin, workspace#channels_admin, workspace#member, workspace#guest]
    define viewer: [user, workspace#legacy_admin, workspace#channels_admin, workspace#member, workspace#guest] or writer
info

Note that the channel type definition has been updated to indicate that viewer is the union of:

  • the set of users with a direct viewer relation to this object
  • the set of users with writer relations to this object

As a result, the authorization model is:

model
  schema 1.1

type user

type workspace
  relations
    define legacy_admin: [user]
    define channels_admin: [user] or legacy_admin
    define member: [user] or channels_admin or legacy_admin
    define guest: [user]

type channel
  relations
    define parent_workspace: [workspace]
    define writer: [user, workspace#legacy_admin, workspace#channels_admin, workspace#member, workspace#guest]
    define viewer: [user, workspace#legacy_admin, workspace#channels_admin, workspace#member, workspace#guest] or writer