assign_realm_role_to_user

Assign Keycloak realm roles to users to manage access permissions. Specify user ID, role names, and optional realm for role assignment.

Instructions

Assign realm roles to a user.

Args:
    user_id: User ID
    role_names: List of role names to assign
    realm: Target realm (uses default if not specified)

Returns:
    Status message

Input Schema

TableJSON Schema

Name	Required	Description	Default
`user_id`	Yes
`role_names`	Yes
`realm`	No

Implementation Reference

src/tools/role_tools.py:208-235 (handler)

The handler function for the 'assign_realm_role_to_user' tool. Decorated with @mcp.tool() for automatic registration. Fetches realm role representations and assigns them to the specified user via Keycloak's role-mappings API endpoint.

@mcp.tool()
async def assign_realm_role_to_user(
    user_id: str, role_names: List[str], realm: Optional[str] = None
) -> Dict[str, str]:
    """
    Assign realm roles to a user.

    Args:
        user_id: User ID
        role_names: List of role names to assign
        realm: Target realm (uses default if not specified)

    Returns:
        Status message
    """
    # Get role representations
    roles = []
    for role_name in role_names:
        role = await client._make_request("GET", f"/roles/{role_name}", realm=realm)
        roles.append(role)

    await client._make_request(
        "POST", f"/users/{user_id}/role-mappings/realm", data=roles, realm=realm
    )
    return {
        "status": "assigned",
        "message": f"Roles {role_names} assigned to user {user_id}",
    }

src/tools/keycloak_client.py:59-108 (helper)

The _make_request method of KeycloakClient, used by the tool to perform authenticated HTTP requests to Keycloak Admin REST API endpoints.

async def _make_request(
    self,
    method: str,
    endpoint: str,
    data: Optional[Dict] = None,
    params: Optional[Dict] = None,
    skip_realm: bool = False,
    realm: Optional[str] = None,
) -> Any:
    """Make authenticated request to Keycloak API"""
    if skip_realm:
        url = f"{self.server_url}/auth/admin{endpoint}"
    else:
        # Use provided realm or fall back to configured realm
        target_realm = realm if realm is not None else self.realm_name
        url = f"{self.server_url}/auth/admin/realms/{target_realm}{endpoint}"

    try:
        client = await self._ensure_client()
        headers = await self._get_headers()

        response = await client.request(
            method=method,
            url=url,
            headers=headers,
            json=data,
            params=params,
        )

        # If token expired, refresh and retry
        if response.status_code == 401:
            await self._get_token()
            headers = await self._get_headers()
            response = await client.request(
                method=method,
                url=url,
                headers=headers,
                json=data,
                params=params,
            )

        response.raise_for_status()

        if response.content:
            return response.json()
        return None

    except httpx.RequestError as e:
        raise Exception(f"Keycloak API request failed: {str(e)}")

src/tools/__init__.py:5-5 (registration)
Import statement that loads the role_tools module, triggering the evaluation of decorators like @mcp.tool() which register the tool.
```
from . import role_tools
```

mcp-keycloak