From a4906bf8a5f5938ea167427c40f518642500cbcd Mon Sep 17 00:00:00 2001 From: Xiao Yijun Date: Sat, 24 Jan 2026 23:53:28 +0800 Subject: [PATCH 1/3] docs: add Asgardeo provider guide --- docs/provider-guides/asgardeo.mdx | 101 ++++++++++++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 102 insertions(+) create mode 100644 docs/provider-guides/asgardeo.mdx diff --git a/docs/provider-guides/asgardeo.mdx b/docs/provider-guides/asgardeo.mdx new file mode 100644 index 0000000..796da7e --- /dev/null +++ b/docs/provider-guides/asgardeo.mdx @@ -0,0 +1,101 @@ +--- +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} + +You can find the issuer URL in the Asgardeo Console: + +1. Log in to the [Asgardeo Console](https://console.asgardeo.io) and select your organization +2. Navigate to the created application and open the **Info** tab +3. The **Issuer** field will be displayed there + +The issuer URL should look like: + +``` +https://api.asgardeo.io/t//oauth2/token +``` + +You can also discover this endpoint dynamically via the [OIDC discovery endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs). + +## Create API resource and scopes {#create-api-resource-and-scopes} + +Asgardeo supports Role-Based Access Control (RBAC) and fine-grained authorization using API resources and scopes. + +1. Log in to the [Asgardeo Console](https://console.asgardeo.io) and select your organization +2. Navigate to **API Authorization** in the left menu +3. Click **New API Resource** and fill in the details: + - **Identifier**: Your MCP server URL, e.g., `http://localhost:3001/` + - **Display Name**: e.g., "Todo Manager" +4. 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. + +## 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 API 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} + +User information is encoded inside the ID token returned along with the access token. But as an OIDC provider, Asgardeo exposes a [UserInfo endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/) that allows applications to retrieve claims about the authenticated user in the payload. + +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. You'll need to register the client manually through the Asgardeo Console. + +### 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 **Standard-Based Application** → **OAuth 2.0/OpenID Connect** + - Enter an application name like `VS Code` + - In the **Authorized Redirect URLs** field, add: + - `http://127.0.0.1` + - `https://vscode.dev/redirect` + - Click **Create** +3. Configure the protocol settings: + - Under the **Protocol** tab: + - Copy the **Client ID** for later use + - Ensure switching to `JWT` for the `Token Type` in **Access Token** section + - Click **Update** +4. Configure API authorization (if using RBAC): + - Go to the **API Authorization** tab + - Authorize the API resource you created earlier + - Select the scopes the application can request 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', ], }, From b25d7f8b9a7dcced65970e6804c5ce96fe60b63d Mon Sep 17 00:00:00 2001 From: Xiao Yijun Date: Thu, 20 Aug 2026 11:00:39 +0800 Subject: [PATCH 2/3] docs: improve Asgardeo provider guide Add a token audience section, clarify public client / PKCE / JWT token type settings, fix the issuer URL section ordering, and mark Asgardeo DCR as limited in the provider list. Co-Authored-By: Claude Opus 5 --- docs/provider-guides/asgardeo.mdx | 38 ++++++++++++++++++++----------- src/pages/provider-list.mdx | 6 +++-- 2 files changed, 29 insertions(+), 15 deletions(-) diff --git a/docs/provider-guides/asgardeo.mdx b/docs/provider-guides/asgardeo.mdx index 796da7e..7acdade 100644 --- a/docs/provider-guides/asgardeo.mdx +++ b/docs/provider-guides/asgardeo.mdx @@ -13,19 +13,19 @@ If you don't have an Asgardeo account, you can [sign up for free](https://asgard ## Get issuer URL {#get-issuer-url} -You can find the issuer URL in the Asgardeo Console: - -1. Log in to the [Asgardeo Console](https://console.asgardeo.io) and select your organization -2. Navigate to the created application and open the **Info** tab -3. The **Issuer** field will be displayed there - -The issuer URL should look like: +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 discover this endpoint dynamically via the [OIDC discovery endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs). +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). ## Create API resource and scopes {#create-api-resource-and-scopes} @@ -44,6 +44,15 @@ Asgardeo supports Role-Based Access Control (RBAC) and fine-grained authorizatio The scopes will be included in the JWT access token's `scope` claim as a space-separated string. +## 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 scopes being requested: when a client requests scopes that belong to an API resource, Asgardeo includes that API resource's **Identifier** in the `aud` claim of the issued JWT access token. + +This means: + +- The **Identifier** you set for the API resource is what your MCP server must validate as the audience. Configure the exact 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 API resource scopes, otherwise the token will not carry your API 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: @@ -71,13 +80,13 @@ Alternatively, you can configure roles at the application level: ## Retrieving user identity {#retrieving-user-identity} -User information is encoded inside the ID token returned along with the access token. But as an OIDC provider, Asgardeo exposes a [UserInfo endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/) that allows applications to retrieve claims about the authenticated user in the payload. +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. You'll need to register the client manually through the Asgardeo Console. +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. ### Register a client for VS Code @@ -90,12 +99,15 @@ While Asgardeo supports dynamic client registration via a standard API, the endp - `http://127.0.0.1` - `https://vscode.dev/redirect` - Click **Create** -3. Configure the protocol settings: - - Under the **Protocol** tab: +3. Configure the protocol settings under the **Protocol** tab: - Copy the **Client ID** for later use - - Ensure switching to `JWT` for the `Token Type` in **Access Token** section + - Enable **Public client**, since MCP clients such as VS Code are public clients that cannot keep a client secret + - Set **PKCE** to mandatory (**Authorization code** grant with PKCE is required by OAuth 2.1) + - In the **Access Token** section, set **Token Type** 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. Configure API authorization (if using RBAC): - Go to the **API Authorization** tab - Authorize the API resource you created earlier - Select the scopes the application can request +5. Configure the copied **Client ID** in your MCP client 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 + From 1a59e10a9b31852607ffaa5abe768172a4883ad9 Mon Sep 17 00:00:00 2001 From: Xiao Yijun Date: Thu, 20 Aug 2026 11:04:03 +0800 Subject: [PATCH 3/3] docs: use Asgardeo MCP-native flows in provider guide Address review feedback: register the client with the MCP Client Application template, and register the server as an MCP server resource instead of a generic API resource. Co-Authored-By: Claude Opus 5 --- docs/provider-guides/asgardeo.mdx | 44 ++++++++++++++++++------------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/docs/provider-guides/asgardeo.mdx b/docs/provider-guides/asgardeo.mdx index 7acdade..a7cb5aa 100644 --- a/docs/provider-guides/asgardeo.mdx +++ b/docs/provider-guides/asgardeo.mdx @@ -27,16 +27,16 @@ You can also verify it in the Asgardeo Console: Alternatively, discover it dynamically via the [OIDC discovery endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs). -## Create API resource and scopes {#create-api-resource-and-scopes} +## Register MCP server and scopes {#register-mcp-server-and-scopes} -Asgardeo supports Role-Based Access Control (RBAC) and fine-grained authorization using API resources 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. Navigate to **API Authorization** in the left menu -3. Click **New API Resource** and fill in the details: +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. Add the scopes your MCP server needs, e.g.: +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" @@ -44,14 +44,20 @@ Asgardeo supports Role-Based Access Control (RBAC) and fine-grained authorizatio 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 scopes being requested: when a client requests scopes that belong to an API resource, Asgardeo includes that API resource's **Identifier** in the `aud` claim of the issued JWT access token. +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** you set for the API resource is what your MCP server must validate as the audience. Configure the exact 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 API resource scopes, otherwise the token will not carry your API resource in `aud`. Make sure your MCP server advertises the required scopes in its protected resource metadata. +- 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} @@ -62,7 +68,7 @@ Roles make it easier to manage permissions for groups of users: 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 API resource +4. For each role, select the scopes from your MCP server resource Alternatively, you can configure roles at the application level: @@ -88,26 +94,28 @@ To fetch an access token that can be used to access the userinfo endpoint, at le 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 **Standard-Based Application** → **OAuth 2.0/OpenID Connect** + - Choose the **MCP Client Application** template - Enter an application name like `VS Code` - - In the **Authorized Redirect URLs** field, add: + - 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 - - Enable **Public client**, since MCP clients such as VS Code are public clients that cannot keep a client secret - - Set **PKCE** to mandatory (**Authorization code** grant with PKCE is required by OAuth 2.1) - - In the **Access Token** section, set **Token Type** to `JWT`, so that MCP Auth can validate the token locally via the JWKS endpoint instead of calling the introspection endpoint + - 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. Configure API authorization (if using RBAC): - - Go to the **API Authorization** tab - - Authorize the API resource you created earlier - - Select the scopes the application can request +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