mcp-gateway

Azure Entra ID Application Roles Setup

Follow these steps to enable application roles, assign them to identities, and pass the role value into adapter/tool definitions for authorization.

1. Enable and Configure Roles on the App Registration

Open the Azure portal and navigate to Entra ID > App registrations; select the app the gateway trusts (e.g., McpGateway).
Go to App roles and choose Create app role.
- Display name: Friendly label shown in the portal (e.g., Adapter Reader).
- Allowed member type: Users/Groups for people or Applications for service principals.
- Value: Immutable string used by Mcp Gateway authorization (e.g., mcp.engineer).
- Provide a meaningful description so administrators know when to grant it.
- Save the role. Repeat for each logical permission your org needs; you can create any value pattern (e.g., mcp.engineer, mcp.scientist).
Always create the admin role with the value mcp.admin. This value is used by the gateway to grant elevated write access beyond the resource creator.
Make sure App roles shows the new entries in the table; this automatically updates the app manifest.

2. Assign Roles to Identities

In the same app registration, open Enterprise applications (service principal) entry.
Navigate to Users and groups > Add user/group.
- Select a user, group, or service principal.
- Choose the desired application role value.
- Confirm the assignment.
Users receive the role via their next sign-in; apps inherit the claims immediately once the service principal is updated.

3. Provide the Role Value When Creating Adapters or Tools

When calling the management APIs (or CLI) to create adapters/tools, populate the requiredRoles collection with the exact Value strings created above.

Example payload fragment:

{
  "name": "sample-adapter",
  // ...
  "requiredRoles": ["mcp.engineer", "mcp.scientist"]
}

The gateway’s SimplePermissionProvider grants:
- Read access if the caller is the creator, holds mcp.admin, or matches one of the requiredRoles entries.
- Write access if the caller is the creator or holds mcp.admin.
If no requiredRoles is configured, it by default ALLOW ALL READ access.

4. Authorize Built-in Agent Tools (`bash`, `read_file`, `write_file`)

The in-process built-in tools run shell commands and read/write files inside the gateway pod, so they are treated as a privileged capability rather than an ordinary resource. Unlike adapters/tools, they have no per-resource requiredRoles; access is gated on the caller’s role — at agent create/update time and again at run time (tool resolution and invocation) — with no creator bypass. Even the author of an agent must hold the required role to reference or invoke a built-in.

Default (fail-closed): only callers holding mcp.admin may reference or invoke built-in tools.
To grant built-in access without full admin, create a dedicated app role (e.g. mcp.builtin), assign it (Section 2), then configure it on the gateway:
```
// appsettings.json
{
  "BuiltinToolSettings": {
    "RequiredRoles": [ "mcp.builtin" ]
  }
}
```
The same setting via environment variables (e.g. in the pod spec) uses the array index form:
```
BuiltinToolSettings__RequiredRoles__0=mcp.builtin
```
mcp.admin is always permitted in addition to any configured roles. Leaving RequiredRoles empty keeps built-ins admin-only.

5. Authorize Workload Identity on Adapters and Tools (`useWorkloadIdentity`)

Setting useWorkloadIdentity: true binds the deployed pod to the cluster’s shared federated identity (the workload-sa service account annotated with azure.workload.identity/client-id). Any container in that pod can then mint Entra ID access tokens for that identity and reach whatever Azure resources it is granted. Because the identity is shared by every workload in the namespace and is not owned by the requester, this is gated on the caller’s role at create and update time, with no creator bypass.

Default (fail-closed): only callers holding mcp.admin may set useWorkloadIdentity: true. Other callers receive 403 Forbidden; adapters and tools that do not request workload identity are unaffected.
To grant this without full admin, create a dedicated app role (e.g. mcp.workload), assign it (Section 2), then configure it on the gateway:
```
// appsettings.json
{
  "WorkloadIdentitySettings": {
    "RequiredRoles": [ "mcp.workload" ]
  }
}
```
The same setting via environment variables (e.g. in the pod spec) uses the array index form:
```
WorkloadIdentitySettings__RequiredRoles__0=mcp.workload
```
mcp.admin is always permitted in addition to any configured roles. Leaving RequiredRoles empty keeps workload identity admin-only.

This site is open source. Improve this page.