Skip to main content

Direct Relationships

note
Fine Grained Authorization (FGA) is the early-stage product we are building at Okta to solve fine-grained authorization at scale. Sign up for the Developer Community Preview to try it out, and join our Discord community if you are interested in learning more about our plans.

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 Okta FGA during the Developer Community Preview can be found here.

In this guide you'll learn how to model relationships that may or may not be assigned directly to individual users.

When to use

Disabling direct relationships for a certain relation on an objects are useful especially in cases where you are trying to model some permissions that are not usually granted individually to a user.

This is useful when:

  • For security reason, not permitting permissions assigned directly to individuals without associating roles

Before You Start​

To better understand this guide, you should be familiar with some Okta FGA Concepts and know how to develop the things listed below.

You will need to know the following:

  • Direct Access
  • Okta FGA Concepts

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 →

Okta FGA 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: is 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 define through relationship tuples and the authorization model
  • A Relationship Tuple: a grouping consisting of a user, a relation and an object stored in Okta FGA
  • Direct Relationship Type Restrictions: used in the context of the relation definition can be used to allow direct relationships to the objects of this type

The Playground

Try this guide out on the Okta FGA Playground

What Are Direct Relationships?​

Direct relationships are relationships where a user has a relationship to an object that is not dependent on any other relationship they have with that object.

When checking for a relationship, a direct relationship exists if a relationship tuple is present in the system with the exact same object and relation that were in the query and where the user is one of:

  • the same user ID as that in the query
  • type bound public access (<type>:*)
  • a set of users that contains the user ID present in the query

Enable Or Disable Direct Relationships​

Direct relationships can be enabled for a specific relation on an object type by adding direct relationship type restrictions from that relation's definition. Likewise, they can be disabled by removing the direct relationship type restrictions.

model
  schema 1.1

type user

type document
  relations
    define viewer: [user, user:*, team#member] or editor
    define editor: [user, team#member]

type team
  relations
    define member: [user]
info

The authorization model describes two object types: document and team.

The document type definition has two relations, editor and viewer. Both relations allow a direct relationship; viewer also allows an indirect relationship through editor.

In the team type definition, there is a single member relation that only allows direct relationships.

How It Affects Your System​

To illustrate the effect enabling or disabling direct relationships on a specific relation has, we'll investigate several situations.

1. With Direct Relationships Enabled​

Let us start with the authorization model we had above:

model
  schema 1.1

type user

type document
  relations
    define viewer: [user, user:*, team#member] or editor
    define editor: [user, team#member]

type team
  relations
    define member: [user]

Now choose the type of relation to see how it affects your system:

Assume you have a tuple that states that Anne is a viewer of document:planning

[
  {
    "user": "user:anne",
    "relation": "viewer",
    "object": "document:planning",
  },
]

Now if we do a check request to see if Anne can view the planning document, we will get a response of {"allowed": true}.

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_SCHEME = 'https'
// FGA_API_HOST = 'api.us1.fga.dev' for Dev Preview and Early Access / '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 = 'fga.us.auth0.com' 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

const fgaClient = new OpenFgaClient({
    apiScheme: process.env.FGA_API_SCHEME,
    apiHost: process.env.FGA_API_HOST,
    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: 'viewer',
    object: 'document:planning',
}, {
  authorization_model_id: '1uHxCSuTP0VKPYSnkq1pbb1jeZw',
});

// allowed = true

This is because:

  • There is a relationship tuple specifying that Anne has a viewer relationship with document:planning.
  • Direct relationships are allowed in the viewer relation definition in the document type definition.

2. With Direct Relationships Disabled​

In this section, we will investigate the effect of disabling direct relationships on the document's viewer relation.

model
  schema 1.1

type user

type document
  relations
    define viewer: editor
    define editor: [user, team#member]

type team
  relations
    define member: [user]
info

Notice that in this updated authorization model, the direct relationship keyword has been removed from the document's viewer relation definition.

Now choose the type of relation to see how it affects your system:

Assume you have a tuple that states that Fred is a viewer of document:planning

[
  {
    "user": "user:fred",
    "relation": "viewer",
    "object": "document:planning",
  },
]

Now if we do a check request to see if Fred can view the planning document, we will get a response of {"allowed": false}.

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_SCHEME = 'https'
// FGA_API_HOST = 'api.us1.fga.dev' for Dev Preview and Early Access / '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 = 'fga.us.auth0.com' 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

const fgaClient = new OpenFgaClient({
    apiScheme: process.env.FGA_API_SCHEME,
    apiHost: process.env.FGA_API_HOST,
    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:fred',
    relation: 'viewer',
    object: 'document:planning',
}, {
  authorization_model_id: '1uHxCSuTP0VKPYSnkq1pbb1jeZw',
});

// allowed = false

This is because:

  • Even though there is a relationship tuple specifying that Fred has a viewer relationship with document:planning.
  • Direct relationships are NOT allowed in the viewer relation definition in the document type definition.