Migrating Relations

In the lifecycle of software development, you will need to make updates or changes to the authorization model. In this guide, you will learn best practices for changing your existing authorization model. With these recommendations, you will minimize downtime and ensure your relationship models stay up to date.

Before you start

This guide assumes you are familiar with the following 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: 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 defined through relationship tuples and the authorization model
A Relationship Tuple: a grouping consisting of a user, a relation and an object stored in OpenFGA
Intersection Operator: the intersection operator can be used to indicate a relationship exists if the user is in all the sets of users

Step by step

The document below is an example of a relational authorization model. In this model, you can assign users to the editor relation. The editor relation has write privileges that regular users do not. In this scenario, you will migrate the following model: There are existing relationship tuples associated with editor relation.

[
  {
    "user": "user:anne",
    "relation": "editor",
    "object": "document:roadmap"
  },
  {
    "user": "user:charles",
    "relation": "editor",
    "object": "document:roadmap"
  }
]

This is the authorization model that you will want to migrate to:

01. Create a backwards compatible model

To avoid service disruption, you will create a backwards compatible model. The backwards compatible model ensures the existing relationship tuple will still work. In the example below, user:Anne still has write privileges to the document:roadmap resource. Test the can_edit definition. It should produce a value of true.

02. Create a new relationship tuple

Now that you have a backwards compatible model, you can create new relationship tuples with a new relation. In this example, you will add Bethany to the writer relationship. Run a check in the API for Bethany to ensure correct access.

03. Migrate the existing relationship tuples

Next, migrate the existing relationship tuples. The new relation makes this definition obsolete. Use the read API to look up all relationship tuples.

Initialize the SDK for Read

Set FGA_API_URL for your service (for example, https://api.fga.example) and FGA_STORE_ID for your store. Use the Read SDK initialization examples, then place this request in the same scope as the client. For Python, use the async with block; for Go, .NET, and Java, use the method that initializes the client. See SDK client setup for authentication options.

const { tuples } = await fgaClient.read({});

options := ClientReadOptions{}
body := ClientReadRequest{}
data, err := fgaClient.Read(context.Background()).
    Body(body).
    Options(options).
    Execute()

var options = new ClientReadOptions {};
var body = new ClientReadRequest {};
var response = await fgaClient.Read(body, options);

options = {}
body = ReadRequestTupleKey()
response = await fga_client.read(body, options)

var body = new ClientReadRequest();
var response = fgaClient.read(body).get();

fga tuple read --store-id=${FGA_STORE_ID}

# Remove Authorization if your service does not require it.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/read" \
  -H "Authorization: Bearer $FGA_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{}'

read();

Response

{
  "tuples": [
    {
      "key": {
        "user": "user:anne",
        "relation": "editor",
        "object": "document:planning"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    },
    {
      "key": {
        "user": "user:charles",
        "relation": "editor",
        "object": "document:planning"
      },
      "timestamp": "2021-10-06T15:32:11.128Z"
    }
  ]
}

Then filter out the tuples that do not match the object type or relation (in this case, document and editor respectively), and update the new tuples with the write relationship. Finally, remove the old relationship tuples.

Perform a write operation before a delete operation to ensure Anne still has access.

Confirm the tuples are correct by running a check on the user. The old relationship tuple no longer exists.

04. Remove obsolete relationship from the model

After you remove the previous relationship tuples, update your authorization model to remove the obsolete relation. Now, the write API will only accept the new relation name. Review the following sections for more information on managing relationship tuples.

Relationship Queries

Understand the differences between check, read, expand and list objects.

Production Best Practices

Learn the best practices of running OpenFGA in a production environment

Getting Started

Modeling Guides

Authorization for Agents

Interacting with the API

Best Practices

Industries

Use Cases

Adopters

Learn

Migrating Relations

Before you start

Step by step

01. Create a backwards compatible model

02. Create a new relationship tuple

03. Migrate the existing relationship tuples

04. Remove obsolete relationship from the model

Relationship Queries

Production Best Practices

​Before you start

​Step by step

​01. Create a backwards compatible model

​02. Create a new relationship tuple

​03. Migrate the existing relationship tuples

​04. Remove obsolete relationship from the model

​Related Sections

Relationship Queries

Production Best Practices

Before you start

Step by step

01. Create a backwards compatible model

02. Create a new relationship tuple

03. Migrate the existing relationship tuples

04. Remove obsolete relationship from the model

Related Sections