GitHub

Let's say, we want to use the Space Blocks Permissions module to manage permissions for a GitHub-like application. In GitHub, users can create repositories and invite other users to collaborate on them. The repository owner can invite other users to collaborate and assign them roles. The roles define the permissions, which the collaborator has for the repository.

According to the official GitHub Documentation on Repository roles for organizations, the following roles are available: Read, Triage, Write, Maintain and Admin.

For each role, the documentation lists the permissions for each role, which are granted to the user. We can see, that the different roles have different permissions for the different areas of a GitHub Repository. For example, the Read role has the permission to Open issues but is not allowed to Approve pull requests.

As users in GitHub can only be invited to a repository, we can assume, that the repository is the resource, which we want to manage permissions for. The permissions are defined for different areas of the repository, which we call resource types later. It is not possible to invite users just to the Issues or just to the Pull Requests of a repository. Therefore, we can assume that the permissions are non-hierarchical.

info

In Enterprise scenarios, GitHub permissions can become hierarchical, by inviting users to an organization and then to a repository. In this case, the organization would be the resource and the repository would be sub-resource. For simplicity, in this example, we assume that we can only add users to a repository.

Define the resources

First, we need to define the resource types, which we want to manage permissions for. In GitHub, each repository belongs to an organization. This would be our top-level resource, which is called Tenant in Space Blocks Permissions. Below the Tenant, Repositories exist. Each repository has Code, Issues and Pull Requests, that we want to manage permissions for.

Next, we should define the permissions, which we want to manage for each resource type. In GitHub lists the permissions for each role in their documentation. These include permissions like Create, Read, Branch etc. on Code level for example. For simplicity of this example, we will only define a few permissions for each resource type.

Let's create these resource types and their permissions in Space Blocks Permissions.

API

Create the Repository resource type.

curl -i --location "https://api.spaceblocks.cloud/public/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/permissions/config/resource-types" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"
  --data '{
    "name": "Repository",
    "id": "repository",
    "parentId: "tenant"
  }'

Add the permissions for the Repository resource type.

curl -i --location "https://api.spaceblocks.cloud/public/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/permissions/config/resource-types/invoice/permissions" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"
  --data '{
    "name": "Invite users",
    "id": "invite"
  }'

# Repeat this for the remaining permissions...

Repeat this for the other resource types.

Create the roles

Like in many applications, you don't assign permissions directly to users. Instead, use roles to define sets of permissions and assign them to users. In GitHub, the roles are called Read, Triage, Write, Maintain and Admin. They are described in detail in the GitHub Documentation on Repository roles for organizations.

View role

Triage role

Write role

Maintain role

Admin role

Let's create these roles in Space Blocks Permissions.

API

Create the View role.

curl -i --location "https://api.spaceblocks.cloud/public/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/permissions/config/roles" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"
  --data '{
    "name": "View",
    "permissions": {
      "repository": [ "view", "fork" ],
      "code": [ "view" ],
      "issues": [ "view", "open", "canBeAssigned" ],
      "pull-requests": [ "view", "open" ]
    }
  }'

Repeat this for the other roles.

Seed data

Now let's bring in some dummy data to play with.

API

Create a tenant called Space Blocks.

curl -i --location https://<YOUR_PERMISSIONS_API_URL>/management/tenant \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"
  --data '{
    "id": "spaceblocks",
    "name": "Space Blocks"
  }'

Create a repository in that tenant called permissions.

curl -i --location https://<YOUR_PERMISSIONS_API_URL>/management/tenants/spaceblocks/resources/repository \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"
  --data '{
    "id": "permissions",
    "name": "permissions"
  }'

Assign permissions

Invite users

Let's add some collaborators to the spaceblocks/permissions repository.

• User Alice should have the Maintain role.
• User Bob should have the Triage role.

API

curl -i --location https://<YOUR_PERMISSIONS_API_URL>/management/tenants/spaceblocks/resources/repository/permissions/members \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"
  --data '{
  "subjects": {
    "alice": "maintain",
    "bob": "triage",
    }
  }'

Invite groups

In GitHub, you can not only add user accounts as collaborators, but also groups. Let's create a group called Developers and add the user Alice to it. Then assign it to the spaceblocks/permissions repository with the View role.

API

Create the Developers group to the spaceblocks tenant and add the user Linda to it.

curl -i --location https://<YOUR_PERMISSIONS_API_URL>/management/tenants/spaceblocks/groups \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>" \
  --data '{
    "id": "developers",
    "name": "Developers",
    "subjects": [
      "Linda"
    ]
  }'

No assign the View role to the Developers group for the spaceblocks/permissions repository.

curl -i --location https://<YOUR_PERMISSIONS_API_URL>/management/tenants/spaceblocks/resources/repository/permissions/members \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"
  --data '{
  "groups": {
    "developers": "view"
    }
  }'

Perform permission checks

Let's check, who is allowed to Open issues in the spaceblocks/permissions repository.

Alice and Bob are allowed to open issues, because they have the Maintain and Triage roles.

API

Check Open permission on Issue level for Alice or Bob.

curl -i --location https://<YOUR_PERMISSIONS_API_URL>/management/tenants/spaceblocks/permissions/check?resourceType=repository&resourceId=permissions&permissionScope=issue&permission=open&subjectId=alice \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"

Response:

true

Linda is allowed to View issues, as the is part of the Developers group, which has the View role. But she is not allowed to Open issues. Let's verify that.

API

Check View permission on Issue level for Linda.

curl -i --location https://<YOUR_PERMISSIONS_API_URL>/management/tenants/spaceblocks/permissions/check?resourceType=repository&resourceId=permissions&permissionScope=issue&permission=view&subjectId=linda \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"

Response:

true

Check Open permission on Issue level for Linda.

curl -i --location https://<YOUR_PERMISSIONS_API_URL>/management/tenants/spaceblocks/permissions/check?resourceType=repository&resourceId=permissions&permissionScope=issue&permission=open&subjectId=linda \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"

Response:

false

That's it. We replicated GitHub's permission model with the help of the Space Blocks Permission module. You can now use the same permission model for your own applications.