Relations

A relation consists of three elements:

• An object
• A relation type
• A subject

If we think of directory objects as vertices in a graph, a relation can be thought of as a labeled, directed edge from an object to a subject.

A relation can therefore be seen as a (object, type, subject) triplet that defines the graph edge object --type--> subject.

Each relation type specifies the type of object on which it can occur. In this tutorial, we created a department object type with viewer, member, and owner relation types. We can add a user as a member of a department by creating a relation of type member between the department object and the user (i.e. department --member--> user).

Finding Users

Before we create relations between our departments and users, let's find our users in the directory.

If you haven't added the demo Citadel identity provider to your Aserto account, please follow step 2 of this guide's prererquisites now. It will populate your directory with a handful of demo users.

We'll use the objects query to find objects of type user:

Query

query ListUsers {
  objects(first: 10, where: {type: {name: {equals: "user"}}}) {
    nodes {
      key
      displayName
    }
  }
}

Results

{
  "data": {
    "objects": {
      "nodes": [
        {
          "key": "fd0614d3-c39a-4781-b7bd-8b96f5a5100d",
          "displayName": "Rick Sanchez"
        },
        {
          "key": "fd1614d3-c39a-4781-b7bd-8b96f5a5100d",
          "displayName": "Morty Smith"
        },
        {
          "key": "fd2614d3-c39a-4781-b7bd-8b96f5a5100d",
          "displayName": "Summer Smith"
        },
        {
          "key": "fd3614d3-c39a-4781-b7bd-8b96f5a5100d",
          "displayName": "Beth Smith"
        },
        {
          "key": "fd4614d3-c39a-4781-b7bd-8b96f5a5100d",
          "displayName": "Jerry Smith"
        }
      ]
    }
  }
}

Creating Relations

We'll start by making Rick an owner of all three departments. The following request creates all three of Rick's owner relations:

Query

mutation CreateRickOwnerRelations {
  spaceships: setRelation(relation: {
    object: {key: "spaceships", type: "department"}
    relationType: {name: "owner", objectType: "department"}
    subject: {key: "fd0614d3-c39a-4781-b7bd-8b96f5a5100d", type: "user"}
  }) {
    relation {
      object {
        displayName
        type {
          name
        }
      }
      type {
        displayName
      }
      subject {
        displayName
        type {
          name
        }
      }
    }
  }

  teleporters: setRelation(relation: {
    object: {key: "teleporters", type: "department"}
    relationType: {name: "owner", objectType: "department"}
    subject: {key: "fd0614d3-c39a-4781-b7bd-8b96f5a5100d", type: "user"}
  }) {
    relation {
      object {
        displayName
        type {
          name
        }
      }
      type {
        displayName
      }
      subject {
        displayName
        type {
          name
        }
      }
    }
  }

  lasers: setRelation(relation: {
    object: {key: "lasers", type: "department"}
    relationType: {name: "owner", objectType: "department"}
    subject: {key: "fd0614d3-c39a-4781-b7bd-8b96f5a5100d", type: "user"}
  }) {
    relation {
      object {
        displayName
        type {
          name
        }
      }
      type {
        displayName
      }
      subject {
        displayName
        type {
          name
        }
      }
    }
  }
}

Results

{
  "data": {
    "spaceships": {
      "relation": {
        "object": {
          "displayName": "Spaceships",
          "type": {
            "name": "department"
          }
        },
        "type": {
          "displayName": "department:owner"
        },
        "subject": {
          "displayName": "Rick Sanchez",
          "type": {
            "name": "user"
          }
        }
      }
    },
    "teleporters": {
      "relation": {
        "object": {
          "displayName": "Teleporters",
          "type": {
            "name": "department"
          }
        },
        "type": {
          "displayName": "department:owner"
        },
        "subject": {
          "displayName": "Rick Sanchez",
          "type": {
            "name": "user"
          }
        }
      }
    },
    "lasers": {
      "relation": {
        "object": {
          "displayName": "Lasers",
          "type": {
            "name": "department"
          }
        },
        "type": {
          "displayName": "department:owner"
        },
        "subject": {
          "displayName": "Rick Sanchez",
          "type": {
            "name": "user"
          }
        }
      }
    }
  }
}

In the same way we can assign other users to roles in different departments by creating relations of the desired type.

Listing Object Relations

We can verify that Rick has the new relations to the correct departments by inspecting his user object and selecting the relations in which it appears as the subject and the object is of type department.

Query

query RicksRelations {
  object(key: "fd0614d3-c39a-4781-b7bd-8b96f5a5100d", type: "user") {
    displayName
    relations(
      side: SUBJECT,
      options: {otherType: "department"},
      first: 3
    ) {
      nodes {
        type {
          displayName
        }
        object {
          type {
            displayName
          }
          displayName
        }
      }
    }
  }
}

Results

{
  "data": {
    "object": {
      "displayName": "Rick Sanchez",
      "relations": {
        "nodes": [
          {
            "type": {
              "displayName": "department:owner"
            },
            "object": {
              "type": {
                "displayName": "Department"
              },
              "displayName": "Teleporters"
            }
          },
          {
            "type": {
              "displayName": "department:owner"
            },
            "object": {
              "type": {
                "displayName": "Department"
              },
              "displayName": "Lasers"
            }
          },
          {
            "type": {
              "displayName": "department:owner"
            },
            "object": {
              "type": {
                "displayName": "Department"
              },
              "displayName": "Spaceships"
            }
          }
        ]
      }
    }
  }
}