Permissions and Access Control Lists (ACL)

Overview

Permissions in Teamwork Graph API define who can view objects. The permissions system uses Access Control Lists (ACL) to specify granular access controls for different actions, supporting both Atlassian and third-party user scenarios.

Permission structure

Permissions are structured as an array of permission objects, each containing an action and access controls:

1
2
permissions: [
  {
    accessControls: [
      {
        principals: [
          { type: 'USER', id: 'user-123' },
          { type: 'GROUP', id: 'group-456' }
        ]
      }
    ]
  }
]

Principal types

Principal types are the kinds of people or groups that can be given permissions in an access control system. Teamwork Graph supports the following principle types:

User principal

An individual, identified by a user ID.

1
2
{
  type: 'USER',
  id: 'user-external-id' // Required: External ID of the user
}

Group principal

A collection of users, identified by a group ID.

1
2
{
  type: 'GROUP',
  id: 'group-external-id' // Required: External ID of the group
}

Atlassian workspace principal

Anyone who is part of a specific Atlassian workspace.

1
2
{
  type: 'ATLASSIAN_WORKSPACE'
  // No id required - grants access to anyone in the Atlassian workspace
}

Container principal

All users within an ACL of the container of the object. For example, for a Confluence document, this would be all users within an ACL for a Confluence space.

1
2
{
  type: 'CONTAINER'
  // No id required - grants access to all users within the container
}

User mapping

User mapping establishes a connection between an Atlassian (1P) user and a third-party (3P) user. This mapping is crucial when ingested objects must adhere to the same ACL patterns as defined in the third-party system.

User mapping methods

For Forge apps that don't support 3LO authentication.

1
2
import { graph } from '@forge/teamwork-graph';
const mappings = [
  {
    externalId: 'user-123',
    accountId: '5dd4fb8db3a9c80fc0a3283b',
    updateSequenceNumber: 1,
    updatedAt: Date.now()
  },
  {
    externalId: 'user-456',
    externalEmailAddress: 'tagapitos@my-company.com',
    updateSequenceNumber: 2,
    updatedAt: Date.now()
  }
];
const response = await graph.mapUsers({
  directMappings: mappings
});

Understanding ACL and permission checks

When an object is ingested into Teamwork Graph, it includes an Access Control List (ACL) that defines who is permitted to access it. Permission checks are conducted via -

Access control logic

AND/OR logic

• Between access controls: AND relationship
• Within access controls: OR relationship

1
2
permissions: [
  {
    accessControls: [
      // Access Control 1: (User A OR User B) AND (Group C OR Group D)
      {
        principals: [
          { type: 'USER', id: 'user-a' },
          { type: 'USER', id: 'user-b' }
        ]
      },
      {
        principals: [
          { type: 'GROUP', id: 'group-c' },
          { type: 'GROUP', id: 'group-d' }
        ]
      }
    ]
  }
]

In this example, a user must be either User A OR User B, AND also be in either Group C OR Group D.

Common permission patterns

Atlassian workspace access

1
2
permissions: [
  {
    accessControls: [
      {
        principals: [
          { type: 'ATLASSIAN_WORKSPACE' }
        ]
      }
    ]
  }
]

Specific user access

1
2
permissions: [
  {
    accessControls: [
      {
        principals: [
          { type: 'USER', id: 'external-user-123' }
        ]
      }
    ]
  }
]

Group-based access

1
2
permissions: [
  {
    accessControls: [
      {
        principals: [
          { type: 'GROUP', id: 'external-group-456' }
        ]
      }
    ]
  }
]

Complete entity example

1
2
import { types } from '@forge/teamwork-graph';
const document: types.DocumentEntity = {
  schemaVersion: '2.0',
  id: 'api-documentation',
  updateSequenceNumber: 123,
  displayName: 'API Documentation',
  description: 'Complete API reference for the platform',
  url: '<https://docs.example.com/api',>
  createdAt: '2024-01-15T10:00:00Z',
  lastUpdatedAt: '2024-01-20T14:30:00Z',
  permissions: [
    {
      accessControls: [
        {
          principals: [
            { type: 'GROUP', id: 'engineering-team' },
            { type: 'GROUP', id: 'qa-team' }
          ]
        }
      ]
    }
  ],
  'atlassian:document': {
    type: { category: 'document' },
    content: { mimeType: 'text/plain', text: 'API documentation content...' }
  }
};

Glossary

• ACL (Access Control List): List of principals who can access a resource.
• 3LO (Three-Legged OAuth): OAuth flow involving user consent.
• Principal: An entity (user, group, etc.) that can be granted permissions.
• User Mapping: Connection between Atlassian and third-party user identities.