Modeling Custom Roles
note
Please note that at this point in time, it is not considered production-ready and does not come with any SLAs; availability and uptime are not guaranteed. Limitations of Auth0 FGA during the Developer Community Preview can be found here.
In this guide you'll learn how to model custom roles in your system using Auth0 FGA.
For example, a Business-to-Business (B2B) application could allow customers to create their own custom roles on the application to grant their users.
In many cases, roles would fit in well as relations on an object type, as seen in Modeling Roles and Permissions. In some cases, however, they may not be enough.
Custom roles are useful when:
- Users of the application are able to create arbitrary sets of roles with different permissions that govern the users' access to objects.
- It is not known beforehand (at the time of Authorization Model creation) what the application roles are.
- The team responsible for building the authorization model is different from the teams responsible for defining roles and access to the application.
Before you start
Before you start this guide, make sure you're familiar with some Auth0 FGA Concepts and know how to develop the things listed below.
Initial Model
To start, let's say there is an application with a type called asset-category
. Users can have view and/or edit access to assets in that category. Any user who can edit can also view.
asset-category
. Users can have view and/or edit access to assets in that category. Any user who can edit can also view.We'll start with the following authorization model showing a system with an asset-category
type. This type allows users to have view and edit access to it.
- DSL
- JSON
type asset-category
relations
define viewer as self or editor
define editor as self
{
"type_definitions": [
{
"type": "asset-category",
"relations": {
"viewer": {
"union": {
"child": [
{
"this": {}
},
{
"computedUserset": {
"relation": "editor"
}
}
]
}
},
"editor": {
"this": {}
}
}
}
]
}
In addition, you'll need to know the following:
Modeling Roles and Permissions
You need to know how to add users to groups and grant groups access to resources. Learn more →
Modeling Object-to-Object Relationships
You need to know how to create relationships between objects and how that might affect a user's relationships to those objects. Learn more →
Concepts & Configuration Language
Step by Step
Starting with the authorization model mentioned above, we want to enable users to create their own custom roles, and tie permissions to those roles to our two users and to the permissions on the logo asset category.
For this guide, we'll model a scenario where a certain organization using our app has created an asset-category
called "logos", and another called "text content".
The company administrator would like to create:
- a media-manager role that allows users to edit assets in the logos asset category
- a media-viewer role that allows users to view all assets in the logos asset category
- a blog-editor role that allows users to edit all assets in the text content asset category
- a blog-viewer role that allows users to view all assets in the text content asset category
Imagine these are what the permissions the roles in one organization using our service are like:
Finally, the administrator wants to assign Anne the media-manager role and Beth the media-viewer role.
At the end, we'll verify our model by ensuring the following access check requests return the expected result.
In order to do this, we need to:
- Update the Authorization Model to add a Role Type
- Use Relationship Tuples to tie the Users to the Roles
- Use Relationship Tuples to associate Permissions with the Roles
- Verify that the Authorization Model works
01. Update the authorization model to add a role type
Because our roles are going to be dynamic and might change frequently, we represent them in a new type instead of as relations on that same type. We'll create new type called role
, where users can be related as assignee to it.
The authorization model becomes this:
- DSL
- JSON
type asset-category
relations
define viewer as self or editor
define editor as self
type role
relations
define assignee as self
{
"type_definitions": [
{
"type": "asset-category",
"relations": {
"viewer": {
"union": {
"child": [
{
"this": {}
},
{
"computedUserset": {
"relation": "editor"
}
}
]
}
},
"editor": {
"this": {}
}
}
},
{
"type": "role",
"relations": {
"assignee": {
"this": {}
}
}
}
]
}
With this change we can add relationship tuples indicating that a certain user is assigned
a certain role
.
02.Use Relationship Tuples to tie the Users to the Roles
Once we've added the role
type, we can assign roles to Anne and Beth. Anne is assigned the "media-manager" role and Beth is assigned the "media-viewer" role. We can do that by adding relationship tuples as follows:
- Node.js
- Go
- .NET
- curl
- Pseudocode
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
// import the SDK
const { Auth0FgaApi } = require('@auth0/fga');
// Initialize the SDK
const fgaClient = new Auth0FgaApi({
environment: process.env.FGA_ENVIRONMENT,
storeId: process.env.FGA_STORE_ID,
clientId: process.env.FGA_CLIENT_ID,
clientSecret: process.env.FGA_CLIENT_SECRET,
});
await fgaClient.write({
writes: {
tuple_keys: [
// Anne is assigned the media-manager role
{ user: 'anne', relation: 'assignee', object: 'role:media-manager'},
// Beth is assigned the media-viewer role
{ user: 'beth', relation: 'assignee', object: 'role:media-viewer'}
]
}
});
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
import (
fgaSdk "github.com/auth0-lab/fga-go-sdk"
"os"
)
func Main() {
configuration, err := fgaSdk.NewConfiguration(fgaSdk.UserConfiguration{
Environment: os.Getenv("FGA_ENVIRONMENT"),
StoreId: os.Getenv("FGA_STORE_ID"),
ClientId: os.Getenv("FGA_CLIENT_ID"),
ClientSecret: os.Getenv("FGA_CLIENT_SECRET"),
})
if err != nil {
// .. Handle error
}
fgaClient := fgaSdk.NewAPIClient(configuration)
}
body := fgaSdk.WriteRequestParams{
Writes: &fgaSdk.TupleKeys{
TupleKeys: []fgaSdk.TupleKey {
{
// Anne is assigned the media-manager role
User: fgaSdk.PtrString("anne"),
Relation: fgaSdk.PtrString("assignee"),
Object: fgaSdk.PtrString("role:media-manager"),
},
{
// Beth is assigned the media-viewer role
User: fgaSdk.PtrString("beth"),
Relation: fgaSdk.PtrString("assignee"),
Object: fgaSdk.PtrString("role:media-viewer"),
},
},
},
}
_, response, err := fgaClient.Auth0FgaApi.Write(context.Background()).Body(body).Execute()
if err != nil {
// .. Handle error
}
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
// import the SDK
using Auth0.Fga.Api;
using Auth0.Fga.Configuration;
using Environment = System.Environment;
namespace ExampleApp;
class MyProgram {
static async Task Main() {
var storeId = Environment.GetEnvironmentVariable("FGA_STORE_ID");
var environment = Environment.GetEnvironmentVariable("FGA_ENVIRONMENT")
var configuration = new Configuration(storeId, environment) {
ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
};
var fgaClient = new Auth0FgaApi(configuration);
}
}
await fgaClient.Write(new WriteRequestParams {
Writes = new TupleKeys(new List<TupleKey>() {
// Anne is assigned the media-manager role
new() { User = "anne", Relation = "assignee", Object = "role:media-manager" },
// Beth is assigned the media-viewer role
new() { User = "beth", Relation = "assignee", Object = "role:media-viewer" }
})
});
Get the Bearer Token and set up the FGA_API_URL environment variable
# Not needed when calling the Playground API
curl -X POST \
https://fga.us.auth0.com/oauth/token \
-H 'content-type: application/json' \
-d '{"client_id":"'$FGA_CLIENT_ID'","client_secret":"'$FGA_CLIENT_SECRET'","audience":"https://api.us1.fga.dev/","grant_type":"client_credentials"}'
# The response will be returned in the form
# {
# "access_token": "eyJ...Ggg",
# "expires_in": 86400,
# "scope": "read:tuples write:tuples check:tuples ... write:authorization-models",
# "token_type": "Bearer"
# }
# Store this `access_token` value in environment variable `FGA_BEARER_TOKEN`
# For non-playground environment
FGA_API_URL='https://api.us1.fga.dev'
# For playground environment
# FGA_API_URL='https://api.playground.fga.dev'
curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/write \
-H "Authorization: Bearer $FGA_BEARER_TOKEN" \ # Not needed if service does not require authorization
-H "content-type: application/json" \
-d '{"writes": { "tuple_keys" : [{"user":"anne","relation":"assignee","object":"role:media-manager"},{"user":"beth","relation":"assignee","object":"role:media-viewer"}] }}'
write([
// Anne is assigned the media-manager role
{
"user":"anne",
"relation":"assignee",
"object":"role:media-manager"
},
// Beth is assigned the media-viewer role
{
"user":"beth",
"relation":"assignee",
"object":"role:media-viewer"
}
])
We can verify they are members of said roles by issuing the following check requests:
- Node.js
- Go
- .NET
- curl
- Pseudocode
- Playground
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
// import the SDK
const { Auth0FgaApi } = require('@auth0/fga');
// Initialize the SDK
const fgaClient = new Auth0FgaApi({
environment: process.env.FGA_ENVIRONMENT,
storeId: process.env.FGA_STORE_ID,
clientId: process.env.FGA_CLIENT_ID,
clientSecret: process.env.FGA_CLIENT_SECRET,
});
// Run a check
const { allowed } = await fgaClient.check({
tuple_key: {
user: 'anne',
relation: 'assignee',
object: 'role:media-manager',
},});
// allowed = true
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
import (
fgaSdk "github.com/auth0-lab/fga-go-sdk"
"os"
)
func Main() {
configuration, err := fgaSdk.NewConfiguration(fgaSdk.UserConfiguration{
Environment: os.Getenv("FGA_ENVIRONMENT"),
StoreId: os.Getenv("FGA_STORE_ID"),
ClientId: os.Getenv("FGA_CLIENT_ID"),
ClientSecret: os.Getenv("FGA_CLIENT_SECRET"),
})
if err != nil {
// .. Handle error
}
fgaClient := fgaSdk.NewAPIClient(configuration)
}
body := fgaSdk.CheckRequestParams{
TupleKey: &fgaSdk.TupleKey{
User: fgaSdk.PtrString("anne"),
Relation: fgaSdk.PtrString("assignee"),
Object: fgaSdk.PtrString("role:media-manager"),
},
data, response, err := fgaClient.Auth0FgaApi.Check(context.Background()).Body(body).Execute()
// data = { allowed: true }
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
// import the SDK
using Auth0.Fga.Api;
using Auth0.Fga.Configuration;
using Environment = System.Environment;
namespace ExampleApp;
class MyProgram {
static async Task Main() {
var storeId = Environment.GetEnvironmentVariable("FGA_STORE_ID");
var environment = Environment.GetEnvironmentVariable("FGA_ENVIRONMENT")
var configuration = new Configuration(storeId, environment) {
ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
};
var fgaClient = new Auth0FgaApi(configuration);
}
}
// Run a check
var response = await fgaClient.Check(new CheckRequestParams(new TupleKey {
User = "anne",
Relation = "assignee",
Object = "role:media-manager"
});
// response.Allowed = true
Get the Bearer Token and set up the FGA_API_URL environment variable
# Not needed when calling the Playground API
curl -X POST \
https://fga.us.auth0.com/oauth/token \
-H 'content-type: application/json' \
-d '{"client_id":"'$FGA_CLIENT_ID'","client_secret":"'$FGA_CLIENT_SECRET'","audience":"https://api.us1.fga.dev/","grant_type":"client_credentials"}'
# The response will be returned in the form
# {
# "access_token": "eyJ...Ggg",
# "expires_in": 86400,
# "scope": "read:tuples write:tuples check:tuples ... write:authorization-models",
# "token_type": "Bearer"
# }
# Store this `access_token` value in environment variable `FGA_BEARER_TOKEN`
# For non-playground environment
FGA_API_URL='https://api.us1.fga.dev'
# For playground environment
# FGA_API_URL='https://api.playground.fga.dev'
curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/check \
-H "Authorization: Bearer $FGA_BEARER_TOKEN" \ # Not needed if service does not require authorization
-H "content-type: application/json" \
-d '{"tuple_key":{"user":"anne","relation":"assignee","object":"role:media-manager"}}'
# Response: {"allowed":true}
check(
"anne", // check if the user `anne`
"assignee", // has an `assignee` relation
"role:media-manager", // with the object `role:media-manager`
);
Reply: true
is anne related to role:media-manager as assignee?
# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`
03. Use Relationship Tuples to associate Permissions with the Roles
With our users and roles set up, we still need to tie members of a certain role to it's corresponding permission(s).
- Node.js
- Go
- .NET
- curl
- Pseudocode
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
// import the SDK
const { Auth0FgaApi } = require('@auth0/fga');
// Initialize the SDK
const fgaClient = new Auth0FgaApi({
environment: process.env.FGA_ENVIRONMENT,
storeId: process.env.FGA_STORE_ID,
clientId: process.env.FGA_CLIENT_ID,
clientSecret: process.env.FGA_CLIENT_SECRET,
});
await fgaClient.write({
writes: {
tuple_keys: [
// Users assigned the media-manager role can edit in the Logos assets category
{ user: 'role:media-manager#assignee', relation: 'editor', object: 'asset-category:logos'},
// Users assigned the media-viewer role can view from the Logos assets category
{ user: 'role:media-viewer#assignee', relation: 'viewer', object: 'asset-category:logos'}
]
}
});
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
import (
fgaSdk "github.com/auth0-lab/fga-go-sdk"
"os"
)
func Main() {
configuration, err := fgaSdk.NewConfiguration(fgaSdk.UserConfiguration{
Environment: os.Getenv("FGA_ENVIRONMENT"),
StoreId: os.Getenv("FGA_STORE_ID"),
ClientId: os.Getenv("FGA_CLIENT_ID"),
ClientSecret: os.Getenv("FGA_CLIENT_SECRET"),
})
if err != nil {
// .. Handle error
}
fgaClient := fgaSdk.NewAPIClient(configuration)
}
body := fgaSdk.WriteRequestParams{
Writes: &fgaSdk.TupleKeys{
TupleKeys: []fgaSdk.TupleKey {
{
// Users assigned the media-manager role can edit in the Logos assets category
User: fgaSdk.PtrString("role:media-manager#assignee"),
Relation: fgaSdk.PtrString("editor"),
Object: fgaSdk.PtrString("asset-category:logos"),
},
{
// Users assigned the media-viewer role can view from the Logos assets category
User: fgaSdk.PtrString("role:media-viewer#assignee"),
Relation: fgaSdk.PtrString("viewer"),
Object: fgaSdk.PtrString("asset-category:logos"),
},
},
},
}
_, response, err := fgaClient.Auth0FgaApi.Write(context.Background()).Body(body).Execute()
if err != nil {
// .. Handle error
}
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
// import the SDK
using Auth0.Fga.Api;
using Auth0.Fga.Configuration;
using Environment = System.Environment;
namespace ExampleApp;
class MyProgram {
static async Task Main() {
var storeId = Environment.GetEnvironmentVariable("FGA_STORE_ID");
var environment = Environment.GetEnvironmentVariable("FGA_ENVIRONMENT")
var configuration = new Configuration(storeId, environment) {
ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
};
var fgaClient = new Auth0FgaApi(configuration);
}
}
await fgaClient.Write(new WriteRequestParams {
Writes = new TupleKeys(new List<TupleKey>() {
// Users assigned the media-manager role can edit in the Logos assets category
new() { User = "role:media-manager#assignee", Relation = "editor", Object = "asset-category:logos" },
// Users assigned the media-viewer role can view from the Logos assets category
new() { User = "role:media-viewer#assignee", Relation = "viewer", Object = "asset-category:logos" }
})
});
Get the Bearer Token and set up the FGA_API_URL environment variable
# Not needed when calling the Playground API
curl -X POST \
https://fga.us.auth0.com/oauth/token \
-H 'content-type: application/json' \
-d '{"client_id":"'$FGA_CLIENT_ID'","client_secret":"'$FGA_CLIENT_SECRET'","audience":"https://api.us1.fga.dev/","grant_type":"client_credentials"}'
# The response will be returned in the form
# {
# "access_token": "eyJ...Ggg",
# "expires_in": 86400,
# "scope": "read:tuples write:tuples check:tuples ... write:authorization-models",
# "token_type": "Bearer"
# }
# Store this `access_token` value in environment variable `FGA_BEARER_TOKEN`
# For non-playground environment
FGA_API_URL='https://api.us1.fga.dev'
# For playground environment
# FGA_API_URL='https://api.playground.fga.dev'
curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/write \
-H "Authorization: Bearer $FGA_BEARER_TOKEN" \ # Not needed if service does not require authorization
-H "content-type: application/json" \
-d '{"writes": { "tuple_keys" : [{"user":"role:media-manager#assignee","relation":"editor","object":"asset-category:logos"},{"user":"role:media-viewer#assignee","relation":"viewer","object":"asset-category:logos"}] }}'
write([
// Users assigned the media-manager role can edit in the Logos assets category
{
"user":"role:media-manager#assignee",
"relation":"editor",
"object":"asset-category:logos"
},
// Users assigned the media-viewer role can view from the Logos assets category
{
"user":"role:media-viewer#assignee",
"relation":"viewer",
"object":"asset-category:logos"
}
])
04. Verify that the Authorization Model works
To ensure our model works, it needs to match our expectations:
- Node.js
- Go
- .NET
- curl
- Pseudocode
- Playground
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
// import the SDK
const { Auth0FgaApi } = require('@auth0/fga');
// Initialize the SDK
const fgaClient = new Auth0FgaApi({
environment: process.env.FGA_ENVIRONMENT,
storeId: process.env.FGA_STORE_ID,
clientId: process.env.FGA_CLIENT_ID,
clientSecret: process.env.FGA_CLIENT_SECRET,
});
// Run a check
const { allowed } = await fgaClient.check({
tuple_key: {
user: 'anne',
relation: 'editor',
object: 'asset-category:logos',
},});
// allowed = true
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
import (
fgaSdk "github.com/auth0-lab/fga-go-sdk"
"os"
)
func Main() {
configuration, err := fgaSdk.NewConfiguration(fgaSdk.UserConfiguration{
Environment: os.Getenv("FGA_ENVIRONMENT"),
StoreId: os.Getenv("FGA_STORE_ID"),
ClientId: os.Getenv("FGA_CLIENT_ID"),
ClientSecret: os.Getenv("FGA_CLIENT_SECRET"),
})
if err != nil {
// .. Handle error
}
fgaClient := fgaSdk.NewAPIClient(configuration)
}
body := fgaSdk.CheckRequestParams{
TupleKey: &fgaSdk.TupleKey{
User: fgaSdk.PtrString("anne"),
Relation: fgaSdk.PtrString("editor"),
Object: fgaSdk.PtrString("asset-category:logos"),
},
data, response, err := fgaClient.Auth0FgaApi.Check(context.Background()).Body(body).Execute()
// data = { allowed: true }
Initialize the SDK
// FGA_ENVIRONMENT can be "us" (default if not set) for Developer Community Preview or "playground" for the Playground API
// import the SDK
using Auth0.Fga.Api;
using Auth0.Fga.Configuration;
using Environment = System.Environment;
namespace ExampleApp;
class MyProgram {
static async Task Main() {
var storeId = Environment.GetEnvironmentVariable("FGA_STORE_ID");
var environment = Environment.GetEnvironmentVariable("FGA_ENVIRONMENT")
var configuration = new Configuration(storeId, environment) {
ClientId = Environment.GetEnvironmentVariable("FGA_CLIENT_ID"),
ClientSecret = Environment.GetEnvironmentVariable("FGA_CLIENT_SECRET"),
};
var fgaClient = new Auth0FgaApi(configuration);
}
}
// Run a check
var response = await fgaClient.Check(new CheckRequestParams(new TupleKey {
User = "anne",
Relation = "editor",
Object = "asset-category:logos"
});
// response.Allowed = true
Get the Bearer Token and set up the FGA_API_URL environment variable
# Not needed when calling the Playground API
curl -X POST \
https://fga.us.auth0.com/oauth/token \
-H 'content-type: application/json' \
-d '{"client_id":"'$FGA_CLIENT_ID'","client_secret":"'$FGA_CLIENT_SECRET'","audience":"https://api.us1.fga.dev/","grant_type":"client_credentials"}'
# The response will be returned in the form
# {
# "access_token": "eyJ...Ggg",
# "expires_in": 86400,
# "scope": "read:tuples write:tuples check:tuples ... write:authorization-models",
# "token_type": "Bearer"
# }
# Store this `access_token` value in environment variable `FGA_BEARER_TOKEN`
# For non-playground environment
FGA_API_URL='https://api.us1.fga.dev'
# For playground environment
# FGA_API_URL='https://api.playground.fga.dev'
curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/check \
-H "Authorization: Bearer $FGA_BEARER_TOKEN" \ # Not needed if service does not require authorization
-H "content-type: application/json" \
-d '{"tuple_key":{"user":"anne","relation":"editor","object":"asset-category:logos"}}'
# Response: {"allowed":true}
check(
"anne", // check if the user `anne`
"editor", // has an `editor` relation
"asset-category:logos", // with the object `asset-category:logos`
);
Reply: true
is anne related to asset-category:logos as editor?
# Response: A green path from the user to the object indicating that the response from the API is `{"allowed":true}`
The checks come back as we expect, so our model is working correctly.
Related Sections
Learn how to remove the direct relationship to indicate nonassignable permissions.
Learn about how to model object to object relationships in Auth0 FGA.