docs: add Asgardeo provider guide

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/<your-organization-name>/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

sidebars.ts

@@ -33,6 +33,7 @@ const sidebars: SidebarsConfig = {
       items: [
         'provider-guides/logto',
         'provider-guides/keycloak',
+        'provider-guides/asgardeo',
         'provider-guides/generic',
       ],
     },

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.
 
-<TestProvider />
+<TestProvider />