diff --git a/docs/provider-guides/asgardeo.mdx b/docs/provider-guides/asgardeo.mdx new file mode 100644 index 0000000..a7cb5aa --- /dev/null +++ b/docs/provider-guides/asgardeo.mdx @@ -0,0 +1,121 @@ +--- +sidebar_position: 3 +sidebar_label: Asgardeo +--- + +# Asgardeo + +[Asgardeo](https://wso2.com/asgardeo) is a cloud-native identity as a service (IDaaS) platform that supports OAuth 2.0 and OpenID Connect (OIDC), providing robust identity and access management for modern applications. + +:::note +If you don't have an Asgardeo account, you can [sign up for free](https://asgardeo.io). +::: + +## Get issuer URL {#get-issuer-url} + +The issuer URL is organization-scoped, so you can compose it from your organization name: + +``` +https://api.asgardeo.io/t//oauth2/token +``` + +You can also verify it in the Asgardeo Console: + +1. Log in to the [Asgardeo Console](https://console.asgardeo.io) and select your organization +2. Navigate to any of your applications and open the **Info** tab +3. The **Issuer** field will be displayed there + +Alternatively, discover it dynamically via the [OIDC discovery endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs). + +## Register MCP server and scopes {#register-mcp-server-and-scopes} + +Asgardeo has a first-class MCP server resource type that supports Role-Based Access Control (RBAC) and fine-grained authorization through scopes: + +1. Log in to the [Asgardeo Console](https://console.asgardeo.io) and select your organization +2. Go to **Resources** → **MCP Servers** in the left menu +3. Click **+ New MCP Server** and fill in the details: + - **Identifier**: Your MCP server URL, e.g., `http://localhost:3001/` + - **Display Name**: e.g., "Todo Manager" +4. Click **Next**, then in the **Scopes** tab add the scopes your MCP server needs, e.g.: + - `create:todos`: "Create new todo items" + - `read:todos`: "Read all todo items" + - `delete:todos`: "Delete any todo item" +5. Click **Create** + +The scopes will be included in the JWT access token's `scope` claim as a space-separated string. + +:::note +If your organization doesn't have the **MCP Servers** menu yet, you can achieve the same result with a generic API resource (**API Authorization** → **New API Resource**). Both resource types issue tokens the same way. +::: + +See [Securing MCP servers](https://wso2.com/asgardeo/docs/guides/agentic-ai/mcp/mcp-server-authorization/) in the Asgardeo documentation for more details. + +## Token audience {#token-audience} + +Asgardeo does not support [RFC 8707 resource indicators](https://datatracker.ietf.org/doc/html/rfc8707), so the `resource` parameter sent by MCP clients is ignored. Instead, the audience is derived from the requested scopes: when a client requests scopes that belong to your MCP server resource, Asgardeo puts that resource's **Identifier** in the `aud` claim of the issued JWT access token. + +This means: + +- The **Identifier** is the value your MCP server must validate as the audience. Configure exactly the same value (including the trailing slash, if any) as the `audience` in MCP Auth's Bearer auth config — see [Scope and audience validation](/docs/configure-server/bearer-auth#scope-and-audience-validation). +- MCP clients must request at least one of your MCP server scopes, otherwise the token won't carry your resource in `aud`. Make sure your MCP server advertises the required scopes in its protected resource metadata. + +## Create roles {#create-roles} + +Roles make it easier to manage permissions for groups of users: + +1. Navigate to **User Management > Roles** in the left menu +2. Click **New Role** +3. Create roles with appropriate scopes, e.g.: + - **Admin**: Assign all scopes (`create:todos`, `read:todos`, `delete:todos`) + - **User**: Assign limited scopes (e.g., only `create:todos`) +4. For each role, select the scopes from your MCP server resource + +Alternatively, you can configure roles at the application level: + +1. Navigate to **Applications** and select your application +2. Go to the **Roles** tab +3. Select "Application Role" as the audience type +4. Create and configure roles with their respective scope assignments + +## Assign roles to users {#assign-roles-to-users} + +1. Navigate to **User Management > Roles** +2. Select a role (e.g., "Admin" or "User") +3. Go to the **Users** tab +4. Click **Assign User** and select the users to assign to this role + +## Retrieving user identity {#retrieving-user-identity} + +As an OIDC provider, Asgardeo exposes a standard [userinfo endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/) that allows applications to retrieve claims about the authenticated user. The same claims are also encoded in the ID token returned along with the access token. + +To fetch an access token that can be used to access the userinfo endpoint, at least two scopes are required: `openid` and `profile`. + +## Register MCP client {#register-mcp-client} + +While Asgardeo supports dynamic client registration via a standard API, the endpoint is protected and requires an access token with the necessary permissions. Since MCP clients cannot obtain such a token on their own, you'll need to register the client manually through the Asgardeo Console. + +Asgardeo provides an [MCP Client Application](https://wso2.com/asgardeo/docs/guides/agentic-ai/mcp/register-mcp-client-app/) template that comes preconfigured according to the MCP authorization specification (authorization code grant with PKCE, public client), so use it instead of the generic standard-based application template. + +### Register a client for VS Code + +1. Log in to the [Asgardeo Console](https://console.asgardeo.io) and select your organization +2. Create a new application: + - Go to **Applications** → **New Application** + - Choose the **MCP Client Application** template + - Enter an application name like `VS Code` + - In the **Authorized redirect URLs** field, add: + - `http://127.0.0.1` + - `https://vscode.dev/redirect` + - Keep **Public client** enabled, since MCP clients such as VS Code cannot securely store a client secret + - Click **Create** +3. Configure the protocol settings under the **Protocol** tab: + - Copy the **Client ID** for later use + - In the **Access Token** section, make sure **Token Type** is set to `JWT`, so that MCP Auth can validate the token locally via the JWKS endpoint instead of calling the introspection endpoint + - For browser-based MCP clients (e.g., MCP Inspector), add the client's origin to **Allowed Origins** so that CORS preflight requests succeed + - Click **Update** +4. Authorize the MCP server: + - Go to the **Authorization** tab and click **Authorize a resource** + - Select the MCP server you registered earlier as the resource + - Choose the **Authorized Scopes** the application can request + - Click **Finish** +5. Configure the copied **Client ID** in your MCP client diff --git a/sidebars.ts b/sidebars.ts index 05f64ca..69e0f5c 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -33,6 +33,7 @@ const sidebars: SidebarsConfig = { items: [ 'provider-guides/logto', 'provider-guides/keycloak', + 'provider-guides/asgardeo', 'provider-guides/generic', ], }, diff --git a/src/pages/provider-list.mdx b/src/pages/provider-list.mdx index 248e1a0..5750858 100644 --- a/src/pages/provider-list.mdx +++ b/src/pages/provider-list.mdx @@ -12,7 +12,7 @@ This list contains providers that have been tested with MCP Auth. | --------------------------------------------------------- | -------------- | --------- | ------------ | --------------------------- | ---------------------- | | [Logto](https://logto.io) | OpenID Connect | ✅ | ✅ | ❌[^2] | ✅ | | [Keycloak](https://www.keycloak.org) | OpenID Connect | ✅ | ✅ | ⚠️[^3] | ❌ | -| [Asgardeo](https://wso2.com/asgardeo) | OpenID Connect | ✅ | ✅ | ✅ | ❌ | +| [Asgardeo](https://wso2.com/asgardeo) | OpenID Connect | ✅ | ✅ | ⚠️[^5] | ❌ | | [WSO2 Identity Server](https://wso2.com/identity-server/) | OpenID Connect | ✅ | ✅ | ✅ | ❌ | | [Auth0](https://www.auth0.com) | OpenID Connect | ✅ | ✅ | ✅ | ⚠️[^4] | | [Descope](https://www.descope.com) | OpenID Connect | ✅ | ✅ | ✅ | ⚠️[^4] | @@ -27,6 +27,8 @@ If you have tested MCP Auth with another provider, please feel free to submit a [^4]: Auth0 and Descope support multi-resource refresh tokens (MRRT) but not full RFC 8707. Resource indicator support is limited and not standards-based. +[^5]: While Asgardeo supports dynamic client registration, its registration endpoint requires an access token with the necessary permissions, preventing MCP clients from registering directly. + ## Is Dynamic Client Registration required? {#is-dcr-required} [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) is not required for MCP servers and MCP Auth. In fact, you can choose the approach that best suits your needs: @@ -41,4 +43,4 @@ If you have tested MCP Auth with another provider, please feel free to submit a Enter the URL of your authorization server's `issuer` or metadata endpoint below to check if it's compatible with MCP. - \ No newline at end of file +