# Custom Roles

## Overview

**Custom Roles** is an optional feature in RealmJoin Portal and allows to create additional RealmJoin internal roles. You can assign granular / atomic permissions to these roles and bind them to Entra groups or dedicated users.

{% hint style="info" %}
If custom roles are needed, please **request activation via RealmJoin support**.
{% endhint %}

Custom Roles are defined as JSON. The JSON editor included in RealmJoin Portal offers syntax checking and highlighting and will verify your definition against the Custom Roles JSON schema.

<figure><img src="/files/Pte1ZL1NLvc4SSveQ0G2" alt=""><figcaption><p>Custom Roles JSON Editor</p></figcaption></figure>

## Using the editor

### Syntax check / Errors

The editor will check the syntax as you type. If a syntax error is detected, an error message **View x errors** and bug icon will appear next to **Save.**

<figure><img src="/files/FZ69fXhJdaXVYmymjCPg" alt=""><figcaption><p>JSON error message/button</p></figcaption></figure>

Click on this message to get more details about the error.

### Formatting

You can auto-format the JSON by clicking **Format** in the upper right corner of the page.

<figure><img src="/files/N5s3qomJbDfWY7Ae6XBx" alt=""><figcaption><p>Format Button</p></figcaption></figure>

### Auto-Complete

The Editor can offer Auto-Complete known keywords (like permissions) from the schema.

<figure><img src="/files/gemhr0eBZbbMS8wmFPkI" alt=""><figcaption><p>Keyword Auto-Complete</p></figcaption></figure>

You can press "Ctrl" + "Space" at any time to invoke Auto-Complete.

## Rules

A role is described as a pair of permissions and users and/or groups these permissions are given to.

Roles are listed as part of an array (list) under the keyword **Rules**.

Example set of rules:

```json
{
  "Rules": [
    {
      "Name": "Default: Supporters can change primary user [27e589a7]",
      "Description": "Default rule to allow members of a Supporter group to change the primary user of RealmJoin joined devices. Please keep the ID that is included its name.",
      "Groups": [
        "f31f5765-f56f-47fa-9248-ac2d77221634",
        "422e6b7c-bd99-4082-be1c-88cbc2bb2734"
      ],
      "Permissions": [
        "CanChangeRealmJoinPrimaryUser"
      ]
    },{
      "Name": "Allow John to add new Self Service Forms",
      "Users": [
        "b31f5765-f56f-47fa-9248-ac2d77221622"
      ],
      "Permissions": [
        "CanAddSelfServiceForms"
      ]
    }
  ]
}
```

### Name and Description

**Name** is required, **Description** is optional.

Both are plain text fields (string).

### Permissions

A permission is a unique string, identifying a certain action in RealmJoin Portal. **Permissions** is a list (array) of permissions.

See [Available Permissions](/realmjoin-settings/permission/custom-roles/available-permissions.md) for a list and description of common permissions.

### Groups

A list (array) of Entra group object IDs. Given [permissions](#permissions) will be assigned to all users that are members of these groups.

### Users

A list (array) of Entra user object IDs. Given [permissions](#permissions) will be assigned to these users.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.realmjoin.com/realmjoin-settings/permission/custom-roles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.