Role Bindings

Role Bindings are the mechanism used to grant permissions to specific subjects. While a Role defines what can be done, a Role Binding defines who can do it. By connecting a subject to a role, you authorize that subject to perform the actions specified in the role's rules.

Binding Properties

A Role Binding consists of three essential components:

• Kind: The type of subject being bound. Supported values are USER and API_KEY.
• Role ID: The unique identifier of the Role being assigned.
• Subject: The identifier for the specific user or API key.

Subject Identification

The value provided for the subject field depends on the kind of the binding:

Kind	Subject Value
USER	The user's primary email address (e.g., john.doe@example.com).
API_KEY	The unique ID of the API key (e.g., ak_123456789).

Additive Permissions

ImageFactory supports multiple role bindings for a single subject. This allows you to compose complex permission sets from simpler, reusable roles.

If a user is bound to both a "Template Manager" role and a "Security Auditor" role, they will possess the combined permissions of both roles. This additive model simplifies management by allowing you to assign specific functional roles to team members based on their responsibilities.

Managing Role Bindings

To assign roles to users or API keys, navigate to Permissions in the sidebar and select the Role Bindings tab. From here you can create new bindings, view existing assignments grouped by user, update role assignments, and revoke access.

For a detailed walkthrough, see the Permissions guide.

Via API

Role bindings can also be managed programmatically through the GraphQL API. Below are examples of common operations.

Creating a Role Binding

To grant a user administrative access, you would create a binding between their email and the admin role.

mutation CreateRoleBinding($input: CreateRoleBindingInput!) {
  createRoleBinding(input: $input) {
    id
    kind
    subject
    role {
      name
    }
  }
}

Variables for a User:

{
  "input": {
    "kind": "USER",
    "subject": "admin@company.com",
    "roleId": "role_admin_id"
  }
}

Variables for an API Key:

{
  "input": {
    "kind": "API_KEY",
    "subject": "ak_deploy_pipeline_id",
    "roleId": "role_builder_id"
  }
}

Viewing Bindings by User

You can query all role bindings grouped by user to audit who has access to what.

query GetRoleBindingsByUsers {
  roleBindingsByUsers {
    subject
    bindings {
      id
      role {
        name
        description
      }
    }
  }
}

Updating a Role Binding

If you need to change the level of access for a subject, you can update the roleId of an existing binding.

mutation UpdateRoleBinding($id: ID!, $roleId: ID!) {
  updateRoleBinding(id: $id, roleId: $roleId) {
    id
    role {
      name
    }
  }
}

Deleting a Role Binding

To revoke access, simply delete the role binding. This operation takes effect immediately.

mutation DeleteRoleBinding($id: ID!) {
  deleteRoleBinding(id: $id)
}

Best Practices

• Least Privilege: Assign the most restrictive role that still allows the subject to perform their required tasks.
• Avoid Wildcards for Users: Use specific resource types in roles assigned to human users to prevent accidental modifications.
• Audit Regularly: Use the roleBindingsByUsers query periodically to review access and remove bindings for users who no longer require them.
• Use API Keys for Automation: Never use a human user's credentials for CI/CD pipelines. Create a dedicated API key and bind it to a specific "Automation" role.