diff --git a/docs/tutorials/todo-manager/README.mdx b/docs/tutorials/todo-manager/README.mdx index ed9de7c..38e3794 100644 --- a/docs/tutorials/todo-manager/README.mdx +++ b/docs/tutorials/todo-manager/README.mdx @@ -309,40 +309,43 @@ Keycloak will include the granted scopes in the access token's `scope` claim. -[Asgardeo](https://wso2.com/asgardeo) supports Role-Based Access Control (RBAC) and fine-grained authorization using API resources and scopes. Here's how to configure it: +[Asgardeo](https://wso2.com/asgardeo) supports Role-Based Access Control (RBAC) and fine-grained authorization using API resources and scopes. Here's how to configure it: 1. Sign in to the [Asgardeo Console](https://console.asgardeo.io) 2. Define your API resource and scopes: - - Go to **API Resources** - - Click **"New API Resource"** - - Set the **Identifier** to `https://todo.mcp-server.app` (or your desired URL) - - Let the **Display Name** be `Todo Manager` - - Add the following scopes: - - `create:todos` : "Create new todo items" - - `read:todos` : "Read all todo items" - - `delete:todos` : "Delete any todo item" - - Create the resource + + - Go to **API Resources** + - Click **"New API Resource"** + - Set the **Identifier** to `https://todo.mcp-server.app` (or your desired URL) + - Let the **Display Name** be `Todo Manager` + - Add the following scopes: + - `create:todos` : "Create new todo items" + - `read:todos` : "Read all todo items" + - `delete:todos` : "Delete any todo item" + - Create the resource 3. Create roles: - - Use the **User Management > Roles** to create roles and assign scopes directly. - - Click **New Role** - - Provide the role name (e.g., `Admin` or `User`) in **Basic Details** section - - Let the role audience be `Application` and select the `MCP Inspector Application` as the **Assigned Application** - - In **Permission Selection** section, choose the API resource you created earlier (e.g., `Todo Manager`) - - Select the scopes you want to assign to this role (e.g., `create:todos`, `read:todos`, `delete:todos`) - - Click **Finish** to create the role - If you have already created the application - - Navigate to **Application > MCP Inspector Application > Roles tab** - - Select **Application Role** as the audience type, then click **New Role** - - Create an `Admin` role and attach all three scopes - - Create a `User` role and attach only the `create:todos` scope + - Use the **User Management > Roles** to create roles and assign scopes directly. + - Click **New Role** + - Provide the role name (e.g., `Admin` or `User`) in **Basic Details** section + - Let the role audience be `Application` and select the `MCP Inspector Application` as the **Assigned Application** + - In **Permission Selection** section, choose the API resource you created earlier (e.g., `Todo Manager`) + - Select the scopes you want to assign to this role (e.g., `create:todos`, `read:todos`, `delete:todos`) + - Click **Finish** to create the role + + If you have already created the application + + - Navigate to **Application > MCP Inspector Application > Roles tab** + - Select **Application Role** as the audience type, then click **New Role** + - Create an `Admin` role and attach all three scopes + - Create a `User` role and attach only the `create:todos` scope 4. Assign roles to users: - - Go to **User Management > Roles** - - Select the role you created (e.g., `Admin` or `User`) and move to **Users** tab - - Select **Assign User** and choose the users you want to assign this role to and save. + - Go to **User Management > Roles** + - Select the role you created (e.g., `Admin` or `User`) and move to **Users** tab + - Select **Assign User** and choose the users you want to assign this role to and save. The scopes will be included in the JWT access token's `scope` claim as a space-separated string. After configuring your authorization server, users will receive access tokens containing their granted scopes. The MCP server will use these scopes to determine: @@ -352,9 +355,10 @@ Whether a user can view all todos (`read:todos`) or only their own Whether a user can delete any todo (`delete:todos`) or only their own For more details on configuring Asgardeo, refer to the following resources: + - [API Resources Guide](https://wso2.com/asgardeo/docs/guides/authorization/api-authorization) - [Role Management](https://wso2.com/asgardeo/docs/guides/users/manage-roles) - + For OAuth 2.0 or OpenID Connect providers, you'll need to configure the scopes that represent different permissions. The exact steps will depend on your provider, but generally: @@ -746,6 +750,7 @@ Since Logto does not support Dynamic Client Registration yet, you will need to m ```json { "scope": "openid profile email" } ``` + diff --git a/docs/tutorials/whoami/README.mdx b/docs/tutorials/whoami/README.mdx index 2eaf241..e196f40 100644 --- a/docs/tutorials/whoami/README.mdx +++ b/docs/tutorials/whoami/README.mdx @@ -78,6 +78,7 @@ User information is encoded inside the ID token returned along with the access t You can also discover this endpoint dynamically via the [OIDC discovery endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs) or by navigating to the application's 'Info' tab in the Asgardeo Console. To fetch an access token that can be used to access the userinfo endpoint, at least two scopes are required: `openid` and `profile`. + @@ -433,26 +434,29 @@ Follow these steps to configure Asgardeo for MCP Inspector: 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 **Single-Page Application** - - Enter an application name like `MCP Inspector` - - In the **Authorized Redirect URLs** field, paste the **Redirect URL** copied from MCP Inspector client application (e.g.: `http://localhost:6274/oauth/callback`) - - Click **Create** + + - Go to **Applications** → **New Application** + - Choose **Single-Page Application** + - Enter an application name like `MCP Inspector` + - In the **Authorized Redirect URLs** field, paste the **Redirect URL** copied from MCP Inspector client application (e.g.: `http://localhost:6274/oauth/callback`) + - Click **Create** 3. Configure the protocol settings: - - Under the **Protocol** tab: - - Copy the **Client ID** that was auto generated. - - Ensure switching to `JWT` for the `Token Type` in **Access Token** section - - Click **Update** + + - Under the **Protocol** tab: + - Copy the **Client ID** that was auto generated. + - Ensure switching to `JWT` for the `Token Type` in **Access Token** section + - Click **Update** 4. In MCP Inspector client application: - - Open the **OAuth Configuration** section - - Paste the copied **Client ID** - - Enter the following in the **Auth Params** field to request the necessary scopes: + - Open the **OAuth Configuration** section + - Paste the copied **Client ID** + - Enter the following in the **Auth Params** field to request the necessary scopes: ```json { "scope": "openid profile email" } ``` + @@ -551,7 +555,7 @@ The issuer URL can be found in your Keycloak Admin Console. In your 'mcp-realm', You can find the issuer URL in the Asgardeo Console. Navigate to the created application, and open the **Info** tab. The **Issuer** field will be displayed there and should look like: `https://api.asgardeo.io/t//oauth2/token` - + diff --git a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index a99b061..33ef6be 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -15,11 +15,11 @@ In diesem Tutorial bauen wir einen Todo-Manager-MCP-Server mit Benutzer-Authenti Nach Abschluss dieses Tutorials hast du: -- ✅ Ein grundlegendes Verständnis, wie du rollenbasierte Zugangskontrolle (RBAC) in deinem MCP-Server einrichtest. +- ✅ Ein grundlegendes Verständnis davon, wie du rollenbasierte Zugangskontrolle (RBAC) in deinem MCP-Server einrichtest. - ✅ Einen MCP-Server, der persönliche Todo-Listen verwalten kann. :::note -Bevor du beginnst, empfehlen wir dir dringend, zuerst das [Who am I Tutorial](./whoami) durchzugehen, falls du mit dem MCP-Server und OAuth 2 nicht vertraut bist. +Bevor du startest, empfehlen wir dir dringend, zuerst das [Who am I Tutorial](./whoami) durchzugehen, falls du mit dem MCP-Server und OAuth 2 nicht vertraut bist. ::: ## Überblick \{#overview} @@ -30,7 +30,7 @@ Das Tutorial umfasst folgende Komponenten: - **MCP Inspector**: Ein visuelles Test-Tool für MCP-Server. Es agiert auch als OAuth / OIDC-Client, um den Autorisierungsfluss zu starten und Zugangstokens abzurufen. - **Autorisierungsserver**: Ein OAuth 2.1- oder OpenID Connect-Anbieter, der Benutzeridentitäten verwaltet und Zugangstokens ausstellt. -Hier ist ein Überblicksdiagramm der Interaktion zwischen diesen Komponenten: +Hier ist ein Überblicksdiagramm über die Interaktion dieser Komponenten: ```mermaid sequenceDiagram @@ -43,10 +43,10 @@ sequenceDiagram Client->>Auth: Autorisierungsfluss starten Auth->>Auth: Autorisierungsfluss abschließen Auth->>Client: Mit Autorisierungscode zurückleiten - Client->>Auth: Code gegen Zugangstoken tauschen + Client->>Auth: Code gegen Zugangstoken austauschen Auth->>Client: Zugangstoken zurückgeben Client->>Server: Todo-Operation mit Zugangstoken anfordern - Server->>Server: Zugangstoken validieren und Benutzer-Berechtigungen aus Zugangstoken abrufen + Server->>Server: Zugangstoken validieren und Benutzer-Berechtigungen aus Zugangstoken holen Note over Server: Todo-Operation ausführen Server->>Client: Ergebnis der Todo-Operation zurückgeben ``` @@ -67,7 +67,7 @@ Um [rollenbasierte Zugangskontrolle (RBAC)](https://auth.wiki/rbac) in deinem MC 2. Erstelle API-Ressource und Berechtigungen: - Gehe zu "API-Ressourcen" - - Erstelle eine neue API-Ressource namens "Todo Manager" + - Erstelle eine neue API-Ressource mit dem Namen "Todo Manager" - Füge folgende Berechtigungen hinzu: - `create:todos`: "Neue Todo-Einträge erstellen" - `read:todos`: "Alle Todo-Einträge lesen" @@ -88,6 +88,45 @@ Um [rollenbasierte Zugangskontrolle (RBAC)](https://auth.wiki/rbac) in deinem MC Die Berechtigungen werden im `scope`-Anspruch des JWT-Zugangstokens als durch Leerzeichen getrennte Zeichenkette enthalten sein. + + + [Asgardeo](https://wso2.com/asgardeo) unterstützt rollenbasierte Zugangskontrolle (RBAC) und feingranulare Autorisierung mit API-Ressourcen und Berechtigungen. So konfigurierst du es: + + 1. Melde dich bei der [Asgardeo Console](https://console.asgardeo.io) an + + 2. Definiere deine API-Ressource und Berechtigungen: + - Gehe zu **API Resources** + - Klicke auf **"New API Resource"** + - Setze den **Identifier** auf `https://todo.mcp-server.app` (oder deine gewünschte URL) + - Der **Display Name** ist `Todo Manager` + - Füge folgende Berechtigungen hinzu: + - `create:todos` : "Neue Todo-Einträge erstellen" + - `read:todos` : "Alle Todo-Einträge lesen" + - `delete:todos` : "Beliebigen Todo-Eintrag löschen" + - Erstelle die Ressource + + 3. Erstelle Rollen: + - Nutze **User Management > Roles**, um Rollen zu erstellen und Berechtigungen direkt zuzuweisen. + - Klicke auf **New Role** + - Gib den Rollennamen an (z. B. `Admin` oder `User`) im Bereich **Basic Details** + - Setze die Zielgruppe der Rolle auf `Application` und wähle die **MCP Inspector Application** als **Assigned Application** + - Im Bereich **Permission Selection** wähle die zuvor erstellte API-Ressource (z. B. `Todo Manager`) + - Wähle die Berechtigungen aus, die du dieser Rolle zuweisen möchtest (z. B. `create:todos`, `read:todos`, `delete:todos`) + - Klicke auf **Finish**, um die Rolle zu erstellen + + Falls du die Anwendung bereits erstellt hast: + - Navigiere zu **Application > MCP Inspector Application > Roles tab** + - Wähle **Application Role** als Zielgruppentyp, dann klicke auf **New Role** + - Erstelle eine `Admin`-Rolle und füge alle drei Berechtigungen hinzu + - Erstelle eine `User`-Rolle und füge nur die Berechtigung `create:todos` hinzu + + 4. Weisen Sie Rollen Benutzern zu: + - Gehe zu **User Management > Roles** + - Wähle die erstellte Rolle (z. B. `Admin` oder `User`) und gehe zum Tab **Users** + - Wähle **Assign User** und wähle die Benutzer aus, denen du diese Rolle zuweisen möchtest, und speichere. + + Die Berechtigungen werden im `scope`-Anspruch des JWT-Zugangstokens als durch Leerzeichen getrennte Zeichenkette enthalten sein. + @@ -96,7 +135,7 @@ OAuth 2.0 / OIDC-Anbieter unterstützen in der Regel berechtigungsbasierte Zugan 1. Definiere die benötigten Berechtigungen in deinem Autorisierungsserver 2. Konfiguriere deinen Client so, dass diese Berechtigungen während des Autorisierungsflusses angefordert werden 3. Stelle sicher, dass dein Autorisierungsserver die gewährten Berechtigungen im Zugangstoken einschließt -4. Die Berechtigungen sind normalerweise im `scope`-Anspruch des JWT-Zugangstokens enthalten +4. Die Berechtigungen werden normalerweise im `scope`-Anspruch des JWT-Zugangstokens enthalten Sieh in der Dokumentation deines Anbieters nach, wie: @@ -145,7 +184,7 @@ sequenceDiagram ### Dynamische Client-Registrierung \{#dynamic-client-registration} -Die dynamische Client-Registrierung ist für dieses Tutorial nicht erforderlich, kann aber nützlich sein, wenn du die MCP-Client-Registrierung mit deinem Autorisierungsserver automatisieren möchtest. Siehe [Ist Dynamic Client Registration erforderlich?](../../provider-list.mdx#is-dcr-required) für weitere Details. +Die dynamische Client-Registrierung ist für dieses Tutorial nicht erforderlich, kann aber nützlich sein, wenn du den MCP-Client-Registrierungsprozess mit deinem Autorisierungsserver automatisieren möchtest. Siehe [Ist Dynamic Client Registration erforderlich?](../../provider-list.mdx#is-dcr-required) für weitere Details. ## Verstehe RBAC im Todo-Manager \{#understand-rbac-in-todo-manager} @@ -183,24 +222,24 @@ Wir definieren zwei Rollen mit unterschiedlichen Zugriffsrechten: ### Ressourcenbesitz \{#resource-ownership} -Obwohl die obige Berechtigungstabelle die explizit zugewiesenen Berechtigungen pro Rolle zeigt, gibt es ein wichtiges Prinzip des Ressourcenbesitzes zu beachten: +Obwohl die obige Berechtigungstabelle die explizit zugewiesenen Berechtigungen pro Rolle zeigt, gibt es ein wichtiges Prinzip des Ressourcenbesitzes: -- **Benutzer** haben nicht die Berechtigungen `read:todos` oder `delete:todos`, können aber trotzdem: +- **User** haben nicht die Berechtigungen `read:todos` oder `delete:todos`, können aber trotzdem: - Ihre eigenen Todo-Einträge lesen - Ihre eigenen Todo-Einträge löschen -- **Admins** haben volle Berechtigungen (`read:todos` und `delete:todos`) und können: +- **Admins** haben volle Berechtigungen (`read:todos` und `delete:todos`) und können daher: - Alle Todo-Einträge im System ansehen - Jeden Todo-Eintrag löschen, unabhängig vom Eigentümer -Das demonstriert ein häufiges Muster in RBAC-Systemen, bei dem der Besitz einer Ressource implizite Berechtigungen für eigene Ressourcen gewährt, während administrative Rollen explizite Berechtigungen für alle Ressourcen erhalten. +Das zeigt ein häufiges Muster in RBAC-Systemen, bei dem der Besitz einer Ressource implizite Berechtigungen für eigene Ressourcen gewährt, während administrative Rollen explizite Berechtigungen für alle Ressourcen erhalten. :::tip Mehr erfahren -Um tiefer in RBAC-Konzepte und Best Practices einzutauchen, sieh dir [Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac) an. +Um tiefer in RBAC-Konzepte und Best Practices einzutauchen, siehe [Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac). ::: -## Autorisierung in deinem Anbieter konfigurieren \{#configure-authorization-in-your-provider} +## Autorisierung beim Anbieter konfigurieren \{#configure-authorization-in-your-provider} -Um das oben beschriebene Zugangskontrollsystem zu implementieren, musst du deinen Autorisierungsserver so konfigurieren, dass er die benötigten Berechtigungen unterstützt. So geht es bei verschiedenen Anbietern: +Um das oben beschriebene Zugangskontrollsystem zu implementieren, musst du deinen Autorisierungsserver so konfigurieren, dass er die erforderlichen Berechtigungen unterstützt. So geht es bei verschiedenen Anbietern: @@ -212,7 +251,7 @@ Um das oben beschriebene Zugangskontrollsystem zu implementieren, musst du deine 2. Erstelle API-Ressource und Berechtigungen: - Gehe zu "API-Ressourcen" - - Erstelle eine neue API-Ressource namens "Todo Manager" und verwende `https://todo.mcp-server.app` (zu Demo-Zwecken) als Indikator. + - Erstelle eine neue API-Ressource mit dem Namen "Todo Manager" und verwende `https://todo.mcp-server.app` (zu Demo-Zwecken) als Indikator. - Erstelle folgende Berechtigungen: - `create:todos`: "Neue Todo-Einträge erstellen" - `read:todos`: "Alle Todo-Einträge lesen" @@ -223,7 +262,7 @@ Um das oben beschriebene Zugangskontrollsystem zu implementieren, musst du deine - Gehe zu "Rollen" - Erstelle eine "Admin"-Rolle und weise alle Berechtigungen zu (`create:todos`, `read:todos`, `delete:todos`) - Erstelle eine "User"-Rolle und weise nur die Berechtigung `create:todos` zu - - Wechsle auf der Detailseite der "User"-Rolle zum Tab "Allgemein" und setze die "User"-Rolle als "Standardrolle". + - Im Detailbereich der "User"-Rolle wechsle zum Tab "Allgemein" und setze die "User"-Rolle als "Standardrolle". 4. Benutzerrollen und Berechtigungen verwalten: - Für neue Benutzer: @@ -234,7 +273,7 @@ Um das oben beschriebene Zugangskontrollsystem zu implementieren, musst du deine - Weise dem Benutzer Rollen im Tab "Rollen" zu :::tip Programmatische Rollenverwaltung -Du kannst auch die [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) von Logto verwenden, um Benutzerrollen programmatisch zu verwalten. Das ist besonders nützlich für automatisierte Benutzerverwaltung oder beim Erstellen von Admin-Panels. +Du kannst auch die [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) von Logto verwenden, um Benutzerrollen programmatisch zu verwalten. Das ist besonders nützlich für automatisierte Benutzerverwaltung oder beim Bau von Admin-Panels. ::: Beim Anfordern eines Zugangstokens wird Logto die Berechtigungen im `scope`-Anspruch des Tokens basierend auf den Rollenberechtigungen des Benutzers einfügen. @@ -244,7 +283,7 @@ Beim Anfordern eines Zugangstokens wird Logto die Berechtigungen im `scope`-Ansp In [Keycloak](https://www.keycloak.org) kannst du die erforderlichen Berechtigungen mit Client-Scopes einrichten: -1. Client-Scopes erstellen: +1. Erstelle Client-Scopes: - Gehe in deinem Realm zu "Client scopes" - Erstelle drei neue Client-Scopes: @@ -252,10 +291,10 @@ In [Keycloak](https://www.keycloak.org) kannst du die erforderlichen Berechtigun - `read:todos` - `delete:todos` -2. Den Client konfigurieren: +2. Konfiguriere den Client: - Gehe zu deinen Client-Einstellungen - - Füge im Tab "Client scopes" alle erstellten Scopes hinzu + - Im Tab "Client scopes" füge alle erstellten Scopes hinzu - Stelle sicher, dass der Token-Mapper so konfiguriert ist, dass die Scopes enthalten sind 3. Optional: Rollen für einfachere Verwaltung nutzen @@ -267,12 +306,60 @@ In [Keycloak](https://www.keycloak.org) kannst du die erforderlichen Berechtigun Keycloak wird die gewährten Scopes im `scope`-Anspruch des Zugangstokens enthalten. + + + +[Asgardeo](https://wso2.com/asgardeo) unterstützt rollenbasierte Zugangskontrolle (RBAC) und feingranulare Autorisierung mit API-Ressourcen und Berechtigungen. So konfigurierst du es: + +1. Melde dich bei der [Asgardeo Console](https://console.asgardeo.io) an + +2. Definiere deine API-Ressource und Berechtigungen: + - Gehe zu **API Resources** + - Klicke auf **"New API Resource"** + - Setze den **Identifier** auf `https://todo.mcp-server.app` (oder deine gewünschte URL) + - Der **Display Name** ist `Todo Manager` + - Füge folgende Berechtigungen hinzu: + - `create:todos` : "Neue Todo-Einträge erstellen" + - `read:todos` : "Alle Todo-Einträge lesen" + - `delete:todos` : "Beliebigen Todo-Eintrag löschen" + - Erstelle die Ressource + +3. Erstelle Rollen: + - Nutze **User Management > Roles**, um Rollen zu erstellen und Berechtigungen direkt zuzuweisen. + - Klicke auf **New Role** + - Gib den Rollennamen an (z. B. `Admin` oder `User`) im Bereich **Basic Details** + - Setze die Zielgruppe der Rolle auf `Application` und wähle die **MCP Inspector Application** als **Assigned Application** + - Im Bereich **Permission Selection** wähle die zuvor erstellte API-Ressource (z. B. `Todo Manager`) + - Wähle die Berechtigungen aus, die du dieser Rolle zuweisen möchtest (z. B. `create:todos`, `read:todos`, `delete:todos`) + - Klicke auf **Finish**, um die Rolle zu erstellen + + Falls du die Anwendung bereits erstellt hast: + - Navigiere zu **Application > MCP Inspector Application > Roles tab** + - Wähle **Application Role** als Zielgruppentyp, dann klicke auf **New Role** + - Erstelle eine `Admin`-Rolle und füge alle drei Berechtigungen hinzu + - Erstelle eine `User`-Rolle und füge nur die Berechtigung `create:todos` hinzu + +4. Weisen Sie Rollen Benutzern zu: + - Gehe zu **User Management > Roles** + - Wähle die erstellte Rolle (z. B. `Admin` oder `User`) und gehe zum Tab **Users** + - Wähle **Assign User** und wähle die Benutzer aus, denen du diese Rolle zuweisen möchtest, und speichere. + +Die Berechtigungen werden im `scope`-Anspruch des JWT-Zugangstokens als durch Leerzeichen getrennte Zeichenkette enthalten sein. +Nach der Konfiguration deines Autorisierungsservers erhalten Benutzer Zugangstokens mit ihren gewährten Berechtigungen. Der MCP-Server verwendet diese Berechtigungen, um zu bestimmen: + +Ob ein Benutzer neue Todos erstellen darf (`create:todos`) +Ob ein Benutzer alle Todos (`read:todos`) oder nur seine eigenen sehen darf +Ob ein Benutzer beliebige Todos (`delete:todos`) oder nur seine eigenen löschen darf + +Weitere Details zur Konfiguration von Asgardeo findest du hier: +- [API Resources Guide](https://wso2.com/asgardeo/docs/guides/authorization/api-authorization) +- [Role Management](https://wso2.com/asgardeo/docs/guides/users/manage-roles) -Für OAuth 2.0- oder OpenID Connect-Anbieter musst du die Scopes konfigurieren, die verschiedene Berechtigungen repräsentieren. Die genauen Schritte hängen von deinem Anbieter ab, aber im Allgemeinen: +Für OAuth 2.0- oder OpenID Connect-Anbieter musst du die Berechtigungen konfigurieren, die verschiedene Rechte repräsentieren. Die genauen Schritte hängen von deinem Anbieter ab, aber im Allgemeinen: -1. Scopes definieren: +1. Berechtigungen definieren: - Konfiguriere deinen Autorisierungsserver so, dass er unterstützt: - `create:todos` @@ -281,22 +368,22 @@ Für OAuth 2.0- oder OpenID Connect-Anbieter musst du die Scopes konfigurieren, 2. Client konfigurieren: - - Registriere oder aktualisiere deinen Client, um diese Scopes anzufordern - - Stelle sicher, dass die Scopes im Zugangstoken enthalten sind + - Registriere oder aktualisiere deinen Client, um diese Berechtigungen anzufordern + - Stelle sicher, dass die Berechtigungen im Zugangstoken enthalten sind 3. Berechtigungen zuweisen: - - Verwende die Oberfläche deines Anbieters, um Benutzern die passenden Scopes zuzuweisen - - Manche Anbieter unterstützen rollenbasierte Verwaltung, andere nutzen direkte Scope-Zuweisungen + - Verwende die Oberfläche deines Anbieters, um Benutzern die passenden Berechtigungen zu gewähren + - Manche Anbieter unterstützen rollenbasierte Verwaltung, andere direkte Berechtigungszuweisungen - Sieh in der Dokumentation deines Anbieters nach, was empfohlen wird :::tip -Die meisten Anbieter werden die gewährten Scopes im `scope`-Anspruch des Zugangstokens enthalten. Das Format ist typischerweise eine durch Leerzeichen getrennte Zeichenkette von Scope-Werten. +Die meisten Anbieter werden die gewährten Berechtigungen im `scope`-Anspruch des Zugangstokens enthalten. Das Format ist typischerweise eine durch Leerzeichen getrennte Zeichenkette der Scope-Werte. ::: -Nach der Konfiguration deines Autorisierungsservers erhalten Benutzer Zugangstokens mit ihren gewährten Berechtigungen. Der MCP-Server nutzt diese Berechtigungen, um zu bestimmen: +Nach der Konfiguration deines Autorisierungsservers erhalten Benutzer Zugangstokens mit ihren gewährten Berechtigungen. Der MCP-Server verwendet diese Berechtigungen, um zu bestimmen: - Ob ein Benutzer neue Todos erstellen darf (`create:todos`) - Ob ein Benutzer alle Todos (`read:todos`) oder nur seine eigenen sehen darf @@ -320,7 +407,7 @@ uv init # Oder verwende `pipenv` oder `poetry`, um eine neue virtuelle Umgebung -Richte ein neues Node.js-Projekt ein: +Lege ein neues Node.js-Projekt an: ```bash mkdir mcp-server @@ -332,13 +419,13 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -Wir verwenden TypeScript in unseren Beispielen, da Node.js v22.6.0+ TypeScript nativ mit dem Flag `--experimental-strip-types` ausführen kann. Wenn du JavaScript verwendest, ist der Code ähnlich – stelle nur sicher, dass du Node.js v22.6.0 oder neuer nutzt. Siehe Node.js-Dokumentation für Details. +Wir verwenden TypeScript in unseren Beispielen, da Node.js v22.6.0+ TypeScript nativ mit dem Flag `--experimental-strip-types` unterstützt. Wenn du JavaScript verwendest, ist der Code ähnlich – stelle nur sicher, dass du Node.js v22.6.0 oder neuer nutzt. Siehe Node.js-Dokumentation für Details. ::: -### MCP-SDK und Abhängigkeiten installieren \{#install-the-mcp-sdk-and-dependencies} +### MCP SDK und Abhängigkeiten installieren \{#install-the-mcp-sdk-and-dependencies} @@ -347,7 +434,7 @@ Wir verwenden TypeScript in unseren Beispielen, da Node.js v22.6.0+ TypeScript n pip install "mcp[cli]" starlette uvicorn ``` -Oder ein anderer Paketmanager deiner Wahl, wie `uv` oder `poetry`. +Oder einen anderen Paketmanager deiner Wahl, wie `uv` oder `poetry`. @@ -356,14 +443,14 @@ Oder ein anderer Paketmanager deiner Wahl, wie `uv` oder `poetry`. npm install @modelcontextprotocol/sdk express zod ``` -Oder ein anderer Paketmanager deiner Wahl, wie `pnpm` oder `yarn`. +Oder einen anderen Paketmanager deiner Wahl, wie `pnpm` oder `yarn`. ### MCP-Server erstellen \{#create-the-mcp-server} -Erstelle zunächst einen einfachen MCP-Server mit den Tool-Definitionen: +Erstelle zunächst einen grundlegenden MCP-Server mit den Tool-Definitionen: @@ -381,17 +468,17 @@ mcp = FastMCP("Todo Manager") @mcp.tool() def create_todo(content: str) -> dict[str, Any]: """Neues Todo erstellen.""" - return {"error": "Nicht implementiert"} + return {"error": "Not implemented"} @mcp.tool() def get_todos() -> dict[str, Any]: """Alle Todos auflisten.""" - return {"error": "Nicht implementiert"} + return {"error": "Not implemented"} @mcp.tool() def delete_todo(id: str) -> dict[str, Any]: """Todo anhand der ID löschen.""" - return {"error": "Nicht implementiert"} + return {"error": "Not implemented"} app = Starlette( routes=[Mount('/', app=mcp.sse_app())] @@ -408,7 +495,7 @@ uvicorn todo_manager:app --host 0.0.0.0 --port 3001 :::note -Da die aktuelle MCP Inspector-Implementierung keine Autorisierungsflüsse behandelt, verwenden wir den SSE-Ansatz, um den MCP-Server einzurichten. Wir aktualisieren den Code hier, sobald der MCP Inspector Autorisierungsflüsse unterstützt. +Da die aktuelle MCP Inspector-Implementierung keine Autorisierungsflüsse unterstützt, verwenden wir den SSE-Ansatz, um den MCP-Server einzurichten. Wir aktualisieren den Code hier, sobald der MCP Inspector Autorisierungsflüsse unterstützt. ::: Du kannst auch `pnpm` oder `yarn` verwenden, wenn du möchtest. @@ -431,19 +518,19 @@ const server = new McpServer({ server.tool('create-todo', 'Neues Todo erstellen', { content: z.string() }, async ({ content }) => { return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Nicht implementiert' }) }], + content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], }; }); server.tool('get-todos', 'Alle Todos auflisten', async () => { return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Nicht implementiert' }) }], + content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], }; }); server.tool('delete-todo', 'Todo anhand der ID löschen', { id: z.string() }, async ({ id }) => { return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Nicht implementiert' }) }], + content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], }; }); @@ -470,7 +557,7 @@ app.post('/messages', async (req, res) => { if (transport) { await transport.handlePostMessage(req, res, req.body); } else { - res.status(400).send('Kein Transport für sessionId gefunden'); + res.status(400).send('No transport found for sessionId'); } }); @@ -492,9 +579,9 @@ npm start Jetzt, da der MCP-Server läuft, können wir den MCP Inspector verwenden, um zu prüfen, ob das `whoami`-Tool verfügbar ist. -Aufgrund der aktuellen Implementierung haben wir den [MCP Inspector](https://github.com/mcp-auth/inspector) geforkt, um ihn flexibler und skalierbarer für Authentifizierung und Autorisierung zu machen. Wir haben auch einen Pull Request an das Original-Repository eingereicht, um unsere Änderungen einzubringen. +Aufgrund der aktuellen Implementierung haben wir den [MCP Inspector](https://github.com/mcp-auth/inspector) geforkt, um ihn flexibler und skalierbarer für Authentifizierung und Autorisierung zu machen. Wir haben auch einen Pull Request an das Original-Repository gesendet, um unsere Änderungen einzubringen. -Um den MCP Inspector zu starten, verwende folgenden Befehl (Node.js wird benötigt): +Um den MCP Inspector zu starten, verwende folgenden Befehl (Node.js erforderlich): ```bash git clone https://github.com/mcp-auth/inspector.git @@ -503,24 +590,24 @@ npm install npm run dev ``` -Öffne dann deinen Browser und gehe zu `http://localhost:6274/` (oder eine andere im Terminal angezeigte URL), um den MCP Inspector zu nutzen. +Öffne dann deinen Browser und gehe zu `http://localhost:6274/` (oder die im Terminal angezeigte URL), um den MCP Inspector zu nutzen. -### MCP Inspector mit dem MCP-Server verbinden \{#connect-mcp-inspector-to-the-mcp-server} +### MCP Inspector mit MCP-Server verbinden \{#connect-mcp-inspector-to-the-mcp-server} -Prüfe vor dem Fortfahren folgende Konfiguration im MCP Inspector: +Bevor wir fortfahren, prüfe folgende Konfiguration im MCP Inspector: -- **Transporttyp**: Setze auf `SSE`. -- **URL**: Setze auf die URL deines MCP-Servers. In unserem Fall sollte das `http://localhost:3001/sse` sein. +- **Transport-Typ**: Setze auf `SSE`. +- **URL**: Setze auf die URL deines MCP-Servers. In unserem Fall sollte es `http://localhost:3001/sse` sein. -Jetzt kannst du auf die Schaltfläche "Connect" klicken, um zu sehen, ob der MCP Inspector eine Verbindung zum MCP-Server herstellen kann. Wenn alles in Ordnung ist, solltest du im MCP Inspector den Status "Connected" sehen. +Jetzt kannst du auf den "Connect"-Button klicken, um zu sehen, ob der MCP Inspector eine Verbindung zum MCP-Server herstellen kann. Wenn alles in Ordnung ist, solltest du den Status "Connected" im MCP Inspector sehen. ### Checkpoint: Todo-Manager-Tools ausführen \{#checkpoint-run-todo-manager-tools} 1. Klicke im oberen Menü des MCP Inspectors auf den Tab "Tools". -2. Klicke auf die Schaltfläche "List Tools". +2. Klicke auf den Button "List Tools". 3. Du solltest die Tools `create-todo`, `get-todos` und `delete-todo` auf der Seite sehen. Klicke darauf, um die Tool-Details zu öffnen. -4. Du solltest rechts die Schaltfläche "Run Tool" sehen. Klicke darauf und gib die erforderlichen Parameter ein, um das Tool auszuführen. -5. Du solltest das Tool-Ergebnis mit der JSON-Antwort `{"error": "Nicht implementiert"}` sehen. +4. Du solltest rechts den Button "Run Tool" sehen. Klicke darauf und gib die erforderlichen Parameter ein, um das Tool auszuführen. +5. Du solltest das Tool-Ergebnis mit der JSON-Antwort `{"error": "Not implemented"}` sehen. ![MCP Inspector erster Start](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) @@ -538,8 +625,8 @@ Dies ist normalerweise die Basis-URL deines Autorisierungsservers, z. B. `https:
**Wie du die Metadaten des Autorisierungsservers abrufst** -- Wenn dein Autorisierungsserver dem [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) oder [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) entspricht, kannst du die eingebauten MCP Auth-Utilities verwenden, um die Metadaten automatisch abzurufen. -- Wenn dein Autorisierungsserver diesen Standards nicht entspricht, musst du die Metadaten-URL oder Endpunkte manuell in der MCP-Server-Konfiguration angeben. Prüfe die Dokumentation deines Anbieters für die spezifischen Endpunkte. +- Wenn dein Autorisierungsserver dem [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) oder [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) entspricht, kannst du die eingebauten Utilities von MCP Auth verwenden, um die Metadaten automatisch abzurufen. +- Wenn dein Autorisierungsserver diese Standards nicht erfüllt, musst du die Metadaten-URL oder Endpunkte manuell in der MCP-Server-Konfiguration angeben. Prüfe die Dokumentation deines Anbieters für die spezifischen Endpunkte.
@@ -547,14 +634,14 @@ Dies ist normalerweise die Basis-URL deines Autorisierungsservers, z. B. `https: **Wie du den MCP Inspector als Client in deinem Autorisierungsserver registrierst** - Wenn dein Autorisierungsserver [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) unterstützt, kannst du diesen Schritt überspringen, da der MCP Inspector sich automatisch als Client registriert. -- Wenn dein Autorisierungsserver Dynamic Client Registration nicht unterstützt, musst du den MCP Inspector manuell als Client in deinem Autorisierungsserver registrieren. +- Wenn dein Autorisierungsserver keine Dynamic Client Registration unterstützt, musst du den MCP Inspector manuell als Client in deinem Autorisierungsserver registrieren.
-**Verstehe die Token-Anfrageparameter** +**Token-Request-Parameter verstehen** -Beim Anfordern von Zugangstokens von verschiedenen Autorisierungsservern wirst du verschiedene Ansätze zur Angabe der Zielressource und Berechtigungen sehen. Hier sind die Hauptmuster: +Beim Anfordern von Zugangstokens von verschiedenen Autorisierungsservern gibt es verschiedene Ansätze, um die Zielressource und Berechtigungen anzugeben. Hier die Hauptmuster: - **Ressourcenindikator-basiert**: @@ -581,8 +668,8 @@ Beim Anfordern von Zugangstokens von verschiedenen Autorisierungsservern wirst d } ``` -- **Rein scope-basiert**: - - Verwendet ausschließlich Scopes ohne resource/audience-Parameter +- **Rein berechtigungsbasiert**: + - Verwendet ausschließlich Berechtigungen ohne resource/audience-Parameter - Traditioneller OAuth 2.0-Ansatz - Beispielanfrage: ```json @@ -590,7 +677,7 @@ Beim Anfordern von Zugangstokens von verschiedenen Autorisierungsservern wirst d "scope": "todo-api:create todo-api:read openid profile" } ``` - - Nutzt oft vorangestellte Scopes, um Berechtigungen zu namespacen + - Oft werden Präfixe verwendet, um Berechtigungen zu gruppieren - Häufig in einfacheren OAuth 2.0-Implementierungen :::tip Best Practices @@ -610,45 +697,79 @@ Auch wenn jeder Anbieter eigene Anforderungen hat, führen dich die folgenden Sc -Die Integration des Todo-Managers mit [Logto](https://logto.io) ist unkompliziert, da es sich um einen OpenID Connect-Anbieter handelt, der Ressourcenindikatoren und Scopes unterstützt. So kannst du deine Todo-API mit `https://todo.mcp-server.app` als Ressourcenindikator absichern. +Die Integration des Todo-Managers mit [Logto](https://logto.io) ist einfach, da es ein OpenID Connect-Anbieter ist, der Ressourcenindikatoren und Berechtigungen unterstützt. So kannst du deine Todo-API mit `https://todo.mcp-server.app` als Ressourcenindikator absichern. -Da Logto Dynamic Client Registration noch nicht unterstützt, musst du den MCP Inspector manuell als Client in deinem Logto-Tenant registrieren: +Da Logto noch keine Dynamic Client Registration unterstützt, musst du den MCP Inspector manuell als Client in deinem Logto-Tenant registrieren: -1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, z. B. `http://localhost:6274/oauth/callback`. +1. Öffne deinen MCP Inspector, klicke auf den Button "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, z. B. `http://localhost:6274/oauth/callback`. 2. Melde dich bei der [Logto Console](https://cloud.logto.io) (oder deiner selbst gehosteten Logto Console) an. -3. Navigiere zum Tab "Anwendungen", klicke auf "Anwendung erstellen". Klicke unten auf der Seite auf "App ohne Framework erstellen". -4. Fülle die Anwendungsdetails aus und klicke dann auf "Anwendung erstellen": +3. Navigiere zum Tab "Applications", klicke auf "Create application". Unten auf der Seite klicke auf "Create app without framework". +4. Fülle die Anwendungsdetails aus und klicke auf "Create application": - **Wähle einen Anwendungstyp**: "Single-page application" - **Anwendungsname**: z. B. "MCP Inspector" -5. Im Bereich "Einstellungen / Redirect URIs" füge den kopierten **Redirect URL (auto-populated)**-Wert ein. Klicke dann unten auf "Änderungen speichern". +5. Im Bereich "Settings / Redirect URIs" füge den kopierten **Redirect URL (auto-populated)**-Wert ein. Klicke dann unten auf "Save changes". 6. Im oberen Bereich siehst du den Wert "App ID". Kopiere ihn. 7. Gehe zurück zum MCP Inspector und füge den "App ID"-Wert im Bereich "OAuth Configuration" unter "Client ID" ein. -8. Gib den Wert `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` im Feld "Auth Params" ein. Dadurch enthält das von Logto zurückgegebene Zugangstoken die erforderlichen Berechtigungen für den Zugriff auf den Todo-Manager. +8. Gib `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` im Feld "Auth Params" ein. So wird sichergestellt, dass das von Logto zurückgegebene Zugangstoken die notwendigen Berechtigungen für den Zugriff auf den Todo-Manager enthält. + + + + Während Asgardeo die dynamische Client-Registrierung über eine Standard-API unterstützt, ist der Endpunkt geschützt und erfordert ein Zugangstoken mit den notwendigen Berechtigungen. In diesem Tutorial registrieren wir den Client manuell über die Asgardeo Console. + + :::note + Wenn du noch kein Asgardeo-Konto hast, kannst du dich [kostenlos registrieren](https://asgardeo.io). + ::: + + So konfigurierst du Asgardeo für den MCP Inspector: + + 1. Melde dich bei der [Asgardeo Console](https://console.asgardeo.io) an und wähle deine Organisation aus. + + 2. Erstelle eine neue Anwendung: + - Gehe zu **Applications** → **New Application** + - Wähle **Single-Page Application** + - Gib einen Anwendungsnamen wie `MCP Inspector` ein + - Im Feld **Authorized Redirect URLs** füge die aus dem MCP Inspector kopierte **Redirect URL** ein (z. B.: `http://localhost:6274/oauth/callback`) + - Klicke auf **Create** + + 3. Protokolleinstellungen konfigurieren: + - Im Tab **Protocol**: + - Kopiere die automatisch generierte **Client ID** + - Stelle sicher, dass du auf `JWT` für den `Token Type` im Bereich **Access Token** umstellst + - Klicke auf **Update** + + 4. Im MCP Inspector: + - Öffne den Bereich **OAuth Configuration** + - Füge die kopierte **Client ID** ein + - Gib Folgendes im Feld **Auth Params** ein, um die notwendigen Berechtigungen anzufordern: + + ```json + { "scope": "openid profile email" } + ``` :::note -Dies ist eine generische OAuth 2.0 / OpenID Connect-Anbieter-Integrationsanleitung. Beide folgen ähnlichen Schritten, da OIDC auf OAuth 2.0 aufbaut. Prüfe die Dokumentation deines Anbieters für Details. +Dies ist eine generische Anleitung zur Integration eines OAuth 2.0 / OpenID Connect-Anbieters. Beide folgen ähnlichen Schritten, da OIDC auf OAuth 2.0 aufbaut. Prüfe die Dokumentation deines Anbieters für Details. ::: Wenn dein Anbieter Dynamic Client Registration unterstützt, kannst du direkt zu Schritt 8 unten gehen, um den MCP Inspector zu konfigurieren; andernfalls musst du den MCP Inspector manuell als Client registrieren: -1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, z. B. `http://localhost:6274/oauth/callback`. +1. Öffne deinen MCP Inspector, klicke auf den Button "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, z. B. `http://localhost:6274/oauth/callback`. -2. Melde dich bei der Konsole deines Anbieters an. +2. Melde dich in der Konsole deines Anbieters an. -3. Navigiere zum Bereich "Anwendungen" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. +3. Navigiere zum Bereich "Applications" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. 4. Falls dein Anbieter einen Client-Typ verlangt, wähle "Single-page application" oder "Public client". -5. Nach dem Erstellen der Anwendung musst du die Redirect-URI konfigurieren. Füge den kopierten **Redirect URL (auto-populated)**-Wert ein. +5. Nach dem Erstellen der Anwendung musst du die Redirect URI konfigurieren. Füge den kopierten **Redirect URL (auto-populated)**-Wert ein. 6. Finde die "Client ID" oder "Application ID" der neu erstellten Anwendung und kopiere sie. -7. Gehe zurück zum MCP Inspector und füge den "Client ID"-Wert im Bereich "OAuth Configuration" unter "Client ID" ein. +7. Gehe zurück zum MCP Inspector und füge die "Client ID" im Bereich "OAuth Configuration" unter "Client ID" ein. -8. Gib folgenden Wert im Feld "Auth Params" ein, um die erforderlichen Berechtigungen für Todo-Operationen anzufordern: +8. Gib folgenden Wert im Feld "Auth Params" ein, um die notwendigen Berechtigungen für Todo-Operationen anzufordern: ```json { "scope": "create:todos read:todos delete:todos" } @@ -670,7 +791,7 @@ Installiere zuerst das `mcpauth`-Paket: pip install mcpauth ``` -Oder ein anderer Paketmanager deiner Wahl, wie `uv` oder `poetry`. +Oder einen anderen Paketmanager deiner Wahl, wie `uv` oder `poetry`. @@ -696,11 +817,20 @@ Die Issuer-URL findest du auf der Anwendungsdetailseite in der Logto Console im + + + Die Issuer-URL findest du in der Asgardeo Console. Navigiere zur erstellten Anwendung und öffne den Tab **Info**. Das Feld **Issuer** wird dort angezeigt und sieht etwa so aus: + `https://api.asgardeo.io/t//oauth2/token` + + + + + Für OAuth 2.0-Anbieter musst du: -1. In der Dokumentation deines Anbieters nach der Autorisierungsserver-URL suchen (oft als Issuer-URL oder Basis-URL bezeichnet) +1. In der Dokumentation deines Anbieters nach der URL des Autorisierungsservers suchen (oft als Issuer-URL oder Basis-URL bezeichnet) 2. Manche Anbieter stellen dies unter `https://{your-domain}/.well-known/oauth-authorization-server` bereit 3. Im Admin-Bereich deines Anbieters unter OAuth/API-Einstellungen nachsehen @@ -747,7 +877,7 @@ const mcpAuth = new MCPAuth({ ### MCP-Server aktualisieren \{#update-mcp-server} -Wir sind fast fertig! Jetzt aktualisieren wir den MCP-Server, um die MCP Auth-Route und Middleware-Funktion anzuwenden und die berechtigungsbasierte Zugangskontrolle für die Todo-Manager-Tools basierend auf den Benutzerberechtigungen zu implementieren. +Fast geschafft! Jetzt aktualisieren wir den MCP-Server, um die MCP Auth-Route und Middleware-Funktion anzuwenden und die berechtigungsbasierte Zugangskontrolle für die Todo-Manager-Tools basierend auf den Benutzerberechtigungen zu implementieren. @@ -1011,7 +1141,7 @@ todo_service = TodoService() def create_todo(content: str) -> dict[str, Any]: """Neues Todo erstellen. - Nur Benutzer mit 'create:todos'-Berechtigung dürfen Todos erstellen. + Nur Benutzer mit der Berechtigung 'create:todos' können Todos erstellen. """ # Authentifizierungsinformationen abrufen auth_info = mcp_auth.auth_info @@ -1029,7 +1159,7 @@ def create_todo(content: str) -> dict[str, Any]: # Neues Todo erstellen created_todo = todo_service.create_todo(content=content, owner_id=user_id) - # Erstelltes Todo zurückgeben + # Das erstellte Todo zurückgeben return created_todo.__dict__ # ... @@ -1071,7 +1201,7 @@ server.tool( const userId = assertUserId(authInfo); /** - * Nur Benutzer mit 'create:todos'-Berechtigung dürfen Todos erstellen + * Nur Benutzer mit der Berechtigung 'create:todos' können Todos erstellen */ if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { throw new MCPAuthBearerAuthError('missing_required_scopes'); @@ -1095,22 +1225,22 @@ Du findest unseren [Beispielcode](https://github.com/mcp-auth/js/tree/master/pac ## Checkpoint: Die `todo-manager`-Tools ausführen \{#checkpoint-run-the-todo-manager-tools} -Starte deinen MCP-Server neu und öffne den MCP Inspector im Browser. Wenn du auf die Schaltfläche "Connect" klickst, solltest du zur Anmeldeseite deines Autorisierungsservers weitergeleitet werden. +Starte deinen MCP-Server neu und öffne den MCP Inspector im Browser. Wenn du auf den "Connect"-Button klickst, solltest du zur Anmeldeseite deines Autorisierungsservers weitergeleitet werden. -Nachdem du dich angemeldet hast und zum MCP Inspector zurückkehrst, wiederhole die Aktionen aus dem vorherigen Checkpoint, um die Todo-Manager-Tools auszuführen. Dieses Mal kannst du die Tools mit deiner authentifizierten Benutzeridentität nutzen. Das Verhalten der Tools hängt von den Rollen und Berechtigungen ab, die deinem Benutzer zugewiesen sind: +Nachdem du dich angemeldet hast und zurück im MCP Inspector bist, wiederhole die Aktionen aus dem vorherigen Checkpoint, um die Todo-Manager-Tools auszuführen. Diesmal kannst du die Tools mit deiner authentifizierten Benutzeridentität nutzen. Das Verhalten der Tools hängt von den Rollen und Berechtigungen ab, die deinem Benutzer zugewiesen sind: -- Wenn du als **User** (nur mit `create:todos`-Berechtigung) angemeldet bist: +- Wenn du als **User** angemeldet bist (nur mit `create:todos`-Berechtigung): - Du kannst neue Todos mit dem Tool `create-todo` erstellen - Du kannst nur deine eigenen Todos ansehen und löschen - Du kannst keine Todos anderer Benutzer sehen oder löschen -- Wenn du als **Admin** (mit allen Berechtigungen: `create:todos`, `read:todos`, `delete:todos`) angemeldet bist: +- Wenn du als **Admin** angemeldet bist (mit allen Berechtigungen: `create:todos`, `read:todos`, `delete:todos`): - Du kannst neue Todos erstellen - - Du kannst mit dem Tool `get-todos` alle Todos im System ansehen - - Du kannst mit dem Tool `delete-todo` beliebige Todos löschen, unabhängig davon, wer sie erstellt hat + - Du kannst alle Todos im System mit dem Tool `get-todos` ansehen + - Du kannst beliebige Todos mit dem Tool `delete-todo` löschen, unabhängig davon, wer sie erstellt hat -Du kannst diese verschiedenen Berechtigungsstufen testen, indem du: +Du kannst diese unterschiedlichen Berechtigungsstufen testen, indem du: 1. Die aktuelle Sitzung abmeldest (klicke auf "Disconnect" im MCP Inspector) 2. Dich mit einem anderen Benutzerkonto anmeldest, das andere Rollen/Berechtigungen hat @@ -1141,9 +1271,9 @@ Sieh dir das [MCP Auth Node.js SDK Repository](https://github.com/mcp-auth/js/bl 🎊 Glückwunsch! Du hast das Tutorial erfolgreich abgeschlossen. Lass uns zusammenfassen, was wir gemacht haben: -- Einen einfachen MCP-Server mit Todo-Management-Tools (`create-todo`, `get-todos`, `delete-todo`) eingerichtet +- Einen grundlegenden MCP-Server mit Todo-Management-Tools (`create-todo`, `get-todos`, `delete-todo`) eingerichtet - Rollenbasierte Zugangskontrolle (RBAC) mit unterschiedlichen Berechtigungsstufen für Benutzer und Admins implementiert - Den MCP-Server mit einem Autorisierungsserver über MCP Auth integriert -- Den MCP Inspector so konfiguriert, dass Benutzer authentifiziert werden und Zugangstokens mit Berechtigungen zum Aufrufen von Tools verwendet werden +- Den MCP Inspector so konfiguriert, dass Benutzer authentifiziert werden und Zugangstokens mit Berechtigungen zum Aufrufen der Tools verwendet werden Sieh dir auch andere Tutorials und die Dokumentation an, um das Beste aus MCP Auth herauszuholen. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx index 992917c..aeafe38 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx @@ -9,7 +9,7 @@ import Tabs from '@theme/Tabs'; import SetupOauth from './_setup-oauth.mdx'; import SetupOidc from './_setup-oidc.mdx'; -# Tutorial: Wer bin ich? (Tutorial: Who am I?) +# Tutorial: Wer bin ich? (Who am I?) Dieses Tutorial führt dich durch den Prozess der Einrichtung von MCP Auth, um Benutzer zu authentifizieren und deren Identitätsinformationen vom Autorisierungsserver abzurufen. @@ -23,7 +23,7 @@ Nach Abschluss dieses Tutorials hast du: Das Tutorial umfasst die folgenden Komponenten: - **MCP-Server**: Ein einfacher MCP-Server, der die offiziellen MCP SDKs verwendet, um Anfragen zu verarbeiten. -- **MCP Inspector**: Ein visuelles Testwerkzeug für MCP-Server. Es fungiert auch als OAuth / OIDC-Client, um den Autorisierungsfluss zu starten und Zugangstokens abzurufen. +- **MCP Inspector**: Ein visuelles Test-Tool für MCP-Server. Es fungiert auch als OAuth / OIDC-Client, um den Autorisierungsfluss zu starten und Zugangstokens abzurufen. - **Autorisierungsserver**: Ein OAuth 2.1- oder OpenID Connect-Anbieter, der Benutzeridentitäten verwaltet und Zugangstokens ausstellt. Hier ist ein Überblicksdiagramm der Interaktion zwischen diesen Komponenten: @@ -31,15 +31,15 @@ Hier ist ein Überblicksdiagramm der Interaktion zwischen diesen Komponenten: ```mermaid sequenceDiagram participant Client as MCP Inspector - participant Server as MCP Server + participant Server as MCP-Server participant Auth as Autorisierungsserver Client->>Server: Tool `whoami` anfordern Server->>Client: 401 Nicht autorisiert zurückgeben - Client->>Auth: Autorisierungsfluss starten + Client->>Auth: Autorisierungsfluss initiieren Auth->>Auth: Autorisierungsfluss abschließen Auth->>Client: Mit Autorisierungscode zurückleiten - Client->>Auth: Code gegen Zugangstoken austauschen + Client->>Auth: Code gegen Zugangstoken eintauschen Auth->>Client: Zugangstoken zurückgeben Client->>Server: `whoami` mit Zugangstoken anfordern Server->>Auth: Benutzeridentität mit Zugangstoken abrufen @@ -56,30 +56,41 @@ Um dieses Tutorial abzuschließen, sollte dein Autorisierungsserver eine API zum -[Logto](https://logto.io) ist ein OpenID Connect-Anbieter, der den Standard-[userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) unterstützt, um Benutzeridentitätsinformationen abzurufen. +[Logto](https://logto.io) ist ein OpenID Connect-Anbieter, der den Standard-[userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) unterstützt, um Benutzeridentitätsinformationen abzurufen. -Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo-Endpunkt verwendet werden kann, sind mindestens zwei Berechtigungen (`scopes`) erforderlich: `openid` und `profile`. Du kannst weiterlesen, da wir die Berechtigungskonfiguration später behandeln. +Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo endpoint verwendet werden kann, sind mindestens zwei Berechtigungen (`scopes`) erforderlich: `openid` und `profile`. Du kannst weiterlesen, da wir die Berechtigungskonfiguration später behandeln. -[Keycloak](https://www.keycloak.org) ist eine Open-Source-Lösung für Identitäts- und Zugriffsmanagement, die mehrere Protokolle unterstützt, darunter OpenID Connect (OIDC). Als OIDC-Anbieter implementiert es den Standard-[userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) zum Abrufen von Benutzeridentitätsinformationen. +[Keycloak](https://www.keycloak.org) ist eine Open-Source-Lösung für Identitäts- und Zugriffsmanagement, die mehrere Protokolle unterstützt, darunter OpenID Connect (OIDC). Als OIDC-Anbieter implementiert es den Standard-[userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo), um Benutzeridentitätsinformationen abzurufen. -Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo-Endpunkt verwendet werden kann, sind mindestens zwei Berechtigungen (`scopes`) erforderlich: `openid` und `profile`. Du kannst weiterlesen, da wir die Berechtigungskonfiguration später behandeln. +Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo endpoint verwendet werden kann, sind mindestens zwei Berechtigungen (`scopes`) erforderlich: `openid` und `profile`. Du kannst weiterlesen, da wir die Berechtigungskonfiguration später behandeln. + + + + +[Asgardeo](https://wso2.com/asgardeo) ist eine cloud-native Identity-as-a-Service (IDaaS)-Plattform, die OAuth 2.0 und OpenID Connect (OIDC) unterstützt und robustes Identitäts- und Zugriffsmanagement für moderne Anwendungen bietet. + +Benutzerinformationen sind im ID-Token codiert, das zusammen mit dem Zugangstoken zurückgegeben wird. Aber als OIDC-Anbieter stellt Asgardeo einen [UserInfo endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/) bereit, der es Anwendungen ermöglicht, Ansprüche über den authentifizierten Benutzer im Payload abzurufen. + +Du kannst diesen Endpunkt auch dynamisch über den [OIDC discovery endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs) entdecken oder indem du im Asgardeo Console zur Registerkarte 'Info' der Anwendung navigierst. + +Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo endpoint verwendet werden kann, sind mindestens zwei Berechtigungen (`scopes`) erforderlich: `openid` und `profile`. -Die meisten OpenID Connect-Anbieter unterstützen den [userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) zum Abrufen von Benutzeridentitätsinformationen. +Die meisten OpenID Connect-Anbieter unterstützen den [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo), um Benutzeridentitätsinformationen abzurufen. -Überprüfe die Dokumentation deines Anbieters, um zu sehen, ob dieser Endpunkt unterstützt wird. Wenn dein Anbieter [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) unterstützt, kannst du auch prüfen, ob der `userinfo_endpoint` im Discovery-Dokument (Antwort vom `.well-known/openid-configuration`-Endpunkt) enthalten ist. +Prüfe die Dokumentation deines Anbieters, ob dieser Endpunkt unterstützt wird. Wenn dein Anbieter [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) unterstützt, kannst du auch prüfen, ob der `userinfo_endpoint` im Discovery-Dokument (Antwort vom `.well-known/openid-configuration`-Endpunkt) enthalten ist. -Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo-Endpunkt verwendet werden kann, sind mindestens zwei Berechtigungen (`scopes`) erforderlich: `openid` und `profile`. Überprüfe die Dokumentation deines Anbieters, um die Zuordnung der Berechtigungen zu Benutzeridentitätsansprüchen zu sehen. +Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo endpoint verwendet werden kann, sind mindestens zwei Berechtigungen (`scopes`) erforderlich: `openid` und `profile`. Prüfe die Dokumentation deines Anbieters, um die Zuordnung der Berechtigungen zu Benutzeridentitätsansprüchen zu sehen. -Während OAuth 2.0 keine standardisierte Methode zum Abrufen von Benutzeridentitätsinformationen definiert, implementieren viele Anbieter eigene Endpunkte dafür. Überprüfe die Dokumentation deines Anbieters, um zu erfahren, wie du mit einem Zugangstoken Benutzeridentitätsinformationen abrufen kannst und welche Parameter erforderlich sind, um ein solches Zugangstoken beim Starten des Autorisierungsflusses zu erhalten. +Während OAuth 2.0 keine standardisierte Methode zum Abrufen von Benutzeridentitätsinformationen definiert, implementieren viele Anbieter eigene Endpunkte dafür. Prüfe die Dokumentation deines Anbieters, um zu erfahren, wie du Benutzeridentitätsinformationen mit einem Zugangstoken abrufen kannst und welche Parameter erforderlich sind, um ein solches Zugangstoken beim Aufruf des Autorisierungsflusses zu erhalten. @@ -129,7 +140,7 @@ npm pkg set scripts.start="node whoami.js" pip install "mcp[cli]" starlette uvicorn ``` -Oder ein anderes Paketverwaltungstool deiner Wahl, wie `uv` oder `poetry`. +Oder ein anderer Paketmanager deiner Wahl, wie `uv` oder `poetry`. @@ -138,14 +149,14 @@ Oder ein anderes Paketverwaltungstool deiner Wahl, wie `uv` oder `poetry`. npm install @modelcontextprotocol/sdk express ``` -Oder ein anderes Paketverwaltungstool deiner Wahl, wie `pnpm` oder `yarn`. +Oder ein anderer Paketmanager deiner Wahl, wie `pnpm` oder `yarn`. -### MCP-Server erstellen \{#create-the-mcp-server} +### Den MCP-Server erstellen \{#create-the-mcp-server} -Erstellen wir zunächst einen MCP-Server, der ein `whoami`-Tool implementiert. +Erstelle zunächst einen MCP-Server, der ein `whoami`-Tool implementiert. @@ -180,7 +191,7 @@ uvicorn whoami:app --host 0.0.0.0 --port 3001 :::note -Da die aktuelle MCP Inspector-Implementierung keine Autorisierungsflüsse verarbeitet, verwenden wir den SSE-Ansatz, um den MCP-Server einzurichten. Wir aktualisieren den Code hier, sobald der MCP Inspector Autorisierungsflüsse unterstützt. +Da die aktuelle MCP Inspector-Implementierung keine Autorisierungsflüsse behandelt, verwenden wir den SSE-Ansatz, um den MCP-Server einzurichten. Wir aktualisieren den Code hier, sobald der MCP Inspector Autorisierungsflüsse unterstützt. ::: Du kannst auch `pnpm` oder `yarn` verwenden, wenn du möchtest. @@ -244,11 +255,11 @@ npm start -## MCP-Server inspizieren \{#inspect-the-mcp-server} +## Den MCP-Server inspizieren \{#inspect-the-mcp-server} ### MCP Inspector klonen und ausführen \{#clone-and-run-mcp-inspector} -Jetzt, da der MCP-Server läuft, können wir den MCP Inspector verwenden, um zu sehen, ob das `whoami`-Tool verfügbar ist. +Nachdem der MCP-Server läuft, können wir den MCP Inspector verwenden, um zu sehen, ob das `whoami`-Tool verfügbar ist. Aufgrund der aktuellen Implementierung haben wir den [MCP Inspector](https://github.com/mcp-auth/inspector) geforkt, um ihn flexibler und skalierbarer für Authentifizierung und Autorisierung zu machen. Wir haben auch einen Pull Request an das Original-Repository eingereicht, um unsere Änderungen einzubringen. @@ -265,16 +276,16 @@ npm run dev ### MCP Inspector mit dem MCP-Server verbinden \{#connect-mcp-inspector-to-the-mcp-server} -Bevor wir fortfahren, überprüfe folgende Konfiguration im MCP Inspector: +Bevor wir fortfahren, prüfe folgende Konfiguration im MCP Inspector: -- **Transporttyp**: Auf `SSE` setzen. -- **URL**: Auf die URL deines MCP-Servers setzen. In unserem Fall sollte das `http://localhost:3001/sse` sein. +- **Transporttyp**: Setze auf `SSE`. +- **URL**: Setze auf die URL deines MCP-Servers. In unserem Fall sollte das `http://localhost:3001/sse` sein. Jetzt kannst du auf die Schaltfläche "Connect" klicken, um zu sehen, ob der MCP Inspector eine Verbindung zum MCP-Server herstellen kann. Wenn alles in Ordnung ist, solltest du den Status "Connected" im MCP Inspector sehen. ### Checkpoint: Das `whoami`-Tool ausführen \{#checkpoint-run-the-whoami-tool} -1. Klicke im oberen Menü des MCP Inspectors auf den Tab "Tools". +1. Klicke im oberen Menü des MCP Inspectors auf die Registerkarte "Tools". 2. Klicke auf die Schaltfläche "List Tools". 3. Du solltest das `whoami`-Tool auf der Seite sehen. Klicke darauf, um die Tool-Details zu öffnen. 4. Du solltest auf der rechten Seite die Schaltfläche "Run Tool" sehen. Klicke darauf, um das Tool auszuführen. @@ -289,14 +300,14 @@ Um diesen Abschnitt abzuschließen, sind mehrere Überlegungen zu beachten:
**Die Issuer-URL deines Autorisierungsservers** -Dies ist normalerweise die Basis-URL deines Autorisierungsservers, z. B. `https://auth.example.com`. Einige Anbieter haben einen Pfad wie `https://example.logto.app/oidc`, daher solltest du die Dokumentation deines Anbieters prüfen. +Dies ist in der Regel die Basis-URL deines Autorisierungsservers, z. B. `https://auth.example.com`. Einige Anbieter haben einen Pfad wie `https://example.logto.app/oidc`, prüfe daher die Dokumentation deines Anbieters.
**Wie du die Metadaten des Autorisierungsservers abrufst** -- Wenn dein Autorisierungsserver dem [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) oder [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) entspricht, kannst du die integrierten MCP Auth-Utilities verwenden, um die Metadaten automatisch abzurufen. +- Wenn dein Autorisierungsserver dem Standard für [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) oder [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) entspricht, kannst du die eingebauten Utilities von MCP Auth verwenden, um die Metadaten automatisch abzurufen. - Wenn dein Autorisierungsserver diese Standards nicht unterstützt, musst du die Metadaten-URL oder Endpunkte manuell in der MCP-Server-Konfiguration angeben. Prüfe die Dokumentation deines Anbieters für die spezifischen Endpunkte.
@@ -312,35 +323,35 @@ Dies ist normalerweise die Basis-URL deines Autorisierungsservers, z. B. `https:
**Wie du Benutzeridentitätsinformationen abrufst und wie du die Parameter der Autorisierungsanfrage konfigurierst** -- Für OpenID Connect-Anbieter: In der Regel musst du beim Starten des Autorisierungsflusses mindestens die Berechtigungen `openid` und `profile` anfordern. Dadurch wird sichergestellt, dass das vom Autorisierungsserver zurückgegebene Zugangstoken die erforderlichen Berechtigungen für den Zugriff auf den [userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) enthält, um Benutzeridentitätsinformationen abzurufen. +- Für OpenID Connect-Anbieter: In der Regel musst du beim Starten des Autorisierungsflusses mindestens die Berechtigungen `openid` und `profile` anfordern. Dadurch wird sichergestellt, dass das vom Autorisierungsserver zurückgegebene Zugangstoken die notwendigen Berechtigungen enthält, um auf den [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) zuzugreifen und Benutzeridentitätsinformationen abzurufen. - Hinweis: Einige Anbieter unterstützen den userinfo-Endpunkt möglicherweise nicht. + Hinweis: Einige Anbieter unterstützen den userinfo endpoint möglicherweise nicht. -- Für OAuth 2.0 / OAuth 2.1-Anbieter: Prüfe die Dokumentation deines Anbieters, um zu erfahren, wie du mit einem Zugangstoken Benutzeridentitätsinformationen abrufen kannst und welche Parameter erforderlich sind, um ein solches Zugangstoken beim Starten des Autorisierungsflusses zu erhalten. +- Für OAuth 2.0 / OAuth 2.1-Anbieter: Prüfe die Dokumentation deines Anbieters, um zu erfahren, wie du Benutzeridentitätsinformationen mit einem Zugangstoken abrufen kannst und welche Parameter erforderlich sind, um ein solches Zugangstoken beim Aufruf des Autorisierungsflusses zu erhalten.
-Während jeder Anbieter eigene spezifische Anforderungen haben kann, führen dich die folgenden Schritte durch den Prozess der Integration des MCP Inspectors und MCP Servers mit anbieter-spezifischen Konfigurationen. +Auch wenn jeder Anbieter eigene Anforderungen hat, führen dich die folgenden Schritte durch den Prozess der Integration von MCP Inspector und MCP-Server mit anbieter-spezifischen Konfigurationen. ### MCP Inspector als Client registrieren \{#register-mcp-inspector-as-a-client} -Die Integration mit [Logto](https://logto.io) ist unkompliziert, da es sich um einen OpenID Connect-Anbieter handelt, der den Standard-[userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) unterstützt, um Benutzeridentitätsinformationen abzurufen. +Die Integration mit [Logto](https://logto.io) ist unkompliziert, da es ein OpenID Connect-Anbieter ist, der den Standard-[userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) unterstützt, um Benutzeridentitätsinformationen abzurufen. Da Logto derzeit keine Dynamic Client Registration unterstützt, musst du den MCP Inspector manuell als Client in deinem Logto-Tenant registrieren: -1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, der etwa so aussehen sollte: `http://localhost:6274/oauth/callback`. +1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, der etwa so aussieht: `http://localhost:6274/oauth/callback`. 2. Melde dich bei der [Logto Console](https://cloud.logto.io) (oder deiner selbst gehosteten Logto Console) an. 3. Navigiere zum Tab "Applications", klicke auf "Create application". Klicke unten auf der Seite auf "Create app without framework". 4. Fülle die Anwendungsdetails aus und klicke dann auf "Create application": - **Wähle einen Anwendungstyp**: Wähle "Single-page application". - **Anwendungsname**: Gib einen Namen für deine Anwendung ein, z. B. "MCP Inspector". -5. Im Bereich "Settings / Redirect URIs" füge den zuvor kopierten **Redirect URL (auto-populated)**-Wert ein. Klicke dann unten auf "Save changes". +5. Im Abschnitt "Settings / Redirect URIs" füge den zuvor kopierten **Redirect URL (auto-populated)**-Wert ein. Klicke dann unten auf "Save changes". 6. Im oberen Bereich siehst du den Wert "App ID". Kopiere ihn. -7. Gehe zurück zum MCP Inspector und füge den "App ID"-Wert im Bereich "OAuth Configuration" unter "Client ID" ein. -8. Gib den Wert `{"scope": "openid profile email"}` im Feld "Auth Params" ein. Dadurch wird sichergestellt, dass das von Logto zurückgegebene Zugangstoken die erforderlichen Berechtigungen für den Zugriff auf den userinfo-Endpunkt enthält. +7. Gehe zurück zum MCP Inspector und füge den "App ID"-Wert im Abschnitt "OAuth Configuration" unter "Client ID" ein. +8. Gib den Wert `{"scope": "openid profile email"}` im Feld "Auth Params" ein. Dadurch wird sichergestellt, dass das von Logto zurückgegebene Zugangstoken die notwendigen Berechtigungen für den Zugriff auf den userinfo endpoint enthält. @@ -350,10 +361,10 @@ Da Logto derzeit keine Dynamic Client Registration unterstützt, musst du den MC Obwohl Keycloak die dynamische Client-Registrierung unterstützt, unterstützt sein Client-Registrierungsendpunkt kein CORS, was die direkte Registrierung der meisten MCP-Clients verhindert. Daher müssen wir unseren Client manuell registrieren. :::note -Obwohl Keycloak auf [verschiedene Arten](https://www.keycloak.org/guides#getting-started) (Bare Metal, Kubernetes usw.) installiert werden kann, verwenden wir für dieses Tutorial Docker für eine schnelle und einfache Einrichtung. +Obwohl Keycloak auf [verschiedene Arten](https://www.keycloak.org/guides#getting-started) (Bare Metal, Kubernetes, usw.) installiert werden kann, verwenden wir für dieses Tutorial Docker für eine schnelle und unkomplizierte Einrichtung. ::: -Richte eine Keycloak-Instanz ein und konfiguriere sie wie folgt: +So richtest du eine Keycloak-Instanz ein und konfigurierst sie für unsere Zwecke: 1. Starte eine Keycloak-Instanz mit Docker gemäß der [offiziellen Dokumentation](https://www.keycloak.org/getting-started/getting-started-docker): @@ -361,7 +372,7 @@ Richte eine Keycloak-Instanz ein und konfiguriere sie wie folgt: docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev ``` -2. Greife auf die Keycloak Admin Console (http://localhost:8080/admin) zu und melde dich mit diesen Zugangsdaten an: +2. Greife auf die Keycloak Admin Console zu (http://localhost:8080/admin) und melde dich mit diesen Zugangsdaten an: - Benutzername: `admin` - Passwort: `admin` @@ -378,14 +389,14 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM - Klicke auf "Create new user" - Fülle die Benutzerdetails aus: - Benutzername: `testuser` - - Vorname und Nachname können beliebige Werte sein + - Vorname und Nachname können beliebig sein - Klicke auf "Create" - Setze im Tab "Credentials" ein Passwort und deaktiviere "Temporary" 5. Registriere den MCP Inspector als Client: - - Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, der etwa so aussehen sollte: `http://localhost:6274/oauth/callback`. - - Klicke in der Keycloak Admin Console im linken Menü auf "Clients" + - Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, z. B. `http://localhost:6274/oauth/callback`. + - In der Keycloak Admin Console, klicke im linken Menü auf "Clients" - Klicke auf "Create client" - Fülle die Client-Details aus: - Client-Typ: Wähle "OpenID Connect" @@ -396,35 +407,69 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM - Klicke auf "Next" - Auf der Seite "Login settings": - Füge die zuvor kopierte MCP Inspector Callback-URL in "Valid redirect URIs" ein - - Gib `http://localhost:6274` in "Web origins" ein + - Gib `http://localhost:6274` bei "Web origins" ein - Klicke auf "Save" - Kopiere die "Client ID" (das ist `mcp-inspector`) 6. Zurück im MCP Inspector: - - Füge die kopierte Client ID in das Feld "Client ID" im Bereich "OAuth Configuration" ein - - Gib folgenden Wert im Feld "Auth Params" ein, um die erforderlichen Berechtigungen anzufordern: + - Füge die kopierte Client ID in das Feld "Client ID" im Abschnitt "OAuth Configuration" ein + - Gib folgenden Wert im Feld "Auth Params" ein, um die notwendigen Berechtigungen anzufordern: ```json { "scope": "openid profile email" } ``` - + + + +Obwohl Asgardeo die dynamische Client-Registrierung über eine Standard-API unterstützt, ist der Endpunkt geschützt und erfordert ein Zugangstoken mit den notwendigen Berechtigungen. In diesem Tutorial registrieren wir den Client manuell über die Asgardeo Console. + +:::note +Wenn du noch kein Asgardeo-Konto hast, kannst du dich [kostenlos registrieren](https://asgardeo.io). +::: + +Folge diesen Schritten, um Asgardeo für den MCP Inspector zu konfigurieren: + +1. Melde dich in der [Asgardeo Console](https://console.asgardeo.io) an und wähle deine Organisation aus. + +2. Erstelle eine neue Anwendung: + - Gehe zu **Applications** → **New Application** + - Wähle **Single-Page Application** + - Gib einen Anwendungsnamen wie `MCP Inspector` ein + - Im Feld **Authorized Redirect URLs** füge die **Redirect URL** ein, die du aus der MCP Inspector Client-Anwendung kopiert hast (z. B.: `http://localhost:6274/oauth/callback`) + - Klicke auf **Create** + +3. Konfiguriere die Protokolleinstellungen: + - Unter dem Tab **Protocol**: + - Kopiere die automatisch generierte **Client ID** + - Stelle sicher, dass du auf `JWT` für den `Token Type` im Abschnitt **Access Token** umstellst + - Klicke auf **Update** + +4. In der MCP Inspector Client-Anwendung: + - Öffne den Abschnitt **OAuth Configuration** + - Füge die kopierte **Client ID** ein + - Gib Folgendes im Feld **Auth Params** ein, um die notwendigen Berechtigungen anzufordern: + +```json +{ "scope": "openid profile email" } +``` + :::note -Dies ist eine allgemeine Anleitung zur Integration eines OpenID Connect-Anbieters. Prüfe die Dokumentation deines Anbieters für spezifische Details. +Dies ist eine generische Anleitung zur Integration eines OpenID Connect-Anbieters. Prüfe die Dokumentation deines Anbieters für spezifische Details. ::: -Wenn dein OpenID Connect-Anbieter die dynamische Client-Registrierung unterstützt, kannst du direkt zu Schritt 8 unten gehen, um den MCP Inspector zu konfigurieren; andernfalls musst du den MCP Inspector manuell als Client in deinem OpenID Connect-Anbieter registrieren: +Wenn dein OpenID Connect-Anbieter Dynamic Client Registration unterstützt, kannst du direkt zu Schritt 8 unten gehen, um den MCP Inspector zu konfigurieren; andernfalls musst du den MCP Inspector manuell als Client in deinem OpenID Connect-Anbieter registrieren: -1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, der etwa so aussehen sollte: `http://localhost:6274/oauth/callback`. -2. Melde dich bei der Konsole deines OpenID Connect-Anbieters an. -3. Navigiere zum Bereich "Applications" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. +1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, z. B. `http://localhost:6274/oauth/callback`. +2. Melde dich in der Konsole deines OpenID Connect-Anbieters an. +3. Navigiere zum Abschnitt "Applications" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. 4. Wenn dein Anbieter einen Client-Typ verlangt, wähle "Single-page application" oder "Public client". 5. Nach dem Erstellen der Anwendung musst du die Redirect URI konfigurieren. Füge den zuvor kopierten **Redirect URL (auto-populated)**-Wert ein. 6. Finde die "Client ID" oder "Application ID" der neu erstellten Anwendung und kopiere sie. -7. Gehe zurück zum MCP Inspector und füge die "Client ID" im Bereich "OAuth Configuration" unter "Client ID" ein. -8. Für Standard-OpenID Connect-Anbieter kannst du folgenden Wert im Feld "Auth Params" eingeben, um die erforderlichen Berechtigungen für den Zugriff auf den userinfo-Endpunkt anzufordern: +7. Gehe zurück zum MCP Inspector und füge die "Client ID" im Abschnitt "OAuth Configuration" unter "Client ID" ein. +8. Für Standard-OpenID-Connect-Anbieter kannst du folgenden Wert im Feld "Auth Params" eingeben, um die notwendigen Berechtigungen für den Zugriff auf den userinfo endpoint anzufordern: ```json { "scope": "openid profile email" } @@ -434,19 +479,19 @@ Wenn dein OpenID Connect-Anbieter die dynamische Client-Registrierung unterstüt :::note -Dies ist eine allgemeine Anleitung zur Integration eines OAuth 2.0 / OAuth 2.1-Anbieters. Prüfe die Dokumentation deines Anbieters für spezifische Details. +Dies ist eine generische Anleitung zur Integration eines OAuth 2.0 / OAuth 2.1-Anbieters. Prüfe die Dokumentation deines Anbieters für spezifische Details. ::: -Wenn dein OAuth 2.0 / OAuth 2.1-Anbieter die dynamische Client-Registrierung unterstützt, kannst du direkt zu Schritt 8 unten gehen, um den MCP Inspector zu konfigurieren; andernfalls musst du den MCP Inspector manuell als Client in deinem OAuth 2.0 / OAuth 2.1-Anbieter registrieren: +Wenn dein OAuth 2.0 / OAuth 2.1-Anbieter Dynamic Client Registration unterstützt, kannst du direkt zu Schritt 8 unten gehen, um den MCP Inspector zu konfigurieren; andernfalls musst du den MCP Inspector manuell als Client in deinem OAuth 2.0 / OAuth 2.1-Anbieter registrieren: -1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, der etwa so aussehen sollte: `http://localhost:6274/oauth/callback`. -2. Melde dich bei der Konsole deines OAuth 2.0 / OAuth 2.1-Anbieters an. -3. Navigiere zum Bereich "Applications" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. +1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, z. B. `http://localhost:6274/oauth/callback`. +2. Melde dich in der Konsole deines OAuth 2.0 / OAuth 2.1-Anbieters an. +3. Navigiere zum Abschnitt "Applications" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. 4. Wenn dein Anbieter einen Client-Typ verlangt, wähle "Single-page application" oder "Public client". 5. Nach dem Erstellen der Anwendung musst du die Redirect URI konfigurieren. Füge den zuvor kopierten **Redirect URL (auto-populated)**-Wert ein. 6. Finde die "Client ID" oder "Application ID" der neu erstellten Anwendung und kopiere sie. -7. Gehe zurück zum MCP Inspector und füge die "Client ID" im Bereich "OAuth Configuration" unter "Client ID" ein. -8. Lies die Dokumentation deines Anbieters, um zu erfahren, wie du Zugangstokens für Benutzeridentitätsinformationen abrufst. Möglicherweise musst du die erforderlichen Berechtigungen oder Parameter angeben, um das Zugangstoken zu erhalten. Wenn dein Anbieter z. B. die Berechtigung `profile` für den Zugriff auf Benutzeridentitätsinformationen verlangt, kannst du folgenden Wert im Feld "Auth Params" eingeben: +7. Gehe zurück zum MCP Inspector und füge die "Client ID" im Abschnitt "OAuth Configuration" unter "Client ID" ein. +8. Lies die Dokumentation deines Anbieters, um zu erfahren, wie du Zugangstokens für Benutzeridentitätsinformationen abrufst. Möglicherweise musst du die Berechtigungen oder Parameter angeben, die für das Abrufen des Zugangstokens erforderlich sind. Wenn dein Anbieter z. B. die Berechtigung `profile` für den Zugriff auf Benutzeridentitätsinformationen verlangt, kannst du folgenden Wert im Feld "Auth Params" eingeben: ```json { "scope": "profile" } @@ -457,7 +502,7 @@ Wenn dein OAuth 2.0 / OAuth 2.1-Anbieter die dynamische Client-Registrierung unt ### MCP Auth einrichten \{#set-up-mcp-auth} -In deinem MCP-Server-Projekt musst du das MCP Auth SDK installieren und es so konfigurieren, dass es die Metadaten deines Autorisierungsservers verwendet. +In deinem MCP-Server-Projekt musst du das MCP Auth SDK installieren und so konfigurieren, dass es die Metadaten deines Autorisierungsservers verwendet. @@ -468,7 +513,7 @@ Installiere zunächst das `mcpauth`-Paket: pip install mcpauth ``` -Oder ein anderes Paketverwaltungstool deiner Wahl, wie `uv` oder `poetry`. +Oder ein anderer Paketmanager deiner Wahl, wie `uv` oder `poetry`. @@ -496,22 +541,31 @@ Die Issuer-URL findest du auf der Anwendungsdetailseite in der Logto Console im -Die Issuer-URL findest du in deiner Keycloak Admin Console. Navigiere in deinem 'mcp-realm' zum Abschnitt "Realm settings / Endpoints" und klicke auf den Link "OpenID Endpoint Configuration". Das Feld `issuer` im JSON-Dokument enthält deine Issuer-URL, die etwa so aussehen sollte: `http://localhost:8080/realms/mcp-realm`. +Die Issuer-URL findest du in der Keycloak Admin Console. In deinem 'mcp-realm' navigiere zum Abschnitt "Realm settings / Endpoints" und klicke auf den Link "OpenID Endpoint Configuration". Das Feld `issuer` im JSON-Dokument enthält deine Issuer-URL, die etwa so aussieht: `http://localhost:8080/realms/mcp-realm`. + + + Die Issuer-URL findest du in der Asgardeo Console. Navigiere zur erstellten Anwendung und öffne den Tab **Info**. Das Feld **Issuer** wird dort angezeigt und sollte wie folgt aussehen: + `https://api.asgardeo.io/t//oauth2/token` + + + + + -Der folgende Code geht ebenfalls davon aus, dass der Autorisierungsserver den [userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) zum Abrufen von Benutzeridentitätsinformationen unterstützt. Wenn dein Anbieter diesen Endpunkt nicht unterstützt, musst du die Dokumentation deines Anbieters für den spezifischen Endpunkt prüfen und die userinfo-Endpunkt-Variable durch die korrekte URL ersetzen. +Der folgende Code geht davon aus, dass der Autorisierungsserver den [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) unterstützt, um Benutzeridentitätsinformationen abzurufen. Wenn dein Anbieter diesen Endpunkt nicht unterstützt, prüfe die Dokumentation deines Anbieters für den spezifischen Endpunkt und ersetze die userinfo endpoint-Variable durch die korrekte URL. -Wie bereits erwähnt, definiert OAuth 2.0 keine standardisierte Methode zum Abrufen von Benutzeridentitätsinformationen. Der folgende Code geht davon aus, dass dein Anbieter einen spezifischen Endpunkt zum Abrufen von Benutzeridentitätsinformationen mit einem Zugangstoken bereitstellt. Du musst die Dokumentation deines Anbieters für den spezifischen Endpunkt prüfen und die userinfo-Endpunkt-Variable durch die korrekte URL ersetzen. +Wie bereits erwähnt, definiert OAuth 2.0 keine standardisierte Methode zum Abrufen von Benutzeridentitätsinformationen. Der folgende Code geht davon aus, dass dein Anbieter einen spezifischen Endpunkt zum Abrufen von Benutzeridentitätsinformationen mit einem Zugangstoken bereitstellt. Prüfe die Dokumentation deines Anbieters für den spezifischen Endpunkt und ersetze die userinfo endpoint-Variable durch die korrekte URL. @@ -531,7 +585,7 @@ def whoami() -> dict[str, Any]: """Ein Tool, das die Informationen des aktuellen Benutzers zurückgibt.""" return ( mcp_auth.auth_info.claims - if mcp_auth.auth_info # Dies wird durch die Bearer-Auth-Middleware befüllt + if mcp_auth.auth_info # Dies wird von der Bearer-Auth-Middleware befüllt else {"error": "Nicht authentifiziert"} ) @@ -573,7 +627,7 @@ app.use(mcpAuth.bearerAuth(verifyToken)); Starte deinen MCP-Server neu und öffne den MCP Inspector in deinem Browser. Wenn du auf die Schaltfläche "Connect" klickst, solltest du zur Anmeldeseite deines Autorisierungsservers weitergeleitet werden. -Sobald du dich angemeldet hast und zum MCP Inspector zurückkehrst, wiederhole die Schritte aus dem vorherigen Checkpoint, um das `whoami`-Tool auszuführen. Dieses Mal solltest du die vom Autorisierungsserver zurückgegebenen Benutzeridentitätsinformationen sehen. +Nachdem du dich angemeldet hast und zum MCP Inspector zurückgekehrt bist, wiederhole die Schritte aus dem vorherigen Checkpoint, um das `whoami`-Tool auszuführen. Dieses Mal solltest du die vom Autorisierungsserver zurückgegebenen Benutzeridentitätsinformationen sehen. ![MCP Inspector whoami Tool Ergebnis](/docs-assets/images/tutorials/whoami/result.png) @@ -599,10 +653,10 @@ Sieh dir das [MCP Auth Node.js SDK Repository](https://github.com/mcp-auth/js/bl 🎊 Glückwunsch! Du hast das Tutorial erfolgreich abgeschlossen. Lass uns zusammenfassen, was wir gemacht haben: - Einen grundlegenden MCP-Server mit dem `whoami`-Tool eingerichtet -- Den MCP-Server mit einem Autorisierungsserver unter Verwendung von MCP Auth integriert +- Den MCP-Server mit einem Autorisierungsserver über MCP Auth integriert - Den MCP Inspector so konfiguriert, dass Benutzer authentifiziert und deren Identitätsinformationen abgerufen werden -Du möchtest vielleicht auch einige fortgeschrittene Themen erkunden, darunter: +Du kannst auch einige fortgeschrittene Themen erkunden, darunter: - Die Verwendung von [JWT (JSON Web Token)](https://auth.wiki/jwt) für Authentifizierung und Autorisierung - Die Nutzung von [Ressourcenindikatoren (RFC 8707)](https://auth-wiki.logto.io/resource-indicator), um die zuzugreifenden Ressourcen anzugeben diff --git a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index 0fa2ed3..a401d4f 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 2 -sidebar_label: 'Tutorial: Crea un gestor de tareas' +sidebar_label: 'Tutorial: Construye un gestor de tareas' --- import TabItem from '@theme/TabItem'; @@ -9,7 +9,7 @@ import Tabs from '@theme/Tabs'; import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; import SetupOidc from './_setup-oidc.mdx'; -# Tutorial: Crea un gestor de tareas +# Tutorial: Construye un gestor de tareas En este tutorial, construiremos un servidor MCP gestor de tareas con autenticación y autorización de usuarios. @@ -26,8 +26,8 @@ Antes de comenzar, te recomendamos encarecidamente que revises primero el [tutor El tutorial involucrará los siguientes componentes: -- **Servidor MCP**: Un servidor MCP sencillo que utiliza los SDK oficiales de MCP para manejar solicitudes, con un servicio integrado de tareas para gestionar los elementos de tareas del usuario. -- **Inspector MCP**: Una herramienta visual de pruebas para servidores MCP. También actúa como un cliente OAuth / OIDC para iniciar el flujo de autorización y obtener tokens de acceso. +- **Servidor MCP**: Un servidor MCP simple que utiliza los SDK oficiales de MCP para manejar solicitudes, con un servicio integrado de tareas para gestionar los elementos de tareas del usuario. +- **Inspector MCP**: Una herramienta visual de pruebas para servidores MCP. También actúa como un cliente OAuth / OIDC para iniciar el flujo de autorización y recuperar tokens de acceso. - **Servidor de autorización**: Un proveedor OAuth 2.1 u OpenID Connect que gestiona identidades de usuario y emite tokens de acceso. Aquí tienes un diagrama de alto nivel de la interacción entre estos componentes: @@ -36,7 +36,7 @@ Aquí tienes un diagrama de alto nivel de la interacción entre estos componente sequenceDiagram participant Cliente as Inspector MCP participant Servidor as Servidor MCP - participant Auth as Servidor de autorización + participant Auth as Servidor de Autorización Cliente->>Servidor: Solicitar operación de tareas Servidor->>Cliente: Retornar 401 No autorizado @@ -46,7 +46,7 @@ sequenceDiagram Cliente->>Auth: Intercambiar código por token de acceso Auth->>Cliente: Retornar token de acceso Cliente->>Servidor: Solicitar operación de tareas con token de acceso - Servidor->>Servidor: Validar token de acceso y obtener alcances del token de acceso + Servidor->>Servidor: Validar token de acceso y obtener alcances del usuario desde el token de acceso Note over Servidor: Ejecutar operación de tareas Servidor->>Cliente: Retornar resultado de la operación de tareas ``` @@ -55,14 +55,14 @@ sequenceDiagram ### Tokens de acceso con alcances \{#access-tokens-with-scopes} -Para implementar el [control de acceso basado en roles (RBAC)](https://auth.wiki/rbac) en tu servidor MCP, tu servidor de autorización debe admitir la emisión de tokens de acceso con alcances. Los alcances representan los permisos que se le han otorgado a un usuario. +Para implementar el [control de acceso basado en roles (RBAC)](https://auth.wiki/rbac) en tu servidor MCP, tu servidor de autorización debe admitir la emisión de tokens de acceso con alcances. Los alcances representan los permisos que se le han concedido a un usuario. -[Logto](https://logto.io) proporciona soporte para RBAC a través de sus recursos de API (conforme a [RFC 8707: Indicadores de recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) y funciones de roles. Así es como se configura: +[Logto](https://logto.io) proporciona soporte RBAC a través de sus recursos de API (conforme a [RFC 8707: Indicadores de recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) y funciones de roles. Así es como se configura: -1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o en tu Logto Console autoalojado) +1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o tu Logto Console autoalojado) 2. Crea recurso de API y alcances: @@ -88,6 +88,45 @@ Para implementar el [control de acceso basado en roles (RBAC)](https://auth.wiki Los alcances se incluirán en el reclamo `scope` del token de acceso JWT como una cadena separada por espacios. + + + [Asgardeo](https://wso2.com/asgardeo) admite el control de acceso basado en roles (RBAC) y autorización detallada usando recursos de API y alcances. Así es como se configura: + + 1. Inicia sesión en la [Consola Asgardeo](https://console.asgardeo.io) + + 2. Define tu recurso de API y alcances: + - Ve a **Recursos de API** + - Haz clic en **"Nuevo recurso de API"** + - Establece el **Identificador** en `https://todo.mcp-server.app` (o la URL que desees) + - El **Nombre para mostrar** debe ser `Gestor de tareas` + - Añade los siguientes alcances: + - `create:todos` : "Crear nuevas tareas" + - `read:todos` : "Leer todas las tareas" + - `delete:todos` : "Eliminar cualquier tarea" + - Crea el recurso + + 3. Crea roles: + - Usa **Gestión de usuarios > Roles** para crear roles y asignar alcances directamente. + - Haz clic en **Nuevo rol** + - Proporciona el nombre del rol (por ejemplo, `Admin` o `User`) en la sección **Detalles básicos** + - El público del rol debe ser `Aplicación` y selecciona la **Aplicación MCP Inspector** como la **Aplicación asignada** + - En la sección **Selección de permisos**, elige el recurso de API que creaste antes (por ejemplo, `Gestor de tareas`) + - Selecciona los alcances que deseas asignar a este rol (por ejemplo, `create:todos`, `read:todos`, `delete:todos`) + - Haz clic en **Finalizar** para crear el rol + + Si ya creaste la aplicación + - Navega a **Aplicación > Aplicación MCP Inspector > pestaña Roles** + - Selecciona **Rol de aplicación** como tipo de audiencia, luego haz clic en **Nuevo rol** + - Crea un rol `Admin` y adjunta los tres alcances + - Crea un rol `User` y adjunta solo el alcance `create:todos` + + 4. Asigna roles a los usuarios: + - Ve a **Gestión de usuarios > Roles** + - Selecciona el rol que creaste (por ejemplo, `Admin` o `User`) y ve a la pestaña **Usuarios** + - Selecciona **Asignar usuario** y elige los usuarios a los que deseas asignar este rol y guarda. + + Los alcances se incluirán en el reclamo `scope` del token de acceso JWT como una cadena separada por espacios. + @@ -95,7 +134,7 @@ Los proveedores OAuth 2.0 / OIDC suelen admitir el control de acceso basado en a 1. Define los alcances requeridos en tu servidor de autorización 2. Configura tu cliente para solicitar estos alcances durante el flujo de autorización -3. Asegúrate de que tu servidor de autorización incluya los alcances otorgados en el token de acceso +3. Asegúrate de que tu servidor de autorización incluya los alcances concedidos en el token de acceso 4. Los alcances suelen incluirse en el reclamo `scope` del token de acceso JWT Consulta la documentación de tu proveedor para detalles específicos sobre: @@ -115,7 +154,7 @@ Cuando tu servidor MCP recibe una solicitud, debe: 2. Extraer los alcances del token validado 3. Comprobar si el token tiene los alcances requeridos para la operación solicitada -Por ejemplo, si un usuario quiere crear una nueva tarea, su token de acceso debe incluir el alcance `create:todos`. Así funciona el flujo: +Por ejemplo, si un usuario quiere crear una nueva tarea, su token de acceso debe incluir el alcance `create:todos`. Así es como funciona el flujo: ```mermaid sequenceDiagram @@ -149,7 +188,7 @@ El registro dinámico de clientes no es necesario para este tutorial, pero puede ## Comprende RBAC en el gestor de tareas \{#understand-rbac-in-todo-manager} -Con fines demostrativos, implementaremos un sistema sencillo de control de acceso basado en roles (RBAC) en nuestro servidor MCP gestor de tareas. Esto te mostrará los principios básicos de RBAC manteniendo la implementación simple. +Con fines demostrativos, implementaremos un sistema simple de control de acceso basado en roles (RBAC) en nuestro servidor MCP gestor de tareas. Esto te mostrará los principios básicos de RBAC manteniendo la implementación sencilla. :::note Aunque este tutorial demuestra la gestión de alcances basada en RBAC, es importante señalar que no todos los proveedores de autenticación implementan la gestión de alcances a través de roles. Algunos proveedores pueden tener sus propias implementaciones y mecanismos únicos para gestionar el control de acceso y los permisos. @@ -189,12 +228,12 @@ Aunque la tabla de permisos anterior muestra los alcances explícitos asignados - Leer sus propias tareas - Eliminar sus propias tareas - **Los administradores** tienen todos los permisos (`read:todos` y `delete:todos`), lo que les permite: - - Ver todas las tareas del sistema + - Ver todas las tareas en el sistema - Eliminar cualquier tarea, sin importar la propiedad Esto demuestra un patrón común en los sistemas RBAC donde la propiedad de recursos otorga permisos implícitos a los usuarios para sus propios recursos, mientras que los roles administrativos reciben permisos explícitos para todos los recursos. -:::tip Aprende más +:::tip Más información Para profundizar en los conceptos y mejores prácticas de RBAC, consulta [Dominando RBAC: Un ejemplo completo del mundo real](https://blog.logto.io/mastering-rbac). ::: @@ -205,9 +244,9 @@ Para implementar el sistema de control de acceso que describimos antes, deberás -[Logto](https://logto.io) proporciona soporte para RBAC a través de sus recursos de API y funciones de roles. Así es como se configura: +[Logto](https://logto.io) proporciona soporte RBAC a través de sus recursos de API y funciones de roles. Así es como se configura: -1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o en tu Logto Console autoalojado) +1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o tu Logto Console autoalojado) 2. Crea recurso de API y alcances: @@ -227,7 +266,7 @@ Para implementar el sistema de control de acceso que describimos antes, deberás 4. Gestiona roles y permisos de usuario: - Para nuevos usuarios: - - Obtendrán automáticamente el rol "User" ya que lo establecimos como rol predeterminado + - Obtendrán automáticamente el rol "User" ya que lo establecimos como el rol predeterminado - Para usuarios existentes: - Ve a "Gestión de usuarios" - Selecciona un usuario @@ -265,14 +304,62 @@ En [Keycloak](https://www.keycloak.org), puedes configurar los permisos requerid - Asigna roles a los usuarios - De lo contrario, puedes asignar scopes directamente a los usuarios o a través de permisos a nivel de cliente -Keycloak incluirá los scopes otorgados en el reclamo `scope` del token de acceso. +Keycloak incluirá los scopes concedidos en el reclamo `scope` del token de acceso. + + + + +[Asgardeo](https://wso2.com/asgardeo) admite el control de acceso basado en roles (RBAC) y autorización detallada usando recursos de API y alcances. Así es como se configura: + +1. Inicia sesión en la [Consola Asgardeo](https://console.asgardeo.io) + +2. Define tu recurso de API y alcances: + - Ve a **Recursos de API** + - Haz clic en **"Nuevo recurso de API"** + - Establece el **Identificador** en `https://todo.mcp-server.app` (o la URL que desees) + - El **Nombre para mostrar** debe ser `Gestor de tareas` + - Añade los siguientes alcances: + - `create:todos` : "Crear nuevas tareas" + - `read:todos` : "Leer todas las tareas" + - `delete:todos` : "Eliminar cualquier tarea" + - Crea el recurso + +3. Crea roles: + - Usa **Gestión de usuarios > Roles** para crear roles y asignar alcances directamente. + - Haz clic en **Nuevo rol** + - Proporciona el nombre del rol (por ejemplo, `Admin` o `User`) en la sección **Detalles básicos** + - El público del rol debe ser `Aplicación` y selecciona la **Aplicación MCP Inspector** como la **Aplicación asignada** + - En la sección **Selección de permisos**, elige el recurso de API que creaste antes (por ejemplo, `Gestor de tareas`) + - Selecciona los alcances que deseas asignar a este rol (por ejemplo, `create:todos`, `read:todos`, `delete:todos`) + - Haz clic en **Finalizar** para crear el rol + + Si ya creaste la aplicación + - Navega a **Aplicación > Aplicación MCP Inspector > pestaña Roles** + - Selecciona **Rol de aplicación** como tipo de audiencia, luego haz clic en **Nuevo rol** + - Crea un rol `Admin` y adjunta los tres alcances + - Crea un rol `User` y adjunta solo el alcance `create:todos` + +4. Asigna roles a los usuarios: + - Ve a **Gestión de usuarios > Roles** + - Selecciona el rol que creaste (por ejemplo, `Admin` o `User`) y ve a la pestaña **Usuarios** + - Selecciona **Asignar usuario** y elige los usuarios a los que deseas asignar este rol y guarda. + +Los alcances se incluirán en el reclamo `scope` del token de acceso JWT como una cadena separada por espacios. +Después de configurar tu servidor de autorización, los usuarios recibirán tokens de acceso que contienen sus alcances concedidos. El servidor MCP usará estos alcances para determinar: + +Si un usuario puede crear nuevas tareas (`create:todos`) +Si un usuario puede ver todas las tareas (`read:todos`) o solo las suyas +Si un usuario puede eliminar cualquier tarea (`delete:todos`) o solo las suyas +Para más detalles sobre la configuración de Asgardeo, consulta los siguientes recursos: +- [Guía de recursos de API](https://wso2.com/asgardeo/docs/guides/authorization/api-authorization) +- [Gestión de roles](https://wso2.com/asgardeo/docs/guides/users/manage-roles) -Para proveedores OAuth 2.0 u OpenID Connect, deberás configurar los scopes que representan diferentes permisos. Los pasos exactos dependerán de tu proveedor, pero generalmente: +Para proveedores OAuth 2.0 u OpenID Connect, deberás configurar los alcances que representan diferentes permisos. Los pasos exactos dependerán de tu proveedor, pero generalmente: -1. Define scopes: +1. Define alcances: - Configura tu servidor de autorización para admitir: - `create:todos` @@ -281,22 +368,22 @@ Para proveedores OAuth 2.0 u OpenID Connect, deberás configurar los scopes que 2. Configura el cliente: - - Registra o actualiza tu cliente para solicitar estos scopes - - Asegúrate de que los scopes estén incluidos en el token de acceso + - Registra o actualiza tu cliente para solicitar estos alcances + - Asegúrate de que los alcances se incluyan en el token de acceso 3. Asigna permisos: - - Usa la interfaz de tu proveedor para otorgar los scopes apropiados a los usuarios - - Algunos proveedores pueden admitir la gestión basada en roles, mientras que otros pueden usar asignaciones directas de scopes + - Usa la interfaz de tu proveedor para conceder los alcances apropiados a los usuarios + - Algunos proveedores pueden admitir la gestión basada en roles, mientras que otros pueden usar asignaciones directas de alcances - Consulta la documentación de tu proveedor para el enfoque recomendado :::tip -La mayoría de los proveedores incluirán los scopes otorgados en el reclamo `scope` del token de acceso. El formato suele ser una cadena de valores de scope separados por espacios. +La mayoría de los proveedores incluirán los alcances concedidos en el reclamo `scope` del token de acceso. El formato suele ser una cadena de valores de alcance separados por espacios. ::: -Después de configurar tu servidor de autorización, los usuarios recibirán tokens de acceso que contienen los scopes otorgados. El servidor MCP usará estos scopes para determinar: +Después de configurar tu servidor de autorización, los usuarios recibirán tokens de acceso que contienen sus alcances concedidos. El servidor MCP usará estos alcances para determinar: - Si un usuario puede crear nuevas tareas (`create:todos`) - Si un usuario puede ver todas las tareas (`read:todos`) o solo las suyas @@ -332,7 +419,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -Usamos TypeScript en nuestros ejemplos ya que Node.js v22.6.0+ admite la ejecución de TypeScript de forma nativa usando la bandera `--experimental-strip-types`. Si usas JavaScript, el código será similar; solo asegúrate de usar Node.js v22.6.0 o posterior. Consulta la documentación de Node.js para más detalles. +Usamos TypeScript en nuestros ejemplos ya que Node.js v22.6.0+ admite ejecutar TypeScript de forma nativa usando la bandera `--experimental-strip-types`. Si usas JavaScript, el código será similar; solo asegúrate de usar Node.js v22.6.0 o posterior. Consulta la documentación de Node.js para más detalles. ::: @@ -507,7 +594,7 @@ Luego, abre tu navegador y navega a `http://localhost:6274/` (u otra URL mostrad ### Conecta el inspector MCP al servidor MCP \{#connect-mcp-inspector-to-the-mcp-server} -Antes de continuar, verifica la siguiente configuración en el inspector MCP: +Antes de continuar, revisa la siguiente configuración en el inspector MCP: - **Tipo de transporte**: Establece en `SSE`. - **URL**: Establece la URL de tu servidor MCP. En nuestro caso, debe ser `http://localhost:3001/sse`. @@ -518,7 +605,7 @@ Ahora puedes hacer clic en el botón "Connect" para ver si el inspector MCP pued 1. En el menú superior del inspector MCP, haz clic en la pestaña "Tools". 2. Haz clic en el botón "List Tools". -3. Deberías ver las herramientas `create-todo`, `get-todos` y `delete-todo` listadas en la página. Haz clic en una para ver los detalles de la herramienta. +3. Deberías ver las herramientas `create-todo`, `get-todos` y `delete-todo` listadas en la página. Haz clic en ellas para ver los detalles de la herramienta. 4. Deberías ver el botón "Run Tool" en el lado derecho. Haz clic en él e ingresa los parámetros requeridos para ejecutar la herramienta. 5. Deberías ver el resultado de la herramienta con la respuesta JSON `{"error": "No implementado"}`. @@ -531,12 +618,12 @@ Para completar esta sección, hay varias consideraciones a tener en cuenta:
**La URL del emisor de tu servidor de autorización** -Normalmente es la URL base de tu servidor de autorización, como `https://auth.example.com`. Algunos proveedores pueden tener una ruta como `https://example.logto.app/oidc`, así que asegúrate de consultar la documentación de tu proveedor. +Normalmente es la URL base de tu servidor de autorización, como `https://auth.example.com`. Algunos proveedores pueden tener una ruta como `https://example.logto.app/oidc`, así que asegúrate de revisar la documentación de tu proveedor.
-**Cómo obtener los metadatos del servidor de autorización** +**Cómo recuperar los metadatos del servidor de autorización** - Si tu servidor de autorización cumple con [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) o [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), puedes usar las utilidades integradas de MCP Auth para obtener los metadatos automáticamente. - Si tu servidor de autorización no cumple con estos estándares, deberás especificar manualmente la URL de metadatos o los endpoints en la configuración del servidor MCP. Consulta la documentación de tu proveedor para los endpoints específicos. @@ -554,7 +641,7 @@ Normalmente es la URL base de tu servidor de autorización, como `https://auth.e
**Comprende los parámetros de solicitud de token** -Al solicitar tokens de acceso de diferentes servidores de autorización, encontrarás varios enfoques para especificar el recurso objetivo y los permisos. Aquí los principales patrones: +Al solicitar tokens de acceso de diferentes servidores de autorización, encontrarás varios enfoques para especificar el recurso objetivo y los permisos. Aquí están los principales patrones: - **Basado en indicador de recurso**: @@ -567,12 +654,12 @@ Al solicitar tokens de acceso de diferentes servidores de autorización, encontr "scope": "create:todos read:todos" } ``` - - El servidor emite tokens vinculados específicamente al recurso solicitado + - El servidor emite tokens específicamente vinculados al recurso solicitado - **Basado en audiencia**: - Usa el parámetro `audience` para especificar el destinatario previsto del token - - Similar a los indicadores de recurso pero con semántica diferente + - Similar a los indicadores de recurso pero con diferentes semánticas - Ejemplo de solicitud: ```json { @@ -581,8 +668,8 @@ Al solicitar tokens de acceso de diferentes servidores de autorización, encontr } ``` -- **Basado solo en scopes**: - - Se basa únicamente en scopes sin parámetros de recurso/audiencia +- **Basado solo en alcances**: + - Se basa únicamente en alcances sin parámetros de recurso/audiencia - Enfoque tradicional de OAuth 2.0 - Ejemplo de solicitud: ```json @@ -590,7 +677,7 @@ Al solicitar tokens de acceso de diferentes servidores de autorización, encontr "scope": "todo-api:create todo-api:read openid profile" } ``` - - A menudo usa scopes con prefijo para namespacing de permisos + - A menudo usa alcances con prefijo para namespacing de permisos - Común en implementaciones más simples de OAuth 2.0 :::tip Mejores prácticas @@ -603,19 +690,19 @@ Al solicitar tokens de acceso de diferentes servidores de autorización, encontr
-Aunque cada proveedor puede tener sus propios requisitos específicos, los siguientes pasos te guiarán en el proceso de integración del inspector MCP y el servidor MCP con configuraciones específicas del proveedor. +Aunque cada proveedor puede tener sus propios requisitos específicos, los siguientes pasos te guiarán a través del proceso de integración del inspector MCP y el servidor MCP con configuraciones específicas del proveedor. ### Registra el inspector MCP como cliente \{#register-mcp-inspector-as-a-client} -Integrar el gestor de tareas con [Logto](https://logto.io) es sencillo ya que es un proveedor OpenID Connect que admite indicadores de recurso y scopes, lo que te permite asegurar tu API de tareas con `https://todo.mcp-server.app` como indicador de recurso. +Integrar el gestor de tareas con [Logto](https://logto.io) es sencillo ya que es un proveedor OpenID Connect que admite indicadores de recurso y alcances, lo que te permite asegurar tu API de tareas con `https://todo.mcp-server.app` como indicador de recurso. -Dado que Logto aún no admite Dynamic Client Registration, deberás registrar manualmente el inspector MCP como cliente en tu tenant de Logto: +Como Logto aún no admite Dynamic Client Registration, deberás registrar manualmente el inspector MCP como cliente en tu tenant de Logto: 1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. -2. Inicia sesión en [Logto Console](https://cloud.logto.io) (o en tu Logto Console autoalojado). +2. Inicia sesión en [Logto Console](https://cloud.logto.io) (o tu Logto Console autoalojado). 3. Navega a la pestaña "Applications", haz clic en "Create application". En la parte inferior de la página, haz clic en "Create app without framework". 4. Completa los detalles de la aplicación y haz clic en "Create application": - **Selecciona un tipo de aplicación**: Elige "Single-page application". @@ -623,8 +710,42 @@ Dado que Logto aún no admite Dynamic Client Registration, deberás registrar ma 5. En la sección "Settings / Redirect URIs", pega el valor de **Redirect URL (auto-populated)** que copiaste del inspector MCP. Luego haz clic en "Save changes" en la barra inferior. 6. En la tarjeta superior, verás el valor "App ID". Cópialo. 7. Vuelve al inspector MCP y pega el valor "App ID" en la sección "OAuth Configuration" bajo "Client ID". -8. Ingresa el valor `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` en el campo "Auth Params". Esto asegurará que el token de acceso devuelto por Logto contenga los scopes necesarios para acceder al gestor de tareas. +8. Ingresa el valor `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` en el campo "Auth Params". Esto asegurará que el token de acceso devuelto por Logto contenga los alcances necesarios para acceder al gestor de tareas. + + + + Aunque Asgardeo admite el registro dinámico de clientes mediante una API estándar, el endpoint está protegido y requiere un token de acceso con los permisos necesarios. En este tutorial, registraremos el cliente manualmente a través de la Consola Asgardeo. + + :::note + Si no tienes una cuenta de Asgardeo, puedes [registrarte gratis](https://asgardeo.io). + ::: + + Sigue estos pasos para configurar Asgardeo para MCP Inspector: + + 1. Inicia sesión en la [Consola Asgardeo](https://console.asgardeo.io) y selecciona tu organización. + + 2. Crea una nueva aplicación: + - Ve a **Applications** → **New Application** + - Elige **Single-Page Application** + - Ingresa un nombre de aplicación como `MCP Inspector` + - En el campo **Authorized Redirect URLs**, pega la **Redirect URL** copiada de la aplicación cliente MCP Inspector (por ejemplo: `http://localhost:6274/oauth/callback`) + - Haz clic en **Create** + + 3. Configura los ajustes del protocolo: + - Bajo la pestaña **Protocol**: + - Copia el **Client ID** que se generó automáticamente. + - Asegúrate de cambiar a `JWT` para el `Token Type` en la sección **Access Token** + - Haz clic en **Update** + + 4. En la aplicación cliente MCP Inspector: + - Abre la sección **OAuth Configuration** + - Pega el **Client ID** copiado + - Ingresa lo siguiente en el campo **Auth Params** para solicitar los alcances necesarios: + + ```json + { "scope": "openid profile email" } + ``` @@ -632,7 +753,7 @@ Dado que Logto aún no admite Dynamic Client Registration, deberás registrar ma Esta es una guía genérica de integración de proveedor OAuth 2.0 / OpenID Connect. Ambos siguen pasos similares ya que OIDC se basa en OAuth 2.0. Consulta la documentación de tu proveedor para detalles específicos. ::: -Si tu proveedor admite Dynamic Client Registration, puedes ir directamente al paso 8 para configurar el inspector MCP; de lo contrario, deberás registrar manualmente el inspector MCP como cliente: +Si tu proveedor admite Dynamic Client Registration, puedes ir directamente al paso 8 a continuación para configurar el inspector MCP; de lo contrario, deberás registrar manualmente el inspector MCP como cliente: 1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. @@ -648,7 +769,7 @@ Si tu proveedor admite Dynamic Client Registration, puedes ir directamente al pa 7. Vuelve al inspector MCP y pega el valor "Client ID" en la sección "OAuth Configuration" bajo "Client ID". -8. Ingresa el siguiente valor en el campo "Auth Params" para solicitar los scopes necesarios para las operaciones de tareas: +8. Ingresa el siguiente valor en el campo "Auth Params" para solicitar los alcances necesarios para las operaciones de tareas: ```json { "scope": "create:todos read:todos delete:todos" } @@ -696,6 +817,15 @@ La URL del emisor se puede encontrar en la página de detalles de tu aplicación + + + Puedes encontrar la URL del emisor en la Consola Asgardeo. Navega a la aplicación creada y abre la pestaña **Info**. El campo **Issuer** se mostrará allí y debería verse así: + `https://api.asgardeo.io/t//oauth2/token` + + + + + Para proveedores OAuth 2.0, deberás: @@ -747,7 +877,7 @@ const mcpAuth = new MCPAuth({ ### Actualiza el servidor MCP \{#update-mcp-server} -¡Ya casi terminamos! Es momento de actualizar el servidor MCP para aplicar la ruta y función middleware de MCP Auth, luego implementar el control de acceso basado en permisos para las herramientas del gestor de tareas según los scopes del usuario. +¡Ya casi terminamos! Es hora de actualizar el servidor MCP para aplicar la ruta y función middleware de MCP Auth, luego implementar el control de acceso basado en permisos para las herramientas del gestor de tareas según los alcances del usuario. @@ -803,7 +933,7 @@ app.use(mcpAuth.bearerAuth('jwt')); A continuación, implementemos las herramientas específicas. -Primero, vamos a crear un servicio de tareas sencillo para proporcionar operaciones CRUD básicas para gestionar tareas en memoria. +Primero, vamos a crear un servicio simple de tareas para proporcionar operaciones CRUD básicas para gestionar tareas en memoria. @@ -811,7 +941,7 @@ Primero, vamos a crear un servicio de tareas sencillo para proporcionar operacio # service.py """ -Un servicio de tareas sencillo para fines demostrativos. +Un servicio simple de tareas para fines demostrativos. Utiliza una lista en memoria para almacenar tareas. """ @@ -821,7 +951,7 @@ import random import string class Todo: -"""Representa una tarea.""" +"""Representa un elemento de tarea.""" def __init__(self, id: str, content: str, owner_id: str, created_at: str): self.id = id @@ -839,7 +969,7 @@ class Todo: } class TodoService: -"""Un servicio de tareas sencillo para fines demostrativos.""" +"""Un servicio simple de tareas para fines demostrativos.""" def __init__(self): self._todos: List[Todo] = [] @@ -880,10 +1010,10 @@ class TodoService: Args: content: El contenido de la tarea - owner_id: El ID del usuario propietario de la tarea + owner_id: El ID del usuario propietario de esta tarea Returns: - Diccionario de la tarea creada + Representación en diccionario de la tarea creada """ todo = Todo( id=self._generate_id(), @@ -902,7 +1032,7 @@ class TodoService: todo_id: El ID de la tarea a eliminar Returns: - Diccionario de la tarea eliminada si se encuentra, None en caso contrario + Representación en diccionario de la tarea eliminada si se encuentra, None en caso contrario """ for i, todo in enumerate(self._todos): if todo.id == todo_id: @@ -931,7 +1061,7 @@ type Todo = { }; /** - * Un servicio de tareas sencillo para fines demostrativos. + * Un servicio simple de tareas para fines demostrativos. * Usa un array en memoria para almacenar tareas */ export class TodoService { @@ -982,7 +1112,7 @@ export class TodoService { -luego en la capa de herramientas, determinaremos si las operaciones están permitidas según los scopes del usuario: +luego en la capa de herramientas, determinaremos si las operaciones están permitidas según los alcances del usuario: @@ -994,14 +1124,14 @@ from typing import Any, Optional from mcpauth.errors import MCPAuthBearerAuthError def assert_user_id(auth_info: Optional[dict]) -> str: - """Extrae y valida el ID de usuario del auth info.""" + """Extrae y valida el ID de usuario desde la información de autenticación.""" subject = auth_info.get('subject') if auth_info else None if not subject: raise ValueError('Información de autenticación inválida') return subject def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """Comprueba si el usuario tiene todos los scopes requeridos.""" + """Comprueba si el usuario tiene todos los alcances requeridos.""" return all(scope in user_scopes for scope in required_scopes) # Crea una instancia de TodoService @@ -1011,7 +1141,7 @@ todo_service = TodoService() def create_todo(content: str) -> dict[str, Any]: """Crear una nueva tarea. - Solo los usuarios con el scope 'create:todos' pueden crear tareas. + Solo los usuarios con el alcance 'create:todos' pueden crear tareas. """ # Obtiene la información de autenticación auth_info = mcp_auth.auth_info @@ -1035,7 +1165,7 @@ def create_todo(content: str) -> dict[str, Any]: # ... ``` -Puedes consultar nuestro [código de ejemplo](https://github.com/mcp-auth/python/tree/master/samples/server) para todas las implementaciones detalladas. +Puedes consultar nuestro [código de ejemplo](https://github.com/mcp-auth/python/tree/master/samples/server) para todas las demás implementaciones detalladas. @@ -1057,7 +1187,7 @@ const assertUserId = (authInfo?: AuthInfo) => { }; /** - * Comprueba si el usuario tiene todos los scopes requeridos para una operación + * Comprueba si el usuario tiene todos los alcances requeridos para una operación */ const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { return requiredScopes.every((scope) => userScopes.includes(scope)); @@ -1071,7 +1201,7 @@ server.tool( const userId = assertUserId(authInfo); /** - * Solo los usuarios con el scope 'create:todos' pueden crear tareas + * Solo los usuarios con el alcance 'create:todos' pueden crear tareas */ if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { throw new MCPAuthBearerAuthError('missing_required_scopes'); @@ -1088,7 +1218,7 @@ server.tool( // ... ``` -Puedes consultar nuestro [código de ejemplo](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) para todas las implementaciones detalladas. +Puedes consultar nuestro [código de ejemplo](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) para todas las demás implementaciones detalladas. @@ -1099,13 +1229,13 @@ Reinicia tu servidor MCP y abre el inspector MCP en tu navegador. Cuando hagas c Una vez que inicies sesión y regreses al inspector MCP, repite las acciones que hicimos en el punto de control anterior para ejecutar las herramientas del gestor de tareas. Esta vez, puedes usar estas herramientas con tu identidad de usuario autenticada. El comportamiento de las herramientas dependerá de los roles y permisos asignados a tu usuario: -- Si has iniciado sesión como **User** (con solo el scope `create:todos`): +- Si has iniciado sesión como **User** (con solo el alcance `create:todos`): - Puedes crear nuevas tareas usando la herramienta `create-todo` - Solo puedes ver y eliminar tus propias tareas - No podrás ver ni eliminar tareas de otros usuarios -- Si has iniciado sesión como **Admin** (con todos los scopes: `create:todos`, `read:todos`, `delete:todos`): +- Si has iniciado sesión como **Admin** (con todos los alcances: `create:todos`, `read:todos`, `delete:todos`): - Puedes crear nuevas tareas - Puedes ver todas las tareas del sistema usando la herramienta `get-todos` - Puedes eliminar cualquier tarea usando la herramienta `delete-todo`, sin importar quién la creó @@ -1114,7 +1244,7 @@ Puedes probar estos diferentes niveles de permisos: 1. Cerrando la sesión actual (haz clic en el botón "Disconnect" en el inspector MCP) 2. Iniciando sesión con una cuenta de usuario diferente que tenga otros roles/permisos -3. Probando las mismas herramientas de nuevo para observar cómo cambia el comportamiento según los permisos del usuario +3. Probando las mismas herramientas nuevamente para observar cómo cambia el comportamiento según los permisos del usuario Esto demuestra cómo funciona el control de acceso basado en roles (RBAC) en la práctica, donde diferentes usuarios tienen diferentes niveles de acceso a la funcionalidad del sistema. @@ -1124,14 +1254,14 @@ Esto demuestra cómo funciona el control de acceso basado en roles (RBAC) en la :::info -Consulta el [repositorio del SDK de MCP Auth Python](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) para el código completo del servidor MCP (versión OIDC). +Consulta el [repositorio del SDK MCP Auth Python](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) para el código completo del servidor MCP (versión OIDC). ::: :::info -Consulta el [repositorio del SDK de MCP Auth Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) para el código completo del servidor MCP (versión OIDC). +Consulta el [repositorio del SDK MCP Auth Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) para el código completo del servidor MCP (versión OIDC). ::: @@ -1144,6 +1274,6 @@ Consulta el [repositorio del SDK de MCP Auth Node.js](https://github.com/mcp-aut - Configuración de un servidor MCP básico con herramientas de gestión de tareas (`create-todo`, `get-todos`, `delete-todo`) - Implementación de control de acceso basado en roles (RBAC) con diferentes niveles de permisos para usuarios y administradores - Integración del servidor MCP con un servidor de autorización usando MCP Auth -- Configuración del Inspector MCP para autenticar usuarios y usar tokens de acceso con scopes para llamar a herramientas +- Configuración del MCP Inspector para autenticar usuarios y usar tokens de acceso con alcances para llamar a herramientas -Asegúrate de consultar otros tutoriales y documentación para sacar el máximo provecho de MCP Auth. \ No newline at end of file +Asegúrate de consultar otros tutoriales y documentación para aprovechar al máximo MCP Auth. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx index 152faa9..efb9824 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 1 -sidebar_label: 'Tutorial: ¿Quién soy?' +sidebar_label: 'Tutorial: ¿Quién soy yo?' --- import TabItem from '@theme/TabItem'; @@ -9,22 +9,22 @@ import Tabs from '@theme/Tabs'; import SetupOauth from './_setup-oauth.mdx'; import SetupOidc from './_setup-oidc.mdx'; -# Tutorial: ¿Quién soy? (Who am I?) +# Tutorial: ¿Quién soy yo? (Who am I?) -Este tutorial te guiará a través del proceso de configurar MCP Auth para autenticar usuarios y obtener su información de identidad desde el servidor de autorización. +Este tutorial te guiará a través del proceso de configuración de MCP Auth para autenticar usuarios y recuperar su información de identidad desde el servidor de autorización. Después de completar este tutorial, tendrás: - ✅ Una comprensión básica de cómo usar MCP Auth para autenticar usuarios. -- ✅ Un servidor MCP que ofrece una herramienta para obtener información de identidad del usuario. +- ✅ Un servidor MCP que ofrece una herramienta para recuperar información de identidad del usuario. ## Descripción general \{#overview} El tutorial involucrará los siguientes componentes: - **Servidor MCP**: Un servidor MCP sencillo que utiliza los SDKs oficiales de MCP para manejar solicitudes. -- **Inspector MCP**: Una herramienta visual de pruebas para servidores MCP. También actúa como un cliente OAuth / OIDC para iniciar el flujo de autorización y obtener tokens de acceso. -- **Servidor de autorización**: Un proveedor OAuth 2.1 u OpenID Connect que gestiona identidades de usuario y emite tokens de acceso. +- **Inspector MCP**: Una herramienta visual de pruebas para servidores MCP. También actúa como un cliente OAuth / OIDC para iniciar el flujo de autorización y recuperar tokens de acceso. +- **Servidor de autorización (Authorization server)**: Un proveedor OAuth 2.1 u OpenID Connect que gestiona identidades de usuario y emite tokens de acceso. Aquí tienes un diagrama de alto nivel de la interacción entre estos componentes: @@ -49,48 +49,59 @@ sequenceDiagram ## Comprende tu servidor de autorización \{#understand-your-authorization-server} -### Obtener información de identidad del usuario \{#retrieving-user-identity-information} +### Recuperar información de identidad del usuario \{#retrieving-user-identity-information} -Para completar este tutorial, tu servidor de autorización debe ofrecer una API para obtener información de identidad del usuario: +Para completar este tutorial, tu servidor de autorización debe ofrecer una API para recuperar información de identidad del usuario: -[Logto](https://logto.io) es un proveedor OpenID Connect que admite el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) estándar para obtener información de identidad del usuario. +[Logto](https://logto.io) es un proveedor OpenID Connect que admite el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) estándar para recuperar información de identidad del usuario. -Para obtener un token de acceso que pueda usarse para acceder al endpoint userinfo, se requieren al menos dos alcances: `openid` y `profile`. Puedes seguir leyendo, ya que cubriremos la configuración de alcances más adelante. +Para obtener un token de acceso que pueda usarse para acceder al endpoint userinfo, se requieren al menos dos alcances (scopes): `openid` y `profile`. Puedes seguir leyendo, ya que cubriremos la configuración de alcances más adelante. -[Keycloak](https://www.keycloak.org) es una solución de gestión de identidad y acceso de código abierto que admite múltiples protocolos, incluido OpenID Connect (OIDC). Como proveedor OIDC, implementa el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) estándar para obtener información de identidad del usuario. +[Keycloak](https://www.keycloak.org) es una solución de gestión de identidad y acceso de código abierto que admite múltiples protocolos, incluido OpenID Connect (OIDC). Como proveedor OIDC, implementa el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) estándar para recuperar información de identidad del usuario. Para obtener un token de acceso que pueda usarse para acceder al endpoint userinfo, se requieren al menos dos alcances: `openid` y `profile`. Puedes seguir leyendo, ya que cubriremos la configuración de alcances más adelante. + + + + +[Asgardeo](https://wso2.com/asgardeo) es una plataforma de identidad como servicio (IDaaS) nativa en la nube que admite OAuth 2.0 y OpenID Connect (OIDC), proporcionando una gestión robusta de identidad y acceso para aplicaciones modernas. + +La información del usuario se codifica dentro del token de ID devuelto junto con el token de acceso. Pero como proveedor OIDC, Asgardeo expone un [endpoint UserInfo](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/) que permite a las aplicaciones recuperar reclamos sobre el usuario autenticado en el payload. + +También puedes descubrir este endpoint dinámicamente a través del [endpoint de descubrimiento OIDC](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs) o navegando a la pestaña 'Info' de la aplicación en la Consola de Asgardeo. + +Para obtener un token de acceso que pueda usarse para acceder al endpoint userinfo, se requieren al menos dos alcances: `openid` y `profile`. -La mayoría de los proveedores OpenID Connect admiten el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para obtener información de identidad del usuario. +La mayoría de los proveedores OpenID Connect admiten el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar información de identidad del usuario. Consulta la documentación de tu proveedor para ver si admite este endpoint. Si tu proveedor admite [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), también puedes comprobar si el `userinfo_endpoint` está incluido en el documento de descubrimiento (respuesta del endpoint `.well-known/openid-configuration`). -Para obtener un token de acceso que pueda usarse para acceder al endpoint userinfo, se requieren al menos dos alcances: `openid` y `profile`. Consulta la documentación de tu proveedor para ver el mapeo de alcances a reclamos de identidad del usuario. +Para obtener un token de acceso que pueda usarse para acceder al endpoint userinfo, se requieren al menos dos alcances: `openid` y `profile`. Consulta la documentación de tu proveedor para ver el mapeo de alcances a reclamos de identidad de usuario. -Aunque OAuth 2.0 no define una forma estándar de obtener información de identidad del usuario, muchos proveedores implementan sus propios endpoints para hacerlo. Consulta la documentación de tu proveedor para ver cómo obtener información de identidad del usuario usando un token de acceso y qué parámetros se requieren para obtener dicho token al invocar el flujo de autorización. +Aunque OAuth 2.0 no define una forma estándar de recuperar información de identidad del usuario, muchos proveedores implementan sus propios endpoints para hacerlo. Consulta la documentación de tu proveedor para ver cómo recuperar información de identidad del usuario usando un token de acceso y qué parámetros se requieren para obtener dicho token de acceso al invocar el flujo de autorización. -### Registro dinámico de clientes \{#dynamic-client-registration} +### Registro dinámico de clientes (Dynamic Client Registration) \{#dynamic-client-registration} -El registro dinámico de clientes no es necesario para este tutorial, pero puede ser útil si deseas automatizar el proceso de registro del cliente MCP con tu servidor de autorización. Consulta [¿Es necesario el registro dinámico de clientes?](../../provider-list.mdx#is-dcr-required) para más detalles. +El registro dinámico de clientes no es necesario para este tutorial, pero puede ser útil si deseas automatizar el proceso de registro del cliente MCP con tu servidor de autorización. Consulta [¿Se requiere Dynamic Client Registration?](../../provider-list.mdx#is-dcr-required) para más detalles. ## Configura el servidor MCP \{#set-up-the-mcp-server} -Usaremos los [SDKs oficiales de MCP](https://github.com/modelcontextprotocol) para crear un servidor MCP con una herramienta `whoami` que obtiene información de identidad del usuario desde el servidor de autorización. +Usaremos los [SDKs oficiales de MCP](https://github.com/modelcontextprotocol) para crear un servidor MCP con una herramienta `whoami` que recupera información de identidad del usuario desde el servidor de autorización. ### Crea un nuevo proyecto \{#create-a-new-project} @@ -205,7 +216,7 @@ server.tool('whoami', async () => { }; }); -// Abajo está el código boilerplate de la documentación del SDK de MCP +// A continuación el código boilerplate de la documentación del SDK de MCP const PORT = 3001; const app = express(); @@ -265,10 +276,10 @@ Luego, abre tu navegador y navega a `http://localhost:6274/` (u otra URL mostrad ### Conecta el inspector MCP al servidor MCP \{#connect-mcp-inspector-to-the-mcp-server} -Antes de continuar, revisa la siguiente configuración en el inspector MCP: +Antes de continuar, verifica la siguiente configuración en el inspector MCP: -- **Tipo de transporte**: Establece en `SSE`. -- **URL**: Establece la URL de tu servidor MCP. En nuestro caso, debería ser `http://localhost:3001/sse`. +- **Tipo de transporte (Transport Type)**: Establece en `SSE`. +- **URL**: Establece la URL de tu servidor MCP. En nuestro caso, debe ser `http://localhost:3001/sse`. Ahora puedes hacer clic en el botón "Connect" para ver si el inspector MCP puede conectarse al servidor MCP. Si todo está bien, deberías ver el estado "Connected" en el inspector MCP. @@ -287,14 +298,14 @@ Ahora puedes hacer clic en el botón "Connect" para ver si el inspector MCP pued Para completar esta sección, hay varias consideraciones a tener en cuenta:
-**La URL del emisor de tu servidor de autorización** +**La URL del emisor (issuer) de tu servidor de autorización** Normalmente es la URL base de tu servidor de autorización, como `https://auth.example.com`. Algunos proveedores pueden tener una ruta como `https://example.logto.app/oidc`, así que asegúrate de consultar la documentación de tu proveedor.
-**Cómo obtener los metadatos del servidor de autorización** +**Cómo recuperar los metadatos del servidor de autorización** - Si tu servidor de autorización cumple con [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) o [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), puedes usar las utilidades integradas de MCP Auth para obtener los metadatos automáticamente. - Si tu servidor de autorización no cumple con estos estándares, deberás especificar manualmente la URL de metadatos o los endpoints en la configuración del servidor MCP. Consulta la documentación de tu proveedor para los endpoints específicos. @@ -304,19 +315,19 @@ Normalmente es la URL base de tu servidor de autorización, como `https://auth.e
**Cómo registrar el inspector MCP como cliente en tu servidor de autorización** -- Si tu servidor de autorización admite [registro dinámico de clientes](https://datatracker.ietf.org/doc/html/rfc7591), puedes omitir este paso ya que el inspector MCP se registrará automáticamente como cliente. -- Si tu servidor de autorización no admite el registro dinámico de clientes, deberás registrar manualmente el inspector MCP como cliente en tu servidor de autorización. +- Si tu servidor de autorización admite [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), puedes omitir este paso ya que el inspector MCP se registrará automáticamente como cliente. +- Si tu servidor de autorización no admite Dynamic Client Registration, deberás registrar manualmente el inspector MCP como cliente en tu servidor de autorización.
-**Cómo obtener información de identidad del usuario y cómo configurar los parámetros de la solicitud de autorización** +**Cómo recuperar información de identidad del usuario y cómo configurar los parámetros de la solicitud de autorización** -- Para proveedores OpenID Connect: normalmente necesitas solicitar al menos los alcances `openid` y `profile` al iniciar el flujo de autorización. Esto asegurará que el token de acceso devuelto por el servidor de autorización contenga los alcances necesarios para acceder al [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) y obtener información de identidad del usuario. +- Para proveedores OpenID Connect: normalmente necesitas solicitar al menos los alcances `openid` y `profile` al iniciar el flujo de autorización. Esto asegurará que el token de acceso devuelto por el servidor de autorización contenga los alcances necesarios para acceder al [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) y recuperar información de identidad del usuario. Nota: Algunos proveedores pueden no admitir el endpoint userinfo. -- Para proveedores OAuth 2.0 / OAuth 2.1: consulta la documentación de tu proveedor para ver cómo obtener información de identidad del usuario usando un token de acceso y qué parámetros se requieren para obtener dicho token al invocar el flujo de autorización. +- Para proveedores OAuth 2.0 / OAuth 2.1: consulta la documentación de tu proveedor para ver cómo recuperar información de identidad del usuario usando un token de acceso y qué parámetros se requieren para obtener dicho token de acceso al invocar el flujo de autorización.
@@ -327,14 +338,14 @@ Aunque cada proveedor puede tener sus propios requisitos específicos, los sigui -Integrar con [Logto](https://logto.io) es sencillo, ya que es un proveedor OpenID Connect que admite el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) estándar para obtener información de identidad del usuario. +Integrar con [Logto](https://logto.io) es sencillo ya que es un proveedor OpenID Connect que admite el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) estándar para recuperar información de identidad del usuario. -Como Logto aún no admite el registro dinámico de clientes, deberás registrar manualmente el inspector MCP como cliente en tu tenant de Logto: +Como Logto aún no admite Dynamic Client Registration, deberás registrar manualmente el inspector MCP como cliente en tu tenant de Logto: 1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. -2. Inicia sesión en [Logto Console](https://cloud.logto.io) (o tu instancia autoalojada de Logto Console). +2. Inicia sesión en [Logto Console](https://cloud.logto.io) (o tu instancia autogestionada de Logto Console). 3. Navega a la pestaña "Applications", haz clic en "Create application". En la parte inferior de la página, haz clic en "Create app without framework". -4. Completa los detalles de la aplicación y haz clic en "Create application": +4. Rellena los detalles de la aplicación y haz clic en "Create application": - **Selecciona un tipo de aplicación**: Elige "Single-page application". - **Nombre de la aplicación**: Ingresa un nombre para tu aplicación, por ejemplo, "MCP Inspector". 5. En la sección "Settings / Redirect URIs", pega el valor de **Redirect URL (auto-populated)** que copiaste del inspector MCP. Luego haz clic en "Save changes" en la barra inferior. @@ -353,7 +364,7 @@ Aunque Keycloak admite el registro dinámico de clientes, su endpoint de registr Aunque Keycloak puede instalarse de [varias formas](https://www.keycloak.org/guides#getting-started) (bare metal, kubernetes, etc.), para este tutorial, usaremos Docker para una configuración rápida y sencilla. ::: -Vamos a configurar una instancia de Keycloak y ajustarla a nuestras necesidades: +Configura una instancia de Keycloak y ajústala a nuestras necesidades: 1. Primero, ejecuta una instancia de Keycloak usando Docker siguiendo la [documentación oficial](https://www.keycloak.org/getting-started/getting-started-docker): @@ -374,9 +385,9 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM 4. Crea un usuario de prueba: - - Haz clic en "Users" en el menú de la izquierda + - Haz clic en "Users" en el menú izquierdo - Haz clic en "Create new user" - - Completa los detalles del usuario: + - Rellena los detalles del usuario: - Usuario: `testuser` - Nombre y apellido pueden ser cualquier valor - Haz clic en "Create" @@ -385,9 +396,9 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM 5. Registra el inspector MCP como cliente: - Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. - - En la consola de administración de Keycloak, haz clic en "Clients" en el menú de la izquierda + - En la consola de administración de Keycloak, haz clic en "Clients" en el menú izquierdo - Haz clic en "Create client" - - Completa los detalles del cliente: + - Rellena los detalles del cliente: - Tipo de cliente: Selecciona "OpenID Connect" - Client ID: Ingresa `mcp-inspector` - Haz clic en "Next" @@ -408,21 +419,55 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM { "scope": "openid profile email" } ``` - + + + +Aunque Asgardeo admite el registro dinámico de clientes a través de una API estándar, el endpoint está protegido y requiere un token de acceso con los permisos necesarios. En este tutorial, registraremos el cliente manualmente a través de la Consola de Asgardeo. + +:::note +Si no tienes una cuenta de Asgardeo, puedes [registrarte gratis](https://asgardeo.io). +::: + +Sigue estos pasos para configurar Asgardeo para el inspector MCP: + +1. Inicia sesión en la [Consola de Asgardeo](https://console.asgardeo.io) y selecciona tu organización. + +2. Crea una nueva aplicación: + - Ve a **Applications** → **New Application** + - Elige **Single-Page Application** + - Ingresa un nombre de aplicación como `MCP Inspector` + - En el campo **Authorized Redirect URLs**, pega la **Redirect URL** copiada de la aplicación cliente MCP Inspector (por ejemplo: `http://localhost:6274/oauth/callback`) + - Haz clic en **Create** + +3. Configura los ajustes del protocolo: + - Bajo la pestaña **Protocol**: + - Copia el **Client ID** que se generó automáticamente. + - Asegúrate de cambiar a `JWT` en la sección **Access Token** para el `Token Type` + - Haz clic en **Update** + +4. En la aplicación cliente MCP Inspector: + - Abre la sección **OAuth Configuration** + - Pega el **Client ID** copiado + - Ingresa lo siguiente en el campo **Auth Params** para solicitar los alcances necesarios: + +```json +{ "scope": "openid profile email" } +``` + :::note Esta es una guía genérica de integración con proveedores OpenID Connect. Consulta la documentación de tu proveedor para detalles específicos. ::: -Si tu proveedor OpenID Connect admite el registro dinámico de clientes, puedes ir directamente al paso 8 a continuación para configurar el inspector MCP; de lo contrario, deberás registrar manualmente el inspector MCP como cliente en tu proveedor OpenID Connect: +Si tu proveedor OpenID Connect admite Dynamic Client Registration, puedes ir directamente al paso 8 a continuación para configurar el inspector MCP; de lo contrario, deberás registrar manualmente el inspector MCP como cliente en tu proveedor OpenID Connect: 1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. 2. Inicia sesión en la consola de tu proveedor OpenID Connect. 3. Navega a la sección "Applications" o "Clients", luego crea una nueva aplicación o cliente. 4. Si tu proveedor requiere un tipo de cliente, selecciona "Single-page application" o "Public client". 5. Después de crear la aplicación, deberás configurar la URI de redirección. Pega el valor de **Redirect URL (auto-populated)** que copiaste del inspector MCP. -6. Busca el "Client ID" o "Application ID" de la nueva aplicación y cópialo. +6. Busca el "Client ID" o "Application ID" de la aplicación recién creada y cópialo. 7. Vuelve al inspector MCP y pega el valor "Client ID" en la sección "OAuth Configuration" bajo "Client ID". 8. Para proveedores OpenID Connect estándar, puedes ingresar el siguiente valor en el campo "Auth Params" para solicitar los alcances necesarios para acceder al endpoint userinfo: @@ -437,16 +482,16 @@ Si tu proveedor OpenID Connect admite el registro dinámico de clientes, puedes Esta es una guía genérica de integración con proveedores OAuth 2.0 / OAuth 2.1. Consulta la documentación de tu proveedor para detalles específicos. ::: -Si tu proveedor OAuth 2.0 / OAuth 2.1 admite el registro dinámico de clientes, puedes ir directamente al paso 8 a continuación para configurar el inspector MCP; de lo contrario, deberás registrar manualmente el inspector MCP como cliente en tu proveedor OAuth 2.0 / OAuth 2.1: +Si tu proveedor OAuth 2.0 / OAuth 2.1 admite Dynamic Client Registration, puedes ir directamente al paso 8 a continuación para configurar el inspector MCP; de lo contrario, deberás registrar manualmente el inspector MCP como cliente en tu proveedor OAuth 2.0 / OAuth 2.1: 1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. 2. Inicia sesión en la consola de tu proveedor OAuth 2.0 / OAuth 2.1. 3. Navega a la sección "Applications" o "Clients", luego crea una nueva aplicación o cliente. 4. Si tu proveedor requiere un tipo de cliente, selecciona "Single-page application" o "Public client". 5. Después de crear la aplicación, deberás configurar la URI de redirección. Pega el valor de **Redirect URL (auto-populated)** que copiaste del inspector MCP. -6. Busca el "Client ID" o "Application ID" de la nueva aplicación y cópialo. +6. Busca el "Client ID" o "Application ID" de la aplicación recién creada y cópialo. 7. Vuelve al inspector MCP y pega el valor "Client ID" en la sección "OAuth Configuration" bajo "Client ID". -8. Lee la documentación de tu proveedor para ver cómo obtener tokens de acceso para información de identidad del usuario. Es posible que debas especificar los alcances o parámetros requeridos para obtener el token de acceso. Por ejemplo, si tu proveedor requiere el alcance `profile` para acceder a la información de identidad del usuario, puedes ingresar el siguiente valor en el campo "Auth Params": +8. Lee la documentación de tu proveedor para ver cómo recuperar tokens de acceso para información de identidad del usuario. Puede que necesites especificar los alcances o parámetros requeridos para obtener el token de acceso. Por ejemplo, si tu proveedor requiere el alcance `profile` para acceder a la información de identidad del usuario, puedes ingresar el siguiente valor en el campo "Auth Params": ```json { "scope": "profile" } @@ -455,9 +500,9 @@ Si tu proveedor OAuth 2.0 / OAuth 2.1 admite el registro dinámico de clientes, -### Configura MCP Auth \{#set-up-mcp-auth} +### Configura MCP auth \{#set-up-mcp-auth} -En tu proyecto del servidor MCP, necesitas instalar el SDK de MCP Auth y configurarlo para usar los metadatos de tu servidor de autorización. +En tu proyecto de servidor MCP, necesitas instalar el SDK de MCP Auth y configurarlo para usar los metadatos de tu servidor de autorización. @@ -488,7 +533,7 @@ MCP Auth requiere los metadatos del servidor de autorización para poder inicial -La URL del emisor se puede encontrar en la página de detalles de tu aplicación en Logto Console, en la sección "Endpoints & Credentials / Issuer endpoint". Debería verse como `https://my-project.logto.app/oidc`. +La URL del emisor (issuer) se puede encontrar en la página de detalles de tu aplicación en Logto Console, en la sección "Endpoints & Credentials / Issuer endpoint". Debería verse como `https://my-project.logto.app/oidc`. @@ -496,22 +541,31 @@ La URL del emisor se puede encontrar en la página de detalles de tu aplicación -La URL del emisor se puede encontrar en tu consola de administración de Keycloak. En tu 'mcp-realm', navega a la sección "Realm settings / Endpoints" y haz clic en el enlace "OpenID Endpoint Configuration". El campo `issuer` en el documento JSON contendrá tu URL de emisor, que debería verse como `http://localhost:8080/realms/mcp-realm`. +La URL del emisor (issuer) se puede encontrar en tu consola de administración de Keycloak. En tu 'mcp-realm', navega a la sección "Realm settings / Endpoints" y haz clic en el enlace "OpenID Endpoint Configuration". El campo `issuer` en el documento JSON contendrá tu URL de emisor, que debería verse como `http://localhost:8080/realms/mcp-realm`. + + + Puedes encontrar la URL del emisor en la Consola de Asgardeo. Navega a la aplicación creada y abre la pestaña **Info**. El campo **Issuer** se mostrará allí y debería verse así: + `https://api.asgardeo.io/t//oauth2/token` + + + + + -El siguiente código también asume que el servidor de autorización admite el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para obtener información de identidad del usuario. Si tu proveedor no admite este endpoint, deberás consultar la documentación de tu proveedor para el endpoint específico y reemplazar la variable del endpoint userinfo con la URL correcta. +El siguiente código también asume que el servidor de autorización admite el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar información de identidad del usuario. Si tu proveedor no admite este endpoint, deberás consultar la documentación de tu proveedor para el endpoint específico y reemplazar la variable del endpoint userinfo con la URL correcta. -Como mencionamos antes, OAuth 2.0 no define una forma estándar de obtener información de identidad del usuario. El siguiente código asume que tu proveedor tiene un endpoint específico para obtener información de identidad del usuario usando un token de acceso. Deberás consultar la documentación de tu proveedor para el endpoint específico y reemplazar la variable del endpoint userinfo con la URL correcta. +Como mencionamos antes, OAuth 2.0 no define una forma estándar de recuperar información de identidad del usuario. El siguiente código asume que tu proveedor tiene un endpoint específico para recuperar información de identidad del usuario usando un token de acceso. Deberás consultar la documentación de tu proveedor para el endpoint específico y reemplazar la variable del endpoint userinfo con la URL correcta. @@ -531,7 +585,7 @@ def whoami() -> dict[str, Any]: """Una herramienta que retorna la información del usuario actual.""" return ( mcp_auth.auth_info.claims - if mcp_auth.auth_info # Esto será poblado por el middleware Bearer auth + if mcp_auth.auth_info # Esto será completado por el middleware Bearer auth else {"error": "Not authenticated"} ) @@ -596,11 +650,11 @@ Consulta el [repositorio del SDK de MCP Auth para Node.js](https://github.com/mc ## Notas finales \{#closing-notes} -🎊 ¡Felicidades! Has completado exitosamente el tutorial. Recapitulemos lo que hemos hecho: +🎊 ¡Felicidades! Has completado con éxito el tutorial. Recapitulemos lo que hemos hecho: - Configuración de un servidor MCP básico con la herramienta `whoami` - Integración del servidor MCP con un servidor de autorización usando MCP Auth -- Configuración del Inspector MCP para autenticar usuarios y obtener su información de identidad +- Configuración del Inspector MCP para autenticar usuarios y recuperar su información de identidad También puedes explorar algunos temas avanzados, incluyendo: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index a628aa1..cd0ec53 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -11,22 +11,22 @@ import SetupOidc from './_setup-oidc.mdx'; # Tutoriel : Créer un gestionnaire de tâches -Dans ce tutoriel, nous allons construire un serveur MCP de gestionnaire de tâches avec authentification et autorisation des utilisateurs. +Dans ce tutoriel, nous allons construire un serveur MCP gestionnaire de tâches avec authentification et autorisation des utilisateurs. Après avoir terminé ce tutoriel, vous aurez : -- ✅ Une compréhension de base de la configuration du contrôle d’accès basé sur les rôles (RBAC) dans votre serveur MCP. +- ✅ Une compréhension de base de la mise en place du contrôle d’accès basé sur les rôles (RBAC) dans votre serveur MCP. - ✅ Un serveur MCP capable de gérer des listes de tâches personnelles. :::note Avant de commencer, nous vous recommandons fortement de suivre d'abord le [tutoriel Who am I](./whoami) si vous n'êtes pas familier avec le serveur MCP et OAuth 2. ::: -## Aperçu \{#overview} +## Vue d’ensemble \{#overview} Le tutoriel impliquera les composants suivants : -- **Serveur MCP** : Un serveur MCP simple qui utilise les SDK officiels MCP pour gérer les requêtes, avec un service Todo intégré pour gérer les tâches de l'utilisateur. +- **Serveur MCP** : Un serveur MCP simple qui utilise les SDK officiels MCP pour gérer les requêtes, avec un service Todo intégré pour la gestion des tâches utilisateur. - **Inspecteur MCP** : Un outil de test visuel pour les serveurs MCP. Il agit également comme un client OAuth / OIDC pour initier le flux d’autorisation et récupérer les jetons d’accès. - **Serveur d’autorisation** : Un fournisseur OAuth 2.1 ou OpenID Connect qui gère les identités des utilisateurs et délivre les jetons d’accès. @@ -38,56 +38,95 @@ sequenceDiagram participant Server as Serveur MCP participant Auth as Serveur d’autorisation - Client->>Server: Demander une opération todo - Server->>Client: Retourner 401 Non autorisé - Client->>Auth: Initier le flux d’autorisation - Auth->>Auth: Compléter le flux d’autorisation - Auth->>Client: Rediriger avec le code d’autorisation - Client->>Auth: Échanger le code contre un jeton d’accès - Auth->>Client: Retourner le jeton d’accès - Client->>Server: Demander une opération todo avec le jeton d’accès - Server->>Server: Valider le jeton d’accès et obtenir les portées utilisateur depuis le jeton d’accès - Note over Server: Exécuter l’opération todo - Server->>Client: Retourner le résultat de l’opération todo + Client->>Server: Demande d’opération todo + Server->>Client: Retourne 401 Non autorisé + Client->>Auth: Initie le flux d’autorisation + Auth->>Auth: Complète le flux d’autorisation + Auth->>Client: Redirige avec le code d’autorisation + Client->>Auth: Échange le code contre un jeton d’accès + Auth->>Client: Retourne le jeton d’accès + Client->>Server: Demande d’opération todo avec jeton d’accès + Server->>Server: Valide le jeton d’accès et récupère les portées utilisateur depuis le jeton d’accès + Note over Server: Exécute l’opération todo + Server->>Client: Retourne le résultat de l’opération todo ``` ## Comprendre votre serveur d’autorisation \{#understand-your-authorization-server} ### Jetons d’accès avec portées \{#access-tokens-with-scopes} -Pour mettre en œuvre le [contrôle d’accès basé sur les rôles (RBAC)](https://auth.wiki/rbac) dans votre serveur MCP, votre serveur d’autorisation doit prendre en charge l’émission de jetons d’accès avec des portées. Les portées représentent les permissions accordées à un utilisateur. +Pour mettre en œuvre le contrôle d’accès basé sur les rôles (RBAC) dans votre serveur MCP, votre serveur d’autorisation doit prendre en charge l’émission de jetons d’accès avec des portées. Les portées représentent les permissions accordées à un utilisateur. -[Logto](https://logto.io) fournit la prise en charge du RBAC via ses ressources API (conformes à [RFC 8707 : Indicateurs de ressource pour OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) et ses fonctionnalités de rôles. Voici comment le configurer : +[Logto](https://logto.io) propose la prise en charge du RBAC via ses ressources API (conformes à la [RFC 8707 : Indicateurs de ressource pour OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) et ses fonctionnalités de rôles. Voici comment le configurer : -1. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre propre instance Logto Console) +1. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre Logto Console auto-hébergée) 2. Créez une ressource API et des portées : - Allez dans "Ressources API" - - Créez une nouvelle ressource API nommée "Todo Manager" + - Créez une nouvelle ressource API nommée "Gestionnaire de tâches" - Ajoutez les portées suivantes : - `create:todos` : "Créer de nouvelles tâches" - `read:todos` : "Lire toutes les tâches" - `delete:todos` : "Supprimer n’importe quelle tâche" -3. Créez des rôles (recommandé pour une gestion plus simple) : +3. Créez des rôles (recommandé pour une gestion plus facile) : - Allez dans "Rôles" - - Créez un rôle "Admin" et assignez toutes les portées (`create:todos`, `read:todos`, `delete:todos`) - - Créez un rôle "User" et assignez uniquement la portée `create:todos` + - Créez un rôle "Admin" et assignez-lui toutes les portées (`create:todos`, `read:todos`, `delete:todos`) + - Créez un rôle "Utilisateur" et assignez-lui uniquement la portée `create:todos` -4. Assignez les permissions : +4. Attribuez les permissions : - Allez dans "Utilisateurs" - Sélectionnez un utilisateur - Vous pouvez soit : - - Assigner des rôles dans l’onglet "Rôles" (recommandé) - - Ou assigner directement des portées dans l’onglet "Permissions" + - Attribuer des rôles dans l’onglet "Rôles" (recommandé) + - Ou attribuer directement des portées dans l’onglet "Permissions" Les portées seront incluses dans la revendication `scope` du jeton d’accès JWT sous forme de chaîne séparée par des espaces. + + + [Asgardeo](https://wso2.com/asgardeo) prend en charge le contrôle d’accès basé sur les rôles (RBAC) et l’autorisation fine via les ressources API et les portées. Voici comment le configurer : + + 1. Connectez-vous à la [Console Asgardeo](https://console.asgardeo.io) + + 2. Définissez votre ressource API et vos portées : + - Allez dans **Ressources API** + - Cliquez sur **"Nouvelle ressource API"** + - Définissez l’**Identifiant** sur `https://todo.mcp-server.app` (ou l’URL souhaitée) + - Laissez le **Nom d’affichage** à `Gestionnaire de tâches` + - Ajoutez les portées suivantes : + - `create:todos` : "Créer de nouvelles tâches" + - `read:todos` : "Lire toutes les tâches" + - `delete:todos` : "Supprimer n’importe quelle tâche" + - Créez la ressource + + 3. Créez des rôles : + - Utilisez **Gestion des utilisateurs > Rôles** pour créer des rôles et attribuer directement les portées. + - Cliquez sur **Nouveau rôle** + - Indiquez le nom du rôle (par exemple, `Admin` ou `Utilisateur`) dans la section **Détails de base** + - Laissez l’audience du rôle à `Application` et sélectionnez l’**Application MCP Inspector** comme **Application assignée** + - Dans la section **Sélection des permissions**, choisissez la ressource API créée précédemment (par exemple, `Gestionnaire de tâches`) + - Sélectionnez les portées à attribuer à ce rôle (par exemple, `create:todos`, `read:todos`, `delete:todos`) + - Cliquez sur **Terminer** pour créer le rôle + + Si vous avez déjà créé l’application + - Naviguez vers **Application > MCP Inspector Application > Onglet Rôles** + - Sélectionnez **Rôle d’application** comme type d’audience, puis cliquez sur **Nouveau rôle** + - Créez un rôle `Admin` et attachez-lui les trois portées + - Créez un rôle `Utilisateur` et attachez-lui uniquement la portée `create:todos` + + 4. Attribuez les rôles aux utilisateurs : + - Allez dans **Gestion des utilisateurs > Rôles** + - Sélectionnez le rôle créé (par exemple, `Admin` ou `Utilisateur`) et passez à l’onglet **Utilisateurs** + - Sélectionnez **Attribuer un utilisateur** et choisissez les utilisateurs à qui attribuer ce rôle, puis enregistrez. + + Les portées seront incluses dans la revendication `scope` du jeton d’accès JWT sous forme de chaîne séparée par des espaces. + @@ -98,7 +137,7 @@ Les fournisseurs OAuth 2.0 / OIDC prennent généralement en charge le contrôle 3. Assurez-vous que votre serveur d’autorisation inclut les portées accordées dans le jeton d’accès 4. Les portées sont généralement incluses dans la revendication `scope` du jeton d’accès JWT -Consultez la documentation de votre fournisseur pour les détails spécifiques sur : +Consultez la documentation de votre fournisseur pour plus de détails sur : - Comment définir et gérer les portées - Comment les portées sont incluses dans le jeton d’accès @@ -126,20 +165,20 @@ sequenceDiagram Client->>MCP Server: Requête avec jeton d’accès alt Validation JWT - MCP Server->>Auth Server: Récupérer JWKS - Auth Server-->>MCP Server: Retourner JWKS - MCP Server->>MCP Server: Valider le JWT localement + MCP Server->>Auth Server: Récupère JWKS + Auth Server-->>MCP Server: Retourne JWKS + MCP Server->>MCP Server: Valide le JWT localement else Introspection du jeton MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: Retourner les infos du jeton
(active, scope, etc.) + Auth Server-->>MCP Server: Retourne les infos du jeton
(actif, scope, etc.) end - MCP Server->>MCP Server: Extraire & vérifier les portées + MCP Server->>MCP Server: Extrait & vérifie les portées alt Possède les portées requises - MCP Server->>Client: Autoriser l’opération + MCP Server->>Client: Autorise l’opération else Portées manquantes - MCP Server->>Client: Retourner 403 Interdit + MCP Server->>Client: Retourne 403 Interdit end ``` @@ -149,7 +188,7 @@ L’enregistrement dynamique de client n’est pas requis pour ce tutoriel, mais ## Comprendre le RBAC dans le gestionnaire de tâches \{#understand-rbac-in-todo-manager} -À des fins de démonstration, nous allons mettre en œuvre un système simple de contrôle d’accès basé sur les rôles (RBAC) dans notre serveur MCP gestionnaire de tâches. Cela vous montrera les principes de base du RBAC tout en gardant l’implémentation simple. +À des fins de démonstration, nous allons implémenter un système simple de contrôle d’accès basé sur les rôles (RBAC) dans notre serveur MCP gestionnaire de tâches. Cela vous montrera les principes de base du RBAC tout en gardant l’implémentation simple. :::note Bien que ce tutoriel démontre la gestion des portées basée sur le RBAC, il est important de noter que tous les fournisseurs d’authentification n’implémentent pas la gestion des portées via les rôles. Certains fournisseurs peuvent avoir leurs propres mécanismes uniques pour gérer le contrôle d’accès et les permissions. @@ -171,14 +210,14 @@ Pour contrôler l’accès à ces outils, nous définissons les portées suivant ### Rôles et permissions \{#roles-and-permissions} -Nous allons définir deux rôles avec différents niveaux d’accès : +Nous définirons deux rôles avec différents niveaux d’accès : -| Rôle | create:todos | read:todos | delete:todos | -| ----- | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | +| Rôle | create:todos | read:todos | delete:todos | +| ------ | ------------ | ---------- | ------------ | +| Admin | ✅ | ✅ | ✅ | +| User | ✅ | | | -- **User** : Un utilisateur régulier qui peut créer des tâches et voir ou supprimer uniquement ses propres tâches +- **Utilisateur** : Un utilisateur régulier qui peut créer des tâches et voir ou supprimer uniquement ses propres tâches - **Admin** : Un administrateur qui peut créer, voir et supprimer toutes les tâches, quel que soit le propriétaire ### Propriété des ressources \{#resource-ownership} @@ -188,56 +227,56 @@ Bien que le tableau des permissions ci-dessus montre les portées explicites att - **Les utilisateurs** n’ont pas les portées `read:todos` ou `delete:todos`, mais ils peuvent quand même : - Lire leurs propres tâches - Supprimer leurs propres tâches -- **Les admins** ont toutes les permissions (`read:todos` et `delete:todos`), ce qui leur permet de : +- **Les admins** disposent de toutes les permissions (`read:todos` et `delete:todos`), ce qui leur permet de : - Voir toutes les tâches du système - Supprimer n’importe quelle tâche, quel que soit le propriétaire Cela illustre un schéma courant dans les systèmes RBAC où la propriété d’une ressource accorde des permissions implicites aux utilisateurs pour leurs propres ressources, tandis que les rôles administratifs reçoivent des permissions explicites pour toutes les ressources. :::tip En savoir plus -Pour approfondir les concepts et bonnes pratiques du RBAC, consultez [Maîtriser le RBAC : Un exemple complet du monde réel](https://blog.logto.io/mastering-rbac). +Pour approfondir les concepts et bonnes pratiques du RBAC, consultez [Maîtriser le RBAC : Un exemple complet et concret](https://blog.logto.io/mastering-rbac). ::: ## Configurer l’autorisation dans votre fournisseur \{#configure-authorization-in-your-provider} -Pour mettre en œuvre le système de contrôle d’accès décrit précédemment, vous devrez configurer votre serveur d’autorisation pour prendre en charge les portées requises. Voici comment faire avec différents fournisseurs : +Pour mettre en œuvre le système de contrôle d’accès décrit précédemment, vous devrez configurer votre serveur d’autorisation pour prendre en charge les portées requises. Voici comment procéder avec différents fournisseurs : -[Logto](https://logto.io) fournit la prise en charge du RBAC via ses ressources API et ses fonctionnalités de rôles. Voici comment le configurer : +[Logto](https://logto.io) propose la prise en charge du RBAC via ses ressources API et ses fonctionnalités de rôles. Voici comment le configurer : -1. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre propre instance Logto Console) +1. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre Logto Console auto-hébergée) 2. Créez une ressource API et des portées : - Allez dans "Ressources API" - - Créez une nouvelle ressource API nommée "Todo Manager" et utilisez `https://todo.mcp-server.app` (à des fins de démonstration) comme indicateur. + - Créez une nouvelle ressource API nommée "Gestionnaire de tâches" et utilisez `https://todo.mcp-server.app` (à des fins de démonstration) comme indicateur. - Créez les portées suivantes : - `create:todos` : "Créer de nouvelles tâches" - `read:todos` : "Lire toutes les tâches" - `delete:todos` : "Supprimer n’importe quelle tâche" -3. Créez des rôles (recommandé pour une gestion plus simple) : +3. Créez des rôles (recommandé pour une gestion plus facile) : - Allez dans "Rôles" - - Créez un rôle "Admin" et assignez toutes les portées (`create:todos`, `read:todos`, `delete:todos`) - - Créez un rôle "User" et assignez uniquement la portée `create:todos` - - Dans la page de détails du rôle "User", passez à l’onglet "Général" et définissez le rôle "User" comme "Rôle par défaut". + - Créez un rôle "Admin" et assignez-lui toutes les portées (`create:todos`, `read:todos`, `delete:todos`) + - Créez un rôle "Utilisateur" et assignez-lui uniquement la portée `create:todos` + - Dans la page de détails du rôle "Utilisateur", passez à l’onglet "Général" et définissez le rôle "Utilisateur" comme "Rôle par défaut". 4. Gérez les rôles et permissions des utilisateurs : - Pour les nouveaux utilisateurs : - - Ils recevront automatiquement le rôle "User" puisque nous l’avons défini comme rôle par défaut + - Ils recevront automatiquement le rôle "Utilisateur" puisque nous l’avons défini comme rôle par défaut - Pour les utilisateurs existants : - Allez dans "Gestion des utilisateurs" - Sélectionnez un utilisateur - - Assignez des rôles à l’utilisateur dans l’onglet "Rôles" + - Attribuez des rôles à l’utilisateur dans l’onglet "Rôles" :::tip Gestion programmatique des rôles Vous pouvez également utiliser la [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) de Logto pour gérer les rôles des utilisateurs de manière programmatique. Ceci est particulièrement utile pour la gestion automatisée des utilisateurs ou lors de la création de panneaux d’administration. ::: -Lors de la demande d’un jeton d’accès, Logto inclura les portées dans la revendication `scope` du jeton en fonction des permissions de rôle de l’utilisateur. +Lors de la demande d’un jeton d’accès, Logto inclura les portées dans la revendication `scope` du jeton en fonction des permissions du rôle de l’utilisateur. @@ -246,7 +285,7 @@ Dans [Keycloak](https://www.keycloak.org), vous pouvez configurer les permission 1. Créez des portées client : - - Dans votre realm, allez dans "Client scopes" + - Dans votre realm, allez dans "Portées client" - Créez trois nouvelles portées client : - `create:todos` - `read:todos` @@ -255,38 +294,86 @@ Dans [Keycloak](https://www.keycloak.org), vous pouvez configurer les permission 2. Configurez le client : - Allez dans les paramètres de votre client - - Dans l’onglet "Client scopes", ajoutez toutes les portées que vous avez créées - - Assurez-vous que le mappage du jeton est configuré pour inclure les portées + - Dans l’onglet "Portées client", ajoutez toutes les portées que vous avez créées + - Assurez-vous que le mappage de jeton est configuré pour inclure les portées -3. Optionnel : Utilisez les rôles pour une gestion plus simple - - Si vous préférez la gestion basée sur les rôles : +3. Optionnel : Utilisez les rôles pour une gestion plus facile + - Si vous préférez une gestion basée sur les rôles : - Créez des rôles de realm pour différents niveaux d’accès - Mappez les portées aux rôles - - Assignez les rôles aux utilisateurs - - Sinon, vous pouvez assigner directement les portées aux utilisateurs ou via les permissions au niveau du client + - Attribuez les rôles aux utilisateurs + - Sinon, vous pouvez attribuer directement les portées aux utilisateurs ou via les permissions au niveau du client Keycloak inclura les portées accordées dans la revendication `scope` du jeton d’accès. + + + +[Asgardeo](https://wso2.com/asgardeo) prend en charge le contrôle d’accès basé sur les rôles (RBAC) et l’autorisation fine via les ressources API et les portées. Voici comment le configurer : + +1. Connectez-vous à la [Console Asgardeo](https://console.asgardeo.io) + +2. Définissez votre ressource API et vos portées : + - Allez dans **Ressources API** + - Cliquez sur **"Nouvelle ressource API"** + - Définissez l’**Identifiant** sur `https://todo.mcp-server.app` (ou l’URL souhaitée) + - Laissez le **Nom d’affichage** à `Gestionnaire de tâches` + - Ajoutez les portées suivantes : + - `create:todos` : "Créer de nouvelles tâches" + - `read:todos` : "Lire toutes les tâches" + - `delete:todos` : "Supprimer n’importe quelle tâche" + - Créez la ressource + +3. Créez des rôles : + - Utilisez **Gestion des utilisateurs > Rôles** pour créer des rôles et attribuer directement les portées. + - Cliquez sur **Nouveau rôle** + - Indiquez le nom du rôle (par exemple, `Admin` ou `Utilisateur`) dans la section **Détails de base** + - Laissez l’audience du rôle à `Application` et sélectionnez l’**Application MCP Inspector** comme **Application assignée** + - Dans la section **Sélection des permissions**, choisissez la ressource API créée précédemment (par exemple, `Gestionnaire de tâches`) + - Sélectionnez les portées à attribuer à ce rôle (par exemple, `create:todos`, `read:todos`, `delete:todos`) + - Cliquez sur **Terminer** pour créer le rôle + + Si vous avez déjà créé l’application + - Naviguez vers **Application > MCP Inspector Application > Onglet Rôles** + - Sélectionnez **Rôle d’application** comme type d’audience, puis cliquez sur **Nouveau rôle** + - Créez un rôle `Admin` et attachez-lui les trois portées + - Créez un rôle `Utilisateur` et attachez-lui uniquement la portée `create:todos` + +4. Attribuez les rôles aux utilisateurs : + - Allez dans **Gestion des utilisateurs > Rôles** + - Sélectionnez le rôle créé (par exemple, `Admin` ou `Utilisateur`) et passez à l’onglet **Utilisateurs** + - Sélectionnez **Attribuer un utilisateur** et choisissez les utilisateurs à qui attribuer ce rôle, puis enregistrez. + +Les portées seront incluses dans la revendication `scope` du jeton d’accès JWT sous forme de chaîne séparée par des espaces. +Après avoir configuré votre serveur d’autorisation, les utilisateurs recevront des jetons d’accès contenant leurs portées accordées. Le serveur MCP utilisera ces portées pour déterminer : + +Si un utilisateur peut créer de nouvelles tâches (`create:todos`) +Si un utilisateur peut voir toutes les tâches (`read:todos`) ou seulement les siennes +Si un utilisateur peut supprimer n’importe quelle tâche (`delete:todos`) ou seulement les siennes + +Pour plus de détails sur la configuration d’Asgardeo, consultez les ressources suivantes : +- [Guide des ressources API](https://wso2.com/asgardeo/docs/guides/authorization/api-authorization) +- [Gestion des rôles](https://wso2.com/asgardeo/docs/guides/users/manage-roles) Pour les fournisseurs OAuth 2.0 ou OpenID Connect, vous devrez configurer les portées qui représentent différentes permissions. Les étapes exactes dépendront de votre fournisseur, mais généralement : -1. Définissez les portées : +1. Définir les portées : - Configurez votre serveur d’autorisation pour prendre en charge : - `create:todos` - `read:todos` - `delete:todos` -2. Configurez le client : +2. Configurer le client : - Enregistrez ou mettez à jour votre client pour demander ces portées - Assurez-vous que les portées sont incluses dans le jeton d’accès -3. Assignez les permissions : +3. Attribuer les permissions : - Utilisez l’interface de votre fournisseur pour accorder les portées appropriées aux utilisateurs - - Certains fournisseurs peuvent prendre en charge la gestion basée sur les rôles, tandis que d’autres utilisent des attributions directes de portées + - Certains fournisseurs peuvent prendre en charge la gestion basée sur les rôles, tandis que d’autres utilisent des attributions de portées directes - Consultez la documentation de votre fournisseur pour l’approche recommandée :::tip @@ -302,848 +389,4 @@ Après avoir configuré votre serveur d’autorisation, les utilisateurs recevro - Si un utilisateur peut voir toutes les tâches (`read:todos`) ou seulement les siennes - Si un utilisateur peut supprimer n’importe quelle tâche (`delete:todos`) ou seulement les siennes -## Mettre en place le serveur MCP \{#set-up-the-mcp-server} - -Nous allons utiliser les [SDK officiels MCP](https://github.com/modelcontextprotocol) pour créer notre serveur MCP gestionnaire de tâches. - -### Créer un nouveau projet \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # Ou utilisez `pipenv` ou `poetry` pour créer un nouvel environnement virtuel -``` - - - - -Créez un nouveau projet Node.js : - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # Ou utilisez `pnpm init` -npm pkg set type="module" -npm pkg set main="todo-manager.ts" -npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" -``` - -:::note -Nous utilisons TypeScript dans nos exemples car Node.js v22.6.0+ prend en charge l’exécution native de TypeScript avec l’option `--experimental-strip-types`. Si vous utilisez JavaScript, le code sera similaire – assurez-vous simplement d’utiliser Node.js v22.6.0 ou ultérieur. Voir la documentation Node.js pour plus de détails. -::: - - - - -### Installer le SDK MCP et les dépendances \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme `uv` ou `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express zod -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme `pnpm` ou `yarn`. - - - - -### Créer le serveur MCP \{#create-the-mcp-server} - -Commençons par créer un serveur MCP de base avec la définition des outils : - - - - -Créez un fichier nommé `todo-manager.py` et ajoutez le code suivant : - -```python -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -mcp = FastMCP("Todo Manager") - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Créer une nouvelle tâche.""" - return {"error": "Non implémenté"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """Lister toutes les tâches.""" - return {"error": "Non implémenté"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """Supprimer une tâche par id.""" - return {"error": "Non implémenté"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Lancez le serveur avec : - -```bash -uvicorn todo_manager:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Comme l’implémentation actuelle de l’inspecteur MCP ne gère pas les flux d’autorisation, nous utiliserons l’approche SSE pour mettre en place le serveur MCP. Nous mettrons à jour le code ici dès que l’inspecteur MCP prendra en charge les flux d’autorisation. -::: - -Vous pouvez également utiliser `pnpm` ou `yarn` si vous préférez. - -Créez un fichier nommé `todo-manager.ts` et ajoutez le code suivant : - -```ts -// todo-manager.ts - -import { z } from 'zod'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// Créer un serveur MCP -const server = new McpServer({ - name: 'Todo Manager', - version: '0.0.0', -}); - -server.tool('create-todo', 'Créer une nouvelle tâche', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Non implémenté' }) }], - }; -}); - -server.tool('get-todos', 'Lister toutes les tâches', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Non implémenté' }) }], - }; -}); - -server.tool('delete-todo', 'Supprimer une tâche par id', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Non implémenté' }) }], - }; -}); - -// Ci-dessous le code standard issu de la documentation du SDK MCP -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('Aucun transport trouvé pour ce sessionId'); - } -}); - -app.listen(PORT); -``` - -Lancez le serveur avec : - -```bash -npm start -``` - - - - -## Inspecter le serveur MCP \{#inspect-the-mcp-server} - -### Cloner et lancer l’inspecteur MCP \{#clone-and-run-mcp-inspector} - -Maintenant que nous avons le serveur MCP en fonctionnement, nous pouvons utiliser l’inspecteur MCP pour vérifier si l’outil `whoami` est disponible. - -En raison des limitations de l’implémentation actuelle, nous avons forké l’[inspecteur MCP](https://github.com/mcp-auth/inspector) pour le rendre plus flexible et évolutif pour l’authentification et l’autorisation. Nous avons également soumis une pull request au dépôt original pour inclure nos modifications. - -Pour lancer l’inspecteur MCP, vous pouvez utiliser la commande suivante (Node.js requis) : - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Ensuite, ouvrez votre navigateur et allez sur `http://localhost:6274/` (ou l’URL affichée dans le terminal) pour accéder à l’inspecteur MCP. - -### Connecter l’inspecteur MCP au serveur MCP \{#connect-mcp-inspector-to-the-mcp-server} - -Avant de continuer, vérifiez la configuration suivante dans l’inspecteur MCP : - -- **Type de transport** : Réglez sur `SSE`. -- **URL** : Réglez sur l’URL de votre serveur MCP. Dans notre cas, cela devrait être `http://localhost:3001/sse`. - -Vous pouvez maintenant cliquer sur le bouton "Connecter" pour voir si l’inspecteur MCP peut se connecter au serveur MCP. Si tout est correct, vous devriez voir le statut "Connecté" dans l’inspecteur MCP. - -### Point de contrôle : Exécuter les outils du gestionnaire de tâches \{#checkpoint-run-todo-manager-tools} - -1. Dans le menu supérieur de l’inspecteur MCP, cliquez sur l’onglet "Outils". -2. Cliquez sur le bouton "Lister les outils". -3. Vous devriez voir les outils `create-todo`, `get-todos` et `delete-todo` listés sur la page. Cliquez dessus pour ouvrir les détails de l’outil. -4. Vous devriez voir le bouton "Exécuter l’outil" à droite. Cliquez dessus et saisissez les paramètres requis pour exécuter l’outil. -5. Vous devriez voir le résultat de l’outil avec la réponse JSON `{"error": "Non implémenté"}`. - -![Première exécution de l’inspecteur MCP](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## Intégrer avec votre serveur d’autorisation \{#integrate-with-your-authorization-server} - -Pour compléter cette section, plusieurs points sont à prendre en compte : - -
-**L’URL de l’émetteur de votre serveur d’autorisation** - -Il s’agit généralement de l’URL de base de votre serveur d’autorisation, comme `https://auth.example.com`. Certains fournisseurs peuvent avoir un chemin comme `https://example.logto.app/oidc`, alors assurez-vous de vérifier la documentation de votre fournisseur. - -
- -
-**Comment récupérer les métadonnées du serveur d’autorisation** - -- Si votre serveur d’autorisation est conforme à [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) ou [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), vous pouvez utiliser les utilitaires intégrés de MCP Auth pour récupérer automatiquement les métadonnées. -- Si votre serveur d’autorisation n’est pas conforme à ces standards, vous devrez spécifier manuellement l’URL des métadonnées ou les points de terminaison dans la configuration du serveur MCP. Consultez la documentation de votre fournisseur pour les points de terminaison spécifiques. - -
- -
-**Comment enregistrer l’inspecteur MCP comme client dans votre serveur d’autorisation** - -- Si votre serveur d’autorisation prend en charge [l’enregistrement dynamique de client](https://datatracker.ietf.org/doc/html/rfc7591), vous pouvez passer cette étape car l’inspecteur MCP s’enregistrera automatiquement comme client. -- Si votre serveur d’autorisation ne prend pas en charge l’enregistrement dynamique de client, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre serveur d’autorisation. - -
- -
-**Comprendre les paramètres de la requête de jeton** - -Lorsque vous demandez des jetons d’accès à différents serveurs d’autorisation, vous rencontrerez diverses approches pour spécifier la ressource cible et les permissions. Voici les principaux schémas : - -- **Basé sur l’indicateur de ressource** : - - - Utilise le paramètre `resource` pour spécifier l’API cible (voir [RFC 8707 : Indicateurs de ressource pour OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) - - Courant dans les implémentations OAuth 2.0 modernes - - Exemple de requête : - ```json - { - "resource": "https://todo.mcp-server.app", - "scope": "create:todos read:todos" - } - ``` - - Le serveur délivre des jetons liés spécifiquement à la ressource demandée - -- **Basé sur l’audience** : - - - Utilise le paramètre `audience` pour spécifier le destinataire du jeton - - Semblable aux indicateurs de ressource mais avec une sémantique différente - - Exemple de requête : - ```json - { - "audience": "todo-api", - "scope": "create:todos read:todos" - } - ``` - -- **Basé uniquement sur les portées** : - - S’appuie uniquement sur les portées sans paramètres de ressource / audience - - Approche OAuth 2.0 traditionnelle - - Exemple de requête : - ```json - { - "scope": "todo-api:create todo-api:read openid profile" - } - ``` - - Utilise souvent des portées préfixées pour nommer les permissions - - Courant dans les implémentations OAuth 2.0 plus simples - -:::tip Bonnes pratiques - -- Consultez la documentation de votre fournisseur pour les paramètres pris en charge -- Certains fournisseurs prennent en charge plusieurs approches simultanément -- Les indicateurs de ressource offrent une meilleure sécurité via la restriction d’audience -- Privilégiez les indicateurs de ressource lorsque disponibles pour un meilleur contrôle d’accès - ::: - -
- -Bien que chaque fournisseur puisse avoir ses propres exigences spécifiques, les étapes suivantes vous guideront dans l’intégration de l’inspecteur MCP et du serveur MCP avec des configurations spécifiques au fournisseur. - -### Enregistrer l’inspecteur MCP comme client \{#register-mcp-inspector-as-a-client} - - - - -L’intégration du gestionnaire de tâches avec [Logto](https://logto.io) est simple car il s’agit d’un fournisseur OpenID Connect qui prend en charge les indicateurs de ressource et les portées, vous permettant de sécuriser votre API todo avec `https://todo.mcp-server.app` comme indicateur de ressource. - -Comme Logto ne prend pas encore en charge l’enregistrement dynamique de client, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre tenant Logto : - -1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. -2. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre propre instance Logto Console). -3. Accédez à l’onglet "Applications", cliquez sur "Créer une application". En bas de la page, cliquez sur "Créer une application sans framework". -4. Remplissez les détails de l’application, puis cliquez sur "Créer l’application" : - - **Sélectionnez un type d’application** : Choisissez "Application monopage". - - **Nom de l’application** : Saisissez un nom pour votre application, par exemple "MCP Inspector". -5. Dans la section "Paramètres / URI de redirection", collez la valeur **Redirect URL (auto-populated)** que vous avez copiée depuis l’inspecteur MCP. Cliquez ensuite sur "Enregistrer les modifications" dans la barre du bas. -6. Dans la carte du haut, vous verrez la valeur "App ID". Copiez-la. -7. Retournez dans l’inspecteur MCP et collez la valeur "App ID" dans la section "Configuration OAuth" sous "Client ID". -8. Saisissez la valeur `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` dans le champ "Auth Params". Cela garantira que le jeton d’accès retourné par Logto contient les portées nécessaires pour accéder au gestionnaire de tâches. - - - - -:::note -Ceci est un guide générique d’intégration pour les fournisseurs OAuth 2.0 / OpenID Connect. Les deux suivent des étapes similaires car OIDC est construit sur OAuth 2.0. Consultez la documentation de votre fournisseur pour les détails spécifiques. -::: - -Si votre fournisseur prend en charge l’enregistrement dynamique de client, vous pouvez passer directement à l’étape 8 ci-dessous pour configurer l’inspecteur MCP ; sinon, vous devrez enregistrer manuellement l’inspecteur MCP comme client : - -1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. - -2. Connectez-vous à la console de votre fournisseur. - -3. Accédez à la section "Applications" ou "Clients", puis créez une nouvelle application ou client. - -4. Si votre fournisseur demande un type de client, sélectionnez "Application monopage" ou "Client public". - -5. Après avoir créé l’application, vous devrez configurer l’URI de redirection. Collez la valeur **Redirect URL (auto-populated)** que vous avez copiée depuis l’inspecteur MCP. - -6. Trouvez le "Client ID" ou "Application ID" de la nouvelle application et copiez-le. - -7. Retournez dans l’inspecteur MCP et collez la valeur "Client ID" dans la section "Configuration OAuth" sous "Client ID". - -8. Saisissez la valeur suivante dans le champ "Auth Params" pour demander les portées nécessaires aux opérations todo : - -```json -{ "scope": "create:todos read:todos delete:todos" } -``` - - - - -### Configurer MCP Auth \{#set-up-mcp-auth} - -Dans votre projet serveur MCP, vous devez installer le SDK MCP Auth et le configurer pour utiliser les métadonnées de votre serveur d’autorisation. - - - - -D’abord, installez le paquet `mcpauth` : - -```bash -pip install mcpauth -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme `uv` ou `poetry`. - - - - -D’abord, installez le paquet `mcp-auth` : - -```bash -npm install mcp-auth -``` - - - - -MCP Auth nécessite les métadonnées du serveur d’autorisation pour pouvoir s’initialiser. Selon votre fournisseur : - - - - - -L’URL de l’émetteur peut être trouvée dans la page de détails de votre application dans Logto Console, dans la section "Endpoints & Credentials / Issuer endpoint". Elle devrait ressembler à `https://my-project.logto.app/oidc`. - - - - - - - -Pour les fournisseurs OAuth 2.0, vous devrez : - -1. Vérifier la documentation de votre fournisseur pour l’URL du serveur d’autorisation (souvent appelée issuer URL ou base URL) -2. Certains fournisseurs exposent cela à `https://{your-domain}/.well-known/oauth-authorization-server` -3. Cherchez dans la console d’administration de votre fournisseur sous les paramètres OAuth/API - - - - - - - - - - - -Mettez à jour le fichier `todo-manager.py` pour inclure la configuration MCP Auth : - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Remplacez par votre endpoint issuer -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Mettez à jour le fichier `todo-manager.ts` pour inclure la configuration MCP Auth : - -```ts -// todo-manager.ts - -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Remplacez par votre endpoint issuer -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -### Mettre à jour le serveur MCP \{#update-mcp-server} - -Nous y sommes presque ! Il est temps de mettre à jour le serveur MCP pour appliquer la route et le middleware MCP Auth, puis d’implémenter le contrôle d’accès basé sur les permissions pour les outils du gestionnaire de tâches en fonction des portées de l’utilisateur. - - - - -```python -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Créer une nouvelle tâche.""" - return ( - mcp_auth.auth_info.scopes - if mcp_auth.auth_info # Ceci sera renseigné par le middleware Bearer auth - else {"error": "Non authentifié"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt")) -app = Starlette( - routes=[ - # Ajouter la route metadata (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Protéger le serveur MCP avec le middleware Bearer auth - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool( - 'create-todo', - 'Créer une nouvelle tâche', - { content: z.string() }, - async ({ content, authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Non authentifié' }) }, - ], - }; - } -); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth('jwt')); -``` - - - - -Ensuite, implémentons les outils spécifiques. - -Commençons par créer un service de tâches simple pour fournir des opérations CRUD de base pour la gestion des tâches en mémoire. - - - -```python -# service.py - -""" -Un service Todo simple à des fins de démonstration. -Utilise une liste en mémoire pour stocker les tâches. -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: -"""Représente une tâche.""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """Convertir la tâche en dictionnaire pour la sérialisation JSON.""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - -class TodoService: -"""Un service Todo simple à des fins de démonstration.""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - Obtenir toutes les tâches, éventuellement filtrées par owner_id. - - Args: - owner_id: Si fourni, ne retourne que les tâches appartenant à cet utilisateur - - Returns: - Liste de dictionnaires de tâches - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - Obtenir une tâche par son ID. - - Args: - todo_id: L’ID de la tâche à récupérer - - Returns: - Objet Todo si trouvé, None sinon - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - Créer une nouvelle tâche. - - Args: - content: Le contenu de la tâche - owner_id: L’ID de l’utilisateur propriétaire de cette tâche - - Returns: - Dictionnaire représentant la tâche créée - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - Supprimer une tâche par son ID. - - Args: - todo_id: L’ID de la tâche à supprimer - - Returns: - Dictionnaire représentant la tâche supprimée si trouvée, None sinon - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """Générer un ID aléatoire pour une tâche.""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) - -```` - - - - - -```ts -// todo-service.ts - -type Todo = { - id: string; - content: string; - ownerId: string; - createdAt: string; -}; - -/** - * Un service Todo simple à des fins de démonstration. - * Utilise un tableau en mémoire pour stocker les tâches - */ -export class TodoService { - private readonly todos: Todo[] = []; - - getAllTodos(ownerId?: string): Todo[] { - if (ownerId) { - return this.todos.filter((todo) => todo.ownerId === ownerId); - } - return this.todos; - } - - getTodoById(id: string): Todo | undefined { - return this.todos.find((todo) => todo.id === id); - } - - createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { - const todo: Todo = { - id: this.genId(), - content, - ownerId, - createdAt: new Date().toISOString(), - }; - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - this.todos.push(todo); - return todo; - } - - deleteTodo(id: string): Todo | undefined { - const index = this.todos.findIndex((todo) => todo.id === id); - - if (index === -1) { - return undefined; - } - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - const [deleted] = this.todos.splice(index, 1); - return deleted; - } - - private genId(): string { - return Math.random().toString(36).slice(2, 10); - } -} -```` - - - - -puis dans la couche outils, nous déterminerons si les opérations sont autorisées en fonction des portées de l’utilisateur : - - - - -```python -# todo-manager.py - -from typing import Any, Optional -from mcpauth.errors import MCPAuthBearerAuthError - -def assert_user_id(auth_info: Optional[dict]) -> str: - """Extraire et valider l’ID utilisateur depuis les infos d’auth.""" - subject = auth_info.get('subject') if auth_info else None - if not subject: - raise ValueError('Invalid auth info') - return subject - -def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """Vérifier si l’utilisateur possède toutes les portées requises.""" - return all(scope in user_scopes for scope in required_scopes) - -# Créer une instance de TodoService -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Créer une nouvelle tâche. - - Seuls les utilisateurs avec la portée 'create:todos' peuvent créer des tâches. - """ - # Obtenir les infos d’authentification - auth_info = mcp_auth.auth_info - - # Valider l’ID utilisateur - try: - user_id = assert_user_id(auth_info) - except ValueError as e: - return {"error": str(e)} - - # Vérifier si l’utilisateur a les permissions requises - if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): - raise MCPAuthBearerAuthError('missing_required_scopes') - - # Créer la nouvelle tâche - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - - # Retourner la tâche créée - return created_todo.__dict__ - -# ... -``` - -Vous pouvez consulter notre [code d’exemple](https://github.com/mcp-auth/python/tree/master/samples/server) pour toutes les autres implémentations détaillées. - - - - -```ts -// todo-manager.ts - -// ... autres imports -import assert from 'node:assert'; -import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; -import { TodoService } from './todo-service.js'; - -const todoService = new TodoService(); - -const assertUserId = (authInfo?: AuthInfo) => { - const { subject } = authInfo ?? {}; - assert(subject, 'Invalid auth info'); - return subject; -}; - -/** - * Vérifie si l’utilisateur possède toutes les portées requises pour une opération - */ -const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { - return requiredScopes.every((scope) => userScopes.includes(scope)); -}; - -server.tool( - 'create-todo', - 'Créer une nouvelle tâche', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { - const userId = assertUserId(authInfo); - - /** - * Seuls les utilisateurs avec la portée 'create:todos' peuvent créer des tâches - */ - if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { - throw new MCPAuthBearerAuthError('missing_required_scopes'); - } - - const createdTodo = todoService.createTodo({ content, ownerId: userId }); - - return { - content: [{ type: 'text', text: JSON.stringify(createdTodo) }], - }; - } -); - -// ... -``` - -Vous pouvez consulter notre [code d’exemple](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) pour toutes les autres implémentations détaillées. - - - - -## Point de contrôle : Exécuter les outils `todo-manager` \{#checkpoint-run-the-todo-manager-tools} - -Redémarrez votre serveur MCP et ouvrez l’inspecteur MCP dans votre navigateur. Lorsque vous cliquez sur le bouton "Connecter", vous devriez être redirigé vers la page de connexion de votre serveur d’autorisation. - -Une fois connecté et de retour dans l’inspecteur MCP, répétez les actions du point de contrôle précédent pour exécuter les outils du gestionnaire de tâches. Cette fois, vous pouvez utiliser ces outils avec votre identité utilisateur authentifiée. Le comportement des outils dépendra des rôles et permissions attribués à votre utilisateur : - -- Si vous êtes connecté en tant que **User** (avec uniquement la portée `create:todos`) : - - - Vous pouvez créer de nouvelles tâches avec l’outil `create-todo` - - Vous ne pouvez voir et supprimer que vos propres tâches - - Vous ne pourrez pas voir ou supprimer les tâches des autres utilisateurs - -- Si vous êtes connecté en tant qu’**Admin** (avec toutes les portées : `create:todos`, `read:todos`, `delete:todos`) : - - Vous pouvez créer de nouvelles tâches - - Vous pouvez voir toutes les tâches du système avec l’outil `get-todos` - - Vous pouvez supprimer n’importe quelle tâche avec l’outil `delete-todo`, quel que soit le créateur - -Vous pouvez tester ces différents niveaux de permission en : - -1. Vous déconnectant de la session en cours (cliquez sur le bouton "Déconnecter" dans l’inspecteur MCP) -2. Vous connectant avec un autre compte utilisateur ayant des rôles / permissions différents -3. Essayant à nouveau les mêmes outils pour observer comment le comportement change selon les permissions de l’utilisateur - -Cela démontre comment le contrôle d’accès basé sur les rôles (RBAC) fonctionne en pratique, où différents utilisateurs ont différents niveaux d’accès aux fonctionnalités du système. - -![Résultat de l’outil todo manager dans l’inspecteur MCP](/docs-assets/images/tutorials/todo-manager/result.png) - - - - -:::info -Consultez le [dépôt du SDK MCP Auth Python](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) pour le code complet du serveur MCP (version OIDC). -::: - - - - -:::info -Consultez le [dépôt du SDK MCP Auth Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) pour le code complet du serveur MCP (version OIDC). -::: - - - - -## Notes de clôture \{#closing-notes} - -🎊 Félicitations ! Vous avez terminé avec succès le tutoriel. Récapitulons ce que nous avons fait : - -- Mise en place d’un serveur MCP de base avec des outils de gestion de tâches (`create-todo`, `get-todos`, `delete-todo`) -- Implémentation du contrôle d’accès basé sur les rôles (RBAC) avec différents niveaux de permission pour les utilisateurs et les administrateurs -- Intégration du serveur MCP avec un serveur d’autorisation en utilisant MCP Auth -- Configuration de l’inspecteur MCP pour authentifier les utilisateurs et utiliser des jetons d’accès avec des portées pour appeler les outils - -N’hésitez pas à consulter d’autres tutoriels et la documentation pour tirer le meilleur parti de MCP Auth. +[La traduction continue dans la prochaine réponse...] \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx index 4d6c15a..6425e00 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx @@ -11,7 +11,7 @@ import SetupOidc from './_setup-oidc.mdx'; # Tutoriel : Qui suis-je ? (Tutorial: Who am I?) -Ce tutoriel vous guidera à travers le processus de configuration de MCP Auth pour authentifier les utilisateurs et récupérer leurs informations d'identité depuis le serveur d’autorisation (Authorization Server). +Ce tutoriel va vous guider dans le processus de configuration de MCP Auth pour authentifier les utilisateurs et récupérer leurs informations d'identité depuis le serveur d’autorisation (Authorization Server). Après avoir terminé ce tutoriel, vous aurez : @@ -22,9 +22,9 @@ Après avoir terminé ce tutoriel, vous aurez : Le tutoriel impliquera les composants suivants : -- **Serveur MCP** : Un serveur MCP simple qui utilise les SDK officiels MCP pour gérer les requêtes. +- **Serveur MCP** : Un serveur MCP simple qui utilise les SDK officiels MCP pour traiter les requêtes. - **Inspecteur MCP** : Un outil de test visuel pour les serveurs MCP. Il agit également comme un client OAuth / OIDC pour initier le flux d’autorisation et récupérer les jetons d’accès (Access tokens). -- **Serveur d’autorisation (Authorization server)** : Un fournisseur OAuth 2.1 ou OpenID Connect qui gère les identités utilisateur et émet les jetons d’accès (Access tokens). +- **Serveur d’autorisation (Authorization server)** : Un fournisseur OAuth 2.1 ou OpenID Connect qui gère les identités utilisateur et délivre les jetons d’accès (Access tokens). Voici un schéma de haut niveau de l’interaction entre ces composants : @@ -37,7 +37,7 @@ sequenceDiagram Client->>Server: Demande de l’outil `whoami` Server->>Client: Retourne 401 Non autorisé Client->>Auth: Initie le flux d’autorisation - Auth->>Auth: Complète le flux d’autorisation + Auth->>Auth: Termine le flux d’autorisation Auth->>Client: Redirige avec le code d’autorisation Client->>Auth: Échange le code contre un jeton d’accès Auth->>Client: Retourne le jeton d’accès @@ -49,7 +49,7 @@ sequenceDiagram ## Comprendre votre serveur d’autorisation \{#understand-your-authorization-server} -### Récupérer les informations d'identité utilisateur \{#retrieving-user-identity-information} +### Récupération des informations d'identité utilisateur \{#retrieving-user-identity-information} Pour compléter ce tutoriel, votre serveur d’autorisation doit offrir une API pour récupérer les informations d'identité utilisateur : @@ -58,28 +58,39 @@ Pour compléter ce tutoriel, votre serveur d’autorisation doit offrir une API [Logto](https://logto.io) est un fournisseur OpenID Connect qui prend en charge l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) standard pour récupérer les informations d'identité utilisateur. -Pour obtenir un jeton d’accès (Access token) utilisable sur l’endpoint userinfo, au moins deux portées (Scopes) sont requises : `openid` et `profile`. Vous pouvez continuer à lire, car nous aborderons la configuration des portées plus loin. +Pour obtenir un jeton d’accès (Access token) utilisable sur l’endpoint userinfo, au moins deux portées (Scopes) sont requises : `openid` et `profile`. Vous pouvez continuer la lecture, car nous aborderons la configuration des portées plus loin. -[Keycloak](https://www.keycloak.org) est une solution open-source de gestion des identités et des accès qui prend en charge plusieurs protocoles, dont OpenID Connect (OIDC). En tant que fournisseur OIDC, il implémente l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) standard pour récupérer les informations d'identité utilisateur. +[Keycloak](https://www.keycloak.org) est une solution open source de gestion des identités et des accès qui prend en charge plusieurs protocoles, dont OpenID Connect (OIDC). En tant que fournisseur OIDC, il implémente l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) standard pour récupérer les informations d'identité utilisateur. -Pour obtenir un jeton d’accès (Access token) utilisable sur l’endpoint userinfo, au moins deux portées (Scopes) sont requises : `openid` et `profile`. Vous pouvez continuer à lire, car nous aborderons la configuration des portées plus loin. +Pour obtenir un jeton d’accès (Access token) utilisable sur l’endpoint userinfo, au moins deux portées (Scopes) sont requises : `openid` et `profile`. Vous pouvez continuer la lecture, car nous aborderons la configuration des portées plus loin. + + + + +[Asgardeo](https://wso2.com/asgardeo) est une plateforme cloud-native d’identité en tant que service (IDaaS) qui prend en charge OAuth 2.0 et OpenID Connect (OIDC), offrant une gestion robuste des identités et des accès pour les applications modernes. + +Les informations utilisateur sont encodées dans le jeton d’identifiant (ID token) retourné avec le jeton d’accès (Access token). Mais en tant que fournisseur OIDC, Asgardeo expose un [endpoint UserInfo](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/) qui permet aux applications de récupérer les revendications (Claims) sur l’utilisateur authentifié dans la charge utile. + +Vous pouvez également découvrir dynamiquement cet endpoint via l’[endpoint de découverte OIDC](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs) ou en naviguant dans l’onglet « Info » de l’application dans la Console Asgardeo. + +Pour obtenir un jeton d’accès (Access token) utilisable sur l’endpoint userinfo, au moins deux portées (Scopes) sont requises : `openid` et `profile`. La plupart des fournisseurs OpenID Connect prennent en charge l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) pour récupérer les informations d'identité utilisateur. -Consultez la documentation de votre fournisseur pour vérifier s’il prend en charge cet endpoint. Si votre fournisseur prend en charge [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), vous pouvez également vérifier si le `userinfo_endpoint` est inclus dans le document de découverte (réponse de l’endpoint `.well-known/openid-configuration`). +Consultez la documentation de votre fournisseur pour vérifier la prise en charge de cet endpoint. Si votre fournisseur prend en charge [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), vous pouvez aussi vérifier si le `userinfo_endpoint` est inclus dans le document de découverte (réponse de l’endpoint `.well-known/openid-configuration`). Pour obtenir un jeton d’accès (Access token) utilisable sur l’endpoint userinfo, au moins deux portées (Scopes) sont requises : `openid` et `profile`. Consultez la documentation de votre fournisseur pour voir la correspondance des portées avec les revendications d'identité utilisateur. -Bien que OAuth 2.0 ne définisse pas de méthode standard pour récupérer les informations d'identité utilisateur, de nombreux fournisseurs implémentent leurs propres endpoints à cet effet. Consultez la documentation de votre fournisseur pour savoir comment récupérer les informations d'identité utilisateur à l’aide d’un jeton d’accès (Access token) et quels paramètres sont requis pour obtenir ce jeton lors de l’appel du flux d’autorisation. +Bien que OAuth 2.0 ne définisse pas de méthode standard pour récupérer les informations d'identité utilisateur, de nombreux fournisseurs implémentent leurs propres endpoints à cet effet. Consultez la documentation de votre fournisseur pour savoir comment récupérer les informations d'identité utilisateur à l’aide d’un jeton d’accès (Access token) et quels paramètres sont requis pour obtenir ce jeton lors de l’invocation du flux d’autorisation. @@ -180,10 +191,10 @@ uvicorn whoami:app --host 0.0.0.0 --port 3001 :::note -Comme l’implémentation actuelle de l’inspecteur MCP ne gère pas les flux d’autorisation, nous utiliserons l’approche SSE pour configurer le serveur MCP. Nous mettrons à jour le code ici dès que l’inspecteur MCP prendra en charge les flux d’autorisation. +Comme l’implémentation actuelle de l’inspecteur MCP ne gère pas les flux d’autorisation, nous utiliserons l’approche SSE pour configurer le serveur MCP. Nous mettrons à jour ce code dès que l’inspecteur MCP prendra en charge les flux d’autorisation. ::: -Vous pouvez également utiliser `pnpm` ou `yarn` si vous préférez. +Vous pouvez aussi utiliser `pnpm` ou `yarn` si vous préférez. Créez un fichier nommé `whoami.js` et ajoutez le code suivant : @@ -252,7 +263,7 @@ Maintenant que le serveur MCP fonctionne, nous pouvons utiliser l’inspecteur M En raison des limites de l’implémentation actuelle, nous avons forké l’[inspecteur MCP](https://github.com/mcp-auth/inspector) pour le rendre plus flexible et évolutif pour l’authentification (Authentication) et l’autorisation (Authorization). Nous avons également soumis une pull request au dépôt original pour inclure nos modifications. -Pour lancer l’inspecteur MCP, vous pouvez utiliser la commande suivante (Node.js est requis) : +Pour lancer l’inspecteur MCP, utilisez la commande suivante (Node.js requis) : ```bash git clone https://github.com/mcp-auth/inspector.git @@ -261,14 +272,14 @@ npm install npm run dev ``` -Ensuite, ouvrez votre navigateur et accédez à `http://localhost:6274/` (ou à l’URL affichée dans le terminal) pour accéder à l’inspecteur MCP. +Ensuite, ouvrez votre navigateur et allez sur `http://localhost:6274/` (ou l’URL affichée dans le terminal) pour accéder à l’inspecteur MCP. ### Connecter l’inspecteur MCP au serveur MCP \{#connect-mcp-inspector-to-the-mcp-server} Avant de continuer, vérifiez la configuration suivante dans l’inspecteur MCP : - **Type de transport** : Réglez sur `SSE`. -- **URL** : Réglez sur l’URL de votre serveur MCP. Dans notre cas, il s’agit de `http://localhost:3001/sse`. +- **URL** : Réglez sur l’URL de votre serveur MCP. Dans notre cas, cela devrait être `http://localhost:3001/sse`. Vous pouvez maintenant cliquer sur le bouton "Connecter" pour voir si l’inspecteur MCP peut se connecter au serveur MCP. Si tout est correct, vous devriez voir le statut "Connecté" dans l’inspecteur MCP. @@ -289,7 +300,7 @@ Pour compléter cette section, plusieurs points sont à prendre en compte :
**L’URL de l’émetteur (Issuer) de votre serveur d’autorisation** -Il s’agit généralement de l’URL de base de votre serveur d’autorisation, comme `https://auth.example.com`. Certains fournisseurs peuvent avoir un chemin comme `https://example.logto.app/oidc`, alors assurez-vous de vérifier la documentation de votre fournisseur. +Il s’agit généralement de l’URL de base de votre serveur d’autorisation, comme `https://auth.example.com`. Certains fournisseurs peuvent avoir un chemin comme `https://example.logto.app/oidc`, alors vérifiez la documentation de votre fournisseur.
@@ -312,11 +323,11 @@ Il s’agit généralement de l’URL de base de votre serveur d’autorisation,
**Comment récupérer les informations d'identité utilisateur et comment configurer les paramètres de la requête d’autorisation** -- Pour les fournisseurs OpenID Connect : généralement, vous devez demander au moins les portées (Scopes) `openid` et `profile` lors de l’initiation du flux d’autorisation. Cela garantira que le jeton d’accès (Access token) retourné par le serveur d’autorisation contient les portées nécessaires pour accéder à l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) et récupérer les informations d'identité utilisateur. +- Pour les fournisseurs OpenID Connect : vous devez généralement demander au moins les portées `openid` et `profile` lors de l’initiation du flux d’autorisation. Cela garantira que le jeton d’accès (Access token) retourné par le serveur d’autorisation contient les portées nécessaires pour accéder à l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) et récupérer les informations d'identité utilisateur. Remarque : certains fournisseurs peuvent ne pas prendre en charge l’endpoint userinfo. -- Pour les fournisseurs OAuth 2.0 / OAuth 2.1 : consultez la documentation de votre fournisseur pour savoir comment récupérer les informations d'identité utilisateur à l’aide d’un jeton d’accès (Access token) et quels paramètres sont requis pour obtenir ce jeton lors de l’appel du flux d’autorisation. +- Pour les fournisseurs OAuth 2.0 / OAuth 2.1 : consultez la documentation de votre fournisseur pour savoir comment récupérer les informations d'identité utilisateur à l’aide d’un jeton d’accès (Access token) et quels paramètres sont requis pour obtenir ce jeton lors de l’invocation du flux d’autorisation.
@@ -332,11 +343,11 @@ L’intégration avec [Logto](https://logto.io) est simple puisqu’il s’agit Comme Logto ne prend pas encore en charge l’enregistrement dynamique du client, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre tenant Logto : 1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. -2. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre Logto Console auto-hébergée). -3. Accédez à l’onglet "Applications", cliquez sur "Créer une application". En bas de la page, cliquez sur "Créer une application sans framework". +2. Connectez-vous à la [Console Logto](https://cloud.logto.io) (ou à votre Console Logto auto-hébergée). +3. Allez dans l’onglet "Applications", cliquez sur "Créer une application". En bas de la page, cliquez sur "Créer une application sans framework". 4. Remplissez les détails de l’application, puis cliquez sur "Créer l’application" : - **Sélectionnez un type d’application** : Choisissez "Application monopage". - - **Nom de l’application** : Entrez un nom pour votre application, par exemple "MCP Inspector". + - **Nom de l’application** : Entrez un nom, par exemple "MCP Inspector". 5. Dans la section "Paramètres / URI de redirection", collez la valeur **Redirect URL (auto-populated)** copiée depuis l’inspecteur MCP. Cliquez ensuite sur "Enregistrer les modifications" dans la barre du bas. 6. Dans la carte du haut, vous verrez la valeur "App ID". Copiez-la. 7. Retournez dans l’inspecteur MCP et collez la valeur "App ID" dans la section "Configuration OAuth" sous "Client ID". @@ -345,17 +356,17 @@ Comme Logto ne prend pas encore en charge l’enregistrement dynamique du client -[Keycloak](https://www.keycloak.org) est une solution open-source de gestion des identités et des accès qui prend en charge le protocole OpenID Connect. +[Keycloak](https://www.keycloak.org) est une solution open source de gestion des identités et des accès prenant en charge le protocole OpenID Connect. Bien que Keycloak prenne en charge l’enregistrement dynamique du client, son endpoint d’enregistrement ne prend pas en charge CORS, ce qui empêche la plupart des clients MCP de s’enregistrer directement. Nous devrons donc enregistrer notre client manuellement. :::note -Bien que Keycloak puisse être installé de [différentes manières](https://www.keycloak.org/guides#getting-started) (bare metal, kubernetes, etc.), pour ce tutoriel, nous utiliserons Docker pour une configuration rapide et simple. +Bien que Keycloak puisse être installé de [plusieurs façons](https://www.keycloak.org/guides#getting-started) (bare metal, kubernetes, etc.), pour ce tutoriel, nous utiliserons Docker pour une configuration rapide et simple. ::: Configurons une instance Keycloak et adaptons-la à nos besoins : -1. Lancez une instance Keycloak avec Docker en suivant la [documentation officielle](https://www.keycloak.org/getting-started/getting-started-docker) : +1. Lancez une instance Keycloak avec Docker selon la [documentation officielle](https://www.keycloak.org/getting-started/getting-started-docker) : ```bash docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev @@ -376,18 +387,18 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM - Cliquez sur "Users" dans le menu de gauche - Cliquez sur "Create new user" - - Remplissez les informations utilisateur : + - Remplissez les informations : - Nom d’utilisateur : `testuser` - Prénom et nom peuvent être quelconques - Cliquez sur "Create" - Dans l’onglet "Credentials", définissez un mot de passe et décochez "Temporary" -5. Enregistrez l’inspecteur MCP comme client : +5. Enregistrez MCP Inspector comme client : - Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. - Dans la console d’administration Keycloak, cliquez sur "Clients" dans le menu de gauche - Cliquez sur "Create client" - - Remplissez les détails du client : + - Remplissez les détails : - Type de client : Sélectionnez "OpenID Connect" - Client ID : Entrez `mcp-inspector` - Cliquez sur "Next" @@ -395,12 +406,12 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM - Assurez-vous que "Standard flow" est activé - Cliquez sur "Next" - Sur la page "Login settings" : - - Collez l’URL de rappel de l’inspecteur MCP précédemment copiée dans "Valid redirect URIs" + - Collez l’URL de rappel de l’inspecteur MCP dans "Valid redirect URIs" - Entrez `http://localhost:6274` dans "Web origins" - Cliquez sur "Save" - Copiez le "Client ID" (qui est `mcp-inspector`) -6. De retour dans l’inspecteur MCP : +6. Dans l’inspecteur MCP : - Collez le Client ID copié dans le champ "Client ID" de la section "Configuration OAuth" - Entrez la valeur suivante dans le champ "Auth Params" pour demander les portées nécessaires : @@ -408,7 +419,41 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM { "scope": "openid profile email" } ``` - + + + +Bien que Asgardeo prenne en charge l’enregistrement dynamique du client via une API standard, l’endpoint est protégé et nécessite un jeton d’accès avec les permissions nécessaires. Dans ce tutoriel, nous allons enregistrer le client manuellement via la Console Asgardeo. + +:::note +Si vous n’avez pas de compte Asgardeo, vous pouvez [vous inscrire gratuitement](https://asgardeo.io). +::: + +Suivez ces étapes pour configurer Asgardeo pour MCP Inspector : + +1. Connectez-vous à la [Console Asgardeo](https://console.asgardeo.io) et sélectionnez votre organisation. + +2. Créez une nouvelle application : + - Allez dans **Applications** → **Nouvelle application** + - Choisissez **Application monopage** + - Entrez un nom comme `MCP Inspector` + - Dans le champ **Authorized Redirect URLs**, collez l’**URL de redirection** copiée depuis l’application cliente MCP Inspector (ex : `http://localhost:6274/oauth/callback`) + - Cliquez sur **Créer** + +3. Configurez les paramètres du protocole : + - Sous l’onglet **Protocole** : + - Copiez le **Client ID** généré automatiquement. + - Assurez-vous de passer à `JWT` pour le `Token Type` dans la section **Access Token** + - Cliquez sur **Mettre à jour** + +4. Dans l’application cliente MCP Inspector : + - Ouvrez la section **Configuration OAuth** + - Collez le **Client ID** copié + - Entrez ce qui suit dans le champ **Auth Params** pour demander les portées nécessaires : + +```json +{ "scope": "openid profile email" } +``` + :::note @@ -419,12 +464,12 @@ Si votre fournisseur OpenID Connect prend en charge l’enregistrement dynamique 1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. 2. Connectez-vous à la console de votre fournisseur OpenID Connect. -3. Accédez à la section "Applications" ou "Clients", puis créez une nouvelle application ou un nouveau client. +3. Allez dans la section "Applications" ou "Clients", puis créez une nouvelle application ou un nouveau client. 4. Si votre fournisseur demande un type de client, sélectionnez "Application monopage" ou "Client public". 5. Après avoir créé l’application, vous devrez configurer l’URI de redirection. Collez la valeur **Redirect URL (auto-populated)** copiée depuis l’inspecteur MCP. 6. Trouvez le "Client ID" ou "Application ID" de la nouvelle application et copiez-le. 7. Retournez dans l’inspecteur MCP et collez la valeur "Client ID" dans la section "Configuration OAuth" sous "Client ID". -8. Pour les fournisseurs OpenID Connect standards, vous pouvez entrer la valeur suivante dans le champ "Auth Params" pour demander les portées nécessaires à l’accès à l’endpoint userinfo : +8. Pour les fournisseurs OpenID Connect standard, vous pouvez entrer la valeur suivante dans le champ "Auth Params" pour demander les portées nécessaires à l’accès à l’endpoint userinfo : ```json { "scope": "openid profile email" } @@ -441,12 +486,12 @@ Si votre fournisseur OAuth 2.0 / OAuth 2.1 prend en charge l’enregistrement dy 1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. 2. Connectez-vous à la console de votre fournisseur OAuth 2.0 / OAuth 2.1. -3. Accédez à la section "Applications" ou "Clients", puis créez une nouvelle application ou un nouveau client. +3. Allez dans la section "Applications" ou "Clients", puis créez une nouvelle application ou un nouveau client. 4. Si votre fournisseur demande un type de client, sélectionnez "Application monopage" ou "Client public". 5. Après avoir créé l’application, vous devrez configurer l’URI de redirection. Collez la valeur **Redirect URL (auto-populated)** copiée depuis l’inspecteur MCP. 6. Trouvez le "Client ID" ou "Application ID" de la nouvelle application et copiez-le. 7. Retournez dans l’inspecteur MCP et collez la valeur "Client ID" dans la section "Configuration OAuth" sous "Client ID". -8. Consultez la documentation de votre fournisseur pour savoir comment obtenir des jetons d’accès pour les informations d'identité utilisateur. Vous devrez peut-être spécifier les portées ou paramètres requis pour obtenir le jeton d’accès. Par exemple, si votre fournisseur exige la portée `profile` pour accéder aux informations d'identité utilisateur, vous pouvez entrer la valeur suivante dans le champ "Auth Params" : +8. Consultez la documentation de votre fournisseur pour savoir comment récupérer les jetons d’accès pour les informations d'identité utilisateur. Vous devrez peut-être spécifier les portées ou paramètres nécessaires pour obtenir le jeton d’accès. Par exemple, si votre fournisseur exige la portée `profile` pour accéder aux informations d'identité utilisateur, vous pouvez entrer la valeur suivante dans le champ "Auth Params" : ```json { "scope": "profile" } @@ -488,7 +533,7 @@ MCP Auth nécessite les métadonnées du serveur d’autorisation pour pouvoir s -L’URL de l’émetteur (Issuer) se trouve sur la page de détails de votre application dans Logto Console, dans la section "Endpoints & Credentials / Issuer endpoint". Elle devrait ressembler à `https://my-project.logto.app/oidc`. +L’URL de l’émetteur (Issuer) se trouve sur la page de détails de votre application dans la Console Logto, dans la section "Endpoints & Credentials / Issuer endpoint". Elle devrait ressembler à `https://my-project.logto.app/oidc`. @@ -496,22 +541,31 @@ L’URL de l’émetteur (Issuer) se trouve sur la page de détails de votre app -L’URL de l’émetteur (Issuer) se trouve dans votre console d’administration Keycloak. Dans votre 'mcp-realm', accédez à la section "Realm settings / Endpoints" et cliquez sur le lien "OpenID Endpoint Configuration". Le champ `issuer` dans le document JSON contiendra votre URL d’émetteur, qui devrait ressembler à `http://localhost:8080/realms/mcp-realm`. +L’URL de l’émetteur (Issuer) se trouve dans la console d’administration Keycloak. Dans votre 'mcp-realm', allez dans la section "Realm settings / Endpoints" et cliquez sur le lien "OpenID Endpoint Configuration". Le champ `issuer` dans le document JSON contient votre URL d’émetteur, qui devrait ressembler à `http://localhost:8080/realms/mcp-realm`. + + + Vous pouvez trouver l’URL de l’émetteur (Issuer) dans la Console Asgardeo. Allez dans l’application créée, puis ouvrez l’onglet **Info**. Le champ **Issuer** y sera affiché et devrait ressembler à : + `https://api.asgardeo.io/t//oauth2/token` + + + + + -Le code suivant suppose également que le serveur d’autorisation prend en charge l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) pour récupérer les informations d'identité utilisateur. Si votre fournisseur ne prend pas en charge cet endpoint, vous devrez consulter la documentation de votre fournisseur pour l’endpoint spécifique et remplacer la variable userinfo endpoint par la bonne URL. +Le code suivant suppose également que le serveur d’autorisation prend en charge l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) pour récupérer les informations d'identité utilisateur. Si votre fournisseur ne prend pas en charge cet endpoint, consultez la documentation de votre fournisseur pour l’endpoint spécifique et remplacez la variable de l’endpoint userinfo par la bonne URL. -Comme mentionné précédemment, OAuth 2.0 ne définit pas de méthode standard pour récupérer les informations d'identité utilisateur. Le code suivant suppose que votre fournisseur dispose d’un endpoint spécifique pour récupérer les informations d'identité utilisateur à l’aide d’un jeton d’accès (Access token). Vous devrez consulter la documentation de votre fournisseur pour l’endpoint spécifique et remplacer la variable userinfo endpoint par la bonne URL. +Comme mentionné précédemment, OAuth 2.0 ne définit pas de méthode standard pour récupérer les informations d'identité utilisateur. Le code suivant suppose que votre fournisseur dispose d’un endpoint spécifique pour récupérer les informations d'identité utilisateur à l’aide d’un jeton d’accès (Access token). Consultez la documentation de votre fournisseur pour l’endpoint spécifique et remplacez la variable de l’endpoint userinfo par la bonne URL. @@ -520,7 +574,7 @@ Comme mentionné précédemment, OAuth 2.0 ne définit pas de méthode standard ### Mettre à jour le serveur MCP \{#update-mcp-server} -Nous y sommes presque ! Il est temps de mettre à jour le serveur MCP pour appliquer la route MCP Auth et la fonction middleware, puis faire en sorte que l’outil `whoami` retourne les véritables informations d'identité utilisateur. +Nous y sommes presque ! Il est temps de mettre à jour le serveur MCP pour appliquer la route et la fonction middleware MCP Auth, puis faire en sorte que l’outil `whoami` retourne les véritables informations d'identité utilisateur. @@ -531,7 +585,7 @@ def whoami() -> dict[str, Any]: """Un outil qui retourne les informations de l’utilisateur courant.""" return ( mcp_auth.auth_info.claims - if mcp_auth.auth_info # Ceci sera renseigné par le middleware Bearer auth + if mcp_auth.auth_info # Ceci sera alimenté par le middleware Bearer auth else {"error": "Not authenticated"} ) @@ -606,6 +660,6 @@ Vous pouvez également explorer des sujets avancés, notamment : - Utiliser [JWT (JSON Web Token)](https://auth.wiki/jwt) pour l’authentification (Authentication) et l’autorisation (Authorization) - Exploiter les [indicateurs de ressource (RFC 8707)](https://auth-wiki.logto.io/resource-indicator) pour spécifier les ressources accédées -- Implémenter des mécanismes de contrôle d’accès personnalisés, tels que le [contrôle d’accès basé sur les rôles (RBAC)](https://auth.wiki/rbac) ou le [contrôle d’accès basé sur les attributs (ABAC)](https://auth.wiki/abac) +- Implémenter des mécanismes de contrôle d’accès personnalisés, comme le [contrôle d’accès basé sur les rôles (RBAC)](https://auth.wiki/rbac) ou le [contrôle d’accès basé sur les attributs (ABAC)](https://auth.wiki/abac) N’hésitez pas à consulter d’autres tutoriels et la documentation pour tirer le meilleur parti de MCP Auth. \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index 666cc29..5fded46 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -26,11 +26,11 @@ import SetupOidc from './_setup-oidc.mdx'; このチュートリアルでは、以下のコンポーネントが登場します： -- **MCP サーバー**：MCP 公式 SDK を利用してリクエストを処理し、ユーザーの todo アイテムを管理する Todo サービスを統合したシンプルな MCP サーバー +- **MCP サーバー**：MCP 公式 SDK を使ってリクエストを処理し、ユーザーの todo アイテムを管理する Todo サービスを統合したシンプルな MCP サーバー - **MCP inspector**：MCP サーバーのためのビジュアルテストツール。OAuth / OIDC クライアントとして認可フローを開始し、アクセス トークンを取得する役割も担います。 - **認可サーバー (Authorization server)**：ユーザーのアイデンティティを管理し、アクセス トークンを発行する OAuth 2.1 または OpenID Connect プロバイダー -これらのコンポーネント間のやり取りを示すハイレベルな図です： +これらのコンポーネント間のやり取りを高レベルで示した図です： ```mermaid sequenceDiagram @@ -55,23 +55,23 @@ sequenceDiagram ### スコープ付きアクセス トークン \{#access-tokens-with-scopes} -MCP サーバーで [ロールベースのアクセス制御 (RBAC)](https://auth.wiki/rbac) を実装するには、認可サーバーがスコープ付きのアクセス トークンを発行できる必要があります。スコープは、ユーザーに付与された権限を表します。 +[ロールベースのアクセス制御 (RBAC)](https://auth.wiki/rbac) を MCP サーバーで実装するには、認可サーバーがスコープ付きのアクセス トークンを発行できる必要があります。スコープはユーザーに付与された権限を表します。 [Logto](https://logto.io) は、API リソース（[RFC 8707: OAuth 2.0 のリソースインジケーター](https://datatracker.ietf.org/doc/html/rfc8707) に準拠）とロール機能を通じて RBAC をサポートしています。設定方法は以下の通りです： -1. [Logto Console](https://cloud.logto.io)（またはセルフホストの Logto Console）にサインイン +1. [Logto Console](https://cloud.logto.io)（またはセルフホスト Logto Console）にサインイン 2. API リソースとスコープを作成： - 「API リソース」に移動 - 「Todo Manager」という名前で新しい API リソースを作成 - - 以下のスコープを追加： - - `create:todos`: 「新しい todo アイテムを作成」 - - `read:todos`: 「すべての todo アイテムを取得」 - - `delete:todos`: 「任意の todo アイテムを削除」 + - 次のスコープを追加： + - `create:todos`: "新しい todo アイテムを作成" + - `read:todos`: "すべての todo アイテムを閲覧" + - `delete:todos`: "任意の todo アイテムを削除" 3. ロールを作成（管理を簡単にするため推奨）： @@ -84,28 +84,71 @@ MCP サーバーで [ロールベースのアクセス制御 (RBAC)](https://aut - ユーザーを選択 - 以下のいずれかを実施： - 「ロール」タブでロールを割り当て（推奨） - - または「権限」タブで直接スコープを割り当て + - または「権限」タブでスコープを直接割り当て スコープは JWT アクセス トークンの `scope` クレームにスペース区切りの文字列として含まれます。 + + + [Asgardeo](https://wso2.com/asgardeo) は、API リソースとスコープを使ったロールベースのアクセス制御 (RBAC) ときめ細かな認可をサポートしています。設定方法は以下の通りです： + + 1. [Asgardeo Console](https://console.asgardeo.io) にサインイン + + 2. API リソースとスコープを定義： + - **API Resources** に移動 + - **"New API Resource"** をクリック + - **Identifier** を `https://todo.mcp-server.app`（または任意の URL）に設定 + - **Display Name** を `Todo Manager` に + - 次のスコープを追加： + - `create:todos` : "新しい todo アイテムを作成" + - `read:todos` : "すべての todo アイテムを閲覧" + - `delete:todos` : "任意の todo アイテムを削除" + - リソースを作成 + + 3. ロールを作成： + - **User Management > Roles** でロールを作成し、スコープを直接割り当て + - **New Role** をクリック + - **Basic Details** でロール名（例：`Admin` または `User`）を入力 + - ロールのオーディエンスを `Application` にし、**Assigned Application** で `MCP Inspector Application` を選択 + - **Permission Selection** で先ほど作成した API リソース（例：`Todo Manager`）を選択 + - このロールに割り当てたいスコープを選択（例：`create:todos`, `read:todos`, `delete:todos`） + - **Finish** をクリックしてロールを作成 + + すでにアプリケーションを作成済みの場合 + - **Application > MCP Inspector Application > Roles tab** に移動 + - **Application Role** をオーディエンスタイプに選択し、**New Role** をクリック + - `Admin` ロールを作成し、3 つのスコープすべてを付与 + - `User` ロールを作成し、`create:todos` スコープのみ付与 + + 4. ユーザーにロールを割り当て： + - **User Management > Roles** に移動 + - 作成したロール（例：`Admin` または `User`）を選択し、**Users** タブへ + - **Assign User** を選択し、割り当てたいユーザーを選択して保存 + + スコープは JWT アクセス トークンの `scope` クレームにスペース区切りの文字列として含まれます。 + OAuth 2.0 / OIDC プロバイダーは通常、スコープベースのアクセス制御をサポートしています。RBAC を実装する場合： 1. 認可サーバーで必要なスコープを定義 -2. クライアントが認可フロー中にこれらのスコープをリクエストするよう設定 +2. クライアントで認可フロー時にこれらのスコープをリクエスト 3. 認可サーバーが付与したスコープをアクセス トークンに含めることを確認 4. スコープは通常、JWT アクセス トークンの `scope` クレームに含まれます -スコープの定義・管理方法や、アクセス トークンへのスコープの含め方、ロール管理などの追加 RBAC 機能については、プロバイダーのドキュメントを参照してください。 +詳細は各プロバイダーのドキュメントを参照してください： + +- スコープの定義・管理方法 +- アクセス トークンへのスコープの含め方 +- ロール管理など追加の RBAC 機能 ### トークンの検証と権限チェック \{#validating-tokens-and-checking-permissions} -MCP サーバーがリクエストを受け取った際に行うべきこと： +MCP サーバーがリクエストを受け取った際は、次の処理が必要です： 1. アクセス トークンの署名と有効期限を検証 2. 検証済みトークンからスコープを抽出 @@ -141,29 +184,29 @@ sequenceDiagram ### Dynamic Client Registration \{#dynamic-client-registration} -このチュートリアルでは Dynamic Client Registration は必須ではありませんが、認可サーバーへの MCP クライアント登録を自動化したい場合に便利です。詳細は [Dynamic Client Registration は必要ですか？](../../provider-list.mdx#is-dcr-required) をご覧ください。 +このチュートリアルでは Dynamic Client Registration は必須ではありませんが、認可サーバーへの MCP クライアント登録を自動化したい場合に便利です。詳細は [Dynamic Client Registration は必要？](../../provider-list.mdx#is-dcr-required) を参照してください。 ## Todo マネージャーにおける RBAC を理解する \{#understand-rbac-in-todo-manager} -デモ目的で、todo マネージャー MCP サーバーにシンプルなロールベースのアクセス制御 (RBAC) システムを実装します。これにより、RBAC の基本原則をシンプルな実装で体験できます。 +デモ目的で、todo マネージャー MCP サーバーにシンプルなロールベースのアクセス制御 (RBAC) システムを実装します。これにより、RBAC の基本原則をシンプルな実装で学べます。 :::note -このチュートリアルでは RBAC ベースのスコープ管理を紹介していますが、すべての認証 (Authentication) プロバイダーがロールによるスコープ管理を実装しているわけではありません。プロバイダーによっては独自のアクセス制御や権限管理の仕組みを持っている場合があります。 +このチュートリアルでは RBAC ベースのスコープ管理を紹介していますが、すべての認証 (Authentication) プロバイダーがロールによるスコープ管理を実装しているわけではありません。プロバイダーによっては独自のアクセス制御や権限管理の仕組みを持つ場合があります。 ::: ### ツールとスコープ \{#tools-and-scopes} -todo マネージャー MCP サーバーは、主に次の 3 つのツールを提供します： +Todo マネージャー MCP サーバーは主に 3 つのツールを提供します： - `create-todo`: 新しい todo アイテムを作成 - `get-todos`: すべての todo を一覧表示 - `delete-todo`: ID で todo を削除 -これらのツールへのアクセスを制御するため、以下のスコープを定義します： +これらのツールへのアクセスを制御するため、次のスコープを定義します： - `create:todos`: 新しい todo アイテムの作成を許可 - `delete:todos`: 既存の todo アイテムの削除を許可 -- `read:todos`: すべての todo アイテムの取得を許可 +- `read:todos`: すべての todo アイテムの一覧取得を許可 ### ロールと権限 \{#roles-and-permissions} @@ -181,59 +224,61 @@ todo マネージャー MCP サーバーは、主に次の 3 つのツールを 上記の権限テーブルは各ロールに明示的に割り当てられたスコープを示していますが、リソース所有権の重要な原則も考慮する必要があります： -- **User** は `read:todos` や `delete:todos` スコープを持っていませんが、次のことが可能です： +- **User** は `read:todos` や `delete:todos` スコープを持っていなくても、 - 自分の todo アイテムの閲覧 - 自分の todo アイテムの削除 -- **Admin** は `read:todos` および `delete:todos` のフル権限を持ち、次のことが可能です： + が可能です +- **Admin** は `read:todos` と `delete:todos` のフル権限を持つため、 - システム内のすべての todo アイテムの閲覧 - - 所有者に関係なく任意の todo アイテムの削除 + - すべての todo アイテムの削除（所有者問わず） + が可能です -これは、RBAC システムでよく見られるパターンで、リソース所有者には自分のリソースに対する暗黙的な権限が与えられ、管理者ロールにはすべてのリソースに対する明示的な権限が付与されることを示しています。 +これは、RBAC システムにおいてリソース所有者には自身のリソースに対する暗黙的な権限が与えられ、管理者ロールにはすべてのリソースに対する明示的な権限が与えられるという一般的なパターンを示しています。 :::tip 詳しく学ぶ -RBAC の概念やベストプラクティスについてさらに深く知りたい場合は、[Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac) をご覧ください。 +RBAC の概念やベストプラクティスをさらに深く学びたい場合は、[Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac) をご覧ください。 ::: ## プロバイダーで認可を設定する \{#configure-authorization-in-your-provider} -前述のアクセス制御システムを実装するには、認可サーバーで必要なスコープをサポートするよう設定する必要があります。プロバイダーごとの設定方法は以下の通りです： +前述のアクセス制御システムを実装するには、認可サーバーで必要なスコープをサポートするよう設定が必要です。各プロバイダーでの設定方法は以下の通りです： [Logto](https://logto.io) は、API リソースとロール機能を通じて RBAC をサポートしています。設定方法は以下の通りです： -1. [Logto Console](https://cloud.logto.io)（またはセルフホストの Logto Console）にサインイン +1. [Logto Console](https://cloud.logto.io)（またはセルフホスト Logto Console）にサインイン 2. API リソースとスコープを作成： - 「API リソース」に移動 - - 「Todo Manager」という名前で新しい API リソースを作成し、インジケーターとして `https://todo.mcp-server.app`（デモ用）を使用 - - 以下のスコープを作成： - - `create:todos`: 「新しい todo アイテムを作成」 - - `read:todos`: 「すべての todo アイテムを取得」 - - `delete:todos`: 「任意の todo アイテムを削除」 + - 「Todo Manager」という名前で新しい API リソースを作成し、インジケーターに `https://todo.mcp-server.app`（デモ用）を使用 + - 次のスコープを作成： + - `create:todos`: "新しい todo アイテムを作成" + - `read:todos`: "すべての todo アイテムを閲覧" + - `delete:todos`: "任意の todo アイテムを削除" 3. ロールを作成（管理を簡単にするため推奨）： - 「ロール」に移動 - 「Admin」ロールを作成し、すべてのスコープ（`create:todos`, `read:todos`, `delete:todos`）を割り当て - 「User」ロールを作成し、`create:todos` スコープのみを割り当て - - 「User」ロールの詳細ページで「一般」タブに切り替え、「User」ロールを「デフォルトロール」に設定 + - 「User」ロールの詳細ページで「General」タブに切り替え、「User」ロールを「デフォルトロール」に設定 4. ユーザーロールと権限を管理： - 新規ユーザーの場合： - - デフォルトロールとして「User」を設定したため、自動的に「User」ロールが付与されます + - デフォルトロールに設定したため自動的に「User」ロールが付与されます - 既存ユーザーの場合： - 「ユーザー管理」に移動 - ユーザーを選択 - - 「ロール」タブでユーザーにロールを割り当て + - 「ロール」タブでロールを割り当て :::tip プログラムによるロール管理 -Logto の [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) を使って、ユーザーロールをプログラムで管理することも可能です。自動ユーザー管理や管理画面の構築時に特に便利です。 +Logto の [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) を使ってユーザーロールをプログラムで管理することもできます。自動化や管理画面構築時に便利です。 ::: -アクセストークンをリクエストすると、Logto はユーザーロールの権限に基づいてトークンの `scope` クレームにスコープを含めます。 +アクセストークンをリクエストする際、Logto はユーザーロールの権限に基づきスコープをトークンの `scope` クレームに含めます。 @@ -242,8 +287,8 @@ Logto の [Management API](https://docs.logto.io/integrate-logto/interact-with-m 1. クライアントスコープを作成： - - レルム内で「クライアントスコープ」に移動 - - 以下の 3 つのクライアントスコープを作成： + - リアルムで「Client scopes」に移動 + - 新しいクライアントスコープを 3 つ作成： - `create:todos` - `read:todos` - `delete:todos` @@ -251,18 +296,66 @@ Logto の [Management API](https://docs.logto.io/integrate-logto/interact-with-m 2. クライアントを設定： - クライアント設定に移動 - - 「クライアントスコープ」タブで作成したすべてのスコープを追加 - - トークンマッパーがスコープを含めるように設定されていることを確認 + - 「Client scopes」タブで作成したスコープをすべて追加 + - トークンマッパーがスコープを含めるよう設定されていることを確認 -3. オプション：ロールによる管理を利用 - - ロールベースの管理を希望する場合： - - 異なるアクセスレベル用のレルムロールを作成 +3. オプション：ロールによる管理 + - ロールベース管理を希望する場合： + - アクセスレベルごとにリアルムロールを作成 - スコープをロールにマッピング - ユーザーにロールを割り当て - - それ以外の場合は、ユーザーやクライアントレベルの権限で直接スコープを割り当てることも可能 + - それ以外は、ユーザーやクライアントレベルの権限でスコープを直接割り当てても OK Keycloak は付与されたスコープをアクセス トークンの `scope` クレームに含めます。 + + + +[Asgardeo](https://wso2.com/asgardeo) は、API リソースとスコープを使ったロールベースのアクセス制御 (RBAC) ときめ細かな認可をサポートしています。設定方法は以下の通りです： + +1. [Asgardeo Console](https://console.asgardeo.io) にサインイン + +2. API リソースとスコープを定義： + - **API Resources** に移動 + - **"New API Resource"** をクリック + - **Identifier** を `https://todo.mcp-server.app`（または任意の URL）に設定 + - **Display Name** を `Todo Manager` に + - 次のスコープを追加： + - `create:todos` : "新しい todo アイテムを作成" + - `read:todos` : "すべての todo アイテムを閲覧" + - `delete:todos` : "任意の todo アイテムを削除" + - リソースを作成 + +3. ロールを作成： + - **User Management > Roles** でロールを作成し、スコープを直接割り当て + - **New Role** をクリック + - **Basic Details** でロール名（例：`Admin` または `User`）を入力 + - ロールのオーディエンスを `Application` にし、**Assigned Application** で `MCP Inspector Application` を選択 + - **Permission Selection** で先ほど作成した API リソース（例：`Todo Manager`）を選択 + - このロールに割り当てたいスコープを選択（例：`create:todos`, `read:todos`, `delete:todos`） + - **Finish** をクリックしてロールを作成 + + すでにアプリケーションを作成済みの場合 + - **Application > MCP Inspector Application > Roles tab** に移動 + - **Application Role** をオーディエンスタイプに選択し、**New Role** をクリック + - `Admin` ロールを作成し、3 つのスコープすべてを付与 + - `User` ロールを作成し、`create:todos` スコープのみ付与 + +4. ユーザーにロールを割り当て： + - **User Management > Roles** に移動 + - 作成したロール（例：`Admin` または `User`）を選択し、**Users** タブへ + - **Assign User** を選択し、割り当てたいユーザーを選択して保存 + +スコープは JWT アクセス トークンの `scope` クレームにスペース区切りの文字列として含まれます。 +認可サーバーを設定後、ユーザーは付与されたスコープを含むアクセス トークンを受け取ります。MCP サーバーはこれらのスコープを使って次を判断します： + +ユーザーが新しい todo を作成できるか（`create:todos`） +ユーザーがすべての todo を閲覧できるか（`read:todos`）または自分のものだけか +ユーザーが任意の todo を削除できるか（`delete:todos`）または自分のものだけか + +Asgardeo の詳細な設定方法は以下を参照してください： +- [API Resources Guide](https://wso2.com/asgardeo/docs/guides/authorization/api-authorization) +- [Role Management](https://wso2.com/asgardeo/docs/guides/users/manage-roles) @@ -277,30 +370,30 @@ OAuth 2.0 または OpenID Connect プロバイダーの場合、異なる権限 2. クライアントを設定： - - クライアントを登録または更新し、これらのスコープをリクエストするように設定 + - クライアントを登録または更新し、これらのスコープをリクエスト - スコープがアクセス トークンに含まれることを確認 -3. 権限を割り当てる： - - プロバイダーのインターフェースでユーザーに適切なスコープを付与 - - 一部のプロバイダーはロールベース管理をサポートし、他は直接スコープ割り当てを使用 - - 推奨される方法はプロバイダーのドキュメントを参照 +3. 権限を割り当て： + - プロバイダーの管理画面でユーザーに適切なスコープを付与 + - プロバイダーによってはロールベース管理もサポート + - 推奨方法はプロバイダーのドキュメントを参照 :::tip -ほとんどのプロバイダーは、付与されたスコープをアクセス トークンの `scope` クレームに含めます。形式は通常、スペース区切りのスコープ値の文字列です。 +ほとんどのプロバイダーは付与されたスコープをアクセス トークンの `scope` クレームに含めます。形式は通常スペース区切りのスコープ値です。 ::: -認可サーバーの設定後、ユーザーは付与されたスコープを含むアクセス トークンを受け取ります。MCP サーバーはこれらのスコープを使って次のことを判断します： +認可サーバーを設定後、ユーザーは付与されたスコープを含むアクセス トークンを受け取ります。MCP サーバーはこれらのスコープを使って次を判断します： -- 新しい todo を作成できるか（`create:todos`） -- すべての todo を閲覧できるか（`read:todos`）または自分のものだけか -- 任意の todo を削除できるか（`delete:todos`）または自分のものだけか +- ユーザーが新しい todo を作成できるか（`create:todos`） +- ユーザーがすべての todo を閲覧できるか（`read:todos`）または自分のものだけか +- ユーザーが任意の todo を削除できるか（`delete:todos`）または自分のものだけか ## MCP サーバーをセットアップする \{#set-up-the-mcp-server} -[公式 MCP SDK](https://github.com/modelcontextprotocol) を使って todo マネージャー MCP サーバーを作成します。 +[MCP 公式 SDK](https://github.com/modelcontextprotocol) を使って todo マネージャー MCP サーバーを作成します。 ### 新しいプロジェクトを作成 \{#create-a-new-project} @@ -328,13 +421,13 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -サンプルでは TypeScript を使用しています。Node.js v22.6.0 以降では `--experimental-strip-types` フラグで TypeScript をネイティブ実行できます。JavaScript を使う場合もほぼ同様ですが、Node.js v22.6.0 以降を使用してください。詳細は Node.js ドキュメントを参照してください。 +サンプルでは TypeScript を使用しています。Node.js v22.6.0 以降は `--experimental-strip-types` フラグで TypeScript をネイティブ実行できます。JavaScript を使う場合もほぼ同様ですが、Node.js v22.6.0 以降を利用してください。詳細は Node.js ドキュメントを参照してください。 ::: -### MCP SDK と依存パッケージのインストール \{#install-the-mcp-sdk-and-dependencies} +### MCP SDK と依存パッケージをインストール \{#install-the-mcp-sdk-and-dependencies} @@ -343,7 +436,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" pip install "mcp[cli]" starlette uvicorn ``` -または `uv` や `poetry` などお好みのパッケージマネージャーを利用できます。 +または `uv` や `poetry` などお好みのパッケージマネージャーを利用してください。 @@ -352,7 +445,7 @@ pip install "mcp[cli]" starlette uvicorn npm install @modelcontextprotocol/sdk express zod ``` -または `pnpm` や `yarn` などお好みのパッケージマネージャーを利用できます。 +または `pnpm` や `yarn` などお好みのパッケージマネージャーを利用してください。 @@ -364,7 +457,7 @@ npm install @modelcontextprotocol/sdk express zod -`todo-manager.py` というファイルを作成し、次のコードを追加します： +`todo-manager.py` というファイルを作成し、以下のコードを追加： ```python from typing import Any @@ -404,12 +497,12 @@ uvicorn todo_manager:app --host 0.0.0.0 --port 3001 :::note -現時点の MCP inspector 実装では認可フローに対応していないため、SSE アプローチで MCP サーバーをセットアップします。MCP inspector が認可フローに対応した際にはコードを更新します。 +現時点の MCP inspector 実装は認可フローに対応していないため、SSE アプローチで MCP サーバーをセットアップします。MCP inspector が認可フローに対応次第、コードを更新します。 ::: `pnpm` や `yarn` も利用可能です。 -`todo-manager.ts` というファイルを作成し、次のコードを追加します： +`todo-manager.ts` というファイルを作成し、以下のコードを追加： ```ts // todo-manager.ts @@ -484,13 +577,13 @@ npm start ## MCP サーバーを検証する \{#inspect-the-mcp-server} -### MCP inspector をクローンして起動 \{#clone-and-run-mcp-inspector} +### MCP inspector をクローンして実行 \{#clone-and-run-mcp-inspector} -MCP サーバーが起動したので、MCP inspector を使って `whoami` ツールが利用可能か確認します。 +MCP サーバーが起動したら、MCP inspector を使って `whoami` ツールが利用可能か確認できます。 -現状の実装制限のため、[MCP inspector](https://github.com/mcp-auth/inspector) をフォークし、認証 (Authentication)・認可 (Authorization) に柔軟かつ拡張可能にしました。オリジナルリポジトリにもプルリクエストを提出済みです。 +現状の実装制限のため、[MCP inspector](https://github.com/mcp-auth/inspector) をフォークし、認証 (Authentication)・認可 (Authorization) に柔軟かつ拡張しやすくしています。オリジナルリポジトリにもプルリクエストを提出済みです。 -MCP inspector を起動するには（Node.js が必要です）： +MCP inspector を実行するには、以下のコマンドを使用します（Node.js 必須）： ```bash git clone https://github.com/mcp-auth/inspector.git @@ -506,7 +599,7 @@ npm run dev 進める前に、MCP inspector の設定を確認してください： - **Transport Type**：`SSE` に設定 -- **URL**：MCP サーバーの URL を設定（例：`http://localhost:3001/sse`） +- **URL**：MCP サーバーの URL（例：`http://localhost:3001/sse`） 「Connect」ボタンをクリックし、MCP inspector が MCP サーバーに接続できるか確認します。問題なければ MCP inspector に「Connected」ステータスが表示されます。 @@ -514,9 +607,9 @@ npm run dev 1. MCP inspector の上部メニューで「Tools」タブをクリック 2. 「List Tools」ボタンをクリック -3. `create-todo`, `get-todos`, `delete-todo` ツールが一覧に表示されるはずです。クリックして詳細を開きます。 -4. 右側に「Run Tool」ボタンが表示されます。クリックして必要なパラメータを入力し、ツールを実行します。 -5. ツールの結果として `{"error": "Not implemented"}` という JSON レスポンスが表示されます。 +3. `create-todo`, `get-todos`, `delete-todo` ツールが一覧に表示されるはずです。クリックして詳細を開きます +4. 右側に「Run Tool」ボタンが表示されます。必要なパラメータを入力してツールを実行 +5. ツールの結果として `{"error": "Not implemented"}` という JSON レスポンスが表示されます ![MCP inspector first run](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) @@ -525,7 +618,7 @@ npm run dev このセクションを完了するには、いくつかの考慮事項があります：
-**認可サーバーの発行者 (Issuer) URL** +**認可サーバーの発行者 URL** 通常は認可サーバーのベース URL です（例：`https://auth.example.com`）。プロバイダーによっては `https://example.logto.app/oidc` のようなパスが付く場合もあるので、ドキュメントを確認してください。 @@ -534,16 +627,16 @@ npm run dev
**認可サーバーメタデータの取得方法** -- 認可サーバーが [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) または [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) に準拠していれば、MCP Auth の組み込みユーティリティで自動取得できます。 -- 準拠していない場合は、MCP サーバー設定でメタデータ URL やエンドポイントを手動指定する必要があります。詳細はプロバイダーのドキュメントを参照してください。 +- 認可サーバーが [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) または [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) に準拠していれば、MCP Auth の組み込みユーティリティで自動取得できます +- 準拠していない場合は、MCP サーバー設定でメタデータ URL やエンドポイントを手動指定してください。詳細はプロバイダーのドキュメントを参照
**MCP inspector を認可サーバーのクライアントとして登録する方法** -- 認可サーバーが [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) をサポートしていれば、このステップは不要です。MCP inspector が自動でクライアント登録します。 -- サポートしていない場合は、MCP inspector を手動でクライアント登録する必要があります。 +- 認可サーバーが [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) をサポートしていれば、MCP inspector が自動でクライアント登録します +- サポートしていない場合は、MCP inspector を手動でクライアント登録してください
@@ -552,9 +645,9 @@ npm run dev 認可サーバーからアクセス トークンをリクエストする際、ターゲットリソースや権限指定の方法がいくつかあります。主なパターンは以下の通りです： -- **リソースインジケーター方式**： +- **リソースインジケーター型**： - - `resource` パラメータでターゲット API を指定（[RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707) 参照） + - `resource` パラメータでターゲット API を指定（[RFC 8707: OAuth 2.0 のリソースインジケーター](https://datatracker.ietf.org/doc/html/rfc8707) 参照） - モダンな OAuth 2.0 実装で一般的 - 例： ```json @@ -563,12 +656,12 @@ npm run dev "scope": "create:todos read:todos" } ``` - - サーバーはリソースにバインドされたトークンを発行 + - サーバーはリソースに紐づいたトークンを発行 -- **オーディエンス方式**： +- **オーディエンス型**： - `audience` パラメータでトークンの受信者を指定 - - リソースインジケーターと似ているが意味が異なる + - リソースインジケーターと似ているが意味合いが異なる - 例： ```json { @@ -577,8 +670,8 @@ npm run dev } ``` -- **純粋なスコープ方式**： - - リソースやオーディエンスパラメータなしでスコープのみを利用 +- **純粋なスコープ型**： + - resource/audience パラメータなしでスコープのみを利用 - 従来の OAuth 2.0 アプローチ - 例： ```json @@ -586,61 +679,95 @@ npm run dev "scope": "todo-api:create todo-api:read openid profile" } ``` - - 権限の名前空間化のためにプレフィックス付きスコープを使うことが多い + - スコープにプレフィックスを付けて権限を名前空間化することが多い - シンプルな OAuth 2.0 実装で一般的 :::tip ベストプラクティス -- サポートされているパラメータはプロバイダーのドキュメントを確認 -- 複数の方式を同時にサポートするプロバイダーもある -- リソースインジケーターはオーディエンス制限によるセキュリティ向上に有効 -- 利用可能ならリソースインジケーター方式を推奨 +- プロバイダーのドキュメントでサポートされているパラメータを確認 +- 複数のアプローチを同時にサポートするプロバイダーもあり +- リソースインジケーターはオーディエンス制限によるセキュリティ向上 +- 利用可能ならリソースインジケーターを使うとより良いアクセス制御が可能 :::
-プロバイダーごとに固有の要件がある場合もありますが、以下の手順で MCP inspector および MCP サーバーをプロバイダー固有の設定で統合できます。 +各プロバイダーごとに要件は異なりますが、以下の手順で MCP inspector と MCP サーバーをプロバイダー固有の設定で連携できます。 ### MCP inspector をクライアントとして登録 \{#register-mcp-inspector-as-a-client} -[Logto](https://logto.io) との統合は簡単です。OpenID Connect プロバイダーであり、リソースインジケーターとスコープをサポートしているため、`https://todo.mcp-server.app` をリソースインジケーターとして todo API を安全に保護できます。 +[Logto](https://logto.io) との連携は簡単です。OpenID Connect プロバイダーであり、リソースインジケーターとスコープをサポートしているため、`https://todo.mcp-server.app` をリソースインジケーターとして todo API を安全に保護できます。 -Logto は現時点で Dynamic Client Registration をサポートしていないため、MCP inspector を Logto テナントのクライアントとして手動登録する必要があります： +Logto は現時点で Dynamic Client Registration をサポートしていないため、MCP inspector を手動で Logto テナントのクライアントとして登録する必要があります： 1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)** の値（例：`http://localhost:6274/oauth/callback`）をコピー -2. [Logto Console](https://cloud.logto.io)（またはセルフホストの Logto Console）にサインイン -3. 「アプリケーション」タブで「Create application」をクリック。ページ下部で「Create app without framework」をクリック +2. [Logto Console](https://cloud.logto.io)（またはセルフホスト Logto Console）にサインイン +3. 「Applications」タブで「Create application」をクリック。ページ下部で「Create app without framework」をクリック 4. アプリケーション詳細を入力し、「Create application」をクリック： - **アプリケーションタイプ**：「Single-page application」を選択 - **アプリケーション名**：例「MCP Inspector」 -5. 「Settings / Redirect URIs」セクションで、先ほどコピーした **Redirect URL (auto-populated)** を貼り付け、「Save changes」をクリック -6. 上部カードに「App ID」が表示されるのでコピー -7. MCP inspector に戻り、「OAuth Configuration」セクションの「Client ID」に「App ID」を貼り付け -8. 「Auth Params」フィールドに `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` を入力。これで Logto から返されるアクセストークンに必要なスコープが含まれます。 +5. 「Settings / Redirect URIs」セクションで、MCP inspector からコピーした **Redirect URL (auto-populated)** を貼り付け、「Save changes」をクリック +6. 上部カードに「App ID」値が表示されるのでコピー +7. MCP inspector に戻り、「OAuth Configuration」セクションの「Client ID」に「App ID」値を貼り付け +8. 「Auth Params」フィールドに `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` を入力。これで Logto から返されるアクセス トークンに必要なスコープが含まれるようになります + + + + + Asgardeo は標準 API による Dynamic Client Registration をサポートしていますが、エンドポイントは保護されており、必要な権限を持つアクセストークンが必要です。このチュートリアルでは Asgardeo Console から手動でクライアント登録します。 + + :::note + Asgardeo アカウントをお持ちでない場合は [無料登録](https://asgardeo.io) できます。 + ::: + MCP Inspector 用の Asgardeo 設定手順： + + 1. [Asgardeo Console](https://console.asgardeo.io) にログインし、組織を選択 + + 2. 新しいアプリケーションを作成： + - **Applications** → **New Application** + - **Single-Page Application** を選択 + - アプリ名を `MCP Inspector` などに + - **Authorized Redirect URLs** に MCP Inspector からコピーした **Redirect URL**（例：`http://localhost:6274/oauth/callback`）を貼り付け + - **Create** をクリック + + 3. プロトコル設定： + - **Protocol** タブで + - 自動生成された **Client ID** をコピー + - **Access Token** セクションで `Token Type` を `JWT` に切り替え + - **Update** をクリック + + 4. MCP Inspector 側で： + - **OAuth Configuration** セクションを開く + - コピーした **Client ID** を貼り付け + - **Auth Params** フィールドに以下を入力し必要なスコープをリクエスト： + + ```json + { "scope": "openid profile email" } + ``` :::note -これは一般的な OAuth 2.0 / OpenID Connect プロバイダー統合ガイドです。OIDC は OAuth 2.0 上に構築されているため、手順はほぼ同じです。詳細はプロバイダーのドキュメントを参照してください。 +これは汎用的な OAuth 2.0 / OpenID Connect プロバイダー連携ガイドです。OIDC は OAuth 2.0 の上に構築されているため、手順はほぼ同じです。詳細は各プロバイダーのドキュメントを参照してください。 ::: -プロバイダーが Dynamic Client Registration をサポートしていれば、下記の 8 番に直接進んで MCP inspector を設定できます。サポートしていない場合は MCP inspector を手動でクライアント登録してください： +プロバイダーが Dynamic Client Registration をサポートしていれば、下記の 8 番目の手順に直接進んで MCP inspector を設定できます。サポートしていない場合は MCP inspector を手動でクライアント登録してください： 1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)** の値（例：`http://localhost:6274/oauth/callback`）をコピー -2. プロバイダーのコンソールにサインイン +2. プロバイダーの管理画面にサインイン -3. 「アプリケーション」または「クライアント」セクションで新しいアプリケーションまたはクライアントを作成 +3. 「Applications」または「Clients」セクションで新しいアプリケーションまたはクライアントを作成 4. クライアントタイプが必要な場合は「Single-page application」または「Public client」を選択 -5. アプリケーション作成後、リダイレクト URI を設定。先ほどコピーした **Redirect URL (auto-populated)** を貼り付け +5. アプリ作成後、リダイレクト URI を設定。MCP inspector からコピーした **Redirect URL (auto-populated)** を貼り付け -6. 新規アプリケーションの「Client ID」または「Application ID」をコピー +6. 新規アプリの「Client ID」または「Application ID」をコピー 7. MCP inspector に戻り、「OAuth Configuration」セクションの「Client ID」に貼り付け @@ -666,7 +793,7 @@ MCP サーバープロジェクトで MCP Auth SDK をインストールし、 pip install mcpauth ``` -または `uv` や `poetry` などお好みのパッケージマネージャーを利用できます。 +または `uv` や `poetry` などお好みのパッケージマネージャーを利用してください。 @@ -686,19 +813,27 @@ MCP Auth は認可サーバーメタデータが必要です。プロバイダ -発行者 (Issuer) URL は Logto Console のアプリケーション詳細ページ「Endpoints & Credentials / Issuer endpoint」セクションで確認できます（例：`https://my-project.logto.app/oidc`）。 +発行者 URL は Logto Console のアプリ詳細ページ「Endpoints & Credentials / Issuer endpoint」セクションで確認できます（例：`https://my-project.logto.app/oidc`）。 + + + Asgardeo Console で発行者 URL を確認できます。作成したアプリの **Info** タブを開き、**Issuer** フィールドを参照してください（例：`https://api.asgardeo.io/t//oauth2/token`）。 + + + + + OAuth 2.0 プロバイダーの場合： -1. 認可サーバーの URL（Issuer URL またはベース URL）をドキュメントで確認 +1. 認可サーバー URL（issuer URL や base URL と呼ばれる）をドキュメントで確認 2. 多くの場合 `https://{your-domain}/.well-known/oauth-authorization-server` で公開 -3. 管理コンソールの OAuth/API 設定を確認 +3. 管理画面の OAuth/API 設定を参照 @@ -710,7 +845,7 @@ OAuth 2.0 プロバイダーの場合： -`todo-manager.py` を MCP Auth 設定を含むように更新： +`todo-manager.py` を更新し、MCP Auth 設定を追加： ```python from mcpauth import MCPAuth @@ -725,7 +860,7 @@ mcp_auth = MCPAuth(server=auth_server_config) -`todo-manager.ts` を MCP Auth 設定を含むように更新： +`todo-manager.ts` を更新し、MCP Auth 設定を追加： ```ts // todo-manager.ts @@ -743,7 +878,7 @@ const mcpAuth = new MCPAuth({ ### MCP サーバーを更新 \{#update-mcp-server} -あと少しです！MCP Auth のルートとミドルウェア関数を適用し、ユーザーのスコープに基づく権限管理を todo マネージャーツールに実装します。 +あと少しです！MCP Auth のルートとミドルウェア関数を適用し、ユーザーのスコープに基づく権限制御を todo マネージャーツールに実装します。 @@ -754,7 +889,7 @@ def create_todo(content: str) -> dict[str, Any]: """新しい todo を作成""" return ( mcp_auth.auth_info.scopes - if mcp_auth.auth_info # Bearer 認証ミドルウェアでセットされる + if mcp_auth.auth_info # Bearer auth ミドルウェアでセットされます else {"error": "Not authenticated"} ) @@ -765,7 +900,7 @@ app = Starlette( routes=[ # メタデータルート（`/.well-known/oauth-authorization-server`）を追加 mcp_auth.metadata_route(), - # Bearer 認証ミドルウェアで MCP サーバーを保護 + # Bearer auth ミドルウェアで MCP サーバーを保護 Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), ], ) @@ -797,7 +932,7 @@ app.use(mcpAuth.bearerAuth('jwt')); -次に、実際のツールを実装します。 +次に、具体的なツールを実装します。 まず、メモリ上で todo アイテムの基本的な CRUD 操作を提供するシンプルな todo サービスを作成します。 @@ -845,7 +980,7 @@ class TodoService: すべての todo を取得。owner_id でフィルタ可能。 Args: - owner_id: 指定した場合、そのユーザー所有の todo のみ返す + owner_id: 指定時はこのユーザーの todo のみ返す Returns: Todo 辞書のリスト @@ -860,7 +995,7 @@ class TodoService: ID で todo を取得 Args: - todo_id: 取得する todo の ID + todo_id: 取得したい todo の ID Returns: 見つかれば Todo オブジェクト、なければ None @@ -895,7 +1030,7 @@ class TodoService: ID で todo を削除 Args: - todo_id: 削除する todo の ID + todo_id: 削除したい todo の ID Returns: 削除した todo の辞書（見つかれば）、なければ None @@ -927,7 +1062,7 @@ type Todo = { }; /** - * デモ用のシンプルな Todo サービス。 + * デモ用のシンプルな Todo サービス * メモリ上の配列で todo を管理 */ export class TodoService { @@ -978,7 +1113,7 @@ export class TodoService { -次にツール層で、ユーザーのスコープに基づいて操作が許可されるかどうかを判定します： +次にツール層で、ユーザーのスコープに基づき操作が許可されるか判定します： @@ -1093,23 +1228,23 @@ server.tool( MCP サーバーを再起動し、ブラウザで MCP inspector を開きます。「Connect」ボタンをクリックすると、認可サーバーのサインインページにリダイレクトされます。 -サインインして MCP inspector に戻ったら、前回のチェックポイントと同じ操作で todo マネージャーツールを実行します。今回は認証済みユーザーとしてツールを利用できます。ツールの挙動は、ユーザーに割り当てられたロールと権限によって異なります： +サインイン後 MCP inspector に戻り、前回のチェックポイントと同じ操作を繰り返して todo マネージャーツールを実行します。今回は認証済みユーザーとしてツールを利用できます。ツールの挙動はユーザーに割り当てられたロールと権限によって異なります： -- **User**（`create:todos` スコープのみ）の場合： +- **User**（`create:todos` スコープのみ）でログインしている場合： - `create-todo` ツールで新しい todo を作成可能 - 自分の todo のみ閲覧・削除可能 - 他ユーザーの todo は閲覧・削除不可 -- **Admin**（すべてのスコープ：`create:todos`, `read:todos`, `delete:todos`）の場合： +- **Admin**（すべてのスコープ：`create:todos`, `read:todos`, `delete:todos`）でログインしている場合： - 新しい todo を作成可能 - `get-todos` ツールですべての todo を閲覧可能 - - `delete-todo` ツールで所有者に関係なく任意の todo を削除可能 + - `delete-todo` ツールで誰の todo でも削除可能 異なる権限レベルをテストするには： -1. 現在のセッションからサインアウト（MCP inspector の「Disconnect」ボタンをクリック） -2. 別のロール／権限を持つユーザーアカウントでサインイン +1. MCP inspector で「Disconnect」ボタンをクリックして現在のセッションをサインアウト +2. 別のロール/権限を持つユーザーアカウントでサインイン 3. 同じツールを再度試し、ユーザーの権限による挙動の違いを確認 これにより、ロールベースのアクセス制御 (RBAC) が実際にどのように機能するかを体験できます。 @@ -1120,14 +1255,14 @@ MCP サーバーを再起動し、ブラウザで MCP inspector を開きます :::info -[MCP Auth Python SDK リポジトリ](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) で MCP サーバー（OIDC 版）の完全なコードを確認できます。 +MCP サーバー（OIDC 版）の完全なコードは [MCP Auth Python SDK リポジトリ](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) をご覧ください。 ::: :::info -[MCP Auth Node.js SDK リポジトリ](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) で MCP サーバー（OIDC 版）の完全なコードを確認できます。 +MCP サーバー（OIDC 版）の完全なコードは [MCP Auth Node.js SDK リポジトリ](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) をご覧ください。 ::: @@ -1135,11 +1270,11 @@ MCP サーバーを再起動し、ブラウザで MCP inspector を開きます ## 締めくくり \{#closing-notes} -🎊 おめでとうございます！チュートリアルを無事完了しました。ここまでで行ったことを振り返りましょう： +🎊 おめでとうございます！チュートリアルを無事完了しました。ここまでで実施した内容を振り返りましょう： - Todo 管理ツール（`create-todo`, `get-todos`, `delete-todo`）付きの基本的な MCP サーバーのセットアップ - ユーザーと管理者で異なる権限レベルを持つロールベースのアクセス制御 (RBAC) の実装 -- MCP サーバーを MCP Auth で認可サーバーと統合 -- MCP Inspector でユーザー認証とスコープ付きアクセストークンを使ったツール呼び出し +- MCP Auth を使った MCP サーバーと認可サーバーの連携 +- MCP Inspector でユーザー認証 (Authentication)・スコープ付きアクセス トークンを使ったツール呼び出し 他のチュートリアルやドキュメントもぜひご覧いただき、MCP Auth を最大限に活用してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx index 9322c77..2d9813f 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx @@ -15,82 +15,94 @@ import SetupOidc from './_setup-oidc.mdx'; このチュートリアルを完了すると、次のことができるようになります： -- ✅ MCP Auth を使ってユーザーを認証 (Authentication) する基本的な理解 -- ✅ ユーザーのアイデンティティ情報を取得するツールを提供する MCP サーバー +- ✅ MCP Auth を使ってユーザーを認証 (Authentication) する基本的な流れを理解できる +- ✅ ユーザーのアイデンティティ情報を取得するツールを提供する MCP サーバーを構築できる ## 概要 \{#overview} -このチュートリアルでは、以下のコンポーネントを使用します： +このチュートリアルでは、以下のコンポーネントを扱います： - **MCP サーバー**：MCP 公式 SDK を使ってリクエストを処理するシンプルな MCP サーバー -- **MCP inspector**：MCP サーバーのためのビジュアルテストツール。OAuth / OIDC クライアントとして認可フローを開始し、アクセス トークン (Access token) を取得する役割も担います。 -- **認可 (Authorization) サーバー**：ユーザーのアイデンティティを管理し、アクセス トークン (Access token) を発行する OAuth 2.1 または OpenID Connect プロバイダー +- **MCP inspector**：MCP サーバー用のビジュアルテストツール。OAuth / OIDC クライアントとして認可フローを開始し、アクセス トークンを取得する役割も担います。 +- **認可 (Authorization) サーバー**：ユーザーのアイデンティティを管理し、アクセス トークンを発行する OAuth 2.1 または OpenID Connect プロバイダー -これらのコンポーネント間のやり取りを高レベルで示した図です： +これらのコンポーネント間のやり取りを示す高レベルの図は以下の通りです： ```mermaid sequenceDiagram participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as 認可サーバー (Authorization Server) + participant Server as MCP サーバー + participant Auth as 認可 (Authorization) サーバー Client->>Server: ツール `whoami` をリクエスト Server->>Client: 401 Unauthorized を返す Client->>Auth: 認可フローを開始 Auth->>Auth: 認可フローを完了 Auth->>Client: 認可コード付きでリダイレクト - Client->>Auth: コードをアクセス トークン (Access token) と交換 - Auth->>Client: アクセス トークン (Access token) を返す - Client->>Server: アクセス トークン (Access token) 付きで `whoami` をリクエスト - Server->>Auth: アクセス トークン (Access token) でユーザー情報を取得 + Client->>Auth: コードをアクセス トークンと交換 + Auth->>Client: アクセス トークンを返す + Client->>Server: アクセス トークン付きで `whoami` をリクエスト + Server->>Auth: アクセス トークンでユーザー情報を取得 Auth->>Server: ユーザー情報を返す Server->>Client: ユーザー情報を返す ``` ## 認可 (Authorization) サーバーを理解する \{#understand-your-authorization-server} -### ユーザーのアイデンティティ情報の取得 \{#retrieving-user-identity-information} +### ユーザーアイデンティティ情報の取得 \{#retrieving-user-identity-information} -このチュートリアルを完了するには、認可 (Authorization) サーバーがユーザーのアイデンティティ情報を取得するための API を提供している必要があります： +このチュートリアルを完了するには、認可 (Authorization) サーバーがユーザーアイデンティティ情報を取得するための API を提供している必要があります： -[Logto](https://logto.io) は OpenID Connect プロバイダーであり、標準の [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしてユーザーのアイデンティティ情報を取得できます。 +[Logto](https://logto.io) は、ユーザーアイデンティティ情報を取得するための標準 [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートする OpenID Connect プロバイダーです。 -userinfo エンドポイントにアクセスできるアクセス トークン (Access token) を取得するには、少なくとも `openid` と `profile` の 2 つのスコープ (Scope) が必要です。スコープ (Scope) の設定については後述しますので、そのまま読み進めてください。 +userinfo エンドポイントにアクセスできるアクセス トークンを取得するには、少なくとも `openid` と `profile` の 2 つのスコープが必要です。スコープの設定については後述しますので、そのまま読み進めてください。 -[Keycloak](https://www.keycloak.org) は、OpenID Connect (OIDC) を含む複数のプロトコルをサポートするオープンソースのアイデンティティおよびアクセス管理ソリューションです。OIDC プロバイダーとして、標準の [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) を実装してユーザーのアイデンティティ情報を取得できます。 +[Keycloak](https://www.keycloak.org) は、OpenID Connect (OIDC) を含む複数のプロトコルをサポートするオープンソースのアイデンティティおよびアクセス管理ソリューションです。OIDC プロバイダーとして、標準の [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) を実装しています。 -userinfo エンドポイントにアクセスできるアクセス トークン (Access token) を取得するには、少なくとも `openid` と `profile` の 2 つのスコープ (Scope) が必要です。スコープ (Scope) の設定については後述しますので、そのまま読み進めてください。 +userinfo エンドポイントにアクセスできるアクセス トークンを取得するには、少なくとも `openid` と `profile` の 2 つのスコープが必要です。スコープの設定については後述しますので、そのまま読み進めてください。 + + + + + +[Asgardeo](https://wso2.com/asgardeo) は、OAuth 2.0 および OpenID Connect (OIDC) をサポートするクラウドネイティブな IDaaS プラットフォームで、モダンなアプリケーション向けに堅牢なアイデンティティおよびアクセス管理を提供します。 + +ユーザー情報は、アクセス トークンとともに返される ID トークン内にエンコードされていますが、OIDC プロバイダーとして [UserInfo エンドポイント](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/) も公開しており、アプリケーションはペイロード内で認証済みユーザーのクレーム (Claims) を取得できます。 + +このエンドポイントは [OIDC ディスカバリーエンドポイント](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs) から動的に発見することも、Asgardeo コンソールのアプリケーション「Info」タブから確認することもできます。 + +userinfo エンドポイントにアクセスできるアクセス トークンを取得するには、少なくとも `openid` と `profile` の 2 つのスコープが必要です。 -ほとんどの OpenID Connect プロバイダーは、[userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしてユーザーのアイデンティティ情報を取得できます。 +ほとんどの OpenID Connect プロバイダーは、ユーザーアイデンティティ情報を取得するための [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしています。 -プロバイダーのドキュメントで、このエンドポイントがサポートされているか確認してください。プロバイダーが [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) をサポートしている場合、`.well-known/openid-configuration` エンドポイントのレスポンスに `userinfo_endpoint` が含まれているかも確認できます。 +プロバイダーのドキュメントを確認し、このエンドポイントがサポートされているか確認してください。プロバイダーが [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) をサポートしている場合、`.well-known/openid-configuration` エンドポイントのレスポンスに `userinfo_endpoint` が含まれているか確認できます。 -userinfo エンドポイントにアクセスできるアクセス トークン (Access token) を取得するには、少なくとも `openid` と `profile` の 2 つのスコープ (Scope) が必要です。スコープ (Scope) とユーザーアイデンティティクレーム (Claim) の対応は、プロバイダーのドキュメントを参照してください。 +userinfo エンドポイントにアクセスできるアクセス トークンを取得するには、少なくとも `openid` と `profile` の 2 つのスコープが必要です。スコープとユーザーアイデンティティクレーム (Claims) のマッピングについては、プロバイダーのドキュメントを参照してください。 -OAuth 2.0 ではユーザーのアイデンティティ情報を取得する標準的な方法は定義されていませんが、多くのプロバイダーは独自のエンドポイントを実装しています。プロバイダーのドキュメントで、アクセス トークン (Access token) を使ってユーザーのアイデンティティ情報をどのように取得するか、また認可フローでどのパラメーターが必要かを確認してください。 +OAuth 2.0 にはユーザーアイデンティティ情報を取得する標準的な方法は定義されていませんが、多くのプロバイダーは独自のエンドポイントを実装しています。アクセス トークンを使ってユーザーアイデンティティ情報を取得する方法や、認可フローでアクセス トークンを取得する際に必要なパラメーターについては、プロバイダーのドキュメントを確認してください。 ### Dynamic Client Registration \{#dynamic-client-registration} -Dynamic Client Registration はこのチュートリアルでは必須ではありませんが、MCP クライアントの登録プロセスを認可 (Authorization) サーバーと自動化したい場合に便利です。詳細は [Dynamic Client Registration は必要ですか？](../../provider-list.mdx#is-dcr-required) をご覧ください。 +Dynamic Client Registration はこのチュートリアルでは必須ではありませんが、認可 (Authorization) サーバーへの MCP クライアント登録を自動化したい場合に便利です。詳細は [Dynamic Client Registration は必須ですか？](../../provider-list.mdx#is-dcr-required) を参照してください。 ## MCP サーバーのセットアップ \{#set-up-the-mcp-server} -[MCP 公式 SDK](https://github.com/modelcontextprotocol) を使って、認可 (Authorization) サーバーからユーザーのアイデンティティ情報を取得する `whoami` ツール付きの MCP サーバーを作成します。 +[MCP 公式 SDK](https://github.com/modelcontextprotocol) を使って、認可 (Authorization) サーバーからユーザーアイデンティティ情報を取得する `whoami` ツール付きの MCP サーバーを作成します。 ### 新しいプロジェクトの作成 \{#create-a-new-project} @@ -129,7 +141,7 @@ npm pkg set scripts.start="node whoami.js" pip install "mcp[cli]" starlette uvicorn ``` -または `uv` や `poetry` など、お好みのパッケージマネージャーを使用してください。 +または `uv` や `poetry` など、お好みのパッケージマネージャーを利用できます。 @@ -138,14 +150,14 @@ pip install "mcp[cli]" starlette uvicorn npm install @modelcontextprotocol/sdk express ``` -または `pnpm` や `yarn` など、お好みのパッケージマネージャーを使用してください。 +または `pnpm` や `yarn` など、お好みのパッケージマネージャーを利用できます。 ### MCP サーバーの作成 \{#create-the-mcp-server} -まず、`whoami` ツールを実装した MCP サーバーを作成します。 +まず、`whoami` ツールを実装する MCP サーバーを作成しましょう。 @@ -162,7 +174,7 @@ mcp = FastMCP("WhoAmI") @mcp.tool() def whoami() -> dict[str, Any]: - """現在のユーザー情報を返すツール""" + """現在のユーザー情報を返すツール。""" return {"error": "Not authenticated"} app = Starlette( @@ -170,7 +182,7 @@ app = Starlette( ) ``` -サーバーを起動します： +サーバーを起動するには： ```bash uvicorn whoami:app --host 0.0.0.0 --port 3001 @@ -180,10 +192,10 @@ uvicorn whoami:app --host 0.0.0.0 --port 3001 :::note -現時点の MCP inspector 実装では認可 (Authorization) フローを扱えないため、SSE アプローチで MCP サーバーをセットアップします。MCP inspector が認可 (Authorization) フローに対応した際には、ここにコードを更新します。 +現時点の MCP inspector 実装では認可 (Authorization) フローに対応していないため、SSE アプローチで MCP サーバーをセットアップします。MCP inspector が認可 (Authorization) フローに対応した際にはコードを更新します。 ::: -`pnpm` や `yarn` も利用可能です。 +`pnpm` や `yarn` も利用できます。 `whoami.js` というファイルを作成し、次のコードを追加します： @@ -235,7 +247,7 @@ app.post('/messages', async (req, res) => { app.listen(PORT); ``` -サーバーを起動します： +サーバーを起動するには： ```bash npm start @@ -250,9 +262,9 @@ npm start MCP サーバーが起動したので、MCP inspector を使って `whoami` ツールが利用できるか確認します。 -現状の実装制限のため、[MCP inspector](https://github.com/mcp-auth/inspector) をフォークし、認証 (Authentication)・認可 (Authorization) により柔軟かつ拡張可能にしました。オリジナルリポジトリにもプルリクエストを提出済みです。 +現状の実装の制約により、[MCP inspector](https://github.com/mcp-auth/inspector) をフォークし、認証 (Authentication)・認可 (Authorization) に柔軟かつ拡張性を持たせています。オリジナルリポジトリにもプルリクエストを提出しています。 -MCP inspector を起動するには、以下のコマンドを使用します（Node.js が必要です）： +MCP inspector を起動するには、以下のコマンドを実行します（Node.js が必要です）： ```bash git clone https://github.com/mcp-auth/inspector.git @@ -261,30 +273,30 @@ npm install npm run dev ``` -その後、ブラウザで `http://localhost:6274/`（またはターミナルに表示された他の URL）にアクセスして MCP inspector を開きます。 +その後、ブラウザで `http://localhost:6274/`（またはターミナルに表示された他の URL）にアクセスしてください。 ### MCP inspector を MCP サーバーに接続 \{#connect-mcp-inspector-to-the-mcp-server} -進む前に、MCP inspector で次の設定を確認してください： +進める前に、MCP inspector の設定を確認してください： - **Transport Type**：`SSE` に設定 - **URL**：MCP サーバーの URL を設定（例：`http://localhost:3001/sse`） -「Connect」ボタンをクリックして、MCP inspector が MCP サーバーに接続できるか確認します。問題なければ MCP inspector に「Connected」ステータスが表示されます。 +「Connect」ボタンをクリックして MCP inspector が MCP サーバーに接続できるか確認します。問題なければ MCP inspector 上で「Connected」ステータスが表示されます。 ### チェックポイント: `whoami` ツールの実行 \{#checkpoint-run-the-whoami-tool} 1. MCP inspector の上部メニューで「Tools」タブをクリック 2. 「List Tools」ボタンをクリック 3. ページに `whoami` ツールが表示されているはずです。クリックして詳細を開きます。 -4. 右側に「Run Tool」ボタンが表示されるのでクリック +4. 右側に「Run Tool」ボタンが表示されるのでクリックして実行します。 5. ツールの結果として `{"error": "Not authenticated"}` という JSON レスポンスが表示されます。 -![MCP inspector first run](/docs-assets/images/tutorials/whoami/inspector-first-run.png) +![MCP inspector 初回実行](/docs-assets/images/tutorials/whoami/inspector-first-run.png) ## 認可 (Authorization) サーバーとの連携 \{#integrate-with-your-authorization-server} -このセクションを完了するには、いくつかの考慮事項があります： +このセクションを完了するには、いくつかのポイントを考慮する必要があります：
**認可 (Authorization) サーバーの発行者 (Issuer) URL** @@ -294,29 +306,29 @@ npm run dev
-**認可 (Authorization) サーバーのメタデータ取得方法** +**認可 (Authorization) サーバーメタデータの取得方法** - 認可 (Authorization) サーバーが [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) または [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) に準拠していれば、MCP Auth の組み込みユーティリティで自動取得できます。 -- 準拠していない場合は、MCP サーバーの設定でメタデータ URL やエンドポイントを手動指定する必要があります。詳細はプロバイダーのドキュメントを参照してください。 +- 準拠していない場合は、MCP サーバーの設定でメタデータ URL やエンドポイントを手動で指定する必要があります。詳細はプロバイダーのドキュメントを参照してください。
**MCP inspector を認可 (Authorization) サーバーのクライアントとして登録する方法** -- 認可 (Authorization) サーバーが [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) をサポートしていれば、このステップはスキップできます。MCP inspector が自動でクライアント登録します。 +- 認可 (Authorization) サーバーが [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) をサポートしていれば、この手順はスキップできます（MCP inspector が自動登録します）。 - サポートしていない場合は、MCP inspector を手動でクライアント登録する必要があります。
-**ユーザーのアイデンティティ情報の取得方法と認可リクエストパラメーターの設定方法** +**ユーザーアイデンティティ情報の取得方法と認可リクエストパラメーターの設定方法** -- OpenID Connect プロバイダーの場合：認可フロー開始時に `openid` と `profile` のスコープ (Scope) をリクエストする必要があります。これにより、認可 (Authorization) サーバーから返されるアクセス トークン (Access token) で [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) にアクセスできます。 +- OpenID Connect プロバイダーの場合：認可フロー開始時に少なくとも `openid` と `profile` スコープをリクエストする必要があります。これにより、認可 (Authorization) サーバーから返されるアクセス トークンに [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) へアクセスするための必要なスコープが含まれます。 - ※ 一部プロバイダーは userinfo エンドポイントをサポートしていない場合があります。 + ※一部プロバイダーは userinfo エンドポイントをサポートしていない場合があります。 -- OAuth 2.0 / OAuth 2.1 プロバイダーの場合：アクセス トークン (Access token) でユーザーのアイデンティティ情報を取得する方法や必要なパラメーターはプロバイダーのドキュメントを参照してください。 +- OAuth 2.0 / OAuth 2.1 プロバイダーの場合：アクセス トークンでユーザーアイデンティティ情報を取得する方法や、認可フローで必要なパラメーターについてはプロバイダーのドキュメントを参照してください。
@@ -327,41 +339,41 @@ npm run dev -[Logto](https://logto.io) との連携はシンプルです。OpenID Connect プロバイダーであり、標準の [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしています。 +[Logto](https://logto.io) は OpenID Connect プロバイダーであり、ユーザーアイデンティティ情報を取得するための標準 [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしているため、連携は簡単です。 -Logto は Dynamic Client Registration をまだサポートしていないため、MCP inspector を Logto テナントのクライアントとして手動登録する必要があります： +Logto は Dynamic Client Registration をまだサポートしていないため、MCP inspector を Logto テナントに手動でクライアント登録する必要があります： 1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)** の値（例：`http://localhost:6274/oauth/callback`）をコピー 2. [Logto Console](https://cloud.logto.io)（またはセルフホスト Logto Console）にサインイン -3. 「Applications」タブで「Create application」をクリック。ページ下部で「Create app without framework」をクリック +3. 「Applications」タブで「Create application」をクリックし、ページ下部の「Create app without framework」をクリック 4. アプリケーション詳細を入力し、「Create application」をクリック： - **Select an application type**：「Single-page application」を選択 - **Application name**：例「MCP Inspector」など任意の名前 5. 「Settings / Redirect URIs」セクションで、先ほどコピーした **Redirect URL (auto-populated)** を貼り付け、「Save changes」をクリック 6. 上部カードに「App ID」が表示されるのでコピー -7. MCP inspector に戻り、「OAuth Configuration」の「Client ID」欄に「App ID」を貼り付け -8. 「Auth Params」欄に `{"scope": "openid profile email"}` を入力。これで Logto から返されるアクセス トークン (Access token) に必要なスコープ (Scope) が含まれます。 +7. MCP inspector に戻り、「OAuth Configuration」セクションの「Client ID」欄に「App ID」を貼り付け +8. 「Auth Params」欄に `{"scope": "openid profile email"}` を入力。これで Logto から返されるアクセス トークンに必要なスコープが含まれます。 [Keycloak](https://www.keycloak.org) は OpenID Connect プロトコルをサポートするオープンソースのアイデンティティ・アクセス管理ソリューションです。 -Keycloak は Dynamic Client Registration をサポートしていますが、クライアント登録エンドポイントが CORS に対応していないため、ほとんどの MCP クライアントは直接登録できません。そのため、手動でクライアント登録が必要です。 +Keycloak は Dynamic Client Registration をサポートしていますが、クライアント登録エンドポイントが CORS に対応していないため、ほとんどの MCP クライアントは直接登録できません。したがって、手動でクライアント登録を行います。 :::note -Keycloak は [さまざまな方法](https://www.keycloak.org/guides#getting-started)（ベアメタル、kubernetes など）でインストールできますが、このチュートリアルでは Docker を使って簡単にセットアップします。 +Keycloak は [さまざまな方法](https://www.keycloak.org/guides#getting-started)（ベアメタル、Kubernetes など）でインストールできますが、このチュートリアルでは Docker を使った簡単なセットアップを紹介します。 ::: -Keycloak インスタンスをセットアップし、必要な設定を行います： +Keycloak インスタンスをセットアップし、必要な設定を行いましょう： -1. まず、[公式ドキュメント](https://www.keycloak.org/getting-started/getting-started-docker) に従い Docker で Keycloak を起動： +1. まず、[公式ドキュメント](https://www.keycloak.org/getting-started/getting-started-docker) に従い Docker で Keycloak インスタンスを起動： ```bash docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev ``` -2. Keycloak Admin Console（http://localhost:8080/admin）にアクセスし、以下でログイン： +2. Keycloak Admin Console（http://localhost:8080/admin）にアクセスし、以下の認証情報でログイン： - ユーザー名: `admin` - パスワード: `admin` @@ -376,9 +388,9 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM - 左メニューの「Users」をクリック - 「Create new user」をクリック - - ユーザー詳細を入力（ユーザー名: `testuser`、名・姓は任意） + - ユーザー名：`testuser`（他は任意） - 「Create」をクリック - - 「Credentials」タブでパスワードを設定し、「Temporary」をオフ + - 「Credentials」タブでパスワードを設定し「Temporary」をオフ 5. MCP Inspector をクライアントとして登録： @@ -386,31 +398,68 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM - Keycloak Admin Console で左メニューの「Clients」をクリック - 「Create client」をクリック - クライアント詳細を入力： - - Client type: 「OpenID Connect」を選択 - - Client ID: `mcp-inspector` を入力 + - Client type：「OpenID Connect」を選択 + - Client ID：`mcp-inspector` - 「Next」をクリック - - 「Capability config」ページで「Standard flow」が有効になっていることを確認し、「Next」 - - 「Login settings」ページで、先ほどコピーした MCP Inspector のコールバック URL を「Valid redirect URIs」に貼り付け - - 「Web origins」に `http://localhost:6274` を入力 - - 「Save」をクリック + - 「Capability config」ページ： + - 「Standard flow」が有効になっていることを確認 + - 「Next」をクリック + - 「Login settings」ページ： + - 「Valid redirect URIs」に MCP Inspector のコールバック URL を貼り付け + - 「Web origins」に `http://localhost:6274` を入力 + - 「Save」をクリック - 「Client ID」（`mcp-inspector`）をコピー -6. MCP Inspector に戻り： - - コピーした Client ID を「OAuth Configuration」の「Client ID」欄に貼り付け - - 「Auth Params」欄に以下を入力して必要なスコープ (Scope) をリクエスト： +6. MCP Inspector 側で： + - コピーした Client ID を「OAuth Configuration」セクションの「Client ID」欄に貼り付け + - 「Auth Params」欄に以下を入力し、必要なスコープをリクエスト： ```json { "scope": "openid profile email" } ``` - + + + +Asgardeo は標準 API による Dynamic Client Registration をサポートしていますが、エンドポイントは保護されており、必要な権限を持つアクセストークンが必要です。このチュートリアルでは Asgardeo Console から手動でクライアント登録を行います。 + +:::note +Asgardeo アカウントをお持ちでない場合は [無料登録](https://asgardeo.io) できます。 +::: + +以下の手順で Asgardeo を MCP Inspector 用に設定します： + +1. [Asgardeo Console](https://console.asgardeo.io) にログインし、組織を選択 + +2. 新しいアプリケーションを作成： + - **Applications** → **New Application** + - **Single-Page Application** を選択 + - アプリケーション名（例：`MCP Inspector`）を入力 + - **Authorized Redirect URLs** に MCP Inspector でコピーした **Redirect URL**（例：`http://localhost:6274/oauth/callback`）を貼り付け + - **Create** をクリック + +3. プロトコル設定： + - **Protocol** タブで + - 自動生成された **Client ID** をコピー + - **Access Token** セクションで `Token Type` を `JWT` に変更 + - **Update** をクリック + +4. MCP Inspector 側で： + - **OAuth Configuration** セクションを開く + - コピーした **Client ID** を貼り付け + - **Auth Params** 欄に以下を入力し、必要なスコープをリクエスト： + +```json +{ "scope": "openid profile email" } +``` + :::note これは汎用的な OpenID Connect プロバイダー連携ガイドです。詳細はプロバイダーのドキュメントを参照してください。 ::: -OpenID Connect プロバイダーが Dynamic Client Registration をサポートしていれば、下記 8 の設定に進んで MCP inspector を設定できます。サポートしていない場合は、手動で MCP inspector をクライアント登録する必要があります： +OpenID Connect プロバイダーが Dynamic Client Registration をサポートしていれば、下記手順 8 から MCP inspector の設定が可能です。サポートしていない場合は、手動で MCP inspector をクライアント登録してください： 1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)**（例：`http://localhost:6274/oauth/callback`）をコピー 2. OpenID Connect プロバイダーのコンソールにサインイン @@ -418,8 +467,8 @@ OpenID Connect プロバイダーが Dynamic Client Registration をサポート 4. クライアントタイプが必要な場合は「Single-page application」または「Public client」を選択 5. アプリケーション作成後、リダイレクト URI を設定。コピーした **Redirect URL (auto-populated)** を貼り付け 6. 新規アプリケーションの「Client ID」または「Application ID」をコピー -7. MCP inspector に戻り、「OAuth Configuration」の「Client ID」欄に貼り付け -8. 標準的な OpenID Connect プロバイダーの場合、userinfo エンドポイントにアクセスするために必要なスコープ (Scope) をリクエストするには「Auth Params」欄に以下を入力： +7. MCP inspector に戻り、「OAuth Configuration」セクションの「Client ID」欄に貼り付け +8. 標準的な OpenID Connect プロバイダーの場合、userinfo エンドポイントに必要なスコープをリクエストするため「Auth Params」欄に以下を入力： ```json { "scope": "openid profile email" } @@ -432,7 +481,7 @@ OpenID Connect プロバイダーが Dynamic Client Registration をサポート これは汎用的な OAuth 2.0 / OAuth 2.1 プロバイダー連携ガイドです。詳細はプロバイダーのドキュメントを参照してください。 ::: -OAuth 2.0 / OAuth 2.1 プロバイダーが Dynamic Client Registration をサポートしていれば、下記 8 の設定に進んで MCP inspector を設定できます。サポートしていない場合は、手動で MCP inspector をクライアント登録する必要があります： +OAuth 2.0 / OAuth 2.1 プロバイダーが Dynamic Client Registration をサポートしていれば、下記手順 8 から MCP inspector の設定が可能です。サポートしていない場合は、手動で MCP inspector をクライアント登録してください： 1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)**（例：`http://localhost:6274/oauth/callback`）をコピー 2. OAuth 2.0 / OAuth 2.1 プロバイダーのコンソールにサインイン @@ -440,8 +489,8 @@ OAuth 2.0 / OAuth 2.1 プロバイダーが Dynamic Client Registration をサ 4. クライアントタイプが必要な場合は「Single-page application」または「Public client」を選択 5. アプリケーション作成後、リダイレクト URI を設定。コピーした **Redirect URL (auto-populated)** を貼り付け 6. 新規アプリケーションの「Client ID」または「Application ID」をコピー -7. MCP inspector に戻り、「OAuth Configuration」の「Client ID」欄に貼り付け -8. アクセス トークン (Access token) でユーザーのアイデンティティ情報を取得する方法や必要なスコープ (Scope)・パラメーターはプロバイダーのドキュメントを参照してください。例えば、`profile` スコープ (Scope) が必要な場合は「Auth Params」欄に以下を入力： +7. MCP inspector に戻り、「OAuth Configuration」セクションの「Client ID」欄に貼り付け +8. プロバイダーのドキュメントを参照し、ユーザーアイデンティティ情報取得用のアクセス トークン取得方法を確認。必要なスコープやパラメーターを指定してください。例えば `profile` スコープが必要な場合、「Auth Params」欄に以下を入力： ```json { "scope": "profile" } @@ -452,7 +501,7 @@ OAuth 2.0 / OAuth 2.1 プロバイダーが Dynamic Client Registration をサ ### MCP auth のセットアップ \{#set-up-mcp-auth} -MCP サーバープロジェクトで MCP Auth SDK をインストールし、認可 (Authorization) サーバーのメタデータを使うように設定します。 +MCP サーバープロジェクトで MCP Auth SDK をインストールし、認可 (Authorization) サーバーメタデータを使うように設定します。 @@ -463,7 +512,7 @@ MCP サーバープロジェクトで MCP Auth SDK をインストールし、 pip install mcpauth ``` -または `uv` や `poetry` など、お好みのパッケージマネージャーを使用してください。 +または `uv` や `poetry` など、お好みのパッケージマネージャーを利用できます。 @@ -477,13 +526,13 @@ npm install mcp-auth -MCP Auth は初期化のために認可 (Authorization) サーバーのメタデータが必要です。プロバイダーごとに設定方法が異なります： +MCP Auth は初期化のために認可 (Authorization) サーバーメタデータが必要です。プロバイダーごとに次のように設定します： -発行者 (Issuer) URL は Logto Console のアプリケーション詳細ページ「Endpoints & Credentials / Issuer endpoint」セクションで確認できます。例：`https://my-project.logto.app/oidc` +発行者 (Issuer) URL は Logto Console のアプリケーション詳細ページ「Endpoints & Credentials / Issuer endpoint」セクションで確認できます（例：`https://my-project.logto.app/oidc`）。 @@ -491,22 +540,30 @@ MCP Auth は初期化のために認可 (Authorization) サーバーのメタデ -発行者 (Issuer) URL は Keycloak Admin Console の「mcp-realm」内、「Realm settings / Endpoints」セクションの「OpenID Endpoint Configuration」リンクで確認できます。JSON ドキュメントの `issuer` フィールドが発行者 (Issuer) URL です（例：`http://localhost:8080/realms/mcp-realm`）。 +発行者 (Issuer) URL は Keycloak Admin Console の「mcp-realm」内「Realm settings / Endpoints」セクションの「OpenID Endpoint Configuration」リンクで確認できます。JSON ドキュメントの `issuer` フィールド（例：`http://localhost:8080/realms/mcp-realm`）。 + + + Asgardeo Console で発行者 (Issuer) URL を確認できます。作成したアプリケーションの **Info** タブを開くと **Issuer** フィールドが表示されます（例：`https://api.asgardeo.io/t//oauth2/token`）。 + + + + + -以下のコードは、認可 (Authorization) サーバーが [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしていることを前提としています。サポートしていない場合は、プロバイダーのドキュメントで該当エンドポイントを確認し、userinfo エンドポイント変数を正しい URL に置き換えてください。 +以下のコードは、認可 (Authorization) サーバーがユーザーアイデンティティ情報を取得するための [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしていることを前提としています。サポートしていない場合は、プロバイダーのドキュメントで該当エンドポイントを確認し、userinfo エンドポイント変数を正しい URL に置き換えてください。 -前述の通り、OAuth 2.0 ではユーザーのアイデンティティ情報を取得する標準的な方法は定義されていません。以下のコードは、プロバイダーがアクセス トークン (Access token) でユーザーのアイデンティティ情報を取得できる独自エンドポイントを持っていることを前提としています。プロバイダーのドキュメントで該当エンドポイントを確認し、userinfo エンドポイント変数を正しい URL に置き換えてください。 +前述の通り、OAuth 2.0 にはユーザーアイデンティティ情報取得の標準的な方法はありません。以下のコードは、プロバイダーがアクセス トークンでユーザーアイデンティティ情報を取得するための独自エンドポイントを持っていることを前提としています。プロバイダーのドキュメントで該当エンドポイントを確認し、userinfo エンドポイント変数を正しい URL に置き換えてください。 @@ -515,7 +572,7 @@ MCP Auth は初期化のために認可 (Authorization) サーバーのメタデ ### MCP サーバーの更新 \{#update-mcp-server} -あと少しです！MCP Auth のルートとミドルウェア関数を適用し、`whoami` ツールが実際のユーザーアイデンティティ情報を返すよう MCP サーバーを更新します。 +あと少しです！MCP Auth のルートとミドルウェア関数を適用し、`whoami` ツールが実際のユーザーアイデンティティ情報を返すよう MCP サーバーを更新しましょう。 @@ -523,10 +580,10 @@ MCP Auth は初期化のために認可 (Authorization) サーバーのメタデ ```python @mcp.tool() def whoami() -> dict[str, Any]: - """現在のユーザー情報を返すツール""" + """現在のユーザー情報を返すツール。""" return ( mcp_auth.auth_info.claims - if mcp_auth.auth_info # Bearer auth ミドルウェアでセットされます + if mcp_auth.auth_info # Bearer 認証 (Authentication) ミドルウェアでセットされます else {"error": "Not authenticated"} ) @@ -537,7 +594,7 @@ app = Starlette( routes=[ # メタデータルート（`/.well-known/oauth-authorization-server`）を追加 mcp_auth.metadata_route(), - # Bearer auth ミドルウェアで MCP サーバーを保護 + # Bearer 認証 (Authentication) ミドルウェアで MCP サーバーを保護 Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), ], ) @@ -568,9 +625,9 @@ app.use(mcpAuth.bearerAuth(verifyToken)); MCP サーバーを再起動し、ブラウザで MCP inspector を開きます。「Connect」ボタンをクリックすると、認可 (Authorization) サーバーのサインインページにリダイレクトされます。 -サインイン後 MCP inspector に戻り、前回と同じ手順で `whoami` ツールを実行してください。今回は認可 (Authorization) サーバーから返されたユーザーのアイデンティティ情報が表示されるはずです。 +サインイン後 MCP inspector に戻り、前回のチェックポイントと同じ手順で `whoami` ツールを実行してください。今回は認可 (Authorization) サーバーから返されたユーザーアイデンティティ情報が表示されるはずです。 -![MCP inspector whoami tool result](/docs-assets/images/tutorials/whoami/result.png) +![MCP inspector whoami ツール結果](/docs-assets/images/tutorials/whoami/result.png) @@ -583,7 +640,7 @@ MCP サーバーを再起動し、ブラウザで MCP inspector を開きます :::info -[MCP Auth Node.js SDK リポジトリ](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) で MCP サーバー（OIDC 版）の完全なコードを確認できます。このディレクトリには TypeScript 版と JavaScript 版の両方が含まれています。 +[MCP Auth Node.js SDK リポジトリ](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) で MCP サーバー（OIDC 版）の完全なコードを確認できます。TypeScript 版と JavaScript 版の両方が含まれています。 ::: @@ -594,13 +651,13 @@ MCP サーバーを再起動し、ブラウザで MCP inspector を開きます 🎊 おめでとうございます！チュートリアルを無事完了しました。ここまでの内容を振り返りましょう： - `whoami` ツール付きの基本的な MCP サーバーのセットアップ -- MCP Auth を使った MCP サーバーと認可 (Authorization) サーバーの連携 -- MCP Inspector でユーザー認証 (Authentication) とアイデンティティ情報の取得 +- MCP Auth を使った認可 (Authorization) サーバーとの連携 +- MCP Inspector の設定によるユーザー認証 (Authentication) とアイデンティティ情報の取得 -さらに発展的なトピックとして、以下もぜひご検討ください： +さらに以下の発展的なトピックもぜひご検討ください： - [JWT (JSON Web Token)](https://auth.wiki/jwt) を使った認証 (Authentication)・認可 (Authorization) - [リソースインジケーター (RFC 8707)](https://auth-wiki.logto.io/resource-indicator) を活用したアクセスリソースの指定 -- [ロールベースのアクセス制御 (RBAC)](https://auth.wiki/rbac) や [属性ベースのアクセス制御 (ABAC)](https://auth.wiki/abac) などのカスタムアクセス制御の実装 +- [ロールベースのアクセス制御 (RBAC)](https://auth.wiki/rbac) や [属性ベースのアクセス制御 (ABAC)](https://auth.wiki/abac) などカスタムアクセス制御の実装 他のチュートリアルやドキュメントもぜひご覧いただき、MCP Auth を最大限に活用してください。 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index a0e9d21..f0d6d4a 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -11,7 +11,7 @@ import SetupOidc from './_setup-oidc.mdx'; # 튜토리얼: 할 일 관리 앱 만들기 (Tutorial: Build a todo manager) -이 튜토리얼에서는 사용자 인증 (Authentication) 및 인가 (Authorization)가 적용된 todo manager MCP 서버를 만들어봅니다. +이 튜토리얼에서는 사용자 인증 (Authentication) 및 인가 (Authorization)가 적용된 todo manager MCP 서버를 구축합니다. 이 튜토리얼을 완료하면 다음을 얻게 됩니다: @@ -19,27 +19,27 @@ import SetupOidc from './_setup-oidc.mdx'; - ✅ 개인 할 일 목록을 관리할 수 있는 MCP 서버 :::note -시작하기 전에, MCP 서버와 OAuth 2에 익숙하지 않다면 [Who am I 튜토리얼](./whoami)을 먼저 진행하는 것을 강력히 권장합니다. +시작하기 전에 MCP 서버와 OAuth 2에 익숙하지 않다면 [Who am I 튜토리얼](./whoami)을 먼저 진행하는 것을 강력히 권장합니다. ::: ## 개요 (Overview) \{#overview} 이 튜토리얼에는 다음과 같은 구성 요소가 포함됩니다: -- **MCP 서버**: MCP 공식 SDK를 사용하여 요청을 처리하고, 사용자의 할 일 항목을 관리하는 Todo 서비스를 통합한 간단한 MCP 서버 -- **MCP inspector**: MCP 서버를 시각적으로 테스트할 수 있는 도구. OAuth / OIDC 클라이언트 역할도 하여 인가 플로우를 시작하고 액세스 토큰을 가져옵니다. +- **MCP 서버**: MCP 공식 SDK를 사용하여 요청을 처리하고, 사용자의 할 일 항목을 관리하는 Todo 서비스가 통합된 간단한 MCP 서버 +- **MCP 인스펙터**: MCP 서버를 시각적으로 테스트할 수 있는 도구. OAuth / OIDC 클라이언트 역할도 하여 인가 (Authorization) 플로우를 시작하고 액세스 토큰을 가져옵니다. - **인가 서버 (Authorization server)**: 사용자 아이덴티티를 관리하고 액세스 토큰을 발급하는 OAuth 2.1 또는 OpenID Connect 제공자 아래는 이 구성 요소들 간의 상호작용을 나타낸 고수준 다이어그램입니다: ```mermaid sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as 인가 서버 (Authorization Server) + participant Client as MCP 인스펙터 + participant Server as MCP 서버 + participant Auth as 인가 서버 Client->>Server: 할 일 작업 요청 - Server->>Client: 401 인가되지 않음 반환 + Server->>Client: 401 Unauthorized 반환 Client->>Auth: 인가 플로우 시작 Auth->>Auth: 인가 플로우 완료 Auth->>Client: 인가 코드와 함께 리디렉션 @@ -55,25 +55,25 @@ sequenceDiagram ### 스코프가 포함된 액세스 토큰 (Access tokens with scopes) \{#access-tokens-with-scopes} -[MCP 서버에서 역할 기반 접근 제어 (RBAC)](https://auth.wiki/rbac)를 구현하려면, 인가 서버가 스코프가 포함된 액세스 토큰 발급을 지원해야 합니다. 스코프는 사용자가 부여받은 권한을 나타냅니다. +MCP 서버에서 [역할 기반 접근 제어 (RBAC)](https://auth.wiki/rbac)를 구현하려면, 인가 서버가 스코프가 포함된 액세스 토큰을 발급할 수 있어야 합니다. 스코프는 사용자가 부여받은 권한 (Permissions)을 나타냅니다. -[Logto](https://logto.io)는 API 리소스([RFC 8707: OAuth 2.0을 위한 리소스 지표](https://datatracker.ietf.org/doc/html/rfc8707)) 및 역할 기능을 통해 RBAC를 지원합니다. 설정 방법은 다음과 같습니다: +[Logto](https://logto.io)는 API 리소스 ([RFC 8707: OAuth 2.0을 위한 리소스 지표](https://datatracker.ietf.org/doc/html/rfc8707) 준수)와 역할 (Roles) 기능을 통해 RBAC를 지원합니다. 설정 방법은 다음과 같습니다: 1. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인하세요. 2. API 리소스 및 스코프 생성: - "API Resources"로 이동 - - "Todo Manager"라는 새 API 리소스 생성 + - "Todo Manager"라는 이름의 새 API 리소스 생성 - 다음 스코프 추가: - `create:todos`: "새 할 일 항목 생성" - `read:todos`: "모든 할 일 항목 읽기" - `delete:todos`: "모든 할 일 항목 삭제" -3. 역할 생성(관리를 쉽게 하기 위해 권장): +3. 역할 생성 (관리가 쉬워지므로 권장): - "Roles"로 이동 - "Admin" 역할을 생성하고 모든 스코프(`create:todos`, `read:todos`, `delete:todos`) 할당 @@ -82,72 +82,114 @@ sequenceDiagram 4. 권한 할당: - "Users"로 이동 - 사용자를 선택 - - "Roles" 탭에서 역할을 할당(권장) - - 또는 "Permissions" 탭에서 직접 스코프 할당 + - "Roles" 탭에서 역할을 할당하거나, "Permissions" 탭에서 직접 스코프를 할당할 수 있습니다 (역할 할당 권장) 스코프는 JWT 액세스 토큰의 `scope` 클레임에 공백으로 구분된 문자열로 포함됩니다. + + + [Asgardeo](https://wso2.com/asgardeo)는 API 리소스와 스코프를 사용한 역할 기반 접근 제어 (RBAC) 및 세밀한 인가를 지원합니다. 설정 방법은 다음과 같습니다: + + 1. [Asgardeo Console](https://console.asgardeo.io)에 로그인하세요. + + 2. API 리소스 및 스코프 정의: + - **API Resources**로 이동 + - **"New API Resource"** 클릭 + - **Identifier**를 `https://todo.mcp-server.app` (또는 원하는 URL)로 설정 + - **Display Name**을 `Todo Manager`로 설정 + - 다음 스코프 추가: + - `create:todos` : "새 할 일 항목 생성" + - `read:todos` : "모든 할 일 항목 읽기" + - `delete:todos` : "모든 할 일 항목 삭제" + - 리소스 생성 + + 3. 역할 생성: + - **User Management > Roles**에서 역할을 생성하고 스코프를 직접 할당 + - **New Role** 클릭 + - **Basic Details**에서 역할 이름 입력 (예: `Admin` 또는 `User`) + - 역할 audience를 `Application`으로 설정하고 **Assigned Application**에서 `MCP Inspector Application` 선택 + - **Permission Selection**에서 앞서 만든 API 리소스(`Todo Manager`) 선택 + - 역할에 할당할 스코프 선택 (예: `create:todos`, `read:todos`, `delete:todos`) + - **Finish** 클릭하여 역할 생성 + + 이미 애플리케이션을 생성했다면 + - **Application > MCP Inspector Application > Roles 탭**으로 이동 + - audience type을 **Application Role**로 선택 후 **New Role** 클릭 + - `Admin` 역할을 생성하고 세 가지 스코프 모두 연결 + - `User` 역할을 생성하고 `create:todos` 스코프만 연결 + + 4. 사용자에게 역할 할당: + - **User Management > Roles**로 이동 + - 생성한 역할 선택 후 **Users** 탭으로 이동 + - **Assign User** 선택 후 역할을 할당할 사용자 선택 및 저장 + + 스코프는 JWT 액세스 토큰의 `scope` 클레임에 공백으로 구분된 문자열로 포함됩니다. + -OAuth 2.0 / OIDC 제공자는 일반적으로 스코프 기반 접근 제어를 지원합니다. RBAC를 구현할 때: +OAuth 2.0 / OIDC 제공자는 일반적으로 스코프 기반 접근 제어를 지원합니다. RBAC 구현 시: -1. 인가 서버에서 필요한 스코프 정의 -2. 클라이언트가 인가 플로우 중에 이 스코프를 요청하도록 구성 +1. 인가 서버에 필요한 스코프 정의 +2. 클라이언트가 인가 플로우 중에 이 스코프를 요청하도록 설정 3. 인가 서버가 부여된 스코프를 액세스 토큰에 포함하는지 확인 4. 스코프는 보통 JWT 액세스 토큰의 `scope` 클레임에 포함됨 -스코프 정의 및 관리 방법, 액세스 토큰에 스코프가 포함되는 방식, 역할 관리 등 추가 RBAC 기능은 제공자 문서를 참고하세요. +자세한 내용은 제공자 문서를 참고하세요: + +- 스코프 정의 및 관리 방법 +- 액세스 토큰에 스코프가 어떻게 포함되는지 +- 역할 관리 등 추가 RBAC 기능 ### 토큰 검증 및 권한 확인 (Validating tokens and checking permissions) \{#validating-tokens-and-checking-permissions} -MCP 서버가 요청을 받으면 다음을 수행해야 합니다: +MCP 서버가 요청을 받을 때 다음을 수행해야 합니다: 1. 액세스 토큰의 서명 및 만료 검증 2. 검증된 토큰에서 스코프 추출 3. 요청된 작업에 필요한 스코프가 토큰에 포함되어 있는지 확인 -예를 들어, 사용자가 새 할 일 항목을 생성하려면 액세스 토큰에 `create:todos` 스코프가 포함되어 있어야 합니다. 플로우는 다음과 같습니다: +예를 들어, 사용자가 새 할 일 항목을 생성하려면 액세스 토큰에 `create:todos` 스코프가 포함되어야 합니다. 플로우는 다음과 같습니다: ```mermaid sequenceDiagram participant Client - participant MCP Server - participant Auth Server + participant MCP 서버 + participant 인가 서버 - Client->>MCP Server: 액세스 토큰과 함께 요청 + Client->>MCP 서버: 액세스 토큰과 함께 요청 alt JWT 검증 - MCP Server->>Auth Server: JWKS 가져오기 - Auth Server-->>MCP Server: JWKS 반환 - MCP Server->>MCP Server: JWT 로컬 검증 + MCP 서버->>인가 서버: JWKS 가져오기 + 인가 서버-->>MCP 서버: JWKS 반환 + MCP 서버->>MCP 서버: JWT 로컬 검증 else 토큰 인트로스펙션 - MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: 토큰 정보 반환
(active, scope 등) + MCP 서버->>인가 서버: POST /introspect
(token=access_token) + 인가 서버-->>MCP 서버: 토큰 정보 반환
(active, scope 등) end - MCP Server->>MCP Server: 스코프 추출 및 확인 + MCP 서버->>MCP 서버: 스코프 추출 및 확인 - alt 필요한 스코프 있음 - MCP Server->>Client: 작업 허용 + alt 필요한 스코프 보유 + MCP 서버->>Client: 작업 허용 else 스코프 부족 - MCP Server->>Client: 403 금지 반환 + MCP 서버->>Client: 403 Forbidden 반환 end ``` ### 동적 클라이언트 등록 (Dynamic Client Registration) \{#dynamic-client-registration} -이 튜토리얼에서는 동적 클라이언트 등록이 필수는 아니지만, 인가 서버에 MCP 클라이언트 등록을 자동화하고 싶다면 유용할 수 있습니다. 자세한 내용은 [동적 클라이언트 등록이 필요한가요?](../../provider-list.mdx#is-dcr-required)를 참고하세요. +이 튜토리얼에서는 필수는 아니지만, 인가 서버에 MCP 클라이언트 등록을 자동화하고 싶다면 유용할 수 있습니다. 자세한 내용은 [Is Dynamic Client Registration required?](../../provider-list.mdx#is-dcr-required)를 참고하세요. ## 할 일 관리 앱에서 RBAC 이해하기 (Understand RBAC in todo manager) \{#understand-rbac-in-todo-manager} -데모 목적상, todo manager MCP 서버에 간단한 역할 기반 접근 제어 (RBAC) 시스템을 구현합니다. 이를 통해 RBAC의 기본 원리를 쉽게 이해할 수 있습니다. +데모 목적을 위해, todo manager MCP 서버에 간단한 역할 기반 접근 제어 (RBAC) 시스템을 구현합니다. 이를 통해 RBAC의 기본 원리를 쉽게 이해할 수 있습니다. :::note -이 튜토리얼은 RBAC 기반 스코프 관리를 시연하지만, 모든 인증 (Authentication) 제공자가 역할을 통한 스코프 관리를 구현하는 것은 아닙니다. 일부 제공자는 자체적인 접근 제어 및 권한 관리 방식을 가질 수 있습니다. +이 튜토리얼은 RBAC 기반 스코프 관리를 시연하지만, 모든 인증 (Authentication) 제공자가 역할을 통한 스코프 관리를 구현하는 것은 아닙니다. 일부 제공자는 고유한 접근 제어 및 권한 (Permissions) 관리 방식을 가질 수 있습니다. ::: ### 도구와 스코프 (Tools and scopes) \{#tools-and-scopes} @@ -162,11 +204,11 @@ todo manager MCP 서버는 세 가지 주요 도구를 제공합니다: - `create:todos`: 새 할 일 항목 생성 허용 - `delete:todos`: 기존 할 일 항목 삭제 허용 -- `read:todos`: 모든 할 일 목록 조회 및 검색 허용 +- `read:todos`: 모든 할 일 항목 목록 조회 및 검색 허용 ### 역할과 권한 (Roles and permissions) \{#roles-and-permissions} -접근 수준이 다른 두 가지 역할을 정의합니다: +다음과 같이 서로 다른 접근 수준을 가진 두 가지 역할을 정의합니다: | 역할 (Role) | create:todos | read:todos | delete:todos | | ----------- | ------------ | ---------- | ------------ | @@ -174,18 +216,18 @@ todo manager MCP 서버는 세 가지 주요 도구를 제공합니다: | User | ✅ | | | - **User**: 자신의 할 일만 생성, 조회, 삭제할 수 있는 일반 사용자 -- **Admin**: 모든 할 일을 생성, 조회, 삭제할 수 있는 관리자 +- **Admin**: 소유자와 상관없이 모든 할 일을 생성, 조회, 삭제할 수 있는 관리자 ### 리소스 소유권 (Resource ownership) \{#resource-ownership} -위의 권한 테이블은 각 역할에 명시적으로 할당된 스코프를 보여주지만, 리소스 소유권이라는 중요한 원칙이 있습니다: +위 권한 표는 각 역할에 명시적으로 할당된 스코프를 보여주지만, 리소스 소유권이라는 중요한 원칙이 있습니다: - **User**는 `read:todos` 또는 `delete:todos` 스코프가 없지만, - 자신의 할 일 항목은 읽을 수 있고 - - 자신의 할 일 항목은 삭제할 수 있습니다. -- **Admin**은 전체 권한(`read:todos`, `delete:todos`)을 가지므로, + - 자신의 할 일 항목은 삭제할 수 있습니다 +- **Admin**은 전체 권한 (`read:todos`, `delete:todos`)을 가지므로, - 시스템의 모든 할 일 항목을 볼 수 있고 - - 소유자와 관계없이 모든 할 일 항목을 삭제할 수 있습니다. + - 소유자와 상관없이 모든 할 일을 삭제할 수 있습니다 이는 RBAC 시스템에서 리소스 소유권이 사용자의 자신의 리소스에 대한 암묵적 권한을 부여하고, 관리자는 모든 리소스에 대한 명시적 권한을 받는 일반적인 패턴을 보여줍니다. @@ -207,13 +249,13 @@ RBAC 개념과 모범 사례를 더 깊이 이해하려면 [Mastering RBAC: A Co 2. API 리소스 및 스코프 생성: - "API Resources"로 이동 - - "Todo Manager"라는 새 API 리소스를 생성하고, 인디케이터로 `https://todo.mcp-server.app`(데모 목적)를 사용하세요. + - "Todo Manager"라는 이름의 새 API 리소스를 생성하고, indicator로 `https://todo.mcp-server.app` (데모 목적) 사용 - 다음 스코프 생성: - `create:todos`: "새 할 일 항목 생성" - `read:todos`: "모든 할 일 항목 읽기" - `delete:todos`: "모든 할 일 항목 삭제" -3. 역할 생성(관리를 쉽게 하기 위해 권장): +3. 역할 생성 (관리가 쉬워지므로 권장): - "Roles"로 이동 - "Admin" 역할을 생성하고 모든 스코프(`create:todos`, `read:todos`, `delete:todos`) 할당 @@ -222,13 +264,13 @@ RBAC 개념과 모범 사례를 더 깊이 이해하려면 [Mastering RBAC: A Co 4. 사용자 역할 및 권한 관리: - 신규 사용자: - - "User" 역할이 기본 역할로 자동 할당됨 + - "User" 역할이 기본값이므로 자동으로 할당됨 - 기존 사용자: - "User management"로 이동 - 사용자를 선택 - "Roles" 탭에서 역할 할당 -:::tip 프로그래밍 방식의 역할 관리 +:::tip 프로그래밍 방식 역할 관리 Logto의 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api)를 사용하여 프로그래밍 방식으로 사용자 역할을 관리할 수 있습니다. 자동화된 사용자 관리나 관리자 패널 구축 시 유용합니다. ::: @@ -247,42 +289,90 @@ Logto의 [Management API](https://docs.logto.io/integrate-logto/interact-with-ma - `read:todos` - `delete:todos` -2. 클라이언트 구성: +2. 클라이언트 설정: - 클라이언트 설정으로 이동 - "Client scopes" 탭에서 생성한 모든 스코프 추가 - 토큰 매퍼가 스코프를 포함하도록 설정 -3. 선택 사항: 역할을 통한 관리 - - 역할 기반 관리가 필요하다면: - - 접근 수준별로 Realm 역할 생성 +3. 선택 사항: 역할 기반 관리 사용 + - 역할 기반 관리가 더 편리하다면: + - 다양한 접근 수준의 realm 역할 생성 - 스코프를 역할에 매핑 - - 역할을 사용자에게 할당 - - 그렇지 않으면, 스코프를 사용자에게 직접 할당하거나 클라이언트 수준 권한을 통해 할당 + - 사용자를 역할에 할당 + - 아니면, 사용자 또는 클라이언트 수준 권한을 통해 직접 스코프 할당 가능 Keycloak은 부여된 스코프를 액세스 토큰의 `scope` 클레임에 포함합니다. + + + +[Asgardeo](https://wso2.com/asgardeo)는 API 리소스와 스코프를 사용한 역할 기반 접근 제어 (RBAC) 및 세밀한 인가를 지원합니다. 설정 방법은 다음과 같습니다: + +1. [Asgardeo Console](https://console.asgardeo.io)에 로그인하세요. + +2. API 리소스 및 스코프 정의: + - **API Resources**로 이동 + - **"New API Resource"** 클릭 + - **Identifier**를 `https://todo.mcp-server.app` (또는 원하는 URL)로 설정 + - **Display Name**을 `Todo Manager`로 설정 + - 다음 스코프 추가: + - `create:todos` : "새 할 일 항목 생성" + - `read:todos` : "모든 할 일 항목 읽기" + - `delete:todos` : "모든 할 일 항목 삭제" + - 리소스 생성 + +3. 역할 생성: + - **User Management > Roles**에서 역할을 생성하고 스코프를 직접 할당 + - **New Role** 클릭 + - **Basic Details**에서 역할 이름 입력 (예: `Admin` 또는 `User`) + - 역할 audience를 `Application`으로 설정하고 **Assigned Application**에서 `MCP Inspector Application` 선택 + - **Permission Selection**에서 앞서 만든 API 리소스(`Todo Manager`) 선택 + - 역할에 할당할 스코프 선택 (예: `create:todos`, `read:todos`, `delete:todos`) + - **Finish** 클릭하여 역할 생성 + + 이미 애플리케이션을 생성했다면 + - **Application > MCP Inspector Application > Roles 탭**으로 이동 + - audience type을 **Application Role**로 선택 후 **New Role** 클릭 + - `Admin` 역할을 생성하고 세 가지 스코프 모두 연결 + - `User` 역할을 생성하고 `create:todos` 스코프만 연결 + +4. 사용자에게 역할 할당: + - **User Management > Roles**로 이동 + - 생성한 역할 선택 후 **Users** 탭으로 이동 + - **Assign User** 선택 후 역할을 할당할 사용자 선택 및 저장 + +스코프는 JWT 액세스 토큰의 `scope` 클레임에 공백으로 구분된 문자열로 포함됩니다. +인가 서버를 설정한 후, 사용자는 부여받은 스코프가 포함된 액세스 토큰을 받게 됩니다. MCP 서버는 이 스코프를 사용하여 다음을 판단합니다: + +사용자가 새 할 일을 생성할 수 있는지 (`create:todos`) +사용자가 모든 할 일을 볼 수 있는지 (`read:todos`) 또는 자신의 것만 볼 수 있는지 +사용자가 모든 할 일을 삭제할 수 있는지 (`delete:todos`) 또는 자신의 것만 삭제할 수 있는지 + +Asgardeo 설정에 대한 자세한 내용은 다음 리소스를 참고하세요: +- [API Resources Guide](https://wso2.com/asgardeo/docs/guides/authorization/api-authorization) +- [Role Management](https://wso2.com/asgardeo/docs/guides/users/manage-roles) -OAuth 2.0 또는 OpenID Connect 제공자의 경우, 다양한 권한을 나타내는 스코프를 구성해야 합니다. 구체적인 단계는 제공자마다 다르지만, 일반적으로: +OAuth 2.0 또는 OpenID Connect 제공자의 경우, 다양한 권한을 나타내는 스코프를 설정해야 합니다. 구체적인 단계는 제공자마다 다르지만, 일반적으로: 1. 스코프 정의: - - 인가 서버에서 다음을 지원하도록 구성: + - 인가 서버에서 다음 스코프 지원 설정: - `create:todos` - `read:todos` - `delete:todos` -2. 클라이언트 구성: +2. 클라이언트 설정: - - 클라이언트를 등록하거나 업데이트하여 이 스코프를 요청하도록 설정 - - 스코프가 액세스 토큰에 포함되는지 확인 + - 클라이언트가 이 스코프를 요청하도록 등록 또는 업데이트 + - 액세스 토큰에 스코프가 포함되는지 확인 3. 권한 할당: - - 제공자 인터페이스를 사용하여 사용자에게 적절한 스코프 부여 - - 일부 제공자는 역할 기반 관리, 일부는 직접 스코프 할당을 지원 - - 권장 접근 방식은 제공자 문서를 참고 + - 제공자 인터페이스를 통해 사용자에게 적절한 스코프 부여 + - 일부 제공자는 역할 기반 관리, 일부는 직접 스코프 할당 지원 + - 권장 접근 방식은 제공자 문서 참고 :::tip 대부분의 제공자는 부여된 스코프를 액세스 토큰의 `scope` 클레임에 포함합니다. 형식은 일반적으로 공백으로 구분된 스코프 값 문자열입니다. @@ -291,11 +381,11 @@ OAuth 2.0 또는 OpenID Connect 제공자의 경우, 다양한 권한을 나타 -인가 서버를 설정한 후, 사용자는 부여된 스코프가 포함된 액세스 토큰을 받게 됩니다. MCP 서버는 이 스코프를 사용하여 다음을 판단합니다: +인가 서버를 설정한 후, 사용자는 부여받은 스코프가 포함된 액세스 토큰을 받게 됩니다. MCP 서버는 이 스코프를 사용하여 다음을 판단합니다: - 사용자가 새 할 일을 생성할 수 있는지 (`create:todos`) -- 사용자가 모든 할 일을 볼 수 있는지 (`read:todos`) 또는 자신의 할 일만 볼 수 있는지 -- 사용자가 모든 할 일을 삭제할 수 있는지 (`delete:todos`) 또는 자신의 할 일만 삭제할 수 있는지 +- 사용자가 모든 할 일을 볼 수 있는지 (`read:todos`) 또는 자신의 것만 볼 수 있는지 +- 사용자가 모든 할 일을 삭제할 수 있는지 (`delete:todos`) 또는 자신의 것만 삭제할 수 있는지 ## MCP 서버 설정하기 (Set up the MCP server) \{#set-up-the-mcp-server} @@ -320,7 +410,7 @@ uv init # 또는 `pipenv` 또는 `poetry`로 새 가상환경 생성 ```bash mkdir mcp-server cd mcp-server -npm init -y # 또는 `pnpm init` +npm init -y # 또는 `pnpm init` 사용 npm pkg set type="module" npm pkg set main="todo-manager.ts" npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" @@ -342,7 +432,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" pip install "mcp[cli]" starlette uvicorn ``` -또는 `uv`, `poetry` 등 원하는 패키지 매니저를 사용할 수 있습니다. +또는 `uv`, `poetry` 등 원하는 패키지 매니저 사용 @@ -351,12 +441,12 @@ pip install "mcp[cli]" starlette uvicorn npm install @modelcontextprotocol/sdk express zod ``` -또는 `pnpm`, `yarn` 등 원하는 패키지 매니저를 사용할 수 있습니다. +또는 `pnpm`, `yarn` 등 원하는 패키지 매니저 사용 -### MCP 서버 만들기 (Create the MCP server) \{#create-the-mcp-server} +### MCP 서버 생성 (Create the MCP server) \{#create-the-mcp-server} 먼저, 도구 정의가 포함된 기본 MCP 서버를 만듭니다: @@ -380,7 +470,7 @@ def create_todo(content: str) -> dict[str, Any]: @mcp.tool() def get_todos() -> dict[str, Any]: - """모든 할 일 목록 조회.""" + """모든 할 일 목록.""" return {"error": "Not implemented"} @mcp.tool() @@ -403,7 +493,7 @@ uvicorn todo_manager:app --host 0.0.0.0 --port 3001 :::note -현재 MCP inspector 구현은 인가 플로우를 처리하지 않으므로, SSE 방식을 사용하여 MCP 서버를 설정합니다. MCP inspector가 인가 플로우를 지원하면 코드를 업데이트할 예정입니다. +현재 MCP 인스펙터 구현이 인가 (Authorization) 플로우를 처리하지 않으므로, SSE 방식을 사용하여 MCP 서버를 설정합니다. MCP 인스펙터가 인가 플로우를 지원하면 코드를 업데이트할 예정입니다. ::: `pnpm` 또는 `yarn`도 사용할 수 있습니다. @@ -430,7 +520,7 @@ server.tool('create-todo', '새 할 일 생성', { content: z.string() }, async }; }); -server.tool('get-todos', '모든 할 일 목록 조회', async () => { +server.tool('get-todos', '모든 할 일 목록', async () => { return { content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], }; @@ -481,15 +571,15 @@ npm start -## MCP 서버 검사하기 (Inspect the MCP server) \{#inspect-the-mcp-server} +## MCP 서버 인스펙트 (Inspect the MCP server) \{#inspect-the-mcp-server} -### MCP inspector 클론 및 실행 (Clone and run MCP inspector) \{#clone-and-run-mcp-inspector} +### MCP 인스펙터 클론 및 실행 (Clone and run MCP inspector) \{#clone-and-run-mcp-inspector} -이제 MCP 서버가 실행 중이므로, MCP inspector를 사용하여 `whoami` 도구가 사용 가능한지 확인할 수 있습니다. +MCP 서버가 실행 중이므로, MCP 인스펙터를 사용해 `whoami` 도구가 사용 가능한지 확인할 수 있습니다. -현재 구현의 한계로 인해, [MCP inspector](https://github.com/mcp-auth/inspector)를 포크하여 인증 (Authentication) 및 인가 (Authorization)에 더 유연하고 확장 가능하도록 개선했습니다. 변경 사항을 원본 저장소에 PR로 제출했습니다. +현재 구현의 한계로, [MCP inspector](https://github.com/mcp-auth/inspector)를 포크하여 인증 (Authentication) 및 인가 (Authorization)에 더 유연하고 확장 가능하게 만들었습니다. 변경 사항을 원본 저장소에 PR로 제출했습니다. -MCP inspector를 실행하려면 다음 명령어를 사용하세요(Node.js 필요): +MCP 인스펙터 실행 방법 (Node.js 필요): ```bash git clone https://github.com/mcp-auth/inspector.git @@ -498,51 +588,51 @@ npm install npm run dev ``` -그런 다음 브라우저에서 `http://localhost:6274/` (또는 터미널에 표시된 URL)로 접속하여 MCP inspector에 접근하세요. +브라우저에서 `http://localhost:6274/` (또는 터미널에 표시된 URL)로 접속하여 MCP 인스펙터에 접근하세요. -### MCP inspector를 MCP 서버에 연결 (Connect MCP inspector to the MCP server) \{#connect-mcp-inspector-to-the-mcp-server} +### MCP 인스펙터를 MCP 서버에 연결 (Connect MCP inspector to the MCP server) \{#connect-mcp-inspector-to-the-mcp-server} -진행하기 전에 MCP inspector에서 다음 설정을 확인하세요: +진행하기 전에 MCP 인스펙터에서 다음 설정을 확인하세요: - **Transport Type**: `SSE`로 설정 -- **URL**: MCP 서버의 URL로 설정. 여기서는 `http://localhost:3001/sse`가 됩니다. +- **URL**: MCP 서버의 URL로 설정 (예: `http://localhost:3001/sse`) -이제 "Connect" 버튼을 클릭하여 MCP inspector가 MCP 서버에 연결되는지 확인하세요. 정상적으로 연결되면 MCP inspector에서 "Connected" 상태를 볼 수 있습니다. +이제 "Connect" 버튼을 클릭하여 MCP 인스펙터가 MCP 서버에 연결되는지 확인하세요. 정상적으로 연결되면 MCP 인스펙터에서 "Connected" 상태를 볼 수 있습니다. ### 체크포인트: 할 일 관리 도구 실행 (Checkpoint: Run todo manager tools) \{#checkpoint-run-todo-manager-tools} -1. MCP inspector 상단 메뉴에서 "Tools" 탭 클릭 +1. MCP 인스펙터 상단 메뉴에서 "Tools" 탭 클릭 2. "List Tools" 버튼 클릭 -3. `create-todo`, `get-todos`, `delete-todo` 도구가 페이지에 표시됩니다. 클릭하여 도구 상세 보기 +3. `create-todo`, `get-todos`, `delete-todo` 도구가 페이지에 표시되는지 확인. 클릭하여 도구 상세 보기 4. 우측에 "Run Tool" 버튼이 보입니다. 클릭 후 필요한 파라미터 입력하여 도구 실행 -5. JSON 응답 `{"error": "Not implemented"}`와 함께 도구 결과가 표시됩니다. +5. 도구 결과로 `{"error": "Not implemented"}` JSON 응답이 표시됩니다. -![MCP inspector 첫 실행](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) +![MCP inspector first run](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) ## 인가 서버와 통합 (Integrate with your authorization server) \{#integrate-with-your-authorization-server} 이 섹션을 완료하려면 다음 사항을 고려해야 합니다:
-**인가 서버의 발급자 URL (issuer URL)** +**인가 서버의 발급자(issuer) URL** -일반적으로 인가 서버의 기본 URL입니다. 예: `https://auth.example.com`. 일부 제공자는 `https://example.logto.app/oidc`와 같이 경로가 포함될 수 있으니, 제공자 문서를 꼭 확인하세요. +일반적으로 인가 서버의 기본 URL입니다. 예: `https://auth.example.com`. 일부 제공자는 `https://example.logto.app/oidc`와 같이 경로가 있을 수 있으니, 제공자 문서를 확인하세요.
-**인가 서버 메타데이터 가져오기 방법** +**인가 서버 메타데이터 조회 방법** - 인가 서버가 [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) 또는 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)를 준수한다면, MCP Auth 내장 유틸리티로 자동으로 메타데이터를 가져올 수 있습니다. -- 준수하지 않는 경우, MCP 서버 설정에서 메타데이터 URL 또는 엔드포인트를 수동으로 지정해야 합니다. 제공자 문서에서 엔드포인트를 확인하세요. +- 준수하지 않는 경우, MCP 서버 설정에 메타데이터 URL 또는 엔드포인트를 수동으로 지정해야 합니다. 제공자 문서를 참고하세요.
-**MCP inspector를 인가 서버에 클라이언트로 등록하는 방법** +**MCP 인스펙터를 인가 서버에 클라이언트로 등록하는 방법** -- 인가 서버가 [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)을 지원한다면, MCP inspector가 자동으로 클라이언트로 등록되므로 이 단계를 건너뛸 수 있습니다. -- 지원하지 않는 경우, MCP inspector를 인가 서버에 수동으로 클라이언트로 등록해야 합니다. +- 인가 서버가 [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)을 지원하면, MCP 인스펙터가 자동으로 클라이언트로 등록됩니다. +- 지원하지 않는 경우, MCP 인스펙터를 인가 서버에 수동으로 클라이언트로 등록해야 합니다.
@@ -553,7 +643,7 @@ npm run dev - **리소스 지표 기반**: - - `resource` 파라미터로 대상 API 지정([RFC 8707: OAuth 2.0을 위한 리소스 지표](https://datatracker.ietf.org/doc/html/rfc8707) 참고) + - `resource` 파라미터로 대상 API 지정 ([RFC 8707: OAuth 2.0을 위한 리소스 지표](https://datatracker.ietf.org/doc/html/rfc8707) 참고) - 최신 OAuth 2.0 구현에서 일반적 - 예시 요청: ```json @@ -562,9 +652,9 @@ npm run dev "scope": "create:todos read:todos" } ``` - - 서버는 요청된 리소스에 바인딩된 토큰을 발급 + - 서버가 요청된 리소스에 바인딩된 토큰 발급 -- **Audience 기반**: +- **대상 (audience) 기반**: - `audience` 파라미터로 토큰 수신자 지정 - 리소스 지표와 유사하지만 의미가 다름 @@ -577,7 +667,7 @@ npm run dev ``` - **순수 스코프 기반**: - - 리소스/audience 파라미터 없이 스코프만 사용 + - resource/audience 파라미터 없이 스코프만 사용 - 전통적인 OAuth 2.0 방식 - 예시 요청: ```json @@ -585,65 +675,99 @@ npm run dev "scope": "todo-api:create todo-api:read openid profile" } ``` - - 권한 네임스페이스를 위해 접두어 스코프 사용 + - 권한 네임스페이스를 위해 접두사 스코프 사용 - 간단한 OAuth 2.0 구현에서 일반적 :::tip 모범 사례 -- 제공자 문서에서 지원되는 파라미터 확인 +- 제공자 문서에서 지원 파라미터 확인 - 일부 제공자는 여러 방식을 동시에 지원 -- 리소스 지표는 audience 제한을 통해 보안 강화 -- 가능하다면 리소스 지표 사용을 권장 +- 리소스 지표는 audience 제한을 통해 더 나은 보안 제공 +- 가능하다면 리소스 지표 사용 권장 :::
-각 제공자마다 세부 요구사항이 다를 수 있지만, 아래 단계는 MCP inspector와 MCP 서버를 제공자별 설정과 통합하는 과정을 안내합니다. +각 제공자마다 세부 요구 사항이 다를 수 있지만, 아래 단계는 MCP 인스펙터와 MCP 서버를 제공자별 설정과 통합하는 과정을 안내합니다. -### MCP inspector를 클라이언트로 등록 (Register MCP inspector as a client) \{#register-mcp-inspector-as-a-client} +### MCP 인스펙터를 클라이언트로 등록 (Register MCP inspector as a client) \{#register-mcp-inspector-as-a-client} [Logto](https://logto.io)는 OpenID Connect 제공자로, 리소스 지표와 스코프를 지원하므로 `https://todo.mcp-server.app`를 리소스 지표로 사용하여 todo API를 안전하게 보호할 수 있습니다. -Logto는 아직 동적 클라이언트 등록을 지원하지 않으므로, MCP inspector를 Logto 테넌트에 수동으로 클라이언트로 등록해야 합니다: +Logto는 아직 동적 클라이언트 등록을 지원하지 않으므로, MCP 인스펙터를 Logto 테넌트에 수동으로 클라이언트로 등록해야 합니다: -1. MCP inspector를 열고 "OAuth Configuration" 버튼을 클릭하세요. **Redirect URL (auto-populated)** 값을 복사합니다(예: `http://localhost:6274/oauth/callback`). +1. MCP 인스펙터를 열고 "OAuth Configuration" 버튼을 클릭합니다. **Redirect URL (auto-populated)** 값을 복사하세요 (예: `http://localhost:6274/oauth/callback`). 2. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인하세요. 3. "Applications" 탭으로 이동, "Create application" 클릭. 페이지 하단에서 "Create app without framework" 클릭. 4. 애플리케이션 세부 정보 입력 후 "Create application" 클릭: - **Select an application type**: "Single-page application" 선택 - **Application name**: 예: "MCP Inspector" -5. "Settings / Redirect URIs" 섹션에서 복사한 **Redirect URL (auto-populated)** 값을 붙여넣고, 하단 바에서 "Save changes" 클릭 +5. "Settings / Redirect URIs" 섹션에서 복사한 **Redirect URL**을 붙여넣고, 하단 바에서 "Save changes" 클릭 6. 상단 카드에서 "App ID" 값을 복사 -7. MCP inspector로 돌아가 "OAuth Configuration"의 "Client ID"에 "App ID" 값 붙여넣기 +7. MCP 인스펙터로 돌아가 "OAuth Configuration"의 "Client ID"에 "App ID" 값 붙여넣기 8. "Auth Params" 필드에 `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` 입력. Logto가 todo manager에 필요한 스코프가 포함된 액세스 토큰을 반환하도록 합니다. + + + + Asgardeo는 표준 API를 통한 동적 클라이언트 등록을 지원하지만, 엔드포인트는 보호되어 있으며 필요한 권한이 있는 액세스 토큰이 필요합니다. 이 튜토리얼에서는 Asgardeo Console을 통해 클라이언트를 수동으로 등록합니다. + + :::note + Asgardeo 계정이 없다면 [무료 가입](https://asgardeo.io) 가능합니다. + ::: + + MCP Inspector를 위한 Asgardeo 설정 단계: + + 1. [Asgardeo Console](https://console.asgardeo.io)에 로그인 후 조직 선택 + + 2. 새 애플리케이션 생성: + - **Applications** → **New Application** + - **Single-Page Application** 선택 + - 애플리케이션 이름 입력 (예: `MCP Inspector`) + - **Authorized Redirect URLs**에 MCP Inspector에서 복사한 **Redirect URL** 붙여넣기 (예: `http://localhost:6274/oauth/callback`) + - **Create** 클릭 + + 3. 프로토콜 설정: + - **Protocol** 탭에서: + - 자동 생성된 **Client ID** 복사 + - **Access Token** 섹션에서 `Token Type`을 `JWT`로 변경 + - **Update** 클릭 + + 4. MCP Inspector 클라이언트 애플리케이션에서: + - **OAuth Configuration** 섹션 열기 + - 복사한 **Client ID** 붙여넣기 + - **Auth Params** 필드에 다음 입력: + + ```json + { "scope": "openid profile email" } + ``` :::note -이 가이드는 일반적인 OAuth 2.0 / OpenID Connect 제공자 통합 가이드입니다. OIDC는 OAuth 2.0 위에 구축되어 있으므로 두 방식 모두 유사한 단계를 따릅니다. 구체적인 내용은 제공자 문서를 참고하세요. +이 가이드는 일반적인 OAuth 2.0 / OpenID Connect 제공자 통합 안내입니다. OIDC는 OAuth 2.0 위에 구축되어 있으므로 단계가 유사합니다. 제공자 문서를 참고하세요. ::: -제공자가 동적 클라이언트 등록을 지원한다면 아래 8번 단계로 바로 이동하여 MCP inspector를 설정하세요. 그렇지 않으면 MCP inspector를 수동으로 클라이언트로 등록해야 합니다: +제공자가 동적 클라이언트 등록을 지원한다면 아래 8번 단계로 바로 진행하세요. 그렇지 않으면 MCP 인스펙터를 수동으로 클라이언트로 등록해야 합니다: -1. MCP inspector를 열고 "OAuth Configuration" 버튼을 클릭하세요. **Redirect URL (auto-populated)** 값을 복사합니다(예: `http://localhost:6274/oauth/callback`). +1. MCP 인스펙터를 열고 "OAuth Configuration" 버튼 클릭. **Redirect URL (auto-populated)** 값을 복사 (예: `http://localhost:6274/oauth/callback`). -2. 제공자 콘솔에 로그인하세요. +2. 제공자 콘솔에 로그인 3. "Applications" 또는 "Clients" 섹션으로 이동, 새 애플리케이션 또는 클라이언트 생성 -4. 클라이언트 유형을 요구하는 경우 "Single-page application" 또는 "Public client" 선택 +4. 클라이언트 타입이 필요하다면 "Single-page application" 또는 "Public client" 선택 -5. 애플리케이션 생성 후, 리디렉션 URI를 설정해야 합니다. MCP inspector에서 복사한 **Redirect URL (auto-populated)** 값을 붙여넣으세요. +5. 애플리케이션 생성 후, 리디렉션 URI 설정. MCP 인스펙터에서 복사한 **Redirect URL** 붙여넣기 -6. 새로 생성된 애플리케이션의 "Client ID" 또는 "Application ID"를 찾아 복사 +6. 새로 생성된 애플리케이션의 "Client ID" 또는 "Application ID" 복사 -7. MCP inspector로 돌아가 "OAuth Configuration"의 "Client ID"에 붙여넣기 +7. MCP 인스펙터로 돌아가 "OAuth Configuration"의 "Client ID"에 붙여넣기 -8. "Auth Params" 필드에 다음 값을 입력하여 todo 작업에 필요한 스코프를 요청하세요: +8. "Auth Params" 필드에 다음 값 입력: ```json { "scope": "create:todos read:todos delete:todos" } @@ -654,23 +778,23 @@ Logto는 아직 동적 클라이언트 등록을 지원하지 않으므로, MCP ### MCP Auth 설정 (Set up MCP auth) \{#set-up-mcp-auth} -MCP 서버 프로젝트에서 MCP Auth SDK를 설치하고, 인가 서버 메타데이터를 사용하도록 구성해야 합니다. +MCP 서버 프로젝트에서 MCP Auth SDK를 설치하고, 인가 서버 메타데이터를 사용하도록 설정해야 합니다. -먼저 `mcpauth` 패키지를 설치하세요: +먼저 `mcpauth` 패키지 설치: ```bash pip install mcpauth ``` -또는 `uv`, `poetry` 등 원하는 패키지 매니저를 사용할 수 있습니다. +또는 `uv`, `poetry` 등 원하는 패키지 매니저 사용 -먼저 `mcp-auth` 패키지를 설치하세요: +먼저 `mcp-auth` 패키지 설치: ```bash npm install mcp-auth @@ -685,19 +809,28 @@ MCP Auth는 인가 서버 메타데이터가 필요합니다. 제공자에 따 -발급자 URL(issuer URL)은 Logto Console의 애플리케이션 상세 페이지 "Endpoints & Credentials / Issuer endpoint" 섹션에서 확인할 수 있습니다. 예: `https://my-project.logto.app/oidc`. +발급자(issuer) URL은 Logto Console의 애플리케이션 상세 페이지 "Endpoints & Credentials / Issuer endpoint" 섹션에서 확인할 수 있습니다. 예: `https://my-project.logto.app/oidc` + + + Asgardeo Console에서 발급자(issuer) URL을 확인할 수 있습니다. 생성한 애플리케이션으로 이동하여 **Info** 탭을 열면 **Issuer** 필드가 표시됩니다. 예시: + `https://api.asgardeo.io/t//oauth2/token` + + + + + OAuth 2.0 제공자의 경우: 1. 제공자 문서에서 인가 서버 URL(issuer URL 또는 base URL) 확인 2. 일부 제공자는 `https://{your-domain}/.well-known/oauth-authorization-server`에서 노출 -3. 제공자 관리 콘솔의 OAuth/API 설정에서 확인 +3. 제공자 관리자 콘솔의 OAuth/API 설정에서 확인 @@ -709,7 +842,7 @@ OAuth 2.0 제공자의 경우: -`todo-manager.py`를 업데이트하여 MCP Auth 구성을 추가하세요: +`todo-manager.py`에 MCP Auth 설정 추가: ```python from mcpauth import MCPAuth @@ -724,7 +857,7 @@ mcp_auth = MCPAuth(server=auth_server_config) -`todo-manager.ts`를 업데이트하여 MCP Auth 구성을 추가하세요: +`todo-manager.ts`에 MCP Auth 설정 추가: ```ts // todo-manager.ts @@ -742,7 +875,7 @@ const mcpAuth = new MCPAuth({ ### MCP 서버 업데이트 (Update MCP server) \{#update-mcp-server} -거의 다 왔습니다! 이제 MCP Auth 라우트 및 미들웨어 함수를 적용하고, 사용자의 스코프에 기반한 권한 제어를 할 일 관리 도구에 구현합니다. +거의 다 왔습니다! 이제 MCP Auth 라우트와 미들웨어 함수를 적용하고, 사용자 스코프 기반 권한 제어를 구현합니다. @@ -753,7 +886,7 @@ def create_todo(content: str) -> dict[str, Any]: """새 할 일 생성.""" return ( mcp_auth.auth_info.scopes - if mcp_auth.auth_info # Bearer 인증 미들웨어에서 채워짐 + if mcp_auth.auth_info # Bearer auth 미들웨어로 채워짐 else {"error": "Not authenticated"} ) @@ -764,7 +897,7 @@ app = Starlette( routes=[ # 메타데이터 라우트 추가 (`/.well-known/oauth-authorization-server`) mcp_auth.metadata_route(), - # Bearer 인증 미들웨어로 MCP 서버 보호 + # Bearer auth 미들웨어로 MCP 서버 보호 Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), ], ) @@ -807,7 +940,7 @@ app.use(mcpAuth.bearerAuth('jwt')); """ 데모용 간단한 Todo 서비스. -메모리 내 리스트로 todo를 저장합니다. +메모리 리스트에 todo를 저장합니다. """ from datetime import datetime @@ -844,7 +977,7 @@ class TodoService: 모든 todo 조회, owner_id로 필터링 가능 Args: - owner_id: 제공 시 해당 사용자의 todo만 반환 + owner_id: 지정 시 해당 사용자의 todo만 반환 Returns: todo 딕셔너리 리스트 @@ -862,7 +995,7 @@ class TodoService: todo_id: 조회할 todo의 ID Returns: - 찾으면 Todo 객체, 아니면 None + 찾으면 Todo 객체, 없으면 None """ for todo in self._todos: if todo.id == todo_id: @@ -875,7 +1008,7 @@ class TodoService: Args: content: todo 내용 - owner_id: todo 소유자 ID + owner_id: 소유자 ID Returns: 생성된 todo의 딕셔너리 표현 @@ -897,7 +1030,7 @@ class TodoService: todo_id: 삭제할 todo의 ID Returns: - 삭제된 todo의 딕셔너리 표현(찾으면), 아니면 None + 삭제된 todo의 딕셔너리 표현(찾으면), 없으면 None """ for i, todo in enumerate(self._todos): if todo.id == todo_id: @@ -927,7 +1060,7 @@ type Todo = { /** * 데모용 간단한 Todo 서비스. - * 메모리 배열로 todo를 저장합니다. + * 메모리 배열에 todo 저장 */ export class TodoService { private readonly todos: Todo[] = []; @@ -996,7 +1129,7 @@ def assert_user_id(auth_info: Optional[dict]) -> str: return subject def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """사용자가 모든 필수 스코프를 가지고 있는지 확인""" + """사용자가 모든 필수 스코프를 보유하는지 확인""" return all(scope in user_scopes for scope in required_scopes) # TodoService 인스턴스 생성 @@ -1030,7 +1163,7 @@ def create_todo(content: str) -> dict[str, Any]: # ... ``` -전체 구현 예시는 [샘플 코드](https://github.com/mcp-auth/python/tree/master/samples/server)를 참고하세요. +전체 구현은 [샘플 코드](https://github.com/mcp-auth/python/tree/master/samples/server)에서 확인할 수 있습니다. @@ -1052,7 +1185,7 @@ const assertUserId = (authInfo?: AuthInfo) => { }; /** - * 사용자가 작업에 필요한 모든 스코프를 가지고 있는지 확인 + * 작업에 필요한 모든 스코프를 사용자가 보유하는지 확인 */ const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { return requiredScopes.every((scope) => userScopes.includes(scope)); @@ -1083,49 +1216,49 @@ server.tool( // ... ``` -전체 구현 예시는 [샘플 코드](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager)를 참고하세요. +전체 구현은 [샘플 코드](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager)에서 확인할 수 있습니다. ## 체크포인트: `todo-manager` 도구 실행 (Checkpoint: Run the `todo-manager` tools) \{#checkpoint-run-the-todo-manager-tools} -MCP 서버를 재시작하고 브라우저에서 MCP inspector를 엽니다. "Connect" 버튼을 클릭하면 인가 서버의 로그인 페이지로 리디렉션됩니다. +MCP 서버를 재시작하고 브라우저에서 MCP 인스펙터를 엽니다. "Connect" 버튼을 클릭하면 인가 서버의 로그인 페이지로 리디렉션됩니다. -로그인 후 MCP inspector로 돌아오면, 이전 체크포인트에서 했던 것처럼 todo manager 도구를 실행해보세요. 이번에는 인증된 사용자 아이덴티티로 도구를 사용할 수 있습니다. 도구의 동작은 사용자에게 할당된 역할과 권한에 따라 달라집니다: +로그인 후 MCP 인스펙터로 돌아와 이전 체크포인트에서 했던 것처럼 todo manager 도구를 실행해보세요. 이번에는 인증된 사용자 아이덴티티로 도구를 사용할 수 있습니다. 도구의 동작은 사용자에게 할당된 역할과 권한에 따라 달라집니다: -- **User**(오직 `create:todos` 스코프만 있는 경우)로 로그인했다면: +- **User**(오직 `create:todos` 스코프만 보유)로 로그인한 경우: - `create-todo` 도구로 새 할 일 생성 가능 - 자신의 할 일만 조회 및 삭제 가능 - 다른 사용자의 할 일은 볼 수 없고 삭제할 수 없음 -- **Admin**(모든 스코프: `create:todos`, `read:todos`, `delete:todos`가 있는 경우)로 로그인했다면: +- **Admin**(모든 스코프: `create:todos`, `read:todos`, `delete:todos`)로 로그인한 경우: - 새 할 일 생성 가능 - `get-todos` 도구로 시스템의 모든 할 일 조회 가능 - - `delete-todo` 도구로 소유자와 관계없이 모든 할 일 삭제 가능 + - `delete-todo` 도구로 소유자와 상관없이 모든 할 일 삭제 가능 다른 권한 수준을 테스트하려면: -1. 현재 세션에서 로그아웃(MCP inspector에서 "Disconnect" 클릭) +1. 현재 세션에서 로그아웃(MCP 인스펙터의 "Disconnect" 클릭) 2. 다른 역할/권한을 가진 사용자 계정으로 로그인 3. 동일한 도구를 다시 실행하여 권한에 따라 동작이 어떻게 달라지는지 확인 -이렇게 하면 역할 기반 접근 제어 (RBAC)가 실제로 어떻게 동작하는지 체험할 수 있습니다. +이렇게 하면 역할 기반 접근 제어 (RBAC)가 실제로 어떻게 동작하는지 확인할 수 있습니다. -![MCP inspector todo manager 도구 결과](/docs-assets/images/tutorials/todo-manager/result.png) +![MCP inspector todo manager tool result](/docs-assets/images/tutorials/todo-manager/result.png) :::info -MCP 서버( OIDC 버전 )의 전체 코드는 [MCP Auth Python SDK 저장소](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py)를 참고하세요. +MCP 서버(OIDC 버전) 전체 코드는 [MCP Auth Python SDK 저장소](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py)에서 확인할 수 있습니다. ::: :::info -MCP 서버( OIDC 버전 )의 전체 코드는 [MCP Auth Node.js SDK 저장소](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)를 참고하세요. +MCP 서버(OIDC 버전) 전체 코드는 [MCP Auth Node.js SDK 저장소](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)에서 확인할 수 있습니다. ::: @@ -1133,11 +1266,11 @@ MCP 서버( OIDC 버전 )의 전체 코드는 [MCP Auth Node.js SDK 저장소](h ## 마무리 (Closing notes) \{#closing-notes} -🎊 축하합니다! 튜토리얼을 성공적으로 완료했습니다. 지금까지 한 일을 요약해봅시다: +🎊 축하합니다! 튜토리얼을 성공적으로 완료했습니다. 지금까지 한 일을 요약하면: -- 할 일 관리 도구(`create-todo`, `get-todos`, `delete-todo`)가 포함된 기본 MCP 서버 설정 +- todo 관리 도구(`create-todo`, `get-todos`, `delete-todo`)가 포함된 기본 MCP 서버 설정 - 사용자와 관리자를 위한 다양한 권한 수준의 역할 기반 접근 제어 (RBAC) 구현 - MCP Auth를 사용하여 MCP 서버를 인가 서버와 통합 -- MCP Inspector를 구성하여 사용자를 인증하고, 스코프가 포함된 액세스 토큰으로 도구 호출 +- MCP Inspector를 설정하여 사용자를 인증하고, 스코프가 포함된 액세스 토큰으로 도구 호출 MCP Auth를 최대한 활용하려면 다른 튜토리얼과 문서도 꼭 확인해보세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx index 325551e..b5e5698 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 1 -sidebar_label: '튜토리얼: 나는 누구인가? (Who am I?)' +sidebar_label: '튜토리얼: 나는 누구인가?' --- import TabItem from '@theme/TabItem'; @@ -9,7 +9,7 @@ import Tabs from '@theme/Tabs'; import SetupOauth from './_setup-oauth.mdx'; import SetupOidc from './_setup-oidc.mdx'; -# 튜토리얼: 나는 누구인가? (Who am I?) +# 튜토리얼: 나는 누구인가? (Tutorial: Who am I?) 이 튜토리얼에서는 MCP Auth를 설정하여 사용자를 인증 (Authentication)하고 인가 (Authorization) 서버에서 아이덴티티 정보를 가져오는 과정을 안내합니다. @@ -26,7 +26,7 @@ import SetupOidc from './_setup-oidc.mdx'; - **MCP 인스펙터**: MCP 서버를 위한 시각적 테스트 도구. OAuth / OIDC 클라이언트 역할도 하여 인가 (Authorization) 플로우를 시작하고 액세스 토큰 (Access token)을 가져옵니다. - **인가 (Authorization) 서버**: 사용자 아이덴티티를 관리하고 액세스 토큰 (Access token)을 발급하는 OAuth 2.1 또는 OpenID Connect 제공자 -아래는 이 구성 요소들 간의 상호작용을 나타낸 고수준 다이어그램입니다: +아래는 이 구성 요소들 간의 상호작용을 나타내는 상위 수준 다이어그램입니다: ```mermaid sequenceDiagram @@ -35,7 +35,7 @@ sequenceDiagram participant Auth as 인가 (Authorization) 서버 Client->>Server: `whoami` 도구 요청 - Server->>Client: 401 인가되지 않음 반환 + Server->>Client: 401 인증되지 않음 반환 Client->>Auth: 인가 (Authorization) 플로우 시작 Auth->>Auth: 인가 (Authorization) 플로우 완료 Auth->>Client: 인가 코드와 함께 리디렉션 @@ -67,14 +67,25 @@ userinfo 엔드포인트에 접근할 수 있는 액세스 토큰 (Access token) userinfo 엔드포인트에 접근할 수 있는 액세스 토큰 (Access token)을 얻으려면 최소 두 개의 스코프 (Scope), 즉 `openid`와 `profile`이 필요합니다. 스코프 설정은 아래에서 다루니 계속 읽어주세요. + + + + +[Asgardeo](https://wso2.com/asgardeo)는 OAuth 2.0 및 OpenID Connect (OIDC)를 지원하는 클라우드 네이티브 IDaaS 플랫폼으로, 현대 애플리케이션을 위한 강력한 아이덴티티 및 접근 관리를 제공합니다. + +사용자 정보는 액세스 토큰 (Access token)과 함께 반환되는 ID 토큰 (ID token)에 인코딩되어 있습니다. 하지만 OIDC 제공자로서 Asgardeo는 [UserInfo 엔드포인트](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/)를 제공하여 애플리케이션이 인증된 사용자에 대한 클레임 (Claim)을 페이로드에서 조회할 수 있습니다. + +이 엔드포인트는 [OIDC 디스커버리 엔드포인트](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs) 또는 Asgardeo 콘솔의 'Info' 탭에서 동적으로 확인할 수 있습니다. + +userinfo 엔드포인트에 접근할 수 있는 액세스 토큰 (Access token)을 얻으려면 최소 두 개의 스코프 (Scope), 즉 `openid`와 `profile`이 필요합니다. 대부분의 OpenID Connect 제공자는 [userinfo 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)를 지원하여 사용자 아이덴티티 정보를 조회할 수 있습니다. -제공자의 문서를 확인하여 이 엔드포인트를 지원하는지 확인하세요. 제공자가 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)를 지원한다면, `.well-known/openid-configuration` 엔드포인트의 응답에서 `userinfo_endpoint`가 포함되어 있는지 확인할 수 있습니다. +제공자의 문서를 확인하여 이 엔드포인트를 지원하는지 확인하세요. [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)를 지원한다면, `.well-known/openid-configuration` 엔드포인트의 응답에서 `userinfo_endpoint`가 포함되어 있는지 확인할 수 있습니다. -userinfo 엔드포인트에 접근할 수 있는 액세스 토큰 (Access token)을 얻으려면 최소 두 개의 스코프 (Scope), 즉 `openid`와 `profile`이 필요합니다. 스코프와 사용자 아이덴티티 클레임 (Claim) 매핑은 제공자 문서를 참고하세요. +userinfo 엔드포인트에 접근할 수 있는 액세스 토큰 (Access token)을 얻으려면 최소 두 개의 스코프 (Scope), 즉 `openid`와 `profile`이 필요합니다. 스코프와 사용자 아이덴티티 클레임 (Claim)의 매핑은 제공자 문서를 참고하세요. @@ -86,11 +97,11 @@ OAuth 2.0은 사용자 아이덴티티 정보를 조회하는 표준 방법을 ### 동적 클라이언트 등록 (Dynamic Client Registration) \{#dynamic-client-registration} -이 튜토리얼에서는 동적 클라이언트 등록이 필수는 아니지만, MCP 클라이언트 등록 과정을 자동화하고 싶다면 유용할 수 있습니다. 자세한 내용은 [동적 클라이언트 등록이 필요한가요?](../../provider-list.mdx#is-dcr-required) 를 참고하세요. +이 튜토리얼에서는 동적 클라이언트 등록이 필수는 아니지만, MCP 클라이언트 등록 과정을 자동화하고 싶다면 유용할 수 있습니다. 자세한 내용은 [동적 클라이언트 등록이 필요한가요?](../../provider-list.mdx#is-dcr-required)를 참고하세요. ## MCP 서버 설정하기 \{#set-up-the-mcp-server} -[MCP 공식 SDK](https://github.com/modelcontextprotocol)를 사용하여 인가 (Authorization) 서버에서 사용자 아이덴티티 정보를 조회하는 `whoami` 도구가 포함된 MCP 서버를 만듭니다. +[MCP 공식 SDK](https://github.com/modelcontextprotocol)를 사용하여 인가 (Authorization) 서버에서 사용자 아이덴티티 정보를 조회하는 `whoami` 도구가 있는 MCP 서버를 만듭니다. ### 새 프로젝트 생성하기 \{#create-a-new-project} @@ -100,7 +111,7 @@ OAuth 2.0은 사용자 아이덴티티 정보를 조회하는 표준 방법을 ```bash mkdir mcp-server cd mcp-server -uv init # 또는 `pipenv`나 `poetry`로 새 가상환경 생성 +uv init # 또는 `pipenv` 또는 `poetry`로 새 가상환경 생성 ``` @@ -111,7 +122,7 @@ uv init # 또는 `pipenv`나 `poetry`로 새 가상환경 생성 ```bash mkdir mcp-server cd mcp-server -npm init -y # 또는 `pnpm init` +npm init -y # 또는 `pnpm init` 사용 npm pkg set type="module" npm pkg set main="whoami.js" npm pkg set scripts.start="node whoami.js" @@ -129,7 +140,7 @@ npm pkg set scripts.start="node whoami.js" pip install "mcp[cli]" starlette uvicorn ``` -또는 `uv`, `poetry` 등 원하는 패키지 매니저를 사용하세요. +또는 `uv`나 `poetry` 등 원하는 패키지 매니저를 사용할 수 있습니다. @@ -138,7 +149,7 @@ pip install "mcp[cli]" starlette uvicorn npm install @modelcontextprotocol/sdk express ``` -또는 `pnpm`, `yarn` 등 원하는 패키지 매니저를 사용하세요. +또는 `pnpm`이나 `yarn` 등 원하는 패키지 매니저를 사용할 수 있습니다. @@ -150,7 +161,7 @@ npm install @modelcontextprotocol/sdk express -`whoami.py`라는 파일을 만들고 다음 코드를 추가하세요: +`whoami.py`라는 파일을 만들고 아래 코드를 추가하세요: ```python from mcp.server.fastmcp import FastMCP @@ -170,7 +181,7 @@ app = Starlette( ) ``` -서버 실행: +서버를 실행하려면: ```bash uvicorn whoami:app --host 0.0.0.0 --port 3001 @@ -180,12 +191,12 @@ uvicorn whoami:app --host 0.0.0.0 --port 3001 :::note -현재 MCP 인스펙터 구현은 인가 (Authorization) 플로우를 처리하지 않으므로, SSE 방식을 사용해 MCP 서버를 설정합니다. MCP 인스펙터가 인가 (Authorization) 플로우를 지원하면 코드를 업데이트하겠습니다. +현재 MCP 인스펙터 구현은 인가 (Authorization) 플로우를 처리하지 않으므로, SSE 방식을 사용하여 MCP 서버를 설정합니다. MCP 인스펙터가 인가 (Authorization) 플로우를 지원하면 코드를 업데이트할 예정입니다. ::: `pnpm`이나 `yarn`도 사용할 수 있습니다. -`whoami.js`라는 파일을 만들고 다음 코드를 추가하세요: +`whoami.js`라는 파일을 만들고 아래 코드를 추가하세요: ```js import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; @@ -235,7 +246,7 @@ app.post('/messages', async (req, res) => { app.listen(PORT); ``` -서버 실행: +서버를 실행하려면: ```bash npm start @@ -248,11 +259,11 @@ npm start ### MCP 인스펙터 클론 및 실행 \{#clone-and-run-mcp-inspector} -이제 MCP 서버가 실행 중이므로, MCP 인스펙터를 사용해 `whoami` 도구가 사용 가능한지 확인할 수 있습니다. +이제 MCP 서버가 실행 중이므로, MCP 인스펙터를 사용하여 `whoami` 도구가 사용 가능한지 확인할 수 있습니다. -현재 구현의 한계로 인해, [MCP 인스펙터](https://github.com/mcp-auth/inspector)를 포크하여 인증 (Authentication) 및 인가 (Authorization)에 더 유연하고 확장 가능하도록 개선했습니다. 변경 사항을 원본 저장소에 PR로 제출했습니다. +현재 구현의 한계로 인해, [MCP 인스펙터](https://github.com/mcp-auth/inspector)를 포크하여 인증 (Authentication) 및 인가 (Authorization)에 더 유연하고 확장 가능하도록 개선했습니다. 또한, 원본 저장소에 변경 사항을 반영하는 PR도 제출했습니다. -MCP 인스펙터를 실행하려면 (Node.js 필요): +MCP 인스펙터를 실행하려면 다음 명령어를 사용하세요 (Node.js 필요): ```bash git clone https://github.com/mcp-auth/inspector.git @@ -261,26 +272,26 @@ npm install npm run dev ``` -그런 다음 브라우저에서 `http://localhost:6274/` (또는 터미널에 표시된 URL)로 접속하여 MCP 인스펙터에 접근하세요. +그런 다음 브라우저에서 `http://localhost:6274/` (또는 터미널에 표시된 다른 URL)로 접속하여 MCP 인스펙터에 접근하세요. ### MCP 인스펙터를 MCP 서버에 연결하기 \{#connect-mcp-inspector-to-the-mcp-server} 진행하기 전에 MCP 인스펙터에서 다음 설정을 확인하세요: - **Transport Type**: `SSE`로 설정 -- **URL**: MCP 서버의 URL로 설정 (예: `http://localhost:3001/sse`) +- **URL**: MCP 서버의 URL로 설정. 예시에서는 `http://localhost:3001/sse`가 됩니다. 이제 "Connect" 버튼을 클릭하여 MCP 인스펙터가 MCP 서버에 연결되는지 확인하세요. 정상적으로 연결되면 MCP 인스펙터에서 "Connected" 상태를 볼 수 있습니다. ### 체크포인트: `whoami` 도구 실행하기 \{#checkpoint-run-the-whoami-tool} -1. MCP 인스펙터 상단 메뉴에서 "Tools" 탭 클릭 -2. "List Tools" 버튼 클릭 -3. 페이지에 `whoami` 도구가 표시되어야 합니다. 클릭하여 도구 상세 보기 -4. 우측에 "Run Tool" 버튼이 보입니다. 클릭하여 도구 실행 +1. MCP 인스펙터 상단 메뉴에서 "Tools" 탭을 클릭하세요. +2. "List Tools" 버튼을 클릭하세요. +3. 페이지에 `whoami` 도구가 표시되어야 합니다. 클릭하여 도구 상세 정보를 확인하세요. +4. 오른쪽에 "Run Tool" 버튼이 보입니다. 클릭하여 도구를 실행하세요. 5. JSON 응답 `{"error": "Not authenticated"}`가 결과로 표시되어야 합니다. -![MCP 인스펙터 첫 실행](/docs-assets/images/tutorials/whoami/inspector-first-run.png) +![MCP inspector first run](/docs-assets/images/tutorials/whoami/inspector-first-run.png) ## 인가 (Authorization) 서버와 통합하기 \{#integrate-with-your-authorization-server} @@ -296,7 +307,7 @@ npm run dev
**인가 (Authorization) 서버 메타데이터 조회 방법** -- 인가 (Authorization) 서버가 [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) 또는 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)를 준수한다면, MCP Auth 내장 유틸리티로 메타데이터를 자동으로 가져올 수 있습니다. +- 인가 (Authorization) 서버가 [OAuth 2.0 인가 서버 메타데이터](https://datatracker.ietf.org/doc/html/rfc8414) 또는 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)를 준수한다면, MCP Auth 내장 유틸리티로 메타데이터를 자동으로 가져올 수 있습니다. - 준수하지 않는 경우, MCP 서버 설정에서 메타데이터 URL 또는 엔드포인트를 수동으로 지정해야 합니다. 제공자 문서에서 엔드포인트를 확인하세요.
@@ -304,7 +315,7 @@ npm run dev
**MCP 인스펙터를 인가 (Authorization) 서버에 클라이언트로 등록하는 방법** -- 인가 (Authorization) 서버가 [동적 클라이언트 등록](https://datatracker.ietf.org/doc/html/rfc7591)을 지원한다면, MCP 인스펙터가 자동으로 클라이언트로 등록되므로 이 단계를 건너뛸 수 있습니다. +- [동적 클라이언트 등록](https://datatracker.ietf.org/doc/html/rfc7591)을 지원한다면, MCP 인스펙터가 자동으로 클라이언트로 등록됩니다. - 지원하지 않는 경우, MCP 인스펙터를 인가 (Authorization) 서버에 수동으로 클라이언트로 등록해야 합니다.
@@ -320,7 +331,7 @@ npm run dev
-각 제공자마다 세부 요구사항이 다를 수 있지만, 아래 단계에 따라 MCP 인스펙터와 MCP 서버를 제공자별 설정으로 통합할 수 있습니다. +각 제공자마다 요구 사항이 다를 수 있지만, 아래 단계에 따라 MCP 인스펙터와 MCP 서버를 제공자별 설정으로 통합할 수 있습니다. ### MCP 인스펙터를 클라이언트로 등록하기 \{#register-mcp-inspector-as-a-client} @@ -331,13 +342,13 @@ npm run dev Logto는 아직 동적 클라이언트 등록을 지원하지 않으므로, MCP 인스펙터를 Logto 테넌트에 수동으로 클라이언트로 등록해야 합니다: -1. MCP 인스펙터에서 "OAuth Configuration" 버튼을 클릭하고 **Redirect URL (자동 입력)** 값을 복사하세요. 예: `http://localhost:6274/oauth/callback` +1. MCP 인스펙터를 열고 "OAuth Configuration" 버튼을 클릭하세요. **Redirect URL (auto-populated)** 값을 복사하세요. 예: `http://localhost:6274/oauth/callback` 2. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인하세요. -3. "Applications" 탭에서 "Create application" 클릭. 페이지 하단에서 "Create app without framework" 클릭. -4. 애플리케이션 정보를 입력하고 "Create application" 클릭: +3. "Applications" 탭에서 "Create application"을 클릭하고, 페이지 하단에서 "Create app without framework"를 클릭하세요. +4. 애플리케이션 정보를 입력한 후 "Create application"을 클릭하세요: - **Select an application type**: "Single-page application" 선택 - **Application name**: 예: "MCP Inspector" -5. "Settings / Redirect URIs" 섹션에 복사한 **Redirect URL (자동 입력)** 값을 붙여넣고, 하단 바에서 "Save changes" 클릭 +5. "Settings / Redirect URIs" 섹션에 복사한 **Redirect URL (auto-populated)** 값을 붙여넣고, 하단 바에서 "Save changes"를 클릭하세요. 6. 상단 카드에서 "App ID" 값을 복사하세요. 7. MCP 인스펙터로 돌아가 "OAuth Configuration"의 "Client ID"에 "App ID" 값을 붙여넣으세요. 8. "Auth Params" 필드에 `{"scope": "openid profile email"}` 값을 입력하세요. 이렇게 하면 Logto가 반환하는 액세스 토큰 (Access token)에 userinfo 엔드포인트 접근에 필요한 스코프가 포함됩니다. @@ -347,21 +358,21 @@ Logto는 아직 동적 클라이언트 등록을 지원하지 않으므로, MCP [Keycloak](https://www.keycloak.org)은 OpenID Connect 프로토콜을 지원하는 오픈소스 아이덴티티 및 접근 관리 솔루션입니다. -Keycloak은 동적 클라이언트 등록을 지원하지만, 클라이언트 등록 엔드포인트가 CORS를 지원하지 않아 대부분의 MCP 클라이언트가 직접 등록할 수 없습니다. 따라서 수동으로 클라이언트를 등록해야 합니다. +Keycloak은 동적 클라이언트 등록을 지원하지만, 클라이언트 등록 엔드포인트가 CORS를 지원하지 않아 대부분의 MCP 클라이언트가 직접 등록할 수 없습니다. 따라서 클라이언트를 수동으로 등록해야 합니다. :::note -Keycloak은 [여러 방식](https://www.keycloak.org/guides#getting-started) (베어메탈, 쿠버네티스 등)으로 설치할 수 있지만, 이 튜토리얼에서는 Docker로 빠르게 설정합니다. +Keycloak은 [여러 방식](https://www.keycloak.org/guides#getting-started) (베어메탈, 쿠버네티스 등)으로 설치할 수 있지만, 이 튜토리얼에서는 Docker를 사용합니다. ::: -Keycloak 인스턴스를 설정하고 구성해봅시다: +Keycloak 인스턴스를 설정하고 구성하려면: -1. [공식 문서](https://www.keycloak.org/getting-started/getting-started-docker)를 참고하여 Docker로 Keycloak 인스턴스 실행: +1. [공식 문서](https://www.keycloak.org/getting-started/getting-started-docker)에 따라 Docker로 Keycloak 인스턴스를 실행하세요: ```bash docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev ``` -2. Keycloak Admin Console (http://localhost:8080/admin)에 접속하여 아래 계정으로 로그인: +2. Keycloak Admin Console (http://localhost:8080/admin)에 접속하여 아래 자격증명으로 로그인하세요: - Username: `admin` - Password: `admin` @@ -378,14 +389,14 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM - "Create new user" 클릭 - 사용자 정보 입력: - Username: `testuser` - - First name, Last name은 임의 값 + - 이름, 성은 임의 값 - "Create" 클릭 - - "Credentials" 탭에서 비밀번호 설정, "Temporary" 해제 + - "Credentials" 탭에서 비밀번호 설정 및 "Temporary" 해제 5. MCP 인스펙터를 클라이언트로 등록: - - MCP 인스펙터에서 "OAuth Configuration" 버튼 클릭, **Redirect URL (자동 입력)** 값 복사 (예: `http://localhost:6274/oauth/callback`) - - Keycloak Admin Console에서 좌측 "Clients" 클릭 + - MCP 인스펙터에서 "OAuth Configuration" 버튼 클릭, **Redirect URL (auto-populated)** 복사 (예: `http://localhost:6274/oauth/callback`) + - Keycloak Admin Console에서 좌측 메뉴 "Clients" 클릭 - "Create client" 클릭 - 클라이언트 정보 입력: - Client type: "OpenID Connect" 선택 @@ -400,28 +411,62 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM - "Save" 클릭 - "Client ID" (`mcp-inspector`) 복사 -6. MCP 인스펙터로 돌아가서: - - "OAuth Configuration"의 "Client ID" 필드에 복사한 Client ID 붙여넣기 +6. MCP 인스펙터에서: + - 복사한 Client ID를 "OAuth Configuration"의 "Client ID" 필드에 붙여넣기 - "Auth Params" 필드에 아래 값 입력: ```json { "scope": "openid profile email" } ``` - + + + +Asgardeo는 표준 API를 통한 동적 클라이언트 등록을 지원하지만, 엔드포인트가 보호되어 있어 필요한 권한의 액세스 토큰이 필요합니다. 이 튜토리얼에서는 Asgardeo 콘솔을 통해 수동으로 클라이언트를 등록합니다. + +:::note +Asgardeo 계정이 없다면 [무료로 가입](https://asgardeo.io)할 수 있습니다. +::: + +아래 단계에 따라 Asgardeo를 MCP 인스펙터에 맞게 설정하세요: + +1. [Asgardeo Console](https://console.asgardeo.io)에 로그인하고 조직을 선택하세요. + +2. 새 애플리케이션 생성: + - **Applications** → **New Application** + - **Single-Page Application** 선택 + - 애플리케이션 이름: `MCP Inspector` 등 입력 + - **Authorized Redirect URLs**에 MCP 인스펙터에서 복사한 **Redirect URL** 붙여넣기 (예: `http://localhost:6274/oauth/callback`) + - **Create** 클릭 + +3. 프로토콜 설정 구성: + - **Protocol** 탭에서: + - 자동 생성된 **Client ID** 복사 + - **Access Token** 섹션에서 `Token Type`을 `JWT`로 변경 + - **Update** 클릭 + +4. MCP 인스펙터에서: + - **OAuth Configuration** 섹션 열기 + - 복사한 **Client ID** 붙여넣기 + - **Auth Params** 필드에 아래 값 입력: + +```json +{ "scope": "openid profile email" } +``` + :::note -이 가이드는 일반적인 OpenID Connect 제공자 통합 안내입니다. 세부 사항은 제공자 문서를 참고하세요. +이 가이드는 일반적인 OpenID Connect 제공자 통합 안내입니다. 구체적인 내용은 제공자 문서를 참고하세요. ::: -OpenID Connect 제공자가 동적 클라이언트 등록을 지원한다면 아래 8번 단계로 바로 이동하여 MCP 인스펙터를 설정하세요. 그렇지 않으면 MCP 인스펙터를 수동으로 클라이언트로 등록해야 합니다: +OpenID Connect 제공자가 동적 클라이언트 등록을 지원한다면 아래 8번 단계로 바로 진행할 수 있습니다. 그렇지 않다면 MCP 인스펙터를 수동으로 클라이언트로 등록해야 합니다: -1. MCP 인스펙터에서 "OAuth Configuration" 버튼 클릭, **Redirect URL (자동 입력)** 값 복사 (예: `http://localhost:6274/oauth/callback`) +1. MCP 인스펙터에서 "OAuth Configuration" 버튼 클릭, **Redirect URL (auto-populated)** 복사 (예: `http://localhost:6274/oauth/callback`) 2. OpenID Connect 제공자 콘솔에 로그인 3. "Applications" 또는 "Clients" 섹션에서 새 애플리케이션/클라이언트 생성 4. 클라이언트 타입이 필요하다면 "Single-page application" 또는 "Public client" 선택 -5. 애플리케이션 생성 후, 리디렉션 URI에 MCP 인스펙터의 **Redirect URL (자동 입력)** 값 붙여넣기 +5. 애플리케이션 생성 후, 리디렉션 URI에 복사한 **Redirect URL (auto-populated)** 붙여넣기 6. 새로 생성된 애플리케이션의 "Client ID" 또는 "Application ID" 복사 7. MCP 인스펙터로 돌아가 "OAuth Configuration"의 "Client ID"에 붙여넣기 8. 표준 OpenID Connect 제공자의 경우, userinfo 엔드포인트 접근에 필요한 스코프를 요청하려면 "Auth Params" 필드에 아래 값 입력: @@ -434,16 +479,16 @@ OpenID Connect 제공자가 동적 클라이언트 등록을 지원한다면 아 :::note -이 가이드는 일반적인 OAuth 2.0 / OAuth 2.1 제공자 통합 안내입니다. 세부 사항은 제공자 문서를 참고하세요. +이 가이드는 일반적인 OAuth 2.0 / OAuth 2.1 제공자 통합 안내입니다. 구체적인 내용은 제공자 문서를 참고하세요. ::: -OAuth 2.0 / OAuth 2.1 제공자가 동적 클라이언트 등록을 지원한다면 아래 8번 단계로 바로 이동하여 MCP 인스펙터를 설정하세요. 그렇지 않으면 MCP 인스펙터를 수동으로 클라이언트로 등록해야 합니다: +OAuth 2.0 / OAuth 2.1 제공자가 동적 클라이언트 등록을 지원한다면 아래 8번 단계로 바로 진행할 수 있습니다. 그렇지 않다면 MCP 인스펙터를 수동으로 클라이언트로 등록해야 합니다: -1. MCP 인스펙터에서 "OAuth Configuration" 버튼 클릭, **Redirect URL (자동 입력)** 값 복사 (예: `http://localhost:6274/oauth/callback`) +1. MCP 인스펙터에서 "OAuth Configuration" 버튼 클릭, **Redirect URL (auto-populated)** 복사 (예: `http://localhost:6274/oauth/callback`) 2. OAuth 2.0 / OAuth 2.1 제공자 콘솔에 로그인 3. "Applications" 또는 "Clients" 섹션에서 새 애플리케이션/클라이언트 생성 4. 클라이언트 타입이 필요하다면 "Single-page application" 또는 "Public client" 선택 -5. 애플리케이션 생성 후, 리디렉션 URI에 MCP 인스펙터의 **Redirect URL (자동 입력)** 값 붙여넣기 +5. 애플리케이션 생성 후, 리디렉션 URI에 복사한 **Redirect URL (auto-populated)** 붙여넣기 6. 새로 생성된 애플리케이션의 "Client ID" 또는 "Application ID" 복사 7. MCP 인스펙터로 돌아가 "OAuth Configuration"의 "Client ID"에 붙여넣기 8. 사용자 아이덴티티 정보 조회를 위한 액세스 토큰 (Access token) 발급 방법은 제공자 문서를 참고하세요. 예를 들어, `profile` 스코프가 필요하다면 "Auth Params" 필드에 아래 값 입력: @@ -457,23 +502,23 @@ OAuth 2.0 / OAuth 2.1 제공자가 동적 클라이언트 등록을 지원한다 ### MCP Auth 설정하기 \{#set-up-mcp-auth} -MCP 서버 프로젝트에서 MCP Auth SDK를 설치하고 인가 (Authorization) 서버 메타데이터를 사용하도록 설정해야 합니다. +MCP 서버 프로젝트에서 MCP Auth SDK를 설치하고, 인가 (Authorization) 서버 메타데이터를 사용하도록 설정해야 합니다. -먼저 `mcpauth` 패키지를 설치하세요: +먼저, `mcpauth` 패키지를 설치하세요: ```bash pip install mcpauth ``` -또는 `uv`, `poetry` 등 원하는 패키지 매니저를 사용하세요. +또는 `uv`나 `poetry` 등 원하는 패키지 매니저를 사용할 수 있습니다. -먼저 `mcp-auth` 패키지를 설치하세요: +먼저, `mcp-auth` 패키지를 설치하세요: ```bash npm install mcp-auth @@ -496,12 +541,21 @@ MCP Auth는 인가 (Authorization) 서버 메타데이터가 필요합니다. -발급자 (Issuer) URL은 Keycloak Admin Console에서 'mcp-realm'의 "Realm settings / Endpoints" 섹션에서 "OpenID Endpoint Configuration" 링크를 클릭해 JSON 문서의 `issuer` 필드에서 확인할 수 있습니다. 예: `http://localhost:8080/realms/mcp-realm` +발급자 (Issuer) URL은 Keycloak Admin Console에서 'mcp-realm'의 "Realm settings / Endpoints" 섹션에서 "OpenID Endpoint Configuration" 링크를 클릭하면 나오는 JSON 문서의 `issuer` 필드에서 확인할 수 있습니다. 예: `http://localhost:8080/realms/mcp-realm` + + + Asgardeo Console에서 생성한 애플리케이션의 **Info** 탭에서 발급자 (Issuer) URL을 확인할 수 있습니다. 예시: + `https://api.asgardeo.io/t//oauth2/token` + + + + + 아래 코드는 인가 (Authorization) 서버가 [userinfo 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)를 지원한다고 가정합니다. 지원하지 않는 경우, 제공자 문서에서 엔드포인트를 확인하고 userinfo 엔드포인트 변수를 올바른 URL로 교체하세요. @@ -520,7 +574,7 @@ MCP Auth는 인가 (Authorization) 서버 메타데이터가 필요합니다. ### MCP 서버 업데이트하기 \{#update-mcp-server} -거의 다 왔습니다! 이제 MCP Auth 라우트와 미들웨어를 적용하고, `whoami` 도구가 실제 사용자 아이덴티티 정보를 반환하도록 MCP 서버를 업데이트합니다. +거의 다 왔습니다! 이제 MCP Auth 라우트와 미들웨어 함수를 적용하고, `whoami` 도구가 실제 사용자 아이덴티티 정보를 반환하도록 MCP 서버를 업데이트할 차례입니다. @@ -571,24 +625,24 @@ app.use(mcpAuth.bearerAuth(verifyToken)); ## 체크포인트: 인증 (Authentication)과 함께 `whoami` 도구 실행하기 \{#checkpoint-run-the-whoami-tool-with-authentication} -MCP 서버를 재시작하고 MCP 인스펙터를 브라우저에서 엽니다. "Connect" 버튼을 클릭하면 인가 (Authorization) 서버의 로그인 페이지로 리디렉션됩니다. +MCP 서버를 재시작하고 브라우저에서 MCP 인스펙터를 엽니다. "Connect" 버튼을 클릭하면 인가 (Authorization) 서버의 로그인 페이지로 리디렉션됩니다. 로그인 후 MCP 인스펙터로 돌아오면, 이전 체크포인트에서 했던 것처럼 `whoami` 도구를 실행하세요. 이번에는 인가 (Authorization) 서버가 반환하는 사용자 아이덴티티 정보가 표시됩니다. -![MCP 인스펙터 whoami 도구 결과](/docs-assets/images/tutorials/whoami/result.png) +![MCP inspector whoami tool result](/docs-assets/images/tutorials/whoami/result.png) :::info -[MCP Auth Python SDK 저장소](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py)에서 MCP 서버(OIDC 버전)의 전체 코드를 확인할 수 있습니다. +MCP 서버 (OIDC 버전)의 전체 코드는 [MCP Auth Python SDK 저장소](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py)를 참고하세요. ::: :::info -[MCP Auth Node.js SDK 저장소](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)에서 MCP 서버(OIDC 버전)의 전체 코드를 확인할 수 있습니다. 이 디렉터리에는 TypeScript 및 JavaScript 버전이 모두 포함되어 있습니다. +MCP 서버 (OIDC 버전)의 전체 코드는 [MCP Auth Node.js SDK 저장소](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)를 참고하세요. 이 디렉터리에는 TypeScript 및 JavaScript 버전이 모두 포함되어 있습니다. ::: @@ -596,16 +650,16 @@ MCP 서버를 재시작하고 MCP 인스펙터를 브라우저에서 엽니다. ## 마무리 (Closing notes) \{#closing-notes} -🎊 축하합니다! 튜토리얼을 성공적으로 완료하셨습니다. 지금까지 한 내용을 요약하면: +🎊 축하합니다! 튜토리얼을 성공적으로 완료하셨습니다. 지금까지 한 일을 요약하면: - `whoami` 도구가 포함된 기본 MCP 서버 설정 - MCP Auth를 사용하여 MCP 서버를 인가 (Authorization) 서버와 통합 -- MCP 인스펙터를 설정하여 사용자 인증 (Authentication) 및 아이덴티티 정보 조회 +- MCP 인스펙터를 구성하여 사용자 인증 (Authentication) 및 아이덴티티 정보 조회 -추가로 다음과 같은 고급 주제도 탐구해보세요: +추가로 다음과 같은 고급 주제도 탐구해 볼 수 있습니다: - 인증 (Authentication) 및 인가 (Authorization)에 [JWT (JSON Web Token)](https://auth.wiki/jwt) 사용 - 접근하는 리소스를 지정하기 위한 [리소스 지표 (Resource indicator, RFC 8707)](https://auth-wiki.logto.io/resource-indicator) 활용 - [역할 기반 접근 제어 (RBAC)](https://auth.wiki/rbac) 또는 [속성 기반 접근 제어 (ABAC)](https://auth.wiki/abac) 등 맞춤형 접근 제어 구현 -MCP Auth를 최대한 활용하려면 다른 튜토리얼과 문서도 꼭 확인해보세요. +MCP Auth를 최대한 활용하려면 다른 튜토리얼과 문서도 꼭 확인해 보세요. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index 1edf49a..9c6d7ca 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 2 -sidebar_label: 'Tutorial: Construa um gerenciador de tarefas' +sidebar_label: 'Tutorial: Construindo um gerenciador de tarefas' --- import TabItem from '@theme/TabItem'; @@ -9,14 +9,14 @@ import Tabs from '@theme/Tabs'; import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; import SetupOidc from './_setup-oidc.mdx'; -# Tutorial: Construa um gerenciador de tarefas +# Tutorial: Construindo um gerenciador de tarefas -Neste tutorial, vamos construir um servidor MCP de gerenciador de tarefas com autenticação e autorização de usuário. +Neste tutorial, vamos construir um servidor MCP de gerenciador de tarefas com autenticação e autorização de usuários. Após concluir este tutorial, você terá: - ✅ Uma compreensão básica de como configurar controle de acesso baseado em papel (RBAC) em seu servidor MCP. -- ✅ Um servidor MCP que pode gerenciar listas de tarefas pessoais. +- ✅ Um servidor MCP capaz de gerenciar listas de tarefas pessoais. :::note Antes de começar, recomendamos fortemente que você faça primeiro o [tutorial Quem sou eu](./whoami) caso não esteja familiarizado com o servidor MCP e OAuth 2. @@ -26,7 +26,7 @@ Antes de começar, recomendamos fortemente que você faça primeiro o [tutorial O tutorial envolverá os seguintes componentes: -- **Servidor MCP**: Um servidor MCP simples que usa os SDKs oficiais do MCP para lidar com requisições, com um serviço integrado de Tarefas para gerenciar os itens de tarefas do usuário. +- **Servidor MCP**: Um servidor MCP simples que utiliza os SDKs oficiais do MCP para lidar com requisições, com um serviço integrado de Tarefas para gerenciar os itens de tarefas do usuário. - **MCP inspector**: Uma ferramenta visual de testes para servidores MCP. Também atua como um cliente OAuth / OIDC para iniciar o fluxo de autorização e recuperar tokens de acesso. - **Servidor de autorização**: Um provedor OAuth 2.1 ou OpenID Connect que gerencia identidades de usuários e emite tokens de acesso. @@ -35,7 +35,7 @@ Aqui está um diagrama de alto nível da interação entre esses componentes: ```mermaid sequenceDiagram participant Client as MCP Inspector - participant Server as MCP Server + participant Server as Servidor MCP participant Auth as Servidor de Autorização Client->>Server: Solicitar operação de tarefa @@ -60,9 +60,9 @@ Para implementar [controle de acesso baseado em papel (RBAC)](https://auth.wiki/ -[Logto](https://logto.io) oferece suporte a RBAC por meio de seus recursos de API (conforme [RFC 8707: Indicadores de Recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) e funcionalidades de papéis. Veja como configurar: +[Logto](https://logto.io) fornece suporte a RBAC por meio de seus recursos de API (conforme [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) e funcionalidades de papéis. Veja como configurar: -1. Faça login no [Logto Console](https://cloud.logto.io) (ou em seu Logto Console auto-hospedado) +1. Faça login no [Logto Console](https://cloud.logto.io) (ou no seu Logto Console auto-hospedado) 2. Crie recurso de API e escopos: @@ -88,6 +88,45 @@ Para implementar [controle de acesso baseado em papel (RBAC)](https://auth.wiki/ Os escopos serão incluídos na reivindicação `scope` do token de acesso JWT como uma string separada por espaços. + + + [Asgardeo](https://wso2.com/asgardeo) suporta Controle de Acesso Baseado em Papel (RBAC) e autorização detalhada usando recursos de API e escopos. Veja como configurar: + + 1. Faça login no [Asgardeo Console](https://console.asgardeo.io) + + 2. Defina seu recurso de API e escopos: + - Vá para **API Resources** + - Clique em **"New API Resource"** + - Defina o **Identifier** como `https://todo.mcp-server.app` (ou a URL desejada) + - O **Display Name** pode ser `Todo Manager` + - Adicione os seguintes escopos: + - `create:todos` : "Criar novos itens de tarefa" + - `read:todos` : "Ler todos os itens de tarefa" + - `delete:todos` : "Excluir qualquer item de tarefa" + - Crie o recurso + + 3. Crie papéis: + - Use **User Management > Roles** para criar papéis e atribuir escopos diretamente. + - Clique em **New Role** + - Forneça o nome do papel (ex: `Admin` ou `User`) na seção **Basic Details** + - O público do papel deve ser `Application` e selecione `MCP Inspector Application` como **Assigned Application** + - Na seção **Permission Selection**, escolha o recurso de API criado anteriormente (ex: `Todo Manager`) + - Selecione os escopos que deseja atribuir a este papel (ex: `create:todos`, `read:todos`, `delete:todos`) + - Clique em **Finish** para criar o papel + + Se você já criou o aplicativo + - Navegue até **Application > MCP Inspector Application > Roles tab** + - Selecione **Application Role** como tipo de público, então clique em **New Role** + - Crie um papel `Admin` e anexe os três escopos + - Crie um papel `User` e anexe apenas o escopo `create:todos` + + 4. Atribua papéis aos usuários: + - Vá para **User Management > Roles** + - Selecione o papel criado (ex: `Admin` ou `User`) e vá para a aba **Users** + - Selecione **Assign User** e escolha os usuários para atribuir este papel e salve. + + Os escopos serão incluídos na reivindicação `scope` do token de acesso JWT como uma string separada por espaços. + @@ -102,7 +141,7 @@ Consulte a documentação do seu provedor para detalhes específicos sobre: - Como definir e gerenciar escopos - Como os escopos são incluídos no token de acesso -- Quaisquer recursos adicionais de RBAC, como gerenciamento de papéis +- Quaisquer recursos adicionais de RBAC como gerenciamento de papéis @@ -115,7 +154,7 @@ Quando seu servidor MCP recebe uma requisição, ele precisa: 2. Extrair os escopos do token validado 3. Verificar se o token possui os escopos necessários para a operação solicitada -Por exemplo, se um usuário deseja criar um novo item de tarefa, seu token de acesso deve incluir o escopo `create:todos`. Veja como funciona o fluxo: +Por exemplo, se um usuário deseja criar um novo item de tarefa, seu token de acesso deve incluir o escopo `create:todos`. Veja como o fluxo funciona: ```mermaid sequenceDiagram @@ -123,7 +162,7 @@ sequenceDiagram participant MCP Server participant Auth Server - Client->>MCP Server: Solicitação com token de acesso + Client->>MCP Server: Requisição com token de acesso alt Validação JWT MCP Server->>Auth Server: Buscar JWKS @@ -131,7 +170,7 @@ sequenceDiagram MCP Server->>MCP Server: Validar JWT localmente else Introspecção de Token MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: Retornar informações do token
(ativo, escopo, etc.) + Auth Server-->>MCP Server: Retornar informações do token
(active, scope, etc.) end MCP Server->>MCP Server: Extrair & verificar escopos @@ -143,16 +182,16 @@ sequenceDiagram end ``` -### Registro Dinâmico de Cliente \{#dynamic-client-registration} +### Registro dinâmico de cliente \{#dynamic-client-registration} -O Registro Dinâmico de Cliente não é necessário para este tutorial, mas pode ser útil se você quiser automatizar o processo de registro do cliente MCP com seu servidor de autorização. Veja [Registro Dinâmico de Cliente é necessário?](../../provider-list.mdx#is-dcr-required) para mais detalhes. +O Registro Dinâmico de Cliente não é necessário para este tutorial, mas pode ser útil se você quiser automatizar o processo de registro do cliente MCP com seu servidor de autorização. Veja [O Registro Dinâmico de Cliente é necessário?](../../provider-list.mdx#is-dcr-required) para mais detalhes. -## Entenda RBAC no gerenciador de tarefas \{#understand-rbac-in-todo-manager} +## Entenda o RBAC no gerenciador de tarefas \{#understand-rbac-in-todo-manager} -Para fins de demonstração, implementaremos um sistema simples de controle de acesso baseado em papel (RBAC) em nosso servidor MCP de gerenciador de tarefas. Isso mostrará os princípios básicos do RBAC mantendo a implementação direta. +Para fins de demonstração, implementaremos um sistema simples de controle de acesso baseado em papel (RBAC) em nosso servidor MCP de gerenciador de tarefas. Isso mostrará os princípios básicos do RBAC mantendo a implementação simples. :::note -Embora este tutorial demonstre o gerenciamento de escopos baseado em RBAC, é importante observar que nem todos os provedores de autenticação implementam o gerenciamento de escopos por meio de papéis. Alguns provedores podem ter suas próprias implementações e mecanismos únicos para gerenciar controle de acesso e permissões. +Embora este tutorial demonstre o gerenciamento de escopos baseado em RBAC, é importante observar que nem todos os provedores de autenticação implementam o gerenciamento de escopos por meio de papéis. Alguns provedores podem ter suas próprias implementações e mecanismos exclusivos para gerenciar controle de acesso e permissões. ::: ### Ferramentas e escopos \{#tools-and-scopes} @@ -178,8 +217,8 @@ Definiremos dois papéis com diferentes níveis de acesso: | Admin | ✅ | ✅ | ✅ | | User | ✅ | | | -- **User**: Um usuário comum que pode criar itens de tarefa e visualizar ou excluir apenas suas próprias tarefas -- **Admin**: Um administrador que pode criar, visualizar e excluir todos os itens de tarefa, independentemente da propriedade +- **User**: Um usuário comum que pode criar tarefas e visualizar ou excluir apenas suas próprias tarefas +- **Admin**: Um administrador que pode criar, visualizar e excluir todas as tarefas, independentemente da autoria ### Propriedade do recurso \{#resource-ownership} @@ -188,14 +227,14 @@ Embora a tabela de permissões acima mostre os escopos explícitos atribuídos a - **Usuários** não possuem os escopos `read:todos` ou `delete:todos`, mas ainda podem: - Ler seus próprios itens de tarefa - Excluir seus próprios itens de tarefa -- **Admins** possuem permissões totais (`read:todos` e `delete:todos`), permitindo que: - - Visualizem todos os itens de tarefa no sistema - - Excluam qualquer item de tarefa, independentemente da propriedade +- **Admins** possuem permissões totais (`read:todos` e `delete:todos`), permitindo: + - Visualizar todos os itens de tarefa no sistema + - Excluir qualquer item de tarefa, independentemente da autoria Isso demonstra um padrão comum em sistemas RBAC onde a propriedade do recurso concede permissões implícitas aos usuários para seus próprios recursos, enquanto papéis administrativos recebem permissões explícitas para todos os recursos. :::tip Saiba mais -Para se aprofundar nos conceitos e melhores práticas de RBAC, confira [Dominando RBAC: Um Exemplo Abrangente do Mundo Real](https://blog.logto.io/mastering-rbac). +Para se aprofundar em conceitos e boas práticas de RBAC, confira [Dominando RBAC: Um Exemplo Abrangente do Mundo Real](https://blog.logto.io/mastering-rbac). ::: ## Configure a autorização em seu provedor \{#configure-authorization-in-your-provider} @@ -205,14 +244,14 @@ Para implementar o sistema de controle de acesso que descrevemos anteriormente, -[Logto](https://logto.io) oferece suporte a RBAC por meio de recursos de API e funcionalidades de papéis. Veja como configurar: +[Logto](https://logto.io) fornece suporte a RBAC por meio de seus recursos de API e funcionalidades de papéis. Veja como configurar: -1. Faça login no [Logto Console](https://cloud.logto.io) (ou em seu Logto Console auto-hospedado) +1. Faça login no [Logto Console](https://cloud.logto.io) (ou no seu Logto Console auto-hospedado) 2. Crie recurso de API e escopos: - Vá para "Recursos de API" - - Crie um novo recurso de API chamado "Gerenciador de Tarefas" e use `https://todo.mcp-server.app` (para demonstração) como indicador. + - Crie um novo recurso de API chamado "Gerenciador de Tarefas" usando `https://todo.mcp-server.app` (para demonstração) como indicador. - Crie os seguintes escopos: - `create:todos`: "Criar novos itens de tarefa" - `read:todos`: "Ler todos os itens de tarefa" @@ -233,7 +272,7 @@ Para implementar o sistema de controle de acesso que descrevemos anteriormente, - Selecione um usuário - Atribua papéis ao usuário na aba "Papéis" -:::tip Gerenciamento de Papéis Programático +:::tip Gerenciamento programático de papéis Você também pode usar a [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) do Logto para gerenciar papéis de usuários programaticamente. Isso é especialmente útil para automação de gerenciamento de usuários ou ao construir painéis administrativos. ::: @@ -242,12 +281,12 @@ Ao solicitar um token de acesso, o Logto incluirá os escopos na reivindicação -No [Keycloak](https://www.keycloak.org), você pode configurar as permissões necessárias usando escopos de cliente: +No [Keycloak](https://www.keycloak.org), você pode configurar as permissões necessárias usando client scopes: -1. Crie escopos de cliente: +1. Crie client scopes: - No seu realm, vá para "Client scopes" - - Crie três novos escopos de cliente: + - Crie três novos client scopes: - `create:todos` - `read:todos` - `delete:todos` @@ -255,18 +294,66 @@ No [Keycloak](https://www.keycloak.org), você pode configurar as permissões ne 2. Configure o cliente: - Vá para as configurações do seu cliente - - Na aba "Client scopes", adicione todos os escopos que você criou + - Na aba "Client scopes", adicione todos os escopos criados - Certifique-se de que o token mapper está configurado para incluir escopos 3. Opcional: Use papéis para facilitar o gerenciamento - - Se preferir gerenciamento baseado em papel: + - Se preferir gerenciamento baseado em papéis: - Crie papéis de realm para diferentes níveis de acesso - Mapeie escopos para papéis - Atribua papéis aos usuários - - Caso contrário, você pode atribuir escopos diretamente aos usuários ou por permissões no nível do cliente + - Caso contrário, você pode atribuir escopos diretamente aos usuários ou via permissões de nível de cliente O Keycloak incluirá os escopos concedidos na reivindicação `scope` do token de acesso. + + + +[Asgardeo](https://wso2.com/asgardeo) suporta Controle de Acesso Baseado em Papel (RBAC) e autorização detalhada usando recursos de API e escopos. Veja como configurar: + +1. Faça login no [Asgardeo Console](https://console.asgardeo.io) + +2. Defina seu recurso de API e escopos: + - Vá para **API Resources** + - Clique em **"New API Resource"** + - Defina o **Identifier** como `https://todo.mcp-server.app` (ou a URL desejada) + - O **Display Name** pode ser `Todo Manager` + - Adicione os seguintes escopos: + - `create:todos` : "Criar novos itens de tarefa" + - `read:todos` : "Ler todos os itens de tarefa" + - `delete:todos` : "Excluir qualquer item de tarefa" + - Crie o recurso + +3. Crie papéis: + - Use **User Management > Roles** para criar papéis e atribuir escopos diretamente. + - Clique em **New Role** + - Forneça o nome do papel (ex: `Admin` ou `User`) na seção **Basic Details** + - O público do papel deve ser `Application` e selecione `MCP Inspector Application` como **Assigned Application** + - Na seção **Permission Selection**, escolha o recurso de API criado anteriormente (ex: `Todo Manager`) + - Selecione os escopos que deseja atribuir a este papel (ex: `create:todos`, `read:todos`, `delete:todos`) + - Clique em **Finish** para criar o papel + + Se você já criou o aplicativo + - Navegue até **Application > MCP Inspector Application > Roles tab** + - Selecione **Application Role** como tipo de público, então clique em **New Role** + - Crie um papel `Admin` e anexe os três escopos + - Crie um papel `User` e anexe apenas o escopo `create:todos` + +4. Atribua papéis aos usuários: + - Vá para **User Management > Roles** + - Selecione o papel criado (ex: `Admin` ou `User`) e vá para a aba **Users** + - Selecione **Assign User** e escolha os usuários para atribuir este papel e salve. + +Os escopos serão incluídos na reivindicação `scope` do token de acesso JWT como uma string separada por espaços. +Após configurar seu servidor de autorização, os usuários receberão tokens de acesso contendo seus escopos concedidos. O servidor MCP usará esses escopos para determinar: + +Se um usuário pode criar novas tarefas (`create:todos`) +Se um usuário pode visualizar todas as tarefas (`read:todos`) ou apenas as suas +Se um usuário pode excluir qualquer tarefa (`delete:todos`) ou apenas as suas + +Para mais detalhes sobre a configuração do Asgardeo, consulte: +- [Guia de Recursos de API](https://wso2.com/asgardeo/docs/guides/authorization/api-authorization) +- [Gerenciamento de Papéis](https://wso2.com/asgardeo/docs/guides/users/manage-roles) @@ -286,11 +373,11 @@ Para provedores OAuth 2.0 ou OpenID Connect, você precisará configurar os esco 3. Atribua permissões: - Use a interface do seu provedor para conceder os escopos apropriados aos usuários - - Alguns provedores podem suportar gerenciamento baseado em papel, enquanto outros podem usar atribuições diretas de escopos + - Alguns provedores podem suportar gerenciamento baseado em papéis, enquanto outros podem usar atribuições diretas de escopos - Consulte a documentação do seu provedor para a abordagem recomendada :::tip -A maioria dos provedores incluirá os escopos concedidos na reivindicação `scope` do token de acesso. O formato normalmente é uma string de escopos separados por espaço. +A maioria dos provedores incluirá os escopos concedidos na reivindicação `scope` do token de acesso. O formato normalmente é uma string separada por espaços dos valores de escopo. ::: @@ -299,8 +386,8 @@ A maioria dos provedores incluirá os escopos concedidos na reivindicação `sco Após configurar seu servidor de autorização, os usuários receberão tokens de acesso contendo seus escopos concedidos. O servidor MCP usará esses escopos para determinar: - Se um usuário pode criar novas tarefas (`create:todos`) -- Se um usuário pode visualizar todas as tarefas (`read:todos`) ou apenas as suas próprias -- Se um usuário pode excluir qualquer tarefa (`delete:todos`) ou apenas as suas próprias +- Se um usuário pode visualizar todas as tarefas (`read:todos`) ou apenas as suas +- Se um usuário pode excluir qualquer tarefa (`delete:todos`) ou apenas as suas ## Configure o servidor MCP \{#set-up-the-mcp-server} @@ -332,13 +419,13 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -Estamos usando TypeScript em nossos exemplos, pois o Node.js v22.6.0+ suporta execução nativa de TypeScript usando a flag `--experimental-strip-types`. Se estiver usando JavaScript, o código será semelhante - apenas certifique-se de estar usando Node.js v22.6.0 ou superior. Veja a documentação do Node.js para detalhes. +Estamos usando TypeScript em nossos exemplos pois o Node.js v22.6.0+ suporta execução nativa de TypeScript usando a flag `--experimental-strip-types`. Se estiver usando JavaScript, o código será semelhante - apenas certifique-se de estar usando Node.js v22.6.0 ou superior. Veja a documentação do Node.js para detalhes. ::: -### Instale o SDK MCP e dependências \{#install-the-mcp-sdk-and-dependencies} +### Instale o MCP SDK e dependências \{#install-the-mcp-sdk-and-dependencies} @@ -381,17 +468,17 @@ mcp = FastMCP("Gerenciador de Tarefas") @mcp.tool() def create_todo(content: str) -> dict[str, Any]: """Criar uma nova tarefa.""" - return {"error": "Não implementado"} + return {"error": "Not implemented"} @mcp.tool() def get_todos() -> dict[str, Any]: """Listar todas as tarefas.""" - return {"error": "Não implementado"} + return {"error": "Not implemented"} @mcp.tool() def delete_todo(id: str) -> dict[str, Any]: """Excluir uma tarefa pelo id.""" - return {"error": "Não implementado"} + return {"error": "Not implemented"} app = Starlette( routes=[Mount('/', app=mcp.sse_app())] @@ -431,19 +518,19 @@ const server = new McpServer({ server.tool('create-todo', 'Criar uma nova tarefa', { content: z.string() }, async ({ content }) => { return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Não implementado' }) }], + content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], }; }); server.tool('get-todos', 'Listar todas as tarefas', async () => { return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Não implementado' }) }], + content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], }; }); server.tool('delete-todo', 'Excluir uma tarefa pelo id', { id: z.string() }, async ({ id }) => { return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Não implementado' }) }], + content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], }; }); @@ -470,7 +557,7 @@ app.post('/messages', async (req, res) => { if (transport) { await transport.handlePostMessage(req, res, req.body); } else { - res.status(400).send('Nenhum transporte encontrado para sessionId'); + res.status(400).send('No transport found for sessionId'); } }); @@ -494,7 +581,7 @@ Agora que temos o servidor MCP rodando, podemos usar o MCP inspector para ver se Devido à limitação da implementação atual, fizemos um fork do [MCP inspector](https://github.com/mcp-auth/inspector) para torná-lo mais flexível e escalável para autenticação e autorização. Também enviamos um pull request para o repositório original para incluir nossas alterações. -Para rodar o MCP inspector, você pode usar o seguinte comando (Node.js é necessário): +Para rodar o MCP inspector, use o seguinte comando (Node.js é necessário): ```bash git clone https://github.com/mcp-auth/inspector.git @@ -519,8 +606,8 @@ Agora você pode clicar no botão "Connect" para ver se o MCP inspector consegue 1. No menu superior do MCP inspector, clique na aba "Tools". 2. Clique no botão "List Tools". 3. Você deve ver as ferramentas `create-todo`, `get-todos` e `delete-todo` listadas na página. Clique para abrir os detalhes da ferramenta. -4. Você deve ver o botão "Run Tool" no lado direito. Clique nele e insira os parâmetros necessários para executar a ferramenta. -5. Você verá o resultado da ferramenta com a resposta JSON `{"error": "Não implementado"}`. +4. Você verá o botão "Run Tool" no lado direito. Clique nele e insira os parâmetros necessários para executar a ferramenta. +5. Você verá o resultado da ferramenta com a resposta JSON `{"error": "Not implemented"}`. ![Primeira execução do MCP inspector](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) @@ -531,34 +618,34 @@ Para concluir esta seção, há várias considerações a serem feitas:
**A URL do emissor do seu servidor de autorização** -Geralmente é a URL base do seu servidor de autorização, como `https://auth.example.com`. Alguns provedores podem ter um caminho como `https://example.logto.app/oidc`, então verifique a documentação do seu provedor. +Normalmente é a URL base do seu servidor de autorização, como `https://auth.example.com`. Alguns provedores podem ter um caminho como `https://example.logto.app/oidc`, então verifique a documentação do seu provedor.
**Como recuperar os metadados do servidor de autorização** -- Se seu servidor de autorização estiver em conformidade com o [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) ou [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), você pode usar as utilidades integradas do MCP Auth para buscar os metadados automaticamente. -- Se seu servidor de autorização não estiver em conformidade com esses padrões, você precisará especificar manualmente a URL dos metadados ou endpoints na configuração do servidor MCP. Consulte a documentação do seu provedor para os endpoints específicos. +- Se seu servidor de autorização estiver em conformidade com [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) ou [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), você pode usar as utilidades integradas do MCP Auth para buscar os metadados automaticamente. +- Se seu servidor de autorização não estiver em conformidade com esses padrões, será necessário especificar manualmente a URL dos metadados ou endpoints na configuração do servidor MCP. Consulte a documentação do seu provedor para os endpoints específicos.
**Como registrar o MCP inspector como cliente em seu servidor de autorização** -- Se seu servidor de autorização suporta [Registro Dinâmico de Cliente](https://datatracker.ietf.org/doc/html/rfc7591), você pode pular esta etapa, pois o MCP inspector se registrará automaticamente como cliente. -- Se seu servidor de autorização não suporta Registro Dinâmico de Cliente, você precisará registrar manualmente o MCP inspector como cliente em seu servidor de autorização. +- Se seu servidor de autorização suporta [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), você pode pular esta etapa pois o MCP inspector se registrará automaticamente como cliente. +- Se seu servidor de autorização não suporta Dynamic Client Registration, será necessário registrar manualmente o MCP inspector como cliente em seu servidor de autorização.
-**Entenda os parâmetros de solicitação de token** +**Entenda os parâmetros de requisição de token** -Ao solicitar tokens de acesso de diferentes servidores de autorização, você encontrará várias abordagens para especificar o recurso alvo e as permissões. Aqui estão os principais padrões: +Ao solicitar tokens de acesso de diferentes servidores de autorização, você encontrará várias abordagens para especificar o recurso alvo e permissões. Aqui estão os principais padrões: - **Baseado em indicador de recurso**: - - Usa o parâmetro `resource` para especificar a API alvo (veja [RFC 8707: Indicadores de Recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) + - Usa o parâmetro `resource` para especificar a API alvo (veja [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) - Comum em implementações modernas de OAuth 2.0 - Exemplo de requisição: ```json @@ -591,11 +678,11 @@ Ao solicitar tokens de acesso de diferentes servidores de autorização, você e } ``` - Frequentemente usa escopos prefixados para namespacing de permissões - - Comum em implementações mais simples de OAuth 2.0 + - Comum em implementações OAuth 2.0 mais simples -:::tip Melhores Práticas +:::tip Boas práticas -- Verifique a documentação do seu provedor para os parâmetros suportados +- Verifique a documentação do seu provedor para parâmetros suportados - Alguns provedores suportam múltiplas abordagens simultaneamente - Indicadores de recurso fornecem melhor segurança por restrição de audiência - Considere usar indicadores de recurso quando disponíveis para melhor controle de acesso @@ -612,19 +699,53 @@ Embora cada provedor possa ter requisitos específicos, os passos a seguir irão Integrar o gerenciador de tarefas com o [Logto](https://logto.io) é simples, pois é um provedor OpenID Connect que suporta indicadores de recurso e escopos, permitindo proteger sua API de tarefas com `https://todo.mcp-server.app` como indicador de recurso. -Como o Logto ainda não suporta Registro Dinâmico de Cliente, você precisará registrar manualmente o MCP inspector como cliente em seu tenant Logto: +Como o Logto ainda não suporta Dynamic Client Registration, será necessário registrar manualmente o MCP inspector como cliente em seu tenant Logto: -1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. -2. Faça login no [Logto Console](https://cloud.logto.io) (ou em seu Logto Console auto-hospedado). +1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor de **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. +2. Faça login no [Logto Console](https://cloud.logto.io) (ou no seu Logto Console auto-hospedado). 3. Navegue até a aba "Applications", clique em "Create application". No final da página, clique em "Create app without framework". 4. Preencha os detalhes do aplicativo e clique em "Create application": - **Selecione um tipo de aplicativo**: Escolha "Single-page application". - - **Nome do aplicativo**: Insira um nome para seu aplicativo, por exemplo, "MCP Inspector". -5. Na seção "Settings / Redirect URIs", cole o valor **Redirect URL (auto-populated)** copiado do MCP inspector. Depois clique em "Save changes" na barra inferior. -6. No card superior, você verá o valor "App ID". Copie-o. + - **Nome do aplicativo**: Insira um nome, ex: "MCP Inspector". +5. Na seção "Settings / Redirect URIs", cole o valor de **Redirect URL (auto-populated)** copiado do MCP inspector. Clique em "Save changes" na barra inferior. +6. No cartão superior, você verá o valor "App ID". Copie-o. 7. Volte ao MCP inspector e cole o valor "App ID" na seção "OAuth Configuration" em "Client ID". 8. Insira o valor `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` no campo "Auth Params". Isso garantirá que o token de acesso retornado pelo Logto contenha os escopos necessários para acessar o gerenciador de tarefas. + + + + Embora o Asgardeo suporte registro dinâmico de cliente via API padrão, o endpoint é protegido e requer um token de acesso com as permissões necessárias. Neste tutorial, registraremos o cliente manualmente pelo Console do Asgardeo. + + :::note + Se você não possui uma conta Asgardeo, pode [criar gratuitamente](https://asgardeo.io). + ::: + + Siga estes passos para configurar o Asgardeo para o MCP Inspector: + + 1. Faça login no [Asgardeo Console](https://console.asgardeo.io) e selecione sua organização. + + 2. Crie um novo aplicativo: + - Vá para **Applications** → **New Application** + - Escolha **Single-Page Application** + - Insira um nome como `MCP Inspector` + - No campo **Authorized Redirect URLs**, cole a **Redirect URL** copiada do MCP Inspector (ex: `http://localhost:6274/oauth/callback`) + - Clique em **Create** + + 3. Configure as configurações de protocolo: + - Na aba **Protocol**: + - Copie o **Client ID** gerado automaticamente. + - Certifique-se de trocar para `JWT` em `Token Type` na seção **Access Token** + - Clique em **Update** + + 4. No MCP Inspector: + - Abra a seção **OAuth Configuration** + - Cole o **Client ID** copiado + - Insira o seguinte no campo **Auth Params** para solicitar os escopos necessários: + + ```json + { "scope": "openid profile email" } + ``` @@ -632,17 +753,17 @@ Como o Logto ainda não suporta Registro Dinâmico de Cliente, você precisará Este é um guia genérico de integração com provedores OAuth 2.0 / OpenID Connect. Ambos seguem passos semelhantes, pois OIDC é construído sobre OAuth 2.0. Consulte a documentação do seu provedor para detalhes específicos. ::: -Se seu provedor suporta Registro Dinâmico de Cliente, você pode ir direto ao passo 8 abaixo para configurar o MCP inspector; caso contrário, será necessário registrar manualmente o MCP inspector como cliente: +Se seu provedor suporta Dynamic Client Registration, você pode ir direto ao passo 8 abaixo para configurar o MCP inspector; caso contrário, será necessário registrar manualmente o MCP inspector como cliente: -1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. +1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor de **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. 2. Faça login no console do seu provedor. -3. Navegue até a seção "Applications" ou "Clients" e crie um novo aplicativo ou cliente. +3. Navegue até a seção "Applications" ou "Clients", então crie um novo aplicativo ou cliente. 4. Se seu provedor exigir um tipo de cliente, selecione "Single-page application" ou "Public client". -5. Após criar o aplicativo, será necessário configurar o redirect URI. Cole o valor **Redirect URL (auto-populated)** copiado do MCP inspector. +5. Após criar o aplicativo, será necessário configurar a URI de redirecionamento. Cole o valor de **Redirect URL (auto-populated)** copiado do MCP inspector. 6. Encontre o "Client ID" ou "Application ID" do novo aplicativo e copie-o. @@ -684,25 +805,34 @@ npm install mcp-auth -O MCP Auth requer os metadados do servidor de autorização para poder inicializar. Dependendo do seu provedor: +O MCP Auth requer os metadados do servidor de autorização para inicializar. Dependendo do seu provedor: -A URL do emissor pode ser encontrada na página de detalhes do seu aplicativo no Logto Console, na seção "Endpoints & Credentials / Issuer endpoint". Deve ser algo como `https://meu-projeto.logto.app/oidc`. +A URL do emissor pode ser encontrada na página de detalhes do seu aplicativo no Logto Console, na seção "Endpoints & Credentials / Issuer endpoint". Deve ser algo como `https://my-project.logto.app/oidc`. + + + Você pode encontrar a URL do emissor no Console do Asgardeo. Navegue até o aplicativo criado e abra a aba **Info**. O campo **Issuer** será exibido lá e deve ser algo como: + `https://api.asgardeo.io/t//oauth2/token` + + + + + Para provedores OAuth 2.0, você precisará: 1. Verificar a documentação do seu provedor para a URL do servidor de autorização (geralmente chamada de issuer URL ou base URL) -2. Alguns provedores podem expor isso em `https://{seu-dominio}/.well-known/oauth-authorization-server` -3. Procurar no console administrativo do seu provedor em configurações OAuth/API +2. Alguns provedores podem expor isso em `https://{your-domain}/.well-known/oauth-authorization-server` +3. Procure no console administrativo do seu provedor em configurações OAuth/API @@ -747,7 +877,7 @@ const mcpAuth = new MCPAuth({ ### Atualize o servidor MCP \{#update-mcp-server} -Estamos quase lá! É hora de atualizar o servidor MCP para aplicar a rota e middleware do MCP Auth, depois implementar o controle de acesso baseado em permissões para as ferramentas do gerenciador de tarefas com base nos escopos do usuário. +Estamos quase lá! É hora de atualizar o servidor MCP para aplicar a rota e middleware do MCP Auth, e então implementar o controle de acesso baseado em permissões para as ferramentas do gerenciador de tarefas com base nos escopos do usuário. @@ -759,7 +889,7 @@ def create_todo(content: str) -> dict[str, Any]: return ( mcp_auth.auth_info.scopes if mcp_auth.auth_info # Isso será preenchido pelo middleware Bearer auth - else {"error": "Não autenticado"} + else {"error": "Not authenticated"} ) # ... @@ -786,7 +916,7 @@ server.tool( async ({ content, authInfo }) => { return { content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Não autenticado' }) }, + { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Not authenticated' }) }, ], }; } @@ -982,7 +1112,7 @@ export class TodoService { -então na camada de ferramentas, vamos determinar se as operações são permitidas com base nos escopos do usuário: +em seguida, na camada de ferramentas, vamos determinar se as operações são permitidas com base nos escopos do usuário: @@ -997,7 +1127,7 @@ def assert_user_id(auth_info: Optional[dict]) -> str: """Extrai e valida o ID do usuário do auth info.""" subject = auth_info.get('subject') if auth_info else None if not subject: - raise ValueError('Informação de autenticação inválida') + raise ValueError('Invalid auth info') return subject def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: @@ -1011,7 +1141,7 @@ todo_service = TodoService() def create_todo(content: str) -> dict[str, Any]: """Criar uma nova tarefa. - Apenas usuários com o escopo 'create:todos' podem criar tarefas. + Apenas usuários com escopo 'create:todos' podem criar tarefas. """ # Obter informações de autenticação auth_info = mcp_auth.auth_info @@ -1052,7 +1182,7 @@ const todoService = new TodoService(); const assertUserId = (authInfo?: AuthInfo) => { const { subject } = authInfo ?? {}; - assert(subject, 'Informação de autenticação inválida'); + assert(subject, 'Invalid auth info'); return subject; }; @@ -1071,7 +1201,7 @@ server.tool( const userId = assertUserId(authInfo); /** - * Apenas usuários com o escopo 'create:todos' podem criar tarefas + * Apenas usuários com escopo 'create:todos' podem criar tarefas */ if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { throw new MCPAuthBearerAuthError('missing_required_scopes'); @@ -1101,19 +1231,19 @@ Depois de fazer login e retornar ao MCP inspector, repita as ações do checkpoi - Se você estiver logado como **User** (com apenas o escopo `create:todos`): - - Você pode criar novas tarefas usando a ferramenta `create-todo` - - Você só poderá visualizar e excluir suas próprias tarefas + - Pode criar novas tarefas usando a ferramenta `create-todo` + - Só pode visualizar e excluir suas próprias tarefas - Não poderá ver ou excluir tarefas de outros usuários - Se estiver logado como **Admin** (com todos os escopos: `create:todos`, `read:todos`, `delete:todos`): - - Você pode criar novas tarefas + - Pode criar novas tarefas - Pode visualizar todas as tarefas do sistema usando a ferramenta `get-todos` - Pode excluir qualquer tarefa usando a ferramenta `delete-todo`, independentemente de quem a criou Você pode testar esses diferentes níveis de permissão: 1. Saindo da sessão atual (clique no botão "Disconnect" no MCP inspector) -2. Fazendo login com outra conta de usuário que tenha papéis/permissões diferentes +2. Fazendo login com outra conta de usuário com papéis/permissões diferentes 3. Tentando as mesmas ferramentas novamente para observar como o comportamento muda de acordo com as permissões do usuário Isso demonstra como o controle de acesso baseado em papel (RBAC) funciona na prática, onde diferentes usuários têm diferentes níveis de acesso à funcionalidade do sistema. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx index 2c5c65d..6b363fc 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx @@ -22,7 +22,7 @@ Após concluir este tutorial, você terá: O tutorial envolverá os seguintes componentes: -- **Servidor MCP (MCP server)**: Um servidor MCP simples que utiliza os SDKs oficiais do MCP para lidar com requisições. +- **Servidor MCP**: Um servidor MCP simples que utiliza os SDKs oficiais do MCP para lidar com requisições. - **MCP inspector**: Uma ferramenta visual de testes para servidores MCP. Também atua como um cliente OAuth / OIDC para iniciar o fluxo de autorização e recuperar tokens de acesso. - **Servidor de autorização (Authorization server)**: Um provedor OAuth 2.1 ou OpenID Connect que gerencia identidades de usuários e emite tokens de acesso. @@ -32,7 +32,7 @@ Aqui está um diagrama de alto nível da interação entre esses componentes: sequenceDiagram participant Client as MCP Inspector participant Server as Servidor MCP - participant Auth as Servidor de Autorização + participant Auth as Servidor de autorização Client->>Server: Solicitar ferramenta `whoami` Server->>Client: Retornar 401 Não autorizado @@ -56,25 +56,36 @@ Para concluir este tutorial, seu servidor de autorização deve oferecer uma API -[Logto](https://logto.io) é um provedor OpenID Connect que suporta o endpoint padrão [userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. +[Logto](https://logto.io) é um provedor OpenID Connect que suporta o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) padrão para recuperar informações de identidade do usuário. -Para buscar um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: `openid` e `profile`. Você pode continuar lendo, pois abordaremos a configuração de escopos mais adiante. +Para obter um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: `openid` e `profile`. Você pode continuar lendo, pois abordaremos a configuração de escopos mais adiante. -[Keycloak](https://www.keycloak.org) é uma solução open-source de gerenciamento de identidade e acesso que suporta múltiplos protocolos, incluindo OpenID Connect (OIDC). Como um provedor OIDC, ele implementa o endpoint padrão [userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. +[Keycloak](https://www.keycloak.org) é uma solução open-source de gerenciamento de identidade e acesso que suporta múltiplos protocolos, incluindo OpenID Connect (OIDC). Como provedor OIDC, ele implementa o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) padrão para recuperar informações de identidade do usuário. -Para buscar um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: `openid` e `profile`. Você pode continuar lendo, pois abordaremos a configuração de escopos mais adiante. +Para obter um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: `openid` e `profile`. Você pode continuar lendo, pois abordaremos a configuração de escopos mais adiante. + + + + +[Asgardeo](https://wso2.com/asgardeo) é uma plataforma IDaaS nativa em nuvem que suporta OAuth 2.0 e OpenID Connect (OIDC), fornecendo gerenciamento robusto de identidade e acesso para aplicações modernas. + +As informações do usuário são codificadas dentro do Token de ID retornado junto com o token de acesso. Mas, como provedor OIDC, o Asgardeo expõe um [endpoint UserInfo](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/) que permite que aplicações recuperem reivindicações sobre o usuário autenticado no payload. + +Você também pode descobrir esse endpoint dinamicamente via o [endpoint de descoberta OIDC](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs) ou navegando até a aba 'Info' do aplicativo no Console Asgardeo. + +Para obter um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: `openid` e `profile`. A maioria dos provedores OpenID Connect suporta o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. -Verifique a documentação do seu provedor para saber se ele suporta esse endpoint. Se seu provedor suporta [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), você também pode verificar se o `userinfo_endpoint` está incluído no documento de descoberta (resposta do endpoint `.well-known/openid-configuration`). +Verifique a documentação do seu provedor para ver se ele suporta esse endpoint. Se seu provedor suporta [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), você também pode verificar se o `userinfo_endpoint` está incluído no documento de descoberta (resposta do endpoint `.well-known/openid-configuration`). -Para buscar um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: `openid` e `profile`. Verifique a documentação do seu provedor para ver o mapeamento de escopos para reivindicações de identidade do usuário. +Para obter um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: `openid` e `profile`. Verifique a documentação do seu provedor para ver o mapeamento de escopos para reivindicações de identidade do usuário. @@ -86,7 +97,7 @@ Embora o OAuth 2.0 não defina uma maneira padrão de recuperar informações de ### Registro dinâmico de cliente (Dynamic Client Registration) \{#dynamic-client-registration} -O registro dinâmico de cliente não é necessário para este tutorial, mas pode ser útil se você quiser automatizar o processo de registro do cliente MCP com seu servidor de autorização. Consulte [O registro dinâmico de cliente é necessário?](../../provider-list.mdx#is-dcr-required) para mais detalhes. +O Registro Dinâmico de Cliente não é necessário para este tutorial, mas pode ser útil se você quiser automatizar o processo de registro do cliente MCP com seu servidor de autorização. Consulte [O Registro Dinâmico de Cliente é necessário?](../../provider-list.mdx#is-dcr-required) para mais detalhes. ## Configure o servidor MCP (Set up the MCP server) \{#set-up-the-mcp-server} @@ -261,20 +272,20 @@ npm install npm run dev ``` -Em seguida, abra seu navegador e acesse `http://localhost:6274/` (ou outro URL exibido no terminal) para acessar o MCP inspector. +Depois, abra seu navegador e navegue até `http://localhost:6274/` (ou outro URL exibido no terminal) para acessar o MCP inspector. ### Conecte o MCP inspector ao servidor MCP (Connect MCP inspector to the MCP server) \{#connect-mcp-inspector-to-the-mcp-server} Antes de prosseguir, verifique a seguinte configuração no MCP inspector: - **Tipo de transporte (Transport Type)**: Defina como `SSE`. -- **URL**: Defina como a URL do seu servidor MCP. No nosso caso, deve ser `http://localhost:3001/sse`. +- **URL**: Defina para a URL do seu servidor MCP. No nosso caso, deve ser `http://localhost:3001/sse`. -Agora você pode clicar no botão "Connect" para ver se o MCP inspector consegue se conectar ao servidor MCP. Se tudo estiver correto, você verá o status "Connected" no MCP inspector. +Agora você pode clicar no botão "Connect" para ver se o MCP inspector consegue se conectar ao servidor MCP. Se tudo estiver certo, você verá o status "Connected" no MCP inspector. -### Ponto de verificação: Execute a ferramenta `whoami` (Checkpoint: Run the `whoami` tool) \{#checkpoint-run-the-whoami-tool} +### Checkpoint: Execute a ferramenta `whoami` (Checkpoint: Run the `whoami` tool) \{#checkpoint-run-the-whoami-tool} -1. No menu superior do MCP inspector, clique na guia "Tools". +1. No menu superior do MCP inspector, clique na aba "Tools". 2. Clique no botão "List Tools". 3. Você deve ver a ferramenta `whoami` listada na página. Clique nela para abrir os detalhes da ferramenta. 4. Você deve ver o botão "Run Tool" no lado direito. Clique nele para executar a ferramenta. @@ -304,7 +315,7 @@ Normalmente, é a URL base do seu servidor de autorização, como `https://auth.
**Como registrar o MCP inspector como cliente em seu servidor de autorização (How to register the MCP inspector as a client in your authorization server)** -- Se seu servidor de autorização suporta [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), você pode pular esta etapa, pois o MCP inspector se registrará automaticamente como cliente. +- Se seu servidor de autorização suporta [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), você pode pular esta etapa, pois o MCP inspector irá se registrar automaticamente como cliente. - Se seu servidor de autorização não suporta Dynamic Client Registration, você precisará registrar manualmente o MCP inspector como cliente em seu servidor de autorização.
@@ -312,7 +323,7 @@ Normalmente, é a URL base do seu servidor de autorização, como `https://auth.
**Como recuperar informações de identidade do usuário e como configurar os parâmetros da solicitação de autorização (How to retrieve user identity information and how to configure the authorization request parameters)** -- Para provedores OpenID Connect: normalmente você precisa solicitar pelo menos os escopos `openid` e `profile` ao iniciar o fluxo de autorização. Isso garantirá que o token de acesso retornado pelo servidor de autorização contenha os escopos necessários para acessar o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. +- Para provedores OpenID Connect: normalmente você precisa solicitar pelo menos os escopos `openid` e `profile` ao iniciar o fluxo de autorização. Isso garantirá que o token de acesso retornado pelo servidor de autorização contenha os escopos necessários para acessar o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) e recuperar informações de identidade do usuário. Nota: Alguns provedores podem não suportar o endpoint userinfo. @@ -327,17 +338,17 @@ Embora cada provedor possa ter seus próprios requisitos específicos, as etapas -Integrar com o [Logto](https://logto.io) é simples, pois é um provedor OpenID Connect que suporta o endpoint padrão [userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. +A integração com o [Logto](https://logto.io) é simples, pois é um provedor OpenID Connect que suporta o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) padrão para recuperar informações de identidade do usuário. Como o Logto ainda não suporta Dynamic Client Registration, você precisará registrar manualmente o MCP inspector como cliente em seu tenant Logto: -1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. -2. Faça login no [Logto Console](https://cloud.logto.io) (ou seu Logto Console auto-hospedado). +1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor de **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. +2. Acesse o [Logto Console](https://cloud.logto.io) (ou seu Logto Console auto-hospedado). 3. Navegue até a aba "Applications", clique em "Create application". No final da página, clique em "Create app without framework". 4. Preencha os detalhes do aplicativo e clique em "Create application": - **Selecione um tipo de aplicativo**: Escolha "Single-page application". - **Nome do aplicativo**: Insira um nome para seu aplicativo, por exemplo, "MCP Inspector". -5. Na seção "Settings / Redirect URIs", cole o valor **Redirect URL (auto-populated)** que você copiou do MCP inspector. Em seguida, clique em "Save changes" na barra inferior. +5. Na seção "Settings / Redirect URIs", cole o valor de **Redirect URL (auto-populated)** que você copiou do MCP inspector. Depois clique em "Save changes" na barra inferior. 6. No cartão superior, você verá o valor "App ID". Copie-o. 7. Volte ao MCP inspector e cole o valor "App ID" na seção "OAuth Configuration" em "Client ID". 8. Insira o valor `{"scope": "openid profile email"}` no campo "Auth Params". Isso garantirá que o token de acesso retornado pelo Logto contenha os escopos necessários para acessar o endpoint userinfo. @@ -347,7 +358,7 @@ Como o Logto ainda não suporta Dynamic Client Registration, você precisará re [Keycloak](https://www.keycloak.org) é uma solução open-source de gerenciamento de identidade e acesso que suporta o protocolo OpenID Connect. -Embora o Keycloak suporte registro dinâmico de cliente, seu endpoint de registro de cliente não suporta CORS, impedindo que a maioria dos clientes MCP se registrem diretamente. Portanto, precisaremos registrar nosso cliente manualmente. +Embora o Keycloak suporte registro dinâmico de clientes, seu endpoint de registro de clientes não suporta CORS, impedindo que a maioria dos clientes MCP se registrem diretamente. Portanto, precisaremos registrar nosso cliente manualmente. :::note Embora o Keycloak possa ser instalado de [várias formas](https://www.keycloak.org/guides#getting-started) (bare metal, kubernetes, etc.), para este tutorial, usaremos Docker para uma configuração rápida e simples. @@ -378,17 +389,17 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM - Clique em "Create new user" - Preencha os detalhes do usuário: - Username: `testuser` - - Nome e sobrenome podem ser quaisquer valores + - First name e Last name podem ser quaisquer valores - Clique em "Create" - Na aba "Credentials", defina uma senha e desmarque "Temporary" 5. Registre o MCP Inspector como cliente: - - Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. + - Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor de **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. - No Keycloak Admin Console, clique em "Clients" no menu à esquerda - Clique em "Create client" - Preencha os detalhes do cliente: - - Tipo de cliente: Selecione "OpenID Connect" + - Client type: Selecione "OpenID Connect" - Client ID: Digite `mcp-inspector` - Clique em "Next" - Na página "Capability config": @@ -400,7 +411,7 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM - Clique em "Save" - Copie o "Client ID" (que é `mcp-inspector`) -6. De volta ao MCP Inspector: +6. No MCP Inspector: - Cole o Client ID copiado no campo "Client ID" na seção "OAuth Configuration" - Insira o seguinte valor no campo "Auth Params" para solicitar os escopos necessários: @@ -408,20 +419,54 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM { "scope": "openid profile email" } ``` - + + + +Embora o Asgardeo suporte registro dinâmico de clientes via API padrão, o endpoint é protegido e requer um token de acesso com as permissões necessárias. Neste tutorial, registraremos o cliente manualmente pelo Console Asgardeo. + +:::note +Se você ainda não tem uma conta Asgardeo, pode [criar uma gratuitamente](https://asgardeo.io). +::: + +Siga estes passos para configurar o Asgardeo para o MCP Inspector: + +1. Faça login no [Console Asgardeo](https://console.asgardeo.io) e selecione sua organização. + +2. Crie um novo aplicativo: + - Vá em **Applications** → **New Application** + - Escolha **Single-Page Application** + - Insira um nome como `MCP Inspector` + - No campo **Authorized Redirect URLs**, cole a **Redirect URL** copiada do MCP Inspector (ex.: `http://localhost:6274/oauth/callback`) + - Clique em **Create** + +3. Configure as configurações de protocolo: + - Na aba **Protocol**: + - Copie o **Client ID** gerado automaticamente. + - Certifique-se de mudar para `JWT` em `Token Type` na seção **Access Token** + - Clique em **Update** + +4. No MCP Inspector: + - Abra a seção **OAuth Configuration** + - Cole o **Client ID** copiado + - Insira o seguinte no campo **Auth Params** para solicitar os escopos necessários: + +```json +{ "scope": "openid profile email" } +``` + :::note Este é um guia genérico de integração com provedores OpenID Connect. Verifique a documentação do seu provedor para detalhes específicos. ::: -Se seu provedor OpenID Connect suporta Dynamic Client Registration, você pode ir diretamente para o passo 8 abaixo para configurar o MCP inspector; caso contrário, será necessário registrar manualmente o MCP inspector como cliente em seu provedor OpenID Connect: +Se seu provedor OpenID Connect suporta Dynamic Client Registration, você pode ir direto ao passo 8 abaixo para configurar o MCP inspector; caso contrário, será necessário registrar manualmente o MCP inspector como cliente em seu provedor OpenID Connect: -1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. -2. Faça login no console do seu provedor OpenID Connect. +1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor de **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. +2. Acesse o console do seu provedor OpenID Connect. 3. Navegue até a seção "Applications" ou "Clients" e crie um novo aplicativo ou cliente. 4. Se seu provedor exigir um tipo de cliente, selecione "Single-page application" ou "Public client". -5. Após criar o aplicativo, será necessário configurar a URI de redirecionamento. Cole o valor **Redirect URL (auto-populated)** que você copiou do MCP inspector. +5. Após criar o aplicativo, será necessário configurar a URI de redirecionamento. Cole o valor de **Redirect URL (auto-populated)** que você copiou do MCP inspector. 6. Encontre o "Client ID" ou "Application ID" do aplicativo recém-criado e copie-o. 7. Volte ao MCP inspector e cole o valor "Client ID" na seção "OAuth Configuration" em "Client ID". 8. Para provedores OpenID Connect padrão, você pode inserir o seguinte valor no campo "Auth Params" para solicitar os escopos necessários para acessar o endpoint userinfo: @@ -437,13 +482,13 @@ Se seu provedor OpenID Connect suporta Dynamic Client Registration, você pode i Este é um guia genérico de integração com provedores OAuth 2.0 / OAuth 2.1. Verifique a documentação do seu provedor para detalhes específicos. ::: -Se seu provedor OAuth 2.0 / OAuth 2.1 suporta Dynamic Client Registration, você pode ir diretamente para o passo 8 abaixo para configurar o MCP inspector; caso contrário, será necessário registrar manualmente o MCP inspector como cliente em seu provedor OAuth 2.0 / OAuth 2.1: +Se seu provedor OAuth 2.0 / OAuth 2.1 suporta Dynamic Client Registration, você pode ir direto ao passo 8 abaixo para configurar o MCP inspector; caso contrário, será necessário registrar manualmente o MCP inspector como cliente em seu provedor OAuth 2.0 / OAuth 2.1: -1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. -2. Faça login no console do seu provedor OAuth 2.0 / OAuth 2.1. +1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor de **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. +2. Acesse o console do seu provedor OAuth 2.0 / OAuth 2.1. 3. Navegue até a seção "Applications" ou "Clients" e crie um novo aplicativo ou cliente. 4. Se seu provedor exigir um tipo de cliente, selecione "Single-page application" ou "Public client". -5. Após criar o aplicativo, será necessário configurar a URI de redirecionamento. Cole o valor **Redirect URL (auto-populated)** que você copiou do MCP inspector. +5. Após criar o aplicativo, será necessário configurar a URI de redirecionamento. Cole o valor de **Redirect URL (auto-populated)** que você copiou do MCP inspector. 6. Encontre o "Client ID" ou "Application ID" do aplicativo recém-criado e copie-o. 7. Volte ao MCP inspector e cole o valor "Client ID" na seção "OAuth Configuration" em "Client ID". 8. Leia a documentação do seu provedor para saber como recuperar tokens de acesso para informações de identidade do usuário. Pode ser necessário especificar os escopos ou parâmetros necessários para obter o token de acesso. Por exemplo, se seu provedor exigir o escopo `profile` para acessar informações de identidade do usuário, você pode inserir o seguinte valor no campo "Auth Params": @@ -457,7 +502,7 @@ Se seu provedor OAuth 2.0 / OAuth 2.1 suporta Dynamic Client Registration, você ### Configure o MCP auth (Set up MCP auth) \{#set-up-mcp-auth} -No seu projeto do servidor MCP, você precisa instalar o SDK MCP Auth e configurá-lo para usar os metadados do seu servidor de autorização. +No seu projeto do servidor MCP, você precisa instalar o SDK do MCP Auth e configurá-lo para usar os metadados do seu servidor de autorização. @@ -496,15 +541,24 @@ A URL do emissor pode ser encontrada na página de detalhes do seu aplicativo no -A URL do emissor pode ser encontrada no Keycloak Admin Console. Em seu 'mcp-realm', navegue até a seção "Realm settings / Endpoints" e clique no link "OpenID Endpoint Configuration". O campo `issuer` no documento JSON conterá sua URL de emissor, que deve ser algo como `http://localhost:8080/realms/mcp-realm`. +A URL do emissor pode ser encontrada no Keycloak Admin Console. No seu 'mcp-realm', navegue até a seção "Realm settings / Endpoints" e clique no link "OpenID Endpoint Configuration". O campo `issuer` no documento JSON conterá sua URL de emissor, que deve ser algo como `http://localhost:8080/realms/mcp-realm`. + + + Você pode encontrar a URL do emissor no Console Asgardeo. Navegue até o aplicativo criado e abra a aba **Info**. O campo **Issuer** será exibido lá e deve ser algo como: + `https://api.asgardeo.io/t//oauth2/token` + + + + + -O código a seguir também assume que o servidor de autorização suporta o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. Se seu provedor não suportar esse endpoint, será necessário verificar a documentação do seu provedor para o endpoint específico e substituir a variável do endpoint userinfo pela URL correta. +O código a seguir também assume que o servidor de autorização suporta o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. Se seu provedor não suportar esse endpoint, você precisará verificar a documentação do seu provedor para o endpoint específico e substituir a variável do endpoint userinfo pela URL correta. @@ -569,11 +623,11 @@ app.use(mcpAuth.bearerAuth(verifyToken)); -## Ponto de verificação: Execute a ferramenta `whoami` com autenticação (Checkpoint: Run the `whoami` tool with authentication) \{#checkpoint-run-the-whoami-tool-with-authentication} +## Checkpoint: Execute a ferramenta `whoami` com autenticação (Checkpoint: Run the `whoami` tool with authentication) \{#checkpoint-run-the-whoami-tool-with-authentication} Reinicie seu servidor MCP e abra o MCP inspector no navegador. Ao clicar no botão "Connect", você deve ser redirecionado para a página de login do seu servidor de autorização. -Depois de fazer login e retornar ao MCP inspector, repita as ações que fizemos no ponto de verificação anterior para executar a ferramenta `whoami`. Desta vez, você deve ver as informações de identidade do usuário retornadas pelo servidor de autorização. +Depois de fazer login e retornar ao MCP inspector, repita as ações do checkpoint anterior para executar a ferramenta `whoami`. Desta vez, você deverá ver as informações de identidade do usuário retornadas pelo servidor de autorização. ![Resultado da ferramenta whoami no MCP inspector](/docs-assets/images/tutorials/whoami/result.png) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index 8b44e2d..85ce777 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -15,18 +15,18 @@ import SetupOidc from './_setup-oidc.mdx'; 完成本教程后，你将获得： -- ✅ 对如何在 MCP 服务器中设置基于角色的访问控制 (RBAC) 有基本了解。 -- ✅ 一个可以管理个人待办事项列表的 MCP 服务器。 +- ✅ 基本了解如何在 MCP 服务器中设置基于角色的访问控制 (RBAC) +- ✅ 一个可以管理个人待办事项列表的 MCP 服务器 :::note -在开始之前，如果你对 MCP 服务器和 OAuth 2 不熟悉，强烈建议你先阅读 [Who am I 教程](./whoami)。 +在开始之前，如果你不熟悉 MCP 服务器和 OAuth 2，强烈建议你先阅读 [Who am I 教程](./whoami)。 ::: ## 概览 \{#overview} 本教程将涉及以下组件： -- **MCP 服务器**：一个使用 MCP 官方 SDK 处理请求的简单 MCP 服务器，集成了用于管理用户待办事项的 Todo 服务。 +- **MCP 服务器**：一个简单的 MCP 服务器，使用 MCP 官方 SDK 处理请求，并集成了用于管理用户待办事项的 Todo 服务。 - **MCP inspector**：一个用于 MCP 服务器的可视化测试工具。它还充当 OAuth / OIDC 客户端，用于发起授权流程并获取访问令牌 (Access token)。 - **授权 (Authorization) 服务器**：一个 OAuth 2.1 或 OpenID Connect 提供商，负责管理用户身份并签发访问令牌 (Access token)。 @@ -46,7 +46,7 @@ sequenceDiagram Client->>Auth: 用授权码换取访问令牌 (Access token) Auth->>Client: 返回访问令牌 (Access token) Client->>Server: 携带访问令牌 (Access token) 请求待办事项操作 - Server->>Server: 验证访问令牌 (Access token) 并从中获取用户权限 (Scopes) + Server->>Server: 验证访问令牌 (Access token) 并从访问令牌 (Access token) 获取用户权限 (Scopes) Note over Server: 执行待办事项操作 Server->>Client: 返回待办事项操作结果 ``` @@ -60,7 +60,7 @@ sequenceDiagram -[Logto](https://logto.io) 通过其 API 资源和角色功能（符合 [RFC 8707: OAuth 2.0 的资源指示器](https://datatracker.ietf.org/doc/html/rfc8707)）提供 RBAC 支持。设置方法如下： +[Logto](https://logto.io) 通过其 API 资源（符合 [RFC 8707: OAuth 2.0 的资源指示器](https://datatracker.ietf.org/doc/html/rfc8707)）和角色 (Roles) 功能提供 RBAC 支持。设置方法如下： 1. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console） @@ -73,36 +73,75 @@ sequenceDiagram - `read:todos`：“读取所有待办事项” - `delete:todos`：“删除任意待办事项” -3. 创建角色（推荐，便于管理）： +3. 创建角色 (Roles)（推荐，便于管理）： - - 进入“角色” - - 创建一个“Admin”角色并分配所有权限 (Scopes)（`create:todos`、`read:todos`、`delete:todos`） + - 进入“角色 (Roles)” + - 创建一个“Admin”角色，并分配所有权限 (Scopes)（`create:todos`、`read:todos`、`delete:todos`） - 创建一个“User”角色，仅分配 `create:todos` 权限 (Scope) 4. 分配权限 (Permissions)： - 进入“用户” - 选择一个用户 - 你可以： - - 在“角色”标签页分配角色（推荐） - - 或在“权限”标签页直接分配权限 (Scopes) + - 在“角色 (Roles)”标签页分配角色（推荐） + - 或直接在“权限 (Permissions)”标签页分配权限 (Scopes) 这些权限 (Scopes) 会作为空格分隔的字符串包含在 JWT 访问令牌 (Access token) 的 `scope` 声明 (Claim) 中。 + + + [Asgardeo](https://wso2.com/asgardeo) 支持基于角色的访问控制 (RBAC) 和通过 API 资源与权限 (Scopes) 实现细粒度授权 (Authorization)。配置方法如下： + + 1. 登录 [Asgardeo Console](https://console.asgardeo.io) + + 2. 定义你的 API 资源和权限 (Scopes)： + - 进入 **API Resources** + - 点击 **"New API Resource"** + - 将 **Identifier** 设置为 `https://todo.mcp-server.app`（或你想要的 URL） + - **Display Name** 填写 `Todo Manager` + - 添加以下权限 (Scopes)： + - `create:todos` : "创建新的待办事项" + - `read:todos` : "读取所有待办事项" + - `delete:todos` : "删除任意待办事项" + - 创建资源 + + 3. 创建角色 (Roles)： + - 使用 **User Management > Roles** 创建角色并直接分配权限 (Scopes) + - 点击 **New Role** + - 在 **Basic Details** 部分填写角色名称（如 `Admin` 或 `User`） + - 角色受众选择 `Application`，并选择 `MCP Inspector Application` 作为 **Assigned Application** + - 在 **Permission Selection** 部分，选择你刚刚创建的 API 资源（如 `Todo Manager`） + - 选择要分配给该角色的权限 (Scopes)（如 `create:todos`、`read:todos`、`delete:todos`） + - 点击 **Finish** 创建角色 + + 如果你已经创建了应用 + - 进入 **Application > MCP Inspector Application > Roles tab** + - 选择 **Application Role** 作为受众类型，然后点击 **New Role** + - 创建 `Admin` 角色并附加全部三项权限 (Scopes) + - 创建 `User` 角色并仅附加 `create:todos` 权限 (Scope) + + 4. 分配角色给用户： + - 进入 **User Management > Roles** + - 选择你创建的角色（如 `Admin` 或 `User`），切换到 **Users** 标签页 + - 选择 **Assign User** 并选择要分配该角色的用户，保存即可 + + 权限 (Scopes) 会作为空格分隔的字符串包含在 JWT 访问令牌 (Access token) 的 `scope` 声明 (Claim) 中。 + -OAuth 2.0 / OIDC 提供商通常支持基于权限 (Scope) 的访问控制。在实现 RBAC 时： +OAuth 2.0 / OIDC 提供商通常支持基于权限 (Scopes) 的访问控制。在实现 RBAC 时： -1. 在授权 (Authorization) 服务器中定义所需的权限 (Scopes) -2. 配置客户端在授权 (Authorization) 流程中请求这些权限 (Scopes) -3. 确保授权 (Authorization) 服务器在访问令牌 (Access token) 中包含已授予的权限 (Scopes) +1. 在你的授权 (Authorization) 服务器中定义所需的权限 (Scopes) +2. 配置你的客户端在授权 (Authorization) 流程中请求这些权限 (Scopes) +3. 确保你的授权 (Authorization) 服务器在访问令牌 (Access token) 中包含已授予的权限 (Scopes) 4. 权限 (Scopes) 通常包含在 JWT 访问令牌 (Access token) 的 `scope` 声明 (Claim) 中 请查阅你的提供商文档，了解以下内容： - 如何定义和管理权限 (Scopes) - 权限 (Scopes) 如何包含在访问令牌 (Access token) 中 -- 是否有额外的 RBAC 功能，如角色管理 +- 是否有额外的 RBAC 功能，如角色 (Roles) 管理 @@ -123,7 +162,7 @@ sequenceDiagram participant MCP Server participant Auth Server - Client->>MCP Server: 携带访问令牌 (Access token) 的请求 + Client->>MCP Server: 携带访问令牌 (Access token) 请求 alt JWT 验证 MCP Server->>Auth Server: 获取 JWKS @@ -143,16 +182,16 @@ sequenceDiagram end ``` -### 动态客户端注册 (Dynamic Client Registration) \{#dynamic-client-registration} +### 动态客户端注册 \{#dynamic-client-registration} -本教程不要求动态客户端注册 (Dynamic Client Registration)，但如果你想自动化 MCP 客户端在授权 (Authorization) 服务器的注册流程，可以参考 [是否需要动态客户端注册？](../../provider-list.mdx#is-dcr-required)。 +本教程不要求动态客户端注册，但如果你想自动化 MCP 客户端在授权 (Authorization) 服务器的注册流程，它会很有用。详见 [是否需要动态客户端注册？](../../provider-list.mdx#is-dcr-required)。 ## 了解待办事项管理器中的 RBAC \{#understand-rbac-in-todo-manager} 为了演示，我们将在待办事项管理器 MCP 服务器中实现一个简单的基于角色的访问控制 (RBAC) 系统。这将向你展示 RBAC 的基本原理，同时保持实现简洁。 :::note -虽然本教程演示了基于 RBAC 的权限 (Scope) 管理，但需要注意，并非所有认证 (Authentication) 提供商都通过角色实现权限 (Scope) 管理。有些提供商可能有自己独特的访问控制和权限 (Permission) 管理机制。 +虽然本教程演示了基于 RBAC 的权限 (Scope) 管理，但需要注意，并非所有认证 (Authentication) 提供商都通过角色 (Roles) 实现权限 (Scope) 管理。有些提供商可能有自己独特的访问控制和权限 (Permission) 管理机制。 ::: ### 工具与权限 (Scopes) \{#tools-and-scopes} @@ -161,41 +200,41 @@ sequenceDiagram - `create-todo`：创建新的待办事项 - `get-todos`：列出所有待办事项 -- `delete-todo`：按 ID 删除待办事项 +- `delete-todo`：根据 ID 删除待办事项 -为了控制对这些工具的访问，我们定义以下权限 (Scopes)： +为了控制对这些工具的访问，我们定义了以下权限 (Scopes)： - `create:todos`：允许创建新的待办事项 - `delete:todos`：允许删除现有待办事项 - `read:todos`：允许查询和获取所有待办事项列表 -### 角色与权限 (Roles and permissions) \{#roles-and-permissions} +### 角色 (Roles) 与权限 (Permissions) \{#roles-and-permissions} -我们将定义两个具有不同访问级别的角色： +我们将定义两个具有不同访问级别的角色 (Roles)： -| 角色 (Role) | create:todos | read:todos | delete:todos | -| ----- | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | +| 角色 (Role) | create:todos | read:todos | delete:todos | +| ----------- | ------------ | ---------- | ------------ | +| Admin | ✅ | ✅ | ✅ | +| User | ✅ | | | -- **User**：普通用户，可以创建待办事项，并且只能查看或删除自己的待办事项 +- **User**：普通用户，可以创建待办事项，并仅查看或删除自己的待办事项 - **Admin**：管理员，可以创建、查看和删除所有待办事项，无论归属谁 -### 资源归属 (Resource ownership) \{#resource-ownership} +### 资源归属 \{#resource-ownership} -虽然上表显示了每个角色明确分配的权限 (Scopes)，但还有一个重要的资源归属原则： +虽然上表展示了分配给每个角色 (Role) 的显式权限 (Scopes)，但还有一个重要的资源归属原则： -- **User** 没有 `read:todos` 或 `delete:todos` 权限 (Scopes)，但他们仍然可以： +- **User** 没有 `read:todos` 或 `delete:todos` 权限 (Scope)，但他们仍然可以： - 查看自己的待办事项 - 删除自己的待办事项 - **Admin** 拥有全部权限 (`read:todos` 和 `delete:todos`)，可以： - 查看系统中所有待办事项 - 删除任意待办事项，无论归属谁 -这展示了 RBAC 系统中的常见模式：资源归属为用户自己的资源隐式授予权限 (Permission)，而管理员角色则获得所有资源的显式权限 (Permission)。 +这展示了 RBAC 系统中的常见模式：资源归属为用户自己的资源隐式授予权限，而管理员角色则获得所有资源的显式权限。 :::tip 了解更多 -想深入了解 RBAC 概念和最佳实践，请查阅 [精通 RBAC：一个全面的真实案例](https://blog.logto.io/mastering-rbac)。 +想深入了解 RBAC 概念和最佳实践，请查看 [精通 RBAC：一个全面的真实案例](https://blog.logto.io/mastering-rbac)。 ::: ## 在你的提供商中配置授权 (Authorization) \{#configure-authorization-in-your-provider} @@ -205,25 +244,25 @@ sequenceDiagram -[Logto](https://logto.io) 通过其 API 资源和角色功能提供 RBAC 支持。设置方法如下： +[Logto](https://logto.io) 通过其 API 资源和角色 (Roles) 功能提供 RBAC 支持。设置方法如下： 1. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console） 2. 创建 API 资源和权限 (Scopes)： - 进入“API 资源” - - 创建一个名为“Todo Manager”的新 API 资源，并使用 `https://todo.mcp-server.app`（仅作演示）作为指示器。 + - 创建一个名为“Todo Manager”的新 API 资源，并使用 `https://todo.mcp-server.app`（演示用）作为指示器 - 创建以下权限 (Scopes)： - `create:todos`：“创建新的待办事项” - `read:todos`：“读取所有待办事项” - `delete:todos`：“删除任意待办事项” -3. 创建角色（推荐，便于管理）： +3. 创建角色 (Roles)（推荐，便于管理）： - - 进入“角色” - - 创建一个“Admin”角色并分配所有权限 (Scopes)（`create:todos`、`read:todos`、`delete:todos`） + - 进入“角色 (Roles)” + - 创建一个“Admin”角色，并分配所有权限 (Scopes)（`create:todos`、`read:todos`、`delete:todos`） - 创建一个“User”角色，仅分配 `create:todos` 权限 (Scope) - - 在“User”角色详情页，切换到“常规”标签，并将“User”角色设置为“默认角色”。 + - 在“User”角色详情页，切换到“常规”标签，并将“User”角色设置为“默认角色” 4. 管理用户角色和权限 (Permissions)： - 新用户： @@ -231,13 +270,13 @@ sequenceDiagram - 已有用户： - 进入“用户管理” - 选择一个用户 - - 在“角色”标签页为用户分配角色 + - 在“角色 (Roles)”标签页为用户分配角色 -:::tip 编程方式管理角色 -你也可以使用 Logto 的 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) 以编程方式管理用户角色。这对于自动化用户管理或构建管理面板特别有用。 +:::tip 编程方式管理角色 (Roles) +你也可以使用 Logto 的 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) 以编程方式管理用户角色 (Roles)。这对于自动化用户管理或构建管理面板特别有用。 ::: -请求访问令牌 (Access token) 时，Logto 会根据用户角色权限 (Permissions) 在令牌的 `scope` 声明 (Claim) 中包含相应权限 (Scopes)。 +请求访问令牌 (Access token) 时，Logto 会根据用户角色 (Role) 权限 (Permissions) 在令牌的 `scope` 声明 (Claim) 中包含相应的权限 (Scopes)。 @@ -246,7 +285,7 @@ sequenceDiagram 1. 创建客户端权限 (Client scopes)： - - 在你的 realm 中，进入“客户端权限 (Client scopes)” + - 在你的 realm 中，进入“Client scopes” - 创建三个新的客户端权限 (Client scopes)： - `create:todos` - `read:todos` @@ -255,22 +294,70 @@ sequenceDiagram 2. 配置客户端： - 进入你的客户端设置 - - 在“客户端权限 (Client scopes)”标签页添加你创建的所有权限 (Scopes) + - 在“Client scopes”标签页添加你创建的所有权限 (Scopes) - 确保令牌映射器已配置为包含权限 (Scopes) -3. 可选：使用角色便于管理 - - 如果你更喜欢基于角色的管理： - - 为不同访问级别创建 realm 角色 - - 将权限 (Scopes) 映射到角色 - - 为用户分配角色 - - 否则，你可以直接为用户分配权限 (Scopes) 或通过客户端级权限 (Client-level permissions) +3. 可选：使用角色 (Roles) 便于管理 + - 如果你更喜欢基于角色 (Roles) 的管理： + - 为不同访问级别创建 realm 角色 (Roles) + - 将权限 (Scopes) 映射到角色 (Roles) + - 为用户分配角色 (Roles) + - 否则，你也可以直接为用户或通过客户端级权限分配权限 (Scopes) Keycloak 会在访问令牌 (Access token) 的 `scope` 声明 (Claim) 中包含已授予的权限 (Scopes)。 + + + +[Asgardeo](https://wso2.com/asgardeo) 支持基于角色的访问控制 (RBAC) 和通过 API 资源与权限 (Scopes) 实现细粒度授权 (Authorization)。配置方法如下： + +1. 登录 [Asgardeo Console](https://console.asgardeo.io) + +2. 定义你的 API 资源和权限 (Scopes)： + - 进入 **API Resources** + - 点击 **"New API Resource"** + - 将 **Identifier** 设置为 `https://todo.mcp-server.app`（或你想要的 URL） + - **Display Name** 填写 `Todo Manager` + - 添加以下权限 (Scopes)： + - `create:todos` : "创建新的待办事项" + - `read:todos` : "读取所有待办事项" + - `delete:todos` : "删除任意待办事项" + - 创建资源 + +3. 创建角色 (Roles)： + - 使用 **User Management > Roles** 创建角色并直接分配权限 (Scopes) + - 点击 **New Role** + - 在 **Basic Details** 部分填写角色名称（如 `Admin` 或 `User`） + - 角色受众选择 `Application`，并选择 `MCP Inspector Application` 作为 **Assigned Application** + - 在 **Permission Selection** 部分，选择你刚刚创建的 API 资源（如 `Todo Manager`） + - 选择要分配给该角色的权限 (Scopes)（如 `create:todos`、`read:todos`、`delete:todos`） + - 点击 **Finish** 创建角色 + + 如果你已经创建了应用 + - 进入 **Application > MCP Inspector Application > Roles tab** + - 选择 **Application Role** 作为受众类型，然后点击 **New Role** + - 创建 `Admin` 角色并附加全部三项权限 (Scopes) + - 创建 `User` 角色并仅附加 `create:todos` 权限 (Scope) + +4. 分配角色给用户： + - 进入 **User Management > Roles** + - 选择你创建的角色（如 `Admin` 或 `User`），切换到 **Users** 标签页 + - 选择 **Assign User** 并选择要分配该角色的用户，保存即可 + +权限 (Scopes) 会作为空格分隔的字符串包含在 JWT 访问令牌 (Access token) 的 `scope` 声明 (Claim) 中。 +配置好授权 (Authorization) 服务器后，用户将获得包含其被授予权限 (Scopes) 的访问令牌 (Access token)。MCP 服务器将使用这些权限 (Scopes) 判断： + +用户是否可以创建新的待办事项（`create:todos`） +用户是否可以查看所有待办事项（`read:todos`）或仅查看自己的 +用户是否可以删除任意待办事项（`delete:todos`）或仅删除自己的 + +更多 Asgardeo 配置细节请参考： +- [API Resources Guide](https://wso2.com/asgardeo/docs/guides/authorization/api-authorization) +- [Role Management](https://wso2.com/asgardeo/docs/guides/users/manage-roles) -对于 OAuth 2.0 或 OpenID Connect 提供商，你需要配置代表不同权限 (Permissions) 的权限 (Scopes)。具体步骤取决于你的提供商，但一般流程如下： +对于 OAuth 2.0 或 OpenID Connect 提供商，你需要配置代表不同权限 (Permissions) 的权限 (Scopes)。具体步骤取决于你的提供商，但通常包括： 1. 定义权限 (Scopes)： @@ -285,8 +372,8 @@ Keycloak 会在访问令牌 (Access token) 的 `scope` 声明 (Claim) 中包含 - 确保权限 (Scopes) 被包含在访问令牌 (Access token) 中 3. 分配权限 (Permissions)： - - 使用你的提供商界面为用户授予相应权限 (Scopes) - - 有些提供商支持基于角色的管理，其他则使用直接分配权限 (Scopes) + - 使用你的提供商界面为用户授予合适的权限 (Scopes) + - 有些提供商支持基于角色 (Roles) 的管理，其他则可能直接分配权限 (Scopes) - 查阅你的提供商文档，了解推荐做法 :::tip @@ -296,13 +383,13 @@ Keycloak 会在访问令牌 (Access token) 的 `scope` 声明 (Claim) 中包含 -配置好授权 (Authorization) 服务器后，用户将获得包含其已授予权限 (Scopes) 的访问令牌 (Access token)。MCP 服务器将使用这些权限 (Scopes) 来判断： +配置好授权 (Authorization) 服务器后，用户将获得包含其被授予权限 (Scopes) 的访问令牌 (Access token)。MCP 服务器将使用这些权限 (Scopes) 判断： - 用户是否可以创建新的待办事项（`create:todos`） - 用户是否可以查看所有待办事项（`read:todos`）或仅查看自己的 - 用户是否可以删除任意待办事项（`delete:todos`）或仅删除自己的 -## 搭建 MCP 服务器 \{#set-up-the-mcp-server} +## 设置 MCP 服务器 \{#set-up-the-mcp-server} 我们将使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 创建我们的待办事项管理器 MCP 服务器。 @@ -314,13 +401,13 @@ Keycloak 会在访问令牌 (Access token) 的 `scope` 声明 (Claim) 中包含 ```bash mkdir mcp-server cd mcp-server -uv init # 或使用 `pipenv` 或 `poetry` 创建新的虚拟环境 +uv init # 或使用 `pipenv` 或 `poetry` 创建新虚拟环境 ``` -创建一个新的 Node.js 项目： +新建一个 Node.js 项目： ```bash mkdir mcp-server @@ -332,7 +419,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -我们的示例使用 TypeScript，因为 Node.js v22.6.0+ 原生支持 `--experimental-strip-types` 运行 TypeScript。如果你使用 JavaScript，代码类似——只需确保 Node.js 版本为 v22.6.0 或更高。详情见 Node.js 官方文档。 +我们的示例使用 TypeScript，因为 Node.js v22.6.0+ 原生支持通过 `--experimental-strip-types` 运行 TypeScript。如果你使用 JavaScript，代码类似——只需确保 Node.js 版本为 v22.6.0 或更高。详见 Node.js 官方文档。 ::: @@ -347,7 +434,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" pip install "mcp[cli]" starlette uvicorn ``` -或使用你喜欢的包管理器，如 `uv` 或 `poetry`。 +或你喜欢的其他包管理器，如 `uv` 或 `poetry`。 @@ -356,7 +443,7 @@ pip install "mcp[cli]" starlette uvicorn npm install @modelcontextprotocol/sdk express zod ``` -或使用你喜欢的包管理器，如 `pnpm` 或 `yarn`。 +或你喜欢的其他包管理器，如 `pnpm` 或 `yarn`。 @@ -380,17 +467,17 @@ mcp = FastMCP("Todo Manager") @mcp.tool() def create_todo(content: str) -> dict[str, Any]: - """Create a new todo.""" + """创建新的待办事项。""" return {"error": "Not implemented"} @mcp.tool() def get_todos() -> dict[str, Any]: - """List all todos.""" + """列出所有待办事项。""" return {"error": "Not implemented"} @mcp.tool() def delete_todo(id: str) -> dict[str, Any]: - """Delete a todo by id.""" + """根据 id 删除待办事项。""" return {"error": "Not implemented"} app = Starlette( @@ -408,7 +495,7 @@ uvicorn todo_manager:app --host 0.0.0.0 --port 3001 :::note -由于当前 MCP inspector 实现尚未处理授权 (Authorization) 流程，我们将采用 SSE 方式搭建 MCP 服务器。待 MCP inspector 支持授权 (Authorization) 流程后，我们会更新此处代码。 +由于当前 MCP inspector 实现尚未处理授权 (Authorization) 流程，我们将使用 SSE 方式搭建 MCP 服务器。待 MCP inspector 支持授权 (Authorization) 流程后，我们会更新此处代码。 ::: 你也可以使用 `pnpm` 或 `yarn`。 @@ -429,19 +516,19 @@ const server = new McpServer({ version: '0.0.0', }); -server.tool('create-todo', 'Create a new todo', { content: z.string() }, async ({ content }) => { +server.tool('create-todo', '创建新的待办事项', { content: z.string() }, async ({ content }) => { return { content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], }; }); -server.tool('get-todos', 'List all todos', async () => { +server.tool('get-todos', '列出所有待办事项', async () => { return { content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], }; }); -server.tool('delete-todo', 'Delete a todo by id', { id: z.string() }, async ({ id }) => { +server.tool('delete-todo', '根据 id 删除待办事项', { id: z.string() }, async ({ id }) => { return { content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], }; @@ -492,7 +579,7 @@ npm start 现在 MCP 服务器已运行，我们可以使用 MCP inspector 检查 `whoami` 工具是否可用。 -由于当前实现的限制，我们 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector)，使其在认证 (Authentication) 和授权 (Authorization) 方面更灵活、更易扩展。我们也已向原仓库提交了 pull request。 +由于当前实现的限制，我们 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector)，使其在认证 (Authentication) 和授权 (Authorization) 方面更灵活、可扩展。我们也已向原仓库提交了 PR。 运行 MCP inspector： @@ -503,24 +590,24 @@ npm install npm run dev ``` -然后在浏览器中打开 `http://localhost:6274/`（或终端显示的其他 URL）访问 MCP inspector。 +然后在浏览器中访问 `http://localhost:6274/`（或终端显示的其他 URL）即可进入 MCP inspector。 ### 连接 MCP inspector 到 MCP 服务器 \{#connect-mcp-inspector-to-the-mcp-server} 在继续之前，请检查 MCP inspector 的以下配置： -- **Transport Type**：设置为 `SSE`。 -- **URL**：设置为你的 MCP 服务器地址，本例为 `http://localhost:3001/sse`。 +- **Transport Type**：设置为 `SSE` +- **URL**：设置为你的 MCP 服务器地址，本例为 `http://localhost:3001/sse` -现在你可以点击“Connect”按钮，查看 MCP inspector 是否能连接 MCP 服务器。如果一切正常，你将在 MCP inspector 中看到“Connected”状态。 +现在你可以点击“Connect”按钮，查看 MCP inspector 是否能连接 MCP 服务器。如果一切正常，你会在 MCP inspector 中看到“Connected”状态。 ### 检查点：运行待办事项管理工具 \{#checkpoint-run-todo-manager-tools} -1. 在 MCP inspector 顶部菜单点击“Tools”标签。 -2. 点击“List Tools”按钮。 -3. 你应该能在页面上看到 `create-todo`、`get-todos` 和 `delete-todo` 工具。点击可查看工具详情。 -4. 你将在右侧看到“Run Tool”按钮。点击并输入所需参数运行工具。 -5. 你将看到工具返回的 JSON 响应 `{"error": "Not implemented"}`。 +1. 在 MCP inspector 顶部菜单点击“Tools”标签页 +2. 点击“List Tools”按钮 +3. 你应该能看到 `create-todo`、`get-todos` 和 `delete-todo` 工具出现在页面上，点击可查看工具详情 +4. 右侧会有“Run Tool”按钮，点击并输入所需参数运行工具 +5. 你会看到工具返回结果为 JSON 响应 `{"error": "Not implemented"}` ![MCP inspector 首次运行](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) @@ -538,25 +625,25 @@ npm run dev
**如何获取授权 (Authorization) 服务器元数据** -- 如果你的授权 (Authorization) 服务器符合 [OAuth 2.0 授权服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect 发现](https://openid.net/specs/openid-connect-discovery-1_0.html)，你可以使用 MCP Auth 内置工具自动获取元数据。 -- 如果不符合这些标准，你需要在 MCP 服务器配置中手动指定元数据 URL 或端点。请查阅你的提供商文档。 +- 如果你的授权 (Authorization) 服务器符合 [OAuth 2.0 授权服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，你可以使用 MCP Auth 内置工具自动获取元数据。 +- 如果不符合，你需要在 MCP 服务器配置中手动指定元数据 URL 或端点。请查阅你的提供商文档。
-**如何将 MCP inspector 注册为授权 (Authorization) 服务器的客户端** +**如何在授权 (Authorization) 服务器中注册 MCP inspector 作为客户端** -- 如果你的授权 (Authorization) 服务器支持 [动态客户端注册 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)，可以跳过此步骤，MCP inspector 会自动注册为客户端。 -- 如果不支持动态客户端注册 (Dynamic Client Registration)，你需要手动将 MCP inspector 注册为客户端。 +- 如果你的授权 (Authorization) 服务器支持 [动态客户端注册](https://datatracker.ietf.org/doc/html/rfc7591)，可以跳过此步，MCP inspector 会自动注册为客户端。 +- 如果不支持，你需要手动在授权 (Authorization) 服务器中注册 MCP inspector 作为客户端。
-**了解令牌请求参数** +**理解令牌请求参数** -向不同授权 (Authorization) 服务器请求访问令牌 (Access token) 时，指定目标资源和权限 (Permissions) 的方式各异。主要模式如下： +在向不同授权 (Authorization) 服务器请求访问令牌 (Access token) 时，指定目标资源和权限 (Permissions) 的方式各异，主要有： -- **基于资源指示器 (Resource indicator)**： +- **基于资源指示器**： - 使用 `resource` 参数指定目标 API（见 [RFC 8707: OAuth 2.0 的资源指示器](https://datatracker.ietf.org/doc/html/rfc8707)） - 现代 OAuth 2.0 实现常用 @@ -571,8 +658,8 @@ npm run dev - **基于受众 (Audience)**： - - 使用 `audience` 参数指定令牌的目标接收方 - - 与资源指示器类似，但语义不同 + - 使用 `audience` 参数指定令牌接收方 + - 与资源指示器类似但语义不同 - 示例请求： ```json { @@ -582,73 +669,107 @@ npm run dev ``` - **纯权限 (Scope) 模式**： - - 仅依赖权限 (Scopes)，无资源/受众参数 - - 传统 OAuth 2.0 方式 + - 仅依赖权限 (Scopes)，无 resource/audience 参数 + - 传统 OAuth 2.0 做法 - 示例请求： ```json { "scope": "todo-api:create todo-api:read openid profile" } ``` - - 通常使用前缀权限 (Scopes) 进行命名空间隔离 - - 适用于简单的 OAuth 2.0 实现 + - 通常用前缀权限 (Scopes) 进行命名空间隔离 + - 简单 OAuth 2.0 实现常见 :::tip 最佳实践 - 查阅你的提供商文档，了解支持哪些参数 - 有些提供商同时支持多种方式 -- 资源指示器 (Resource indicator) 通过受众限制提升安全性 -- 如有条件，优先使用资源指示器 (Resource indicator) 以获得更好的访问控制 +- 资源指示器通过受众限制提升安全性 +- 有条件时优先使用资源指示器以获得更好的访问控制 :::
-虽然每个提供商可能有自己的具体要求，以下步骤将指导你如何结合 MCP inspector 和 MCP 服务器进行针对不同提供商的配置。 +虽然每个提供商有自己的具体要求，以下步骤可指导你将 MCP inspector 和 MCP 服务器与各自的配置集成。 -### 注册 MCP inspector 为客户端 \{#register-mcp-inspector-as-a-client} +### 注册 MCP inspector 作为客户端 \{#register-mcp-inspector-as-a-client} -将待办事项管理器集成到 [Logto](https://logto.io) 非常简单，因为它是支持资源指示器 (Resource indicator) 和权限 (Scopes) 的 OpenID Connect 提供商，可以用 `https://todo.mcp-server.app` 作为资源指示器保护你的 todo API。 +将待办事项管理器集成到 [Logto](https://logto.io) 非常简单，因为它是支持资源指示器和权限 (Scopes) 的 OpenID Connect 提供商，可以用 `https://todo.mcp-server.app` 作为资源指示器保护你的 todo API。 -由于 Logto 目前不支持动态客户端注册 (Dynamic Client Registration)，你需要手动在 Logto 租户中注册 MCP inspector 为客户端： +由于 Logto 目前尚不支持动态客户端注册，你需要手动在 Logto 租户中注册 MCP inspector 作为客户端： -1. 打开 MCP inspector，点击 “OAuth Configuration” 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 -2. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console）。 -3. 进入“应用程序”标签，点击“创建应用程序”。在页面底部点击“Create app without framework”。 -4. 填写应用详情，然后点击“创建应用程序”： - - **选择应用类型**：选择“单页应用程序” - - **应用名称**：如 “MCP Inspector” -5. 在“设置 / Redirect URIs”部分，粘贴你从 MCP inspector 复制的 **Redirect URL (auto-populated)**，然后点击底部栏的“保存更改”。 -6. 在顶部卡片中，你会看到 “App ID” 值。复制它。 -7. 回到 MCP inspector，在 “OAuth Configuration” 的 “Client ID” 字段粘贴 “App ID”。 -8. 在 “Auth Params” 字段输入 `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}`。这样 Logto 返回的访问令牌 (Access token) 就包含访问待办事项管理器所需的权限 (Scopes)。 +1. 打开 MCP inspector，点击 "OAuth Configuration" 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback` +2. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console） +3. 进入“应用程序”标签，点击“创建应用程序”。页面底部点击“无框架创建应用” +4. 填写应用详情，点击“创建应用程序”： + - **选择应用类型**：选择“单页应用” + - **应用名称**：如 "MCP Inspector" +5. 在“设置 / Redirect URIs”部分，粘贴你从 MCP inspector 复制的 **Redirect URL (auto-populated)**，然后点击底栏“保存更改” +6. 顶部卡片会显示 "App ID"，复制它 +7. 回到 MCP inspector，在 "OAuth Configuration" 的 "Client ID" 处粘贴 "App ID" +8. 在 "Auth Params" 字段输入 `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}`，确保 Logto 返回的访问令牌 (Access token) 包含访问 todo manager 所需的权限 (Scopes) + + + + 虽然 Asgardeo 支持通过标准 API 动态客户端注册，但该端点受保护且需要具备相应权限的访问令牌 (Access token)。本教程我们将通过 Asgardeo Console 手动注册客户端。 + + :::note + 如果你还没有 Asgardeo 账号，可以[免费注册](https://asgardeo.io)。 + ::: + + 按以下步骤为 MCP Inspector 配置 Asgardeo： + + 1. 登录 [Asgardeo Console](https://console.asgardeo.io) 并选择你的组织 + + 2. 创建新应用： + - 进入 **Applications** → **New Application** + - 选择 **Single-Page Application** + - 应用名称如 `MCP Inspector` + - **Authorized Redirect URLs** 粘贴 MCP Inspector 客户端应用复制的 **Redirect URL**（如：`http://localhost:6274/oauth/callback`） + - 点击 **Create** + + 3. 配置协议设置： + - 在 **Protocol** 标签页下： + - 复制自动生成的 **Client ID** + - 在 **Access Token** 部分切换为 `JWT` 作为 `Token Type` + - 点击 **Update** + + 4. 在 MCP Inspector 客户端应用中： + - 打开 **OAuth Configuration** 区域 + - 粘贴复制的 **Client ID** + - 在 **Auth Params** 字段输入以下内容以请求所需权限 (Scopes)： + + ```json + { "scope": "openid profile email" } + ``` :::note -这是通用的 OAuth 2.0 / OpenID Connect 提供商集成指南。OAuth 2.0 和 OIDC 步骤类似，因为 OIDC 基于 OAuth 2.0。具体细节请查阅你的提供商文档。 +这是通用 OAuth 2.0 / OpenID Connect 提供商集成指南。OAuth 2.0 和 OIDC 步骤类似，OIDC 构建于 OAuth 2.0 之上。具体细节请查阅你的提供商文档。 ::: -如果你的提供商支持动态客户端注册 (Dynamic Client Registration)，可以直接跳到第 8 步配置 MCP inspector；否则需要手动注册 MCP inspector 为客户端： +如果你的提供商支持动态客户端注册，可直接跳到第 8 步配置 MCP inspector；否则需手动注册 MCP inspector 作为客户端： -1. 打开 MCP inspector，点击 “OAuth Configuration” 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 +1. 打开 MCP inspector，点击 "OAuth Configuration" 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback` -2. 登录你的提供商控制台。 +2. 登录你的提供商控制台 -3. 进入“应用程序”或“客户端”部分，创建新应用或客户端。 +3. 进入“应用程序”或“客户端”部分，创建新应用或客户端 -4. 如果需要选择客户端类型，选择“单页应用程序”或“公共客户端”。 +4. 如果需要选择客户端类型，选择“单页应用”或“公共客户端” -5. 创建应用后，需要配置重定向 URI。粘贴你从 MCP inspector 复制的 **Redirect URL (auto-populated)**。 +5. 创建应用后，需配置重定向 URI，粘贴你从 MCP inspector 复制的 **Redirect URL (auto-populated)** -6. 找到新建应用的 “Client ID” 或 “Application ID”，复制它。 +6. 找到新建应用的 "Client ID" 或 "Application ID"，复制它 -7. 回到 MCP inspector，在 “OAuth Configuration” 的 “Client ID” 字段粘贴 “Client ID”。 +7. 回到 MCP inspector，在 "OAuth Configuration" 的 "Client ID" 处粘贴 "Client ID" -8. 在 “Auth Params” 字段输入以下内容，请求待办事项操作所需权限 (Scopes)： +8. 在 "Auth Params" 字段输入以下内容以请求待办事项操作所需权限 (Scopes)： ```json { "scope": "create:todos read:todos delete:todos" } @@ -657,7 +778,7 @@ npm run dev -### 配置 MCP Auth \{#set-up-mcp-auth} +### 设置 MCP Auth \{#set-up-mcp-auth} 在你的 MCP 服务器项目中，需要安装 MCP Auth SDK 并配置其使用你的授权 (Authorization) 服务器元数据。 @@ -670,7 +791,7 @@ npm run dev pip install mcpauth ``` -或使用你喜欢的包管理器，如 `uv` 或 `poetry`。 +或你喜欢的其他包管理器，如 `uv` 或 `poetry`。 @@ -690,12 +811,21 @@ MCP Auth 需要授权 (Authorization) 服务器元数据才能初始化。根据 -发行者 (Issuer) URL 可在 Logto Console 的应用详情页 “Endpoints & Credentials / Issuer endpoint” 部分找到，格式如 `https://my-project.logto.app/oidc`。 +发行者 (Issuer) URL 可在 Logto Console 的应用详情页 "Endpoints & Credentials / Issuer endpoint" 部分找到，形如 `https://my-project.logto.app/oidc`。 + + + 你可以在 Asgardeo Console 找到发行者 (Issuer) URL。进入已创建的应用，打开 **Info** 标签页，**Issuer** 字段即为发行者 (Issuer) 地址，形如： + `https://api.asgardeo.io/t//oauth2/token` + + + + + 对于 OAuth 2.0 提供商，你需要： @@ -721,7 +851,7 @@ from mcpauth import MCPAuth from mcpauth.config import AuthServerType from mcpauth.utils import fetch_server_config -auth_issuer = '' # 替换为你的发行者 (Issuer) 端点 +auth_issuer = '' # 替换为你的发行者 (Issuer) 地址 auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) mcp_auth = MCPAuth(server=auth_server_config) ``` @@ -736,7 +866,7 @@ mcp_auth = MCPAuth(server=auth_server_config) import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const authIssuer = ''; // 替换为你的发行者 (Issuer) 端点 +const authIssuer = ''; // 替换为你的发行者 (Issuer) 地址 const mcpAuth = new MCPAuth({ server: await fetchServerConfig(authIssuer, { type: 'oidc' }), }); @@ -747,7 +877,7 @@ const mcpAuth = new MCPAuth({ ### 更新 MCP 服务器 \{#update-mcp-server} -我们快完成了！现在需要更新 MCP 服务器，应用 MCP Auth 路由和中间件，并基于用户权限 (Scopes) 实现待办事项工具的权限 (Permission) 控制。 +我们快完成了！现在需要更新 MCP 服务器，应用 MCP Auth 路由和中间件函数，并基于用户权限 (Scopes) 实现待办事项工具的权限 (Permission) 控制。 @@ -755,7 +885,7 @@ const mcpAuth = new MCPAuth({ ```python @mcp.tool() def create_todo(content: str) -> dict[str, Any]: - """Create a new todo.""" + """创建新的待办事项。""" return ( mcp_auth.auth_info.scopes if mcp_auth.auth_info # 由 Bearer auth 中间件填充 @@ -781,7 +911,7 @@ app = Starlette( ```js server.tool( 'create-todo', - 'Create a new todo', + '创建新的待办事项', { content: z.string() }, async ({ content, authInfo }) => { return { @@ -801,7 +931,7 @@ app.use(mcpAuth.bearerAuth('jwt')); -接下来，让我们实现具体的工具。 +接下来，让我们实现具体工具。 首先，创建一个简单的 todo 服务，在内存中提供基本的 CRUD 操作。 @@ -811,7 +941,7 @@ app.use(mcpAuth.bearerAuth('jwt')); # service.py """ -一个简单的 Todo 服务，仅用于演示。 +一个用于演示的简单 Todo 服务。 使用内存列表存储 todos。 """ @@ -839,7 +969,7 @@ class Todo: } class TodoService: -"""一个简单的 Todo 服务，仅用于演示。""" +"""一个用于演示的简单 Todo 服务。""" def __init__(self): self._todos: List[Todo] = [] @@ -849,7 +979,7 @@ class TodoService: 获取所有 todos，可选按 owner_id 过滤。 Args: - owner_id: 如提供，仅返回该用户拥有的 todos + owner_id: 如果提供，仅返回该用户拥有的 todos Returns: todo 字典列表 @@ -861,13 +991,13 @@ class TodoService: def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: """ - 按 ID 获取 todo。 + 根据 ID 获取 todo。 Args: todo_id: 要获取的 todo ID Returns: - 找到则返回 Todo 对象，否则为 None + 找到则返回 Todo 对象，否则返回 None """ for todo in self._todos: if todo.id == todo_id: @@ -876,7 +1006,7 @@ class TodoService: def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: """ - 创建新 todo。 + 创建新的 todo。 Args: content: todo 内容 @@ -896,13 +1026,13 @@ class TodoService: def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: """ - 按 ID 删除 todo。 + 根据 ID 删除 todo。 Args: todo_id: 要删除的 todo ID Returns: - 删除的 todo 字典，如未找到则为 None + 删除的 todo 字典，未找到则返回 None """ for i, todo in enumerate(self._todos): if todo.id == todo_id: @@ -911,7 +1041,7 @@ class TodoService: return None def _generate_id(self) -> str: - """生成随机 todo ID。""" + """生成 todo 的随机 ID。""" return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) ```` @@ -931,7 +1061,7 @@ type Todo = { }; /** - * 一个简单的 Todo 服务，仅用于演示。 + * 一个用于演示的简单 Todo 服务。 * 使用内存数组存储 todos */ export class TodoService { @@ -982,7 +1112,7 @@ export class TodoService { -然后在工具层，根据用户权限 (Scopes) 判断操作是否允许： +然后在工具层，根据用户权限 (Scopes) 判断是否允许操作： @@ -994,7 +1124,7 @@ from typing import Any, Optional from mcpauth.errors import MCPAuthBearerAuthError def assert_user_id(auth_info: Optional[dict]) -> str: - """从 auth info 提取并校验用户 ID。""" + """从认证信息中提取并校验用户 ID。""" subject = auth_info.get('subject') if auth_info else None if not subject: raise ValueError('Invalid auth info') @@ -1009,11 +1139,11 @@ todo_service = TodoService() @mcp.tool() def create_todo(content: str) -> dict[str, Any]: - """创建新 todo。 + """创建新的待办事项。 - 只有拥有 'create:todos' 权限 (Scope) 的用户才能创建 todo。 + 只有拥有 'create:todos' 权限 (Scope) 的用户才能创建待办事项。 """ - # 获取认证 (Authentication) 信息 + # 获取认证信息 auth_info = mcp_auth.auth_info # 校验用户 ID @@ -1022,7 +1152,7 @@ def create_todo(content: str) -> dict[str, Any]: except ValueError as e: return {"error": str(e)} - # 检查用户是否有所需权限 (Permissions) + # 检查用户是否有所需权限 if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): raise MCPAuthBearerAuthError('missing_required_scopes') @@ -1035,7 +1165,7 @@ def create_todo(content: str) -> dict[str, Any]: # ... ``` -你可以查看我们的 [示例代码](https://github.com/mcp-auth/python/tree/master/samples/server) 获取其他详细实现。 +你可以查看我们的 [示例代码](https://github.com/mcp-auth/python/tree/master/samples/server) 获取完整实现。 @@ -1057,7 +1187,7 @@ const assertUserId = (authInfo?: AuthInfo) => { }; /** - * 检查用户是否拥有操作所需的所有权限 (Scopes) + * 检查用户是否拥有操作所需的全部权限 (Scopes) */ const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { return requiredScopes.every((scope) => userScopes.includes(scope)); @@ -1065,13 +1195,13 @@ const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): bool server.tool( 'create-todo', - 'Create a new todo', + '创建新的待办事项', { content: z.string() }, ({ content }: { content: string }, { authInfo }) => { const userId = assertUserId(authInfo); /** - * 只有拥有 'create:todos' 权限 (Scope) 的用户才能创建 todo + * 只有拥有 'create:todos' 权限 (Scope) 的用户才能创建待办事项 */ if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { throw new MCPAuthBearerAuthError('missing_required_scopes'); @@ -1088,7 +1218,7 @@ server.tool( // ... ``` -你可以查看我们的 [示例代码](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) 获取其他详细实现。 +你可以查看我们的 [示例代码](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) 获取完整实现。 @@ -1097,41 +1227,41 @@ server.tool( 重启你的 MCP 服务器，并在浏览器中打开 MCP inspector。点击“Connect”按钮后，你会被重定向到授权 (Authorization) 服务器的登录页面。 -登录后回到 MCP inspector，重复上一个检查点的操作运行待办事项管理工具。此时，你可以用已认证 (Authentication) 的用户身份使用这些工具。工具的行为将根据分配给你的角色和权限 (Permissions) 而变化： +登录后返回 MCP inspector，重复上一个检查点的操作运行待办事项工具。这一次，你可以用已认证 (Authentication) 的用户身份使用这些工具。工具的行为将根据分配给你的角色 (Roles) 和权限 (Permissions) 而变化： -- 如果你以 **User**（仅有 `create:todos` 权限 (Scope)）身份登录： +- 如果你以 **User**（仅有 `create:todos` 权限 (Scope)）登录： - 可以用 `create-todo` 工具创建新待办事项 - 只能查看和删除自己的待办事项 - - 无法查看或删除其他用户的待办事项 + - 无法看到或删除其他用户的待办事项 -- 如果你以 **Admin**（拥有全部权限：`create:todos`、`read:todos`、`delete:todos`）身份登录： +- 如果你以 **Admin**（拥有全部权限：`create:todos`、`read:todos`、`delete:todos`）登录： - 可以创建新待办事项 - 可以用 `get-todos` 工具查看系统中所有待办事项 - 可以用 `delete-todo` 工具删除任意待办事项，无论归属谁 你可以通过以下方式测试不同权限级别： -1. 退出当前会话（点击 MCP inspector 的“Disconnect”按钮） -2. 用拥有不同角色/权限的其他用户账号登录 +1. 退出当前会话（在 MCP inspector 点击“Disconnect”按钮） +2. 用拥有不同角色 (Roles)/权限 (Permissions) 的其他用户账号登录 3. 再次尝试相同工具，观察用户权限变化带来的行为差异 这展示了基于角色的访问控制 (RBAC) 在实际中的工作方式，不同用户对系统功能有不同访问级别。 -![MCP inspector 待办事项管理工具结果](/docs-assets/images/tutorials/todo-manager/result.png) +![MCP inspector 待办事项工具结果](/docs-assets/images/tutorials/todo-manager/result.png) :::info -完整 MCP 服务器（OIDC 版本）代码请参考 [MCP Auth Python SDK 仓库](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py)。 +完整 MCP 服务器（OIDC 版本）代码请见 [MCP Auth Python SDK 仓库](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py)。 ::: :::info -完整 MCP 服务器（OIDC 版本）代码请参考 [MCP Auth Node.js SDK 仓库](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。 +完整 MCP 服务器（OIDC 版本）代码请见 [MCP Auth Node.js SDK 仓库](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。 ::: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx index 809d92a..7d4f37a 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx @@ -18,12 +18,12 @@ import SetupOidc from './_setup-oidc.mdx'; - ✅ 对如何使用 MCP Auth 进行用户认证 (Authentication) 的基本理解。 - ✅ 一个 MCP 服务器，提供用于获取用户身份信息的工具。 -## 概览 (Overview) \{#overview} +## 概览 \{#overview} 本教程将涉及以下组件： -- **MCP 服务器**：一个简单的 MCP 服务器，使用 MCP 官方 SDK 处理请求。 -- **MCP inspector**：MCP 服务器的可视化测试工具。它还充当 OAuth / OIDC 客户端，发起授权 (Authorization) 流程并获取访问令牌 (Access token)。 +- **MCP 服务器**：一个使用 MCP 官方 SDK 处理请求的简单 MCP 服务器。 +- **MCP inspector**：用于 MCP 服务器的可视化测试工具。它还充当 OAuth / OIDC 客户端，发起授权 (Authorization) 流程并获取访问令牌 (Access token)。 - **授权 (Authorization) 服务器**：一个 OAuth 2.1 或 OpenID Connect 提供商，管理用户身份并颁发访问令牌 (Access token)。 以下是这些组件之间交互的高级流程图： @@ -31,14 +31,14 @@ import SetupOidc from './_setup-oidc.mdx'; ```mermaid sequenceDiagram participant Client as MCP Inspector - participant Server as MCP Server + participant Server as MCP 服务器 participant Auth as 授权 (Authorization) 服务器 Client->>Server: 请求工具 `whoami` Server->>Client: 返回 401 未授权 (Unauthorized) Client->>Auth: 发起授权 (Authorization) 流程 Auth->>Auth: 完成授权 (Authorization) 流程 - Auth->>Client: 带授权码重定向回客户端 + Auth->>Client: 带授权码重定向回 Client->>Auth: 用授权码换取访问令牌 (Access token) Auth->>Client: 返回访问令牌 (Access token) Client->>Server: 携带访问令牌 (Access token) 请求 `whoami` @@ -49,50 +49,62 @@ sequenceDiagram ## 了解你的授权 (Authorization) 服务器 \{#understand-your-authorization-server} -### 获取用户身份信息 (Retrieving user identity information) \{#retrieving-user-identity-information} +### 获取用户身份信息 \{#retrieving-user-identity-information} 要完成本教程，你的授权 (Authorization) 服务器应提供用于获取用户身份信息的 API： -[Logto](https://logto.io) 是一个 OpenID Connect 提供商，支持标准的 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。 +[Logto](https://logto.io) 是一个支持标准 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 的 OpenID Connect 提供商，可用于获取用户身份信息。 -要获取可用于访问 userinfo 端点的访问令牌 (Access token)，至少需要两个权限 (Scopes)：`openid` 和 `profile`。你可以继续阅读，后续会介绍权限 (Scope) 配置。 +要获取可用于访问 userinfo endpoint 的访问令牌 (Access token)，至少需要两个权限 (Scopes)：`openid` 和 `profile`。你可以继续阅读，我们稍后会介绍权限 (Scope) 配置。 -[Keycloak](https://www.keycloak.org) 是一个开源身份和访问管理解决方案，支持多种协议，包括 OpenID Connect (OIDC)。作为 OIDC 提供商，它实现了标准的 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。 +[Keycloak](https://www.keycloak.org) 是一个开源身份和访问管理解决方案，支持多种协议，包括 OpenID Connect (OIDC)。作为 OIDC 提供商，它实现了标准的 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。 -要获取可用于访问 userinfo 端点的访问令牌 (Access token)，至少需要两个权限 (Scopes)：`openid` 和 `profile`。你可以继续阅读，后续会介绍权限 (Scope) 配置。 +要获取可用于访问 userinfo endpoint 的访问令牌 (Access token)，至少需要两个权限 (Scopes)：`openid` 和 `profile`。你可以继续阅读，我们稍后会介绍权限 (Scope) 配置。 + + + + + +[Asgardeo](https://wso2.com/asgardeo) 是一个云原生身份即服务 (IDaaS) 平台，支持 OAuth 2.0 和 OpenID Connect (OIDC)，为现代应用提供强大的身份和访问管理。 + +用户信息被编码在与访问令牌 (Access token) 一起返回的 ID 令牌 (ID token) 中。但作为 OIDC 提供商，Asgardeo 也暴露了一个 [UserInfo endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/)，允许应用在 payload 中获取已认证 (Authentication) 用户的声明 (Claims)。 + +你也可以通过 [OIDC 发现端点](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs) 动态发现该端点，或在 Asgardeo 控制台的应用 “Info” 标签页中查看。 + +要获取可用于访问 userinfo endpoint 的访问令牌 (Access token)，至少需要两个权限 (Scopes)：`openid` 和 `profile`。 -大多数 OpenID Connect 提供商都支持 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。 +大多数 OpenID Connect 提供商都支持 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。 -请查阅你的提供商文档，确认是否支持该端点。如果你的提供商支持 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，你也可以检查 discovery 文档（`.well-known/openid-configuration` 端点的响应）中是否包含 `userinfo_endpoint`。 +请查阅你的提供商文档，确认是否支持该端点。如果你的提供商支持 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，你也可以检查 discovery 文档（`.well-known/openid-configuration` 的响应）中是否包含 `userinfo_endpoint`。 -要获取可用于访问 userinfo 端点的访问令牌 (Access token)，至少需要两个权限 (Scopes)：`openid` 和 `profile`。请查阅你的提供商文档，了解权限 (Scopes) 与用户身份声明 (Claims) 的映射关系。 +要获取可用于访问 userinfo endpoint 的访问令牌 (Access token)，至少需要两个权限 (Scopes)：`openid` 和 `profile`。请查阅你的提供商文档，了解权限 (Scope) 与用户身份声明 (Claims) 的映射关系。 -虽然 OAuth 2.0 没有定义获取用户身份信息的标准方式，但许多提供商实现了自己的端点。请查阅你的提供商文档，了解如何使用访问令牌 (Access token) 获取用户身份信息，以及在发起授权 (Authorization) 流程时获取该访问令牌 (Access token) 所需的参数。 +虽然 OAuth 2.0 没有定义获取用户身份信息的标准方式，但许多提供商实现了自己的端点。请查阅你的提供商文档，了解如何使用访问令牌 (Access token) 获取用户身份信息，以及在发起授权 (Authorization) 流程时需要哪些参数来获取该访问令牌 (Access token)。 ### 动态客户端注册 (Dynamic Client Registration) \{#dynamic-client-registration} -本教程不要求动态客户端注册，但如果你希望自动化 MCP 客户端在授权 (Authorization) 服务器的注册流程，它会很有用。详见 [是否需要动态客户端注册？](../../provider-list.mdx#is-dcr-required)。 +本教程不要求动态客户端注册 (Dynamic Client Registration)，但如果你想自动化 MCP 客户端在授权 (Authorization) 服务器的注册流程，它会很有用。详见 [是否需要动态客户端注册？](../../provider-list.mdx#is-dcr-required)。 ## 搭建 MCP 服务器 \{#set-up-the-mcp-server} -我们将使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 创建一个带有 `whoami` 工具的 MCP 服务器，用于从授权 (Authorization) 服务器获取用户身份信息。 +我们将使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 创建一个带有 `whoami` 工具的 MCP 服务器，从授权 (Authorization) 服务器获取用户身份信息。 -### 创建新项目 (Create a new project) \{#create-a-new-project} +### 创建新项目 \{#create-a-new-project} @@ -120,7 +132,7 @@ npm pkg set scripts.start="node whoami.js" -### 安装 MCP SDK 及依赖 (Install the MCP SDK and dependencies) \{#install-the-mcp-sdk-and-dependencies} +### 安装 MCP SDK 及依赖 \{#install-the-mcp-sdk-and-dependencies} @@ -129,7 +141,7 @@ npm pkg set scripts.start="node whoami.js" pip install "mcp[cli]" starlette uvicorn ``` -或使用你喜欢的其他包管理器，如 `uv` 或 `poetry`。 +或你喜欢的其他包管理器，如 `uv` 或 `poetry`。 @@ -138,14 +150,14 @@ pip install "mcp[cli]" starlette uvicorn npm install @modelcontextprotocol/sdk express ``` -或使用你喜欢的其他包管理器，如 `pnpm` 或 `yarn`。 +或你喜欢的其他包管理器，如 `pnpm` 或 `yarn`。 -### 创建 MCP 服务器 (Create the MCP server) \{#create-the-mcp-server} +### 创建 MCP 服务器 \{#create-the-mcp-server} -首先，让我们创建一个实现 `whoami` 工具的 MCP 服务器。 +首先，让我们创建一个实现了 `whoami` 工具的 MCP 服务器。 @@ -170,7 +182,7 @@ app = Starlette( ) ``` -使用以下命令运行服务器： +用以下命令运行服务器： ```bash uvicorn whoami:app --host 0.0.0.0 --port 3001 @@ -180,7 +192,7 @@ uvicorn whoami:app --host 0.0.0.0 --port 3001 :::note -由于当前 MCP inspector 实现尚未处理授权 (Authorization) 流程，我们将使用 SSE 方式搭建 MCP 服务器。待 MCP inspector 支持授权 (Authorization) 流程后，我们会更新此处代码。 +由于当前 MCP inspector 实现尚未处理授权 (Authorization) 流程，我们将采用 SSE 方式搭建 MCP 服务器。待 MCP inspector 支持授权 (Authorization) 流程后，我们会更新此处代码。 ::: 你也可以使用 `pnpm` 或 `yarn`。 @@ -235,7 +247,7 @@ app.post('/messages', async (req, res) => { app.listen(PORT); ``` -使用以下命令运行服务器： +用以下命令运行服务器： ```bash npm start @@ -244,15 +256,15 @@ npm start -## 检查 MCP 服务器 (Inspect the MCP server) \{#inspect-the-mcp-server} +## 检查 MCP 服务器 \{#inspect-the-mcp-server} -### 克隆并运行 MCP inspector (Clone and run MCP inspector) \{#clone-and-run-mcp-inspector} +### 克隆并运行 MCP inspector \{#clone-and-run-mcp-inspector} -现在 MCP 服务器已运行，我们可以使用 MCP inspector 检查 `whoami` 工具是否可用。 +现在 MCP 服务器已运行，我们可以用 MCP inspector 检查 `whoami` 工具是否可用。 -由于当前实现的限制，我们 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector)，使其在认证 (Authentication) 和授权 (Authorization) 方面更灵活和可扩展。我们也已向原仓库提交了 pull request。 +由于当前实现的限制，我们 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector)，使其在认证 (Authentication) 和授权 (Authorization) 方面更灵活和可扩展。我们也已向原仓库提交了 PR。 -运行 MCP inspector，可使用以下命令（需要 Node.js）： +运行 MCP inspector，可用如下命令（需 Node.js 环境）： ```bash git clone https://github.com/mcp-auth/inspector.git @@ -261,42 +273,42 @@ npm install npm run dev ``` -然后，在浏览器中打开 `http://localhost:6274/`（或终端显示的其他 URL）访问 MCP inspector。 +然后在浏览器中打开 `http://localhost:6274/`（或终端显示的其他 URL）访问 MCP inspector。 -### 连接 MCP inspector 到 MCP 服务器 (Connect MCP inspector to the MCP server) \{#connect-mcp-inspector-to-the-mcp-server} +### 连接 MCP inspector 到 MCP 服务器 \{#connect-mcp-inspector-to-the-mcp-server} -在继续之前，请检查 MCP inspector 中的以下配置： +在继续之前，请检查 MCP inspector 的以下配置： - **Transport Type**：设置为 `SSE`。 - **URL**：设置为你的 MCP 服务器的 URL。此处应为 `http://localhost:3001/sse`。 -现在你可以点击“Connect”按钮，查看 MCP inspector 是否能连接到 MCP 服务器。如果一切正常，你将在 MCP inspector 中看到“Connected”状态。 +现在你可以点击 “Connect” 按钮，查看 MCP inspector 是否能连接到 MCP 服务器。如果一切正常，你会在 MCP inspector 中看到 “Connected” 状态。 -### 检查点：运行 `whoami` 工具 (Checkpoint: Run the `whoami` tool) \{#checkpoint-run-the-whoami-tool} +### 检查点：运行 `whoami` 工具 \{#checkpoint-run-the-whoami-tool} -1. 在 MCP inspector 顶部菜单点击 "Tools" 标签页。 -2. 点击 "List Tools" 按钮。 +1. 在 MCP inspector 顶部菜单点击 “Tools” 标签。 +2. 点击 “List Tools” 按钮。 3. 你应该能在页面上看到 `whoami` 工具，点击它查看工具详情。 -4. 在右侧你会看到 "Run Tool" 按钮，点击运行该工具。 -5. 你将看到工具返回的 JSON 响应 `{"error": "Not authenticated"}`。 +4. 你会在右侧看到 “Run Tool” 按钮，点击运行该工具。 +5. 你会看到工具返回的 JSON 响应 `{"error": "Not authenticated"}`。 ![MCP inspector 首次运行](/docs-assets/images/tutorials/whoami/inspector-first-run.png) -## 集成你的授权 (Authorization) 服务器 (Integrate with your authorization server) \{#integrate-with-your-authorization-server} +## 集成你的授权 (Authorization) 服务器 \{#integrate-with-your-authorization-server} -完成本节内容时，你需要考虑以下事项： +要完成本节内容，需要考虑以下几点：
**你的授权 (Authorization) 服务器的发行者 (Issuer) URL** -通常是你的授权 (Authorization) 服务器的基础 URL，如 `https://auth.example.com`。有些提供商可能是类似 `https://example.logto.app/oidc` 的路径，请查阅你的提供商文档。 +通常是你的授权 (Authorization) 服务器的基础 URL，如 `https://auth.example.com`。有些提供商可能是 `https://example.logto.app/oidc` 这样的路径，请查阅你的提供商文档。
**如何获取授权 (Authorization) 服务器元数据** -- 如果你的授权 (Authorization) 服务器符合 [OAuth 2.0 授权服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，你可以使用 MCP Auth 内置工具自动获取元数据。 +- 如果你的授权 (Authorization) 服务器符合 [OAuth 2.0 授权 (Authorization) 服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，你可以用 MCP Auth 内置工具自动获取元数据。 - 如果不符合这些标准，你需要在 MCP 服务器配置中手动指定元数据 URL 或端点。请查阅你的提供商文档获取具体端点。
@@ -305,110 +317,144 @@ npm run dev **如何将 MCP inspector 注册为授权 (Authorization) 服务器的客户端** - 如果你的授权 (Authorization) 服务器支持 [动态客户端注册 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)，可以跳过此步骤，MCP inspector 会自动注册为客户端。 -- 如果不支持动态客户端注册，你需要手动在授权 (Authorization) 服务器中注册 MCP inspector 为客户端。 +- 如果不支持动态客户端注册 (Dynamic Client Registration)，你需要手动将 MCP inspector 注册为授权 (Authorization) 服务器的客户端。
-**如何获取用户身份信息以及如何配置授权 (Authorization) 请求参数** +**如何获取用户身份信息及如何配置授权 (Authorization) 请求参数** -- 对于 OpenID Connect 提供商：通常在发起授权 (Authorization) 流程时需要请求至少 `openid` 和 `profile` 权限 (Scopes)。这样授权 (Authorization) 服务器返回的访问令牌 (Access token) 就包含访问 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 所需的权限 (Scopes)。 +- 对于 OpenID Connect 提供商：通常在发起授权 (Authorization) 流程时需至少请求 `openid` 和 `profile` 权限 (Scopes)。这样授权 (Authorization) 服务器返回的访问令牌 (Access token) 就包含访问 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 所需的权限 (Scopes)，可用于获取用户身份信息。 - 注意：部分提供商可能不支持 userinfo 端点。 + 注意：部分提供商可能不支持 userinfo endpoint。 -- 对于 OAuth 2.0 / OAuth 2.1 提供商：请查阅你的提供商文档，了解如何使用访问令牌 (Access token) 获取用户身份信息，以及发起授权 (Authorization) 流程时获取该访问令牌 (Access token) 所需的参数。 +- 对于 OAuth 2.0 / OAuth 2.1 提供商：请查阅你的提供商文档，了解如何用访问令牌 (Access token) 获取用户身份信息，以及发起授权 (Authorization) 流程时需要哪些参数。
虽然每个提供商可能有自己的具体要求，以下步骤将指导你如何结合 MCP inspector 和 MCP 服务器进行针对不同提供商的配置集成。 -### 注册 MCP inspector 为客户端 (Register MCP inspector as a client) \{#register-mcp-inspector-as-a-client} +### 注册 MCP inspector 为客户端 \{#register-mcp-inspector-as-a-client} -与 [Logto](https://logto.io) 集成非常简单，因为它是一个支持标准 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 的 OpenID Connect 提供商。 +与 [Logto](https://logto.io) 集成非常简单，因为它是支持标准 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 的 OpenID Connect 提供商。 由于 Logto 目前尚不支持动态客户端注册 (Dynamic Client Registration)，你需要手动在 Logto 租户中注册 MCP inspector 为客户端： -1. 打开 MCP inspector，点击 "OAuth Configuration" 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 +1. 打开 MCP inspector，点击 “OAuth Configuration” 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 2. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console）。 -3. 进入 "Applications" 标签页，点击 "Create application"。在页面底部点击 "Create app without framework"。 -4. 填写应用详情，然后点击 "Create application"： - - **选择应用类型**：选择 "Single-page application"。 - - **应用名称**：如 "MCP Inspector"。 -5. 在 "Settings / Redirect URIs" 区域，粘贴刚才复制的 **Redirect URL (auto-populated)**，然后点击底部栏的 "Save changes"。 -6. 在顶部卡片中，你会看到 "App ID"。复制它。 -7. 回到 MCP inspector，在 "OAuth Configuration" 区域的 "Client ID" 字段粘贴 "App ID"。 -8. 在 "Auth Params" 字段输入 `{"scope": "openid profile email"}`，确保 Logto 返回的访问令牌 (Access token) 包含访问 userinfo 端点所需的权限 (Scopes)。 +3. 进入 “Applications” 标签，点击 “Create application”。页面底部点击 “Create app without framework”。 +4. 填写应用信息，然后点击 “Create application”： + - **选择应用类型**：选择 “Single-page application”。 + - **应用名称**：如 “MCP Inspector”。 +5. 在 “Settings / Redirect URIs” 区域，粘贴刚才复制的 **Redirect URL (auto-populated)**，然后点击底部栏的 “Save changes”。 +6. 顶部卡片中会显示 “App ID”，复制它。 +7. 回到 MCP inspector，在 “OAuth Configuration” 区域的 “Client ID” 处粘贴 “App ID”。 +8. 在 “Auth Params” 字段输入 `{"scope": "openid profile email"}`，确保 Logto 返回的访问令牌 (Access token) 包含访问 userinfo endpoint 所需的权限 (Scopes)。 -[Keycloak](https://www.keycloak.org) 是一个开源身份和访问管理解决方案，支持 OpenID Connect 协议。 +[Keycloak](https://www.keycloak.org) 是一个支持 OpenID Connect 协议的开源身份和访问管理解决方案。 -虽然 Keycloak 支持动态客户端注册 (Dynamic Client Registration)，但其客户端注册端点不支持 CORS，导致大多数 MCP 客户端无法直接注册。因此，我们需要手动注册客户端。 +虽然 Keycloak 支持动态客户端注册 (Dynamic Client Registration)，但其客户端注册端点不支持 CORS，导致大多数 MCP 客户端无法直接注册。因此我们需要手动注册客户端。 :::note Keycloak 可通过 [多种方式](https://www.keycloak.org/guides#getting-started) 安装（裸机、kubernetes 等），本教程采用 Docker 快速搭建。 ::: -让我们搭建 Keycloak 实例并进行配置： +搭建 Keycloak 实例并进行如下配置： -1. 按 [官方文档](https://www.keycloak.org/getting-started/getting-started-docker) 使用 Docker 运行 Keycloak： +1. 按 [官方文档](https://www.keycloak.org/getting-started/getting-started-docker) 用 Docker 启动 Keycloak： ```bash docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev ``` -2. 访问 Keycloak 管理控制台 (http://localhost:8080/admin)，使用以下凭据登录： +2. 访问 Keycloak 管理控制台 (http://localhost:8080/admin)，用以下凭据登录： - 用户名：`admin` - 密码：`admin` 3. 创建新 Realm： - - 左上角点击 "Create Realm" - - "Realm name" 填写 `mcp-realm` - - 点击 "Create" + - 左上角点击 “Create Realm” + - “Realm name” 填写 `mcp-realm` + - 点击 “Create” 4. 创建测试用户： - - 左侧菜单点击 "Users" - - 点击 "Create new user" + - 左侧菜单点击 “Users” + - 点击 “Create new user” - 填写用户信息： - 用户名：`testuser` - 名字和姓氏可任意填写 - - 点击 "Create" - - 在 "Credentials" 标签页设置密码，并取消勾选 "Temporary" + - 点击 “Create” + - 在 “Credentials” 标签页设置密码，并取消勾选 “Temporary” 5. 注册 MCP Inspector 为客户端： - - 打开 MCP inspector，点击 "OAuth Configuration" 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 - - 在 Keycloak 管理控制台左侧点击 "Clients" - - 点击 "Create client" + - 打开 MCP inspector，点击 “OAuth Configuration” 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 + - 在 Keycloak 管理控制台左侧菜单点击 “Clients” + - 点击 “Create client” - 填写客户端信息： - - Client type: 选择 "OpenID Connect" - - Client ID: 输入 `mcp-inspector` - - 点击 "Next" - - "Capability config" 页面： - - 确保 "Standard flow" 已启用 - - 点击 "Next" - - "Login settings" 页面： - - 在 "Valid redirect URIs" 粘贴 MCP Inspector 回调 URL - - "Web origins" 填写 `http://localhost:6274` - - 点击 "Save" - - 复制 "Client ID"（即 `mcp-inspector`） + - Client type: 选择 “OpenID Connect” + - Client ID: 填写 `mcp-inspector` + - 点击 “Next” + - “Capability config” 页面： + - 确保启用 “Standard flow” + - 点击 “Next” + - “Login settings” 页面： + - 在 “Valid redirect URIs” 粘贴 MCP Inspector 回调 URL + - “Web origins” 填写 `http://localhost:6274` + - 点击 “Save” + - 复制 “Client ID”（即 `mcp-inspector`） 6. 回到 MCP Inspector： - - 在 "OAuth Configuration" 区域的 "Client ID" 字段粘贴复制的 Client ID - - 在 "Auth Params" 字段输入以下内容以请求所需权限 (Scopes)： + - 在 “OAuth Configuration” 区域的 “Client ID” 字段粘贴复制的 Client ID + - 在 “Auth Params” 字段输入以下内容以请求所需权限 (Scopes)： ```json { "scope": "openid profile email" } ``` - + + + +虽然 Asgardeo 支持通过标准 API 进行动态客户端注册 (Dynamic Client Registration)，但该端点受保护且需要具备相应权限的访问令牌 (Access token)。本教程将通过 Asgardeo 控制台手动注册客户端。 + +:::note +如果你还没有 Asgardeo 账号，可以[免费注册](https://asgardeo.io)。 +::: + +按以下步骤为 MCP Inspector 配置 Asgardeo： + +1. 登录 [Asgardeo Console](https://console.asgardeo.io) 并选择你的组织。 + +2. 创建新应用： + - 进入 **Applications** → **New Application** + - 选择 **Single-Page Application** + - 应用名称如 `MCP Inspector` + - **Authorized Redirect URLs** 粘贴 MCP Inspector 客户端应用复制的 **Redirect URL**（如：`http://localhost:6274/oauth/callback`） + - 点击 **Create** + +3. 配置协议设置： + - 在 **Protocol** 标签页下： + - 复制自动生成的 **Client ID** + - 在 **Access Token** 区域将 `Token Type` 切换为 `JWT` + - 点击 **Update** + +4. 在 MCP Inspector 客户端应用中： + - 打开 **OAuth Configuration** 区域 + - 粘贴复制的 **Client ID** + - 在 **Auth Params** 字段输入以下内容以请求所需权限 (Scopes)： + +```json +{ "scope": "openid profile email" } +``` + :::note @@ -417,14 +463,14 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM 如果你的 OpenID Connect 提供商支持动态客户端注册 (Dynamic Client Registration)，可直接跳到第 8 步配置 MCP inspector；否则需手动注册 MCP inspector 为客户端： -1. 打开 MCP inspector，点击 "OAuth Configuration" 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 +1. 打开 MCP inspector，点击 “OAuth Configuration” 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 2. 登录你的 OpenID Connect 提供商控制台。 -3. 进入 "Applications" 或 "Clients" 区域，创建新应用或客户端。 -4. 如需选择客户端类型，选择 "Single-page application" 或 "Public client"。 -5. 创建应用后，需配置重定向 URI。粘贴刚才复制的 **Redirect URL (auto-populated)**。 -6. 找到新建应用的 "Client ID" 或 "Application ID"，复制它。 -7. 回到 MCP inspector，在 "OAuth Configuration" 区域的 "Client ID" 字段粘贴该值。 -8. 对于标准 OpenID Connect 提供商，可在 "Auth Params" 字段输入以下内容以请求访问 userinfo 端点所需权限 (Scopes)： +3. 进入 “Applications” 或 “Clients” 区域，创建新应用或客户端。 +4. 如需选择客户端类型，选 “Single-page application” 或 “Public client”。 +5. 创建应用后需配置重定向 URI，粘贴刚才复制的 **Redirect URL (auto-populated)**。 +6. 找到新建应用的 “Client ID” 或 “Application ID”，复制它。 +7. 回到 MCP inspector，在 “OAuth Configuration” 区域的 “Client ID” 处粘贴 “Client ID”。 +8. 对于标准 OpenID Connect 提供商，可在 “Auth Params” 字段输入以下内容以请求访问 userinfo endpoint 所需权限 (Scopes)： ```json { "scope": "openid profile email" } @@ -439,14 +485,14 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM 如果你的 OAuth 2.0 / OAuth 2.1 提供商支持动态客户端注册 (Dynamic Client Registration)，可直接跳到第 8 步配置 MCP inspector；否则需手动注册 MCP inspector 为客户端： -1. 打开 MCP inspector，点击 "OAuth Configuration" 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 +1. 打开 MCP inspector，点击 “OAuth Configuration” 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 2. 登录你的 OAuth 2.0 / OAuth 2.1 提供商控制台。 -3. 进入 "Applications" 或 "Clients" 区域，创建新应用或客户端。 -4. 如需选择客户端类型，选择 "Single-page application" 或 "Public client"。 -5. 创建应用后，需配置重定向 URI。粘贴刚才复制的 **Redirect URL (auto-populated)**。 -6. 找到新建应用的 "Client ID" 或 "Application ID"，复制它。 -7. 回到 MCP inspector，在 "OAuth Configuration" 区域的 "Client ID" 字段粘贴该值。 -8. 查阅你的提供商文档，了解如何获取用于用户身份信息的访问令牌 (Access token)。你可能需要指定获取访问令牌 (Access token) 所需的权限 (Scopes) 或参数。例如，如果你的提供商要求 `profile` 权限 (Scope) 才能访问用户身份信息，可在 "Auth Params" 字段输入： +3. 进入 “Applications” 或 “Clients” 区域，创建新应用或客户端。 +4. 如需选择客户端类型，选 “Single-page application” 或 “Public client”。 +5. 创建应用后需配置重定向 URI，粘贴刚才复制的 **Redirect URL (auto-populated)**。 +6. 找到新建应用的 “Client ID” 或 “Application ID”，复制它。 +7. 回到 MCP inspector，在 “OAuth Configuration” 区域的 “Client ID” 处粘贴 “Client ID”。 +8. 查阅你的提供商文档，了解如何获取用于用户身份信息的访问令牌 (Access token)。你可能需要指定获取访问令牌 (Access token) 所需的权限 (Scopes) 或参数。例如，如果你的提供商要求 `profile` 权限 (Scope) 才能访问用户身份信息，可在 “Auth Params” 字段输入： ```json { "scope": "profile" } @@ -455,25 +501,25 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM -### 配置 MCP Auth (Set up MCP auth) \{#set-up-mcp-auth} +### 配置 MCP Auth \{#set-up-mcp-auth} 在你的 MCP 服务器项目中，需要安装 MCP Auth SDK 并配置其使用你的授权 (Authorization) 服务器元数据。 -首先，安装 `mcpauth` 包： +首先安装 `mcpauth` 包： ```bash pip install mcpauth ``` -或使用你喜欢的其他包管理器，如 `uv` 或 `poetry`。 +或你喜欢的其他包管理器，如 `uv` 或 `poetry`。 -首先，安装 `mcp-auth` 包： +首先安装 `mcp-auth` 包： ```bash npm install mcp-auth @@ -488,7 +534,7 @@ MCP Auth 需要授权 (Authorization) 服务器元数据以完成初始化。根 -发行者 (Issuer) URL 可在 Logto Console 的应用详情页 "Endpoints & Credentials / Issuer endpoint" 区域找到，类似 `https://my-project.logto.app/oidc`。 +发行者 (Issuer) URL 可在 Logto Console 的应用详情页 “Endpoints & Credentials / Issuer endpoint” 区域找到，形如 `https://my-project.logto.app/oidc`。 @@ -496,31 +542,40 @@ MCP Auth 需要授权 (Authorization) 服务器元数据以完成初始化。根 -发行者 (Issuer) URL 可在 Keycloak 管理控制台找到。在你的 'mcp-realm' 下，进入 "Realm settings / Endpoints" 区域，点击 "OpenID Endpoint Configuration" 链接。JSON 文档中的 `issuer` 字段即为你的发行者 (Issuer) URL，类似 `http://localhost:8080/realms/mcp-realm`。 +发行者 (Issuer) URL 可在 Keycloak 管理控制台找到。在 `mcp-realm` 下，进入 “Realm settings / Endpoints” 区域，点击 “OpenID Endpoint Configuration” 链接。JSON 文档中的 `issuer` 字段即为发行者 (Issuer) URL，形如 `http://localhost:8080/realms/mcp-realm`。 + + + 你可以在 Asgardeo Console 找到发行者 (Issuer) URL。进入已创建的应用，打开 **Info** 标签页。**Issuer** 字段会显示在那里，形如： + `https://api.asgardeo.io/t//oauth2/token` + + + + + -以下代码同样假设授权 (Authorization) 服务器支持 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。如果你的提供商不支持该端点，请查阅文档获取具体端点，并将 userinfo 端点变量替换为正确的 URL。 +以下代码假设授权 (Authorization) 服务器支持 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。如果你的提供商不支持该端点，请查阅文档获取具体端点，并将 userinfo endpoint 变量替换为正确的 URL。 -如前所述，OAuth 2.0 没有定义获取用户身份信息的标准方式。以下代码假设你的提供商有专门的端点用于通过访问令牌 (Access token) 获取用户身份信息。请查阅你的提供商文档获取具体端点，并将 userinfo 端点变量替换为正确的 URL。 +如前所述，OAuth 2.0 没有定义获取用户身份信息的标准方式。以下代码假设你的提供商有特定端点可用访问令牌 (Access token) 获取用户身份信息。请查阅你的提供商文档获取具体端点，并将 userinfo endpoint 变量替换为正确的 URL。 -### 更新 MCP 服务器 (Update MCP server) \{#update-mcp-server} +### 更新 MCP 服务器 \{#update-mcp-server} -我们快完成了！现在需要更新 MCP 服务器，应用 MCP Auth 路由和中间件函数，并让 `whoami` 工具返回实际的用户身份信息。 +快完成了！现在需要更新 MCP 服务器，应用 MCP Auth 路由和中间件函数，并让 `whoami` 工具返回实际的用户身份信息。 @@ -569,11 +624,11 @@ app.use(mcpAuth.bearerAuth(verifyToken)); -## 检查点：带认证 (Authentication) 运行 `whoami` 工具 (Checkpoint: Run the `whoami` tool with authentication) \{#checkpoint-run-the-whoami-tool-with-authentication} +## 检查点：带认证 (Authentication) 运行 `whoami` 工具 \{#checkpoint-run-the-whoami-tool-with-authentication} -重启你的 MCP 服务器，并在浏览器中打开 MCP inspector。当你点击 "Connect" 按钮时，应会被重定向到授权 (Authorization) 服务器的登录页面。 +重启 MCP 服务器，并在浏览器中打开 MCP inspector。当你点击 “Connect” 按钮时，应会被重定向到授权 (Authorization) 服务器的登录页面。 -登录后返回 MCP inspector，重复上一个检查点的操作运行 `whoami` 工具。这一次，你应该能看到授权 (Authorization) 服务器返回的用户身份信息。 +登录后回到 MCP inspector，重复上一个检查点的操作运行 `whoami` 工具。这一次，你应该能看到授权 (Authorization) 服务器返回的用户身份信息。 ![MCP inspector whoami 工具结果](/docs-assets/images/tutorials/whoami/result.png) @@ -588,15 +643,15 @@ app.use(mcpAuth.bearerAuth(verifyToken)); :::info -完整 MCP 服务器（OIDC 版本）代码请参考 [MCP Auth Node.js SDK 仓库](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。该目录包含 TypeScript 和 JavaScript 版本。 +完整 MCP 服务器（OIDC 版本）代码请参考 [MCP Auth Node.js SDK 仓库](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。该目录包含 TypeScript 和 JavaScript 版本代码。 ::: -## 结语 (Closing notes) \{#closing-notes} +## 结语 \{#closing-notes} -🎊 恭喜你！你已成功完成本教程。让我们回顾一下所做的内容： +🎊 恭喜！你已成功完成本教程。让我们回顾一下已完成的内容： - 搭建了带有 `whoami` 工具的基础 MCP 服务器 - 使用 MCP Auth 将 MCP 服务器与授权 (Authorization) 服务器集成 @@ -605,7 +660,7 @@ app.use(mcpAuth.bearerAuth(verifyToken)); 你还可以探索一些进阶主题，包括： - 使用 [JWT (JSON Web Token)](https://auth.wiki/jwt) 进行认证 (Authentication) 和授权 (Authorization) -- 利用 [资源指示器 (resource indicators, RFC 8707)](https://auth-wiki.logto.io/resource-indicator) 指定被访问的资源 +- 利用 [资源指示器 (Resource indicators, RFC 8707)](https://auth-wiki.logto.io/resource-indicator) 指定被访问的资源 - 实现自定义访问控制机制，如 [基于角色的访问控制 (RBAC)](https://auth.wiki/rbac) 或 [基于属性的访问控制 (ABAC)](https://auth.wiki/abac) 欢迎查阅更多教程和文档，充分发挥 MCP Auth 的能力。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx index 2d60908..b19e1a4 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/todo-manager/README.mdx @@ -24,28 +24,28 @@ import SetupOidc from './_setup-oidc.mdx'; ## 概覽 (Overview) \{#overview} -本教學將包含以下元件： +本教學將涵蓋以下元件： - **MCP 伺服器**：一個簡單的 MCP 伺服器，使用 MCP 官方 SDK 處理請求，並整合 Todo 服務來管理使用者的待辦事項。 -- **MCP inspector**：一個 MCP 伺服器的視覺化測試工具，同時作為 OAuth / OIDC 用戶端，啟動授權流程並取得存取權杖 (Access token)。 -- **授權伺服器 (Authorization server)**：一個 OAuth 2.1 或 OpenID Connect 提供者，負責管理使用者身分並簽發存取權杖 (Access token)。 +- **MCP inspector**：MCP 伺服器的視覺化測試工具，同時作為 OAuth / OIDC 用戶端啟動授權流程並取得存取權杖 (Access token)。 +- **授權伺服器 (Authorization server)**：管理使用者身分並簽發存取權杖的 OAuth 2.1 或 OpenID Connect 提供者。 -以下是這些元件間互動的高階圖示： +以下是這些元件互動的高階流程圖： ```mermaid sequenceDiagram participant Client as MCP Inspector - participant Server as MCP Server + participant Server as MCP 伺服器 (MCP Server) participant Auth as 授權伺服器 (Authorization Server) Client->>Server: 請求待辦事項操作 (Request todo operation) Server->>Client: 回傳 401 未授權 (Return 401 Unauthorized) Client->>Auth: 啟動授權流程 (Initiate authorization flow) Auth->>Auth: 完成授權流程 (Complete authorization flow) - Auth->>Client: 帶授權碼重導回來 (Redirect back with authorization code) + Auth->>Client: 以授權碼導回 (Redirect back with authorization code) Client->>Auth: 用授權碼換取存取權杖 (Exchange code for access token) Auth->>Client: 回傳存取權杖 (Return access token) - Client->>Server: 攜帶存取權杖請求待辦事項操作 (Request todo operation with access token) + Client->>Server: 以存取權杖請求待辦事項操作 (Request todo operation with access token) Server->>Server: 驗證存取權杖並取得使用者權限範圍 (Validate access token and get user scopes form access token) Note over Server: 執行待辦事項操作 (Execute todo operation) Server->>Client: 回傳操作結果 (Return todo operation result) @@ -53,55 +53,94 @@ sequenceDiagram ## 瞭解你的授權伺服器 (Understand your authorization server) \{#understand-your-authorization-server} -### 具有權限範圍 (Scopes) 的存取權杖 (Access tokens) \{#access-tokens-with-scopes} +### 具備權限範圍 (Scopes) 的存取權杖 (Access tokens) \{#access-tokens-with-scopes} -要在 MCP 伺服器中實作 [角色型存取控制 (RBAC, Role-based Access Control)](https://auth.wiki/rbac)，你的授權伺服器需支援簽發帶有權限範圍 (Scopes) 的存取權杖 (Access tokens)。權限範圍 (Scopes) 代表使用者被授予的權限。 +要在 MCP 伺服器實作 [角色型存取控制 (RBAC, Role-based Access Control)](https://auth.wiki/rbac)，你的授權伺服器需支援簽發帶有權限範圍 (Scopes) 的存取權杖 (Access tokens)。權限範圍代表使用者被授予的權限。 -[Logto](https://logto.io) 透過 API 資源 (API resources)（符合 [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)）與角色 (Roles) 功能支援 RBAC。設定方式如下： +[Logto](https://logto.io) 透過其 API 資源 (API resources，符合 [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) 與角色 (Roles) 功能支援 RBAC。設定步驟如下： 1. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console） 2. 建立 API 資源與權限範圍 (Scopes)： - - 前往「API 資源 (API Resources)」 - - 建立一個名為「Todo Manager」的新 API 資源 + - 前往「API 資源」 + - 建立名為「Todo Manager」的新 API 資源 - 新增以下權限範圍： - `create:todos`：「建立新待辦事項」 - `read:todos`：「讀取所有待辦事項」 - `delete:todos`：「刪除任一待辦事項」 -3. 建立角色（建議以便管理）： +3. 建立角色（建議，方便管理）： - - 前往「角色 (Roles)」 + - 前往「角色」 - 建立「Admin」角色並指派所有權限範圍（`create:todos`、`read:todos`、`delete:todos`） - 建立「User」角色並僅指派 `create:todos` 權限範圍 4. 指派權限： - - 前往「使用者 (Users)」 + - 前往「使用者」 - 選擇一位使用者 - 你可以： - - 在「角色 (Roles)」分頁指派角色（建議） - - 或直接在「權限 (Permissions)」分頁指派權限範圍 + - 在「角色」分頁指派角色（建議） + - 或直接在「權限」分頁指派權限範圍 -這些權限範圍會以空格分隔字串的形式包含在 JWT 存取權杖的 `scope` 宣告 (Claim) 中。 +權限範圍將以空格分隔字串的形式包含在 JWT 存取權杖的 `scope` 宣告 (Claim) 中。 + + + + [Asgardeo](https://wso2.com/asgardeo) 支援角色型存取控制 (RBAC) 與細緻授權，透過 API 資源與權限範圍。設定方式如下： + + 1. 登入 [Asgardeo Console](https://console.asgardeo.io) + + 2. 定義 API 資源與權限範圍： + - 前往 **API Resources** + - 點選 **"New API Resource"** + - **Identifier** 設為 `https://todo.mcp-server.app`（或你想要的 URL） + - **Display Name** 設為 `Todo Manager` + - 新增以下權限範圍： + - `create:todos` : "Create new todo items" + - `read:todos` : "Read all todo items" + - `delete:todos` : "Delete any todo item" + - 建立資源 + + 3. 建立角色： + - 使用 **User Management > Roles** 建立角色並直接指派權限範圍 + - 點選 **New Role** + - 在 **Basic Details** 輸入角色名稱（如 `Admin` 或 `User`） + - 角色 audience 設為 `Application`，並選擇 `MCP Inspector Application` 為 **Assigned Application** + - 在 **Permission Selection** 選擇剛剛建立的 API 資源（如 `Todo Manager`） + - 勾選要指派給此角色的權限範圍（如 `create:todos`、`read:todos`、`delete:todos`） + - 點選 **Finish** 完成角色建立 + + 若已建立應用程式 + - 前往 **Application > MCP Inspector Application > Roles tab** + - 選擇 **Application Role** 為 audience type，然後點選 **New Role** + - 建立 `Admin` 角色並附加三個權限範圍 + - 建立 `User` 角色並僅附加 `create:todos` 權限範圍 + + 4. 指派角色給使用者： + - 前往 **User Management > Roles** + - 選擇你建立的角色（如 `Admin` 或 `User`），切換到 **Users** 分頁 + - 點選 **Assign User** 並選擇要指派此角色的使用者，儲存即可 + + 權限範圍將以空格分隔字串的形式包含在 JWT 存取權杖的 `scope` 宣告 (Claim) 中。 -OAuth 2.0 / OIDC 提供者通常支援基於權限範圍 (Scope) 的存取控制。實作 RBAC 時： +OAuth 2.0 / OIDC 提供者通常支援基於權限範圍的存取控制。實作 RBAC 時： -1. 在授權伺服器中定義所需的權限範圍 -2. 設定用戶端在授權流程中請求這些權限範圍 +1. 在授權伺服器定義所需權限範圍 +2. 設定用戶端於授權流程中請求這些權限範圍 3. 確保授權伺服器將授予的權限範圍包含在存取權杖中 4. 權限範圍通常會包含在 JWT 存取權杖的 `scope` 宣告 (Claim) 中 請查閱你的提供者文件以瞭解： - 如何定義與管理權限範圍 -- 權限範圍如何包含在存取權杖中 +- 權限範圍如何包含於存取權杖 - 是否有額外的 RBAC 功能如角色管理 @@ -109,10 +148,10 @@ OAuth 2.0 / OIDC 提供者通常支援基於權限範圍 (Scope) 的存取控制 ### 權杖驗證與權限檢查 (Validating tokens and checking permissions) \{#validating-tokens-and-checking-permissions} -當 MCP 伺服器收到請求時，需執行： +當 MCP 伺服器收到請求時，需： 1. 驗證存取權杖的簽章與有效期限 -2. 從驗證後的權杖中擷取權限範圍 (Scopes) +2. 從已驗證的權杖中擷取權限範圍 3. 檢查權杖是否具備執行該操作所需的權限範圍 例如，若使用者要建立新待辦事項，其存取權杖必須包含 `create:todos` 權限範圍。流程如下： @@ -120,39 +159,39 @@ OAuth 2.0 / OIDC 提供者通常支援基於權限範圍 (Scope) 的存取控制 ```mermaid sequenceDiagram participant Client - participant MCP Server - participant Auth Server + participant MCP 伺服器 (MCP Server) + participant 授權伺服器 (Auth Server) - Client->>MCP Server: 攜帶存取權杖請求 (Request with access token) + Client->>MCP 伺服器: 以存取權杖請求 (Request with access token) - alt JWT 驗證 (JWT Validation) - MCP Server->>Auth Server: 取得 JWKS (Fetch JWKS) - Auth Server-->>MCP Server: 回傳 JWKS (Return JWKS) - MCP Server->>MCP Server: 本地驗證 JWT (Validate JWT locally) + alt JWT 驗證 (Validation) + MCP 伺服器->>授權伺服器: 取得 JWKS (Fetch JWKS) + 授權伺服器-->>MCP 伺服器: 回傳 JWKS (Return JWKS) + MCP 伺服器->>MCP 伺服器: 本地驗證 JWT (Validate JWT locally) else 權杖內省 (Token Introspection) - MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: 回傳權杖資訊
(active, scope, etc.) + MCP 伺服器->>授權伺服器: POST /introspect
(token=access_token) + 授權伺服器-->>MCP 伺服器: 回傳權杖資訊
(active, scope, etc.) end - MCP Server->>MCP Server: 擷取並檢查權限範圍 (Extract & check scopes) + MCP 伺服器->>MCP 伺服器: 擷取並檢查權限範圍 (Extract & check scopes) - alt 具備所需權限範圍 (Has required scopes) - MCP Server->>Client: 允許操作 (Allow operation) + alt 有所需權限範圍 (Has required scopes) + MCP 伺服器->>Client: 允許操作 (Allow operation) else 欠缺權限範圍 (Missing scopes) - MCP Server->>Client: 回傳 403 禁止 (Return 403 Forbidden) + MCP 伺服器->>Client: 回傳 403 禁止 (Return 403 Forbidden) end ``` ### 動態用戶端註冊 (Dynamic Client Registration) \{#dynamic-client-registration} -本教學不強制需要動態用戶端註冊，但若你想自動化 MCP 用戶端註冊流程，可參考 [是否需要 Dynamic Client Registration?](../../provider-list.mdx#is-dcr-required)。 +本教學不強制需要動態用戶端註冊，但若你想自動化 MCP 用戶端在授權伺服器的註冊流程，這會很有幫助。詳情請參閱 [是否需要 Dynamic Client Registration？](../../provider-list.mdx#is-dcr-required)。 ## 瞭解 todo manager 的 RBAC (Understand RBAC in todo manager) \{#understand-rbac-in-todo-manager} -為了示範，我們會在 todo manager MCP 伺服器中實作一個簡單的角色型存取控制 (RBAC) 系統，讓你瞭解 RBAC 的基本原則，同時保持實作簡單。 +為了示範，我們會在 todo manager MCP 伺服器中實作一個簡單的角色型存取控制 (RBAC) 系統。這將讓你瞭解 RBAC 的基本原理，同時保持實作簡潔。 :::note -雖然本教學以 RBAC 權限範圍管理為例，但並非所有驗證 (Authentication) 提供者都透過角色 (Role) 來管理權限範圍 (Scope)。有些提供者可能有自己獨特的存取控制與權限管理機制。 +雖然本教學以 RBAC 為基礎進行權限範圍管理，但並非所有驗證 (Authentication) 提供者都透過角色實作權限範圍管理。有些提供者可能有自己獨特的存取控制與權限管理機制。 ::: ### 工具與權限範圍 (Tools and scopes) \{#tools-and-scopes} @@ -163,7 +202,7 @@ sequenceDiagram - `get-todos`：列出所有待辦事項 - `delete-todo`：依 ID 刪除待辦事項 -為了控制這些工具的存取，我們定義以下權限範圍： +為了控管這些工具的存取，我們定義以下權限範圍： - `create:todos`：允許建立新待辦事項 - `delete:todos`：允許刪除現有待辦事項 @@ -171,7 +210,7 @@ sequenceDiagram ### 角色與權限 (Roles and permissions) \{#roles-and-permissions} -我們將定義兩個不同存取層級的角色： +我們將定義兩種不同存取層級的角色： | 角色 (Role) | create:todos | read:todos | delete:todos | | ----------- | ------------ | ---------- | ------------ | @@ -179,11 +218,11 @@ sequenceDiagram | User | ✅ | | | - **User**：一般使用者，可建立待辦事項，僅能檢視或刪除自己的待辦事項 -- **Admin**：管理員，可建立、檢視及刪除所有待辦事項，不論擁有者為誰 +- **Admin**：管理員，可建立、檢視、刪除所有待辦事項，不限擁有者 ### 資源擁有權 (Resource ownership) \{#resource-ownership} -雖然上表顯示每個角色明確被指派的權限範圍，但還有一個重要的「資源擁有權」原則： +雖然上表顯示每個角色明確被指派的權限範圍，但還有一個重要的資源擁有權原則： - **User** 沒有 `read:todos` 或 `delete:todos` 權限範圍，但仍可： - 讀取自己的待辦事項 @@ -192,10 +231,10 @@ sequenceDiagram - 檢視系統中所有待辦事項 - 刪除任何待辦事項，不論擁有者 -這展現了 RBAC 系統中常見的模式：資源擁有權會隱含授予使用者對自己資源的權限，而管理角色則獲得對所有資源的明確權限。 +這展現了 RBAC 系統中常見的模式：資源擁有權會隱含授權使用者操作自己資源的權限，而管理角色則獲得所有資源的明確權限。 :::tip 進一步瞭解 -想深入瞭解 RBAC 概念與最佳實踐，請參閱 [精通 RBAC：完整實例解析 (Mastering RBAC: A Comprehensive Real-World Example)](https://blog.logto.io/mastering-rbac)。 +想深入瞭解 RBAC 概念與最佳實踐，請參閱 [Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac)。 ::: ## 在你的提供者中設定授權 (Configure authorization in your provider) \{#configure-authorization-in-your-provider} @@ -205,48 +244,48 @@ sequenceDiagram -[Logto](https://logto.io) 透過 API 資源 (API resources) 與角色 (Roles) 功能支援 RBAC。設定方式如下： +[Logto](https://logto.io) 透過 API 資源與角色功能支援 RBAC。設定步驟如下： 1. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console） 2. 建立 API 資源與權限範圍： - - 前往「API 資源 (API Resources)」 - - 建立一個名為「Todo Manager」的新 API 資源，並以 `https://todo.mcp-server.app`（僅供示範）作為資源標示符 (indicator)。 + - 前往「API 資源」 + - 建立名為「Todo Manager」的新 API 資源，並以 `https://todo.mcp-server.app`（僅示範用）作為標示符 - 建立以下權限範圍： - `create:todos`：「建立新待辦事項」 - `read:todos`：「讀取所有待辦事項」 - `delete:todos`：「刪除任一待辦事項」 -3. 建立角色（建議以便管理）： +3. 建立角色（建議，方便管理）： - - 前往「角色 (Roles)」 + - 前往「角色」 - 建立「Admin」角色並指派所有權限範圍（`create:todos`、`read:todos`、`delete:todos`） - 建立「User」角色並僅指派 `create:todos` 權限範圍 - - 在「User」角色詳細頁切換到「一般 (General)」分頁，將「User」設為「預設角色 (Default role)」 + - 在「User」角色詳細頁切換到「一般」分頁，將「User」設為「預設角色」 4. 管理使用者角色與權限： - 新使用者： - - 會自動獲得「User」角色（因已設為預設角色） + - 會自動取得「User」角色（因已設為預設角色） - 現有使用者： - - 前往「使用者管理 (User management)」 + - 前往「使用者管理」 - 選擇一位使用者 - - 在「角色 (Roles)」分頁指派角色 + - 在「角色」分頁指派角色 -:::tip 程式化角色管理 (Programmatic Role Management) -你也可以透過 Logto 的 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) 程式化管理使用者角色。這對自動化使用者管理或建立管理後台特別有用。 +:::tip 程式化角色管理 +你也可以使用 Logto 的 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) 以程式方式管理使用者角色。這對自動化使用者管理或建立管理後台特別有用。 ::: -請求存取權杖時，Logto 會根據使用者角色權限將權限範圍包含在權杖的 `scope` 宣告中。 +請求存取權杖時，Logto 會根據使用者角色權限將權限範圍包含於權杖的 `scope` 宣告 (Claim) 中。 -在 [Keycloak](https://www.keycloak.org) 中，你可以透過 client scopes 設定所需權限： +在 [Keycloak](https://www.keycloak.org) 中，你可以透過用戶端權限範圍 (Client scopes) 設定所需權限： -1. 建立 client scopes： +1. 建立用戶端權限範圍： - - 在你的 realm 中，前往「Client scopes」 + - 在你的 realm，前往「Client scopes」 - 建立三個新 client scopes： - `create:todos` - `read:todos` @@ -254,25 +293,73 @@ sequenceDiagram 2. 設定用戶端： - - 前往你的 client 設定 - - 在「Client scopes」分頁新增所有已建立的 scopes - - 確認 token mapper 已設定為包含 scopes + - 前往你的用戶端設定 + - 在「Client scopes」分頁新增你建立的所有 scopes + - 確認權杖映射器 (token mapper) 已設定為包含 scopes 3. 選用：使用角色方便管理 - 若偏好角色型管理： - 建立不同存取層級的 realm roles - 將 scopes 映射到角色 - 指派角色給使用者 - - 否則可直接指派 scopes 給使用者或透過 client-level permissions + - 或可直接將 scopes 指派給使用者或透過 client-level permissions -Keycloak 會將授予的 scopes 包含在存取權杖的 `scope` 宣告中。 +Keycloak 會將授予的 scopes 包含於存取權杖的 `scope` 宣告 (Claim) 中。 + + + +[Asgardeo](https://wso2.com/asgardeo) 支援角色型存取控制 (RBAC) 與細緻授權，透過 API 資源與權限範圍。設定方式如下： + +1. 登入 [Asgardeo Console](https://console.asgardeo.io) + +2. 定義 API 資源與權限範圍： + - 前往 **API Resources** + - 點選 **"New API Resource"** + - **Identifier** 設為 `https://todo.mcp-server.app`（或你想要的 URL） + - **Display Name** 設為 `Todo Manager` + - 新增以下權限範圍： + - `create:todos` : "Create new todo items" + - `read:todos` : "Read all todo items" + - `delete:todos` : "Delete any todo item" + - 建立資源 + +3. 建立角色： + - 使用 **User Management > Roles** 建立角色並直接指派權限範圍 + - 點選 **New Role** + - 在 **Basic Details** 輸入角色名稱（如 `Admin` 或 `User`） + - 角色 audience 設為 `Application`，並選擇 `MCP Inspector Application` 為 **Assigned Application** + - 在 **Permission Selection** 選擇剛剛建立的 API 資源（如 `Todo Manager`） + - 勾選要指派給此角色的權限範圍（如 `create:todos`、`read:todos`、`delete:todos`） + - 點選 **Finish** 完成角色建立 + + 若已建立應用程式 + - 前往 **Application > MCP Inspector Application > Roles tab** + - 選擇 **Application Role** 為 audience type，然後點選 **New Role** + - 建立 `Admin` 角色並附加三個權限範圍 + - 建立 `User` 角色並僅附加 `create:todos` 權限範圍 + +4. 指派角色給使用者： + - 前往 **User Management > Roles** + - 選擇你建立的角色（如 `Admin` 或 `User`），切換到 **Users** 分頁 + - 點選 **Assign User** 並選擇要指派此角色的使用者，儲存即可 + +權限範圍將以空格分隔字串的形式包含在 JWT 存取權杖的 `scope` 宣告 (Claim) 中。 +設定好授權伺服器後，使用者將收到包含其授權權限範圍的存取權杖。MCP 伺服器會根據這些權限範圍判斷： + +是否可建立新待辦事項（`create:todos`） +是否可檢視所有待辦事項（`read:todos`）或僅能檢視自己的 +是否可刪除任一待辦事項（`delete:todos`）或僅能刪除自己的 + +更多 Asgardeo 設定細節請參閱： +- [API Resources Guide](https://wso2.com/asgardeo/docs/guides/authorization/api-authorization) +- [Role Management](https://wso2.com/asgardeo/docs/guides/users/manage-roles) 對於 OAuth 2.0 或 OpenID Connect 提供者，你需要設定代表不同權限的 scopes。具體步驟依提供者而異，但一般流程如下： -1. 定義 scopes： +1. 定義權限範圍： - 設定授權伺服器支援： - `create:todos` @@ -281,30 +368,30 @@ Keycloak 會將授予的 scopes 包含在存取權杖的 `scope` 宣告中。 2. 設定用戶端： - - 註冊或更新用戶端以請求這些 scopes - - 確認 scopes 會包含在存取權杖中 + - 註冊或更新用戶端以請求這些權限範圍 + - 確保權限範圍會包含於存取權杖 3. 指派權限： - - 透過提供者介面授予使用者適當的 scopes - - 有些提供者支援角色型管理，有些則直接指派 scopes + - 使用提供者介面將適當權限範圍授予使用者 + - 有些提供者支援角色型管理，有些則直接指派權限範圍 - 請查閱提供者文件以獲得建議做法 :::tip -大多數提供者會將授予的 scopes 包含在存取權杖的 `scope` 宣告中，格式通常為空格分隔的 scope 字串。 +大多數提供者會將授予的權限範圍包含於存取權杖的 `scope` 宣告 (Claim) 中，格式通常為空格分隔的字串。 ::: -設定好授權伺服器後，使用者將取得包含其授權 scopes 的存取權杖。MCP 伺服器會根據這些 scopes 判斷： +設定好授權伺服器後，使用者將收到包含其授權權限範圍的存取權杖。MCP 伺服器會根據這些權限範圍判斷： -- 使用者是否能建立新待辦事項（`create:todos`） -- 使用者是否能檢視所有待辦事項（`read:todos`）或僅能檢視自己的 -- 使用者是否能刪除任一待辦事項（`delete:todos`）或僅能刪除自己的 +- 是否可建立新待辦事項（`create:todos`） +- 是否可檢視所有待辦事項（`read:todos`）或僅能檢視自己的 +- 是否可刪除任一待辦事項（`delete:todos`）或僅能刪除自己的 ## 設定 MCP 伺服器 (Set up the MCP server) \{#set-up-the-mcp-server} -我們將使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 建立 todo manager MCP 伺服器。 +我們將使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 來建立 todo manager MCP 伺服器。 ### 建立新專案 (Create a new project) \{#create-a-new-project} @@ -332,7 +419,7 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" ``` :::note -我們範例中使用 TypeScript，因為 Node.js v22.6.0+ 原生支援 `--experimental-strip-types` 執行 TypeScript。如果你用 JavaScript，程式碼也很類似——只要確保 Node.js 版本為 v22.6.0 或以上。詳情請參閱 Node.js 文件。 +我們範例使用 TypeScript，因 Node.js v22.6.0+ 原生支援 `--experimental-strip-types` 執行 TypeScript。若你使用 JavaScript，程式碼大致相同，只需確保 Node.js 版本為 v22.6.0 或以上。詳情請見 Node.js 官方文件。 ::: @@ -363,12 +450,12 @@ npm install @modelcontextprotocol/sdk express zod ### 建立 MCP 伺服器 (Create the MCP server) \{#create-the-mcp-server} -首先，建立一個基本的 MCP 伺服器並定義工具： +首先，讓我們建立一個包含工具定義的基本 MCP 伺服器： -建立 `todo-manager.py` 檔案並加入以下程式碼： +建立名為 `todo-manager.py` 的檔案並加入以下程式碼： ```python from typing import Any @@ -408,12 +495,12 @@ uvicorn todo_manager:app --host 0.0.0.0 --port 3001 :::note -目前 MCP inspector 尚未支援授權流程，因此我們採用 SSE 方式設定 MCP 伺服器。待 MCP inspector 支援授權流程後會更新此處程式碼。 +由於目前 MCP inspector 尚未支援授權流程，我們將採用 SSE 方式設定 MCP 伺服器。待 MCP inspector 支援授權流程後，會更新此處程式碼。 ::: -你也可以用 `pnpm` 或 `yarn`。 +你也可以使用 `pnpm` 或 `yarn`。 -建立 `todo-manager.ts` 檔案並加入以下程式碼： +建立名為 `todo-manager.ts` 的檔案並加入以下程式碼： ```ts // todo-manager.ts @@ -447,7 +534,7 @@ server.tool('delete-todo', 'Delete a todo by id', { id: z.string() }, async ({ i }; }); -// 以下為 MCP SDK 文件範例樣板 +// 以下為 MCP SDK 文件範例樣板程式碼 const PORT = 3001; const app = express(); @@ -486,13 +573,13 @@ npm start -## 檢查 MCP 伺服器 (Inspect the MCP server) \{#inspect-the-mcp-server} +### 檢查 MCP 伺服器 (Inspect the MCP server) \{#inspect-the-mcp-server} -### 複製並執行 MCP inspector \{#clone-and-run-mcp-inspector} +#### 下載並執行 MCP inspector \{#clone-and-run-mcp-inspector} -現在 MCP 伺服器已啟動，可以用 MCP inspector 檢查 `whoami` 工具是否可用。 +現在 MCP 伺服器已啟動，我們可以用 MCP inspector 檢查 `whoami` 工具是否可用。 -由於現有實作限制，我們 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector) 以提升其彈性與可擴展性，並已向原專案提交 PR。 +由於目前實作的限制，我們 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector) 以提升其驗證 (Authentication) 與授權 (Authorization) 彈性與擴展性，並已向原專案提交 pull request。 執行 MCP inspector： @@ -503,24 +590,24 @@ npm install npm run dev ``` -然後在瀏覽器開啟 `http://localhost:6274/`（或終端機顯示的其他網址）即可存取 MCP inspector。 +然後在瀏覽器開啟 `http://localhost:6274/`（或終端機顯示的其他網址）以存取 MCP inspector。 -### 連接 MCP inspector 與 MCP 伺服器 \{#connect-mcp-inspector-to-the-mcp-server} +#### 連接 MCP inspector 與 MCP 伺服器 \{#connect-mcp-inspector-to-the-mcp-server} 繼續前請檢查 MCP inspector 設定： - **Transport Type**：設為 `SSE` -- **URL**：設為 MCP 伺服器的 URL，本例為 `http://localhost:3001/sse` +- **URL**：設為你的 MCP 伺服器網址，本例為 `http://localhost:3001/sse` -現在點擊「Connect」按鈕，檢查 MCP inspector 是否能連上 MCP 伺服器。若一切正常，應會看到 MCP inspector 顯示「Connected」狀態。 +現在你可以點擊「Connect」按鈕，檢查 MCP inspector 是否能連線至 MCP 伺服器。若一切正常，MCP inspector 會顯示「Connected」狀態。 -### 檢查點：執行 todo manager 工具 \{#checkpoint-run-todo-manager-tools} +#### 檢查點：執行 todo manager 工具 \{#checkpoint-run-todo-manager-tools} -1. 在 MCP inspector 頂部選單點選「Tools」分頁 -2. 點擊「List Tools」按鈕 -3. 應會看到 `create-todo`、`get-todos`、`delete-todo` 工具列於頁面，點擊可檢視工具詳情 +1. 在 MCP inspector 上方選單點選「Tools」分頁 +2. 點選「List Tools」按鈕 +3. 你應該會看到 `create-todo`、`get-todos`、`delete-todo` 工具列在頁面上，點擊可檢視工具細節 4. 右側會有「Run Tool」按鈕，點擊並輸入必要參數執行工具 -5. 應會看到工具回傳結果為 `{"error": "Not implemented"}` 的 JSON +5. 你會看到工具回傳結果為 `{"error": "Not implemented"}` 的 JSON ![MCP inspector 首次執行畫面](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) @@ -531,15 +618,15 @@ npm run dev
**你的授權伺服器的簽發者 (Issuer) URL** -通常是授權伺服器的基礎網址，如 `https://auth.example.com`。有些提供者可能會是 `https://example.logto.app/oidc` 這類路徑，請查閱提供者文件。 +通常是授權伺服器的基礎網址，如 `https://auth.example.com`。有些提供者會有路徑如 `https://example.logto.app/oidc`，請查閱提供者文件。
**如何取得授權伺服器 metadata** -- 若你的授權伺服器符合 [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，可用 MCP Auth 內建工具自動抓取 metadata。 -- 若不符合，需手動指定 metadata URL 或端點於 MCP 伺服器設定，請查閱提供者文件。 +- 若授權伺服器符合 [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，可用 MCP Auth 內建工具自動取得 metadata。 +- 若不符合，需手動於 MCP 伺服器設定 metadata URL 或端點，請查閱提供者文件。
@@ -558,7 +645,7 @@ npm run dev - **基於資源標示符 (Resource indicator based)**： - - 使用 `resource` 參數指定目標 API（參見 [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)） + - 使用 `resource` 參數指定目標 API（見 [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)） - 現代 OAuth 2.0 常見 - 範例請求： ```json @@ -567,11 +654,11 @@ npm run dev "scope": "create:todos read:todos" } ``` - - 伺服器會簽發專屬於該資源的權杖 + - 伺服器會簽發僅限於該資源的權杖 - **基於受眾 (Audience based)**： - - 使用 `audience` 參數指定權杖預期接收者 + - 使用 `audience` 參數指定權杖接收者 - 與資源標示符類似但語意不同 - 範例請求： ```json @@ -582,7 +669,7 @@ npm run dev ``` - **純權限範圍 (Pure scope based)**： - - 僅依 scopes，不帶 resource/audience 參數 + - 僅依賴 scopes，不帶 resource/audience 參數 - 傳統 OAuth 2.0 作法 - 範例請求： ```json @@ -593,38 +680,72 @@ npm run dev - 常用前綴命名空間權限 - 簡單 OAuth 2.0 常見 -:::tip 最佳實踐 (Best Practices) +:::tip 最佳實踐 -- 查閱提供者文件確認支援哪些參數 +- 查閱提供者文件以確認支援哪些參數 - 有些提供者同時支援多種方式 -- 資源標示符可提升安全性（限制受眾） -- 建議有支援時優先採用資源標示符 +- 資源標示符可提升安全性（受眾限制） +- 建議有支援時優先使用資源標示符 :::
-每個提供者細節不同，以下步驟可協助你依提供者設定 MCP inspector 與 MCP 伺服器。 +雖然各提供者細節不同，以下步驟可協助你整合 MCP inspector 與 MCP 伺服器並進行提供者專屬設定。 -### 註冊 MCP inspector 為用戶端 \{#register-mcp-inspector-as-a-client} +### 註冊 MCP inspector 為用戶端 (Register MCP inspector as a client) \{#register-mcp-inspector-as-a-client} -將 todo manager 與 [Logto](https://logto.io) 整合很簡單，因為它是支援資源標示符與權限範圍的 OpenID Connect 提供者，可用 `https://todo.mcp-server.app` 作為資源標示符保護 todo API。 +將 todo manager 與 [Logto](https://logto.io) 整合非常簡單，因其為支援資源標示符與權限範圍的 OpenID Connect 提供者，可用 `https://todo.mcp-server.app` 作為資源標示符保護 todo API。 -Logto 尚未支援 Dynamic Client Registration，因此需手動將 MCP inspector 註冊為用戶端： +由於 Logto 尚未支援 Dynamic Client Registration，你需手動將 MCP inspector 註冊為 Logto 租戶的用戶端： -1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕，複製 **Redirect URL (auto-populated)**，應類似 `http://localhost:6274/oauth/callback` +1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕，複製 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback` 2. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console） -3. 前往「應用程式 (Applications)」分頁，點擊「建立應用程式 (Create application)」，頁面底部點「Create app without framework」 -4. 填寫應用程式資訊後點「建立應用程式 (Create application)」： +3. 前往「應用程式」分頁，點擊「建立應用程式」，頁面底部點「Create app without framework」 +4. 填寫應用程式資訊後點「建立應用程式」： - **選擇應用程式類型**：選「單頁應用程式 (Single-page application)」 - **應用程式名稱**：如「MCP Inspector」 -5. 在「設定 / Redirect URIs」區塊貼上剛才複製的 Redirect URL，然後點底部「儲存變更 (Save changes)」 -6. 頂部卡片會顯示「App ID」，複製它 +5. 在「設定 / Redirect URIs」區塊貼上剛剛複製的 **Redirect URL (auto-populated)**，然後點底部「儲存變更」 +6. 頂部卡片會顯示「App ID」，請複製 7. 回到 MCP inspector，將「App ID」貼到「OAuth Configuration」的「Client ID」 8. 在「Auth Params」欄位輸入 `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}`，確保 Logto 回傳的存取權杖包含存取 todo manager 所需的權限範圍 + + + + 雖然 Asgardeo 支援標準 API 的動態用戶端註冊，但該端點受保護且需具備相應權限的存取權杖。本教學將透過 Asgardeo Console 手動註冊用戶端。 + + :::note + 若你尚未有 Asgardeo 帳號，可[免費註冊](https://asgardeo.io)。 + ::: + + 設定步驟如下： + + 1. 登入 [Asgardeo Console](https://console.asgardeo.io) 並選擇你的組織 + + 2. 建立新應用程式： + - 前往 **Applications** → **New Application** + - 選擇 **Single-Page Application** + - 輸入應用程式名稱如 `MCP Inspector` + - 在 **Authorized Redirect URLs** 欄位貼上從 MCP Inspector 複製的 **Redirect URL**（如：`http://localhost:6274/oauth/callback`） + - 點選 **Create** + + 3. 設定協定參數： + - 在 **Protocol** 分頁： + - 複製自動產生的 **Client ID** + - 在 **Access Token** 區塊切換為 `JWT` 作為 `Token Type` + - 點選 **Update** + + 4. 在 MCP Inspector 用戶端應用程式： + - 開啟 **OAuth Configuration** + - 貼上複製的 **Client ID** + - 在 **Auth Params** 欄位輸入以下內容以請求必要權限範圍： + + ```json + { "scope": "openid profile email" } + ``` @@ -632,17 +753,17 @@ Logto 尚未支援 Dynamic Client Registration，因此需手動將 MCP inspecto 這是通用 OAuth 2.0 / OpenID Connect 提供者整合指引。兩者步驟類似，因 OIDC 建立於 OAuth 2.0 之上。請查閱你的提供者文件以獲得細節。 ::: -若你的提供者支援 Dynamic Client Registration，可直接跳到第 8 步設定 MCP inspector；否則需手動註冊 MCP inspector 為用戶端： +若你的提供者支援 Dynamic Client Registration，可直接跳至第 8 步設定 MCP inspector；否則需手動註冊 MCP inspector 為用戶端： -1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕，複製 **Redirect URL (auto-populated)**，應類似 `http://localhost:6274/oauth/callback` +1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕，複製 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback` 2. 登入你的提供者管理後台 -3. 前往「應用程式 (Applications)」或「用戶端 (Clients)」區塊，建立新應用程式或用戶端 +3. 前往「應用程式」或「用戶端」區塊，建立新應用程式或用戶端 -4. 若需選擇用戶端類型，請選「單頁應用程式 (Single-page application)」或「公開用戶端 (Public client)」 +4. 若需選擇用戶端類型，請選「單頁應用程式」或「公開用戶端」 -5. 建立應用程式後，需設定 redirect URI，貼上剛才複製的 Redirect URL +5. 建立應用程式後，需設定 redirect URI，貼上剛剛複製的 **Redirect URL (auto-populated)** 6. 找到新應用程式的「Client ID」或「Application ID」並複製 @@ -657,14 +778,14 @@ Logto 尚未支援 Dynamic Client Registration，因此需手動將 MCP inspecto -### 設定 MCP Auth \{#set-up-mcp-auth} +### 設定 MCP Auth (Set up MCP auth) \{#set-up-mcp-auth} -在 MCP 伺服器專案中，需安裝 MCP Auth SDK 並設定使用你的授權伺服器 metadata。 +在 MCP 伺服器專案中，需安裝 MCP Auth SDK 並設定授權伺服器 metadata。 -先安裝 `mcpauth` 套件： +首先安裝 `mcpauth` 套件： ```bash pip install mcpauth @@ -675,7 +796,7 @@ pip install mcpauth -先安裝 `mcp-auth` 套件： +首先安裝 `mcp-auth` 套件： ```bash npm install mcp-auth @@ -684,25 +805,34 @@ npm install mcp-auth -MCP Auth 需要授權伺服器 metadata 來初始化。依你的提供者而定： +MCP Auth 需要授權伺服器 metadata 以初始化。依據你的提供者： -簽發者 (Issuer) URL 可在 Logto Console 應用程式詳情頁「Endpoints & Credentials / Issuer endpoint」區塊找到，格式如 `https://my-project.logto.app/oidc`。 +簽發者 (Issuer) URL 可在 Logto Console 的應用程式詳細頁「Endpoints & Credentials / Issuer endpoint」區塊找到，格式如 `https://my-project.logto.app/oidc`。 + + + 你可在 Asgardeo Console 查詢 issuer URL。前往已建立的應用程式，開啟 **Info** 分頁，**Issuer** 欄位即為該值，格式如： + `https://api.asgardeo.io/t//oauth2/token` + + + + + 對於 OAuth 2.0 提供者，你需要： 1. 查閱提供者文件取得授權伺服器 URL（常稱 issuer URL 或 base URL） 2. 有些提供者會在 `https://{your-domain}/.well-known/oauth-authorization-server` 提供 -3. 也可在管理後台 OAuth/API 設定中找到 +3. 於管理後台 OAuth/API 設定區查找 @@ -747,7 +877,7 @@ const mcpAuth = new MCPAuth({ ### 更新 MCP 伺服器 (Update MCP server) \{#update-mcp-server} -快完成了！現在要更新 MCP 伺服器，套用 MCP Auth 路由與中介軟體，並根據使用者權限範圍實作 todo manager 工具的權限存取控制。 +快完成了！現在要更新 MCP 伺服器，套用 MCP Auth 路由與中介軟體，並根據使用者權限範圍實作 todo manager 工具的權限控管。 @@ -758,7 +888,7 @@ def create_todo(content: str) -> dict[str, Any]: """Create a new todo.""" return ( mcp_auth.auth_info.scopes - if mcp_auth.auth_info # 這會由 Bearer auth middleware 填入 + if mcp_auth.auth_info # 由 Bearer auth middleware 填入 else {"error": "Not authenticated"} ) @@ -769,7 +899,7 @@ app = Starlette( routes=[ # 加入 metadata 路由 (`/.well-known/oauth-authorization-server`) mcp_auth.metadata_route(), - # 用 Bearer auth middleware 保護 MCP 伺服器 + # 以 Bearer auth middleware 保護 MCP 伺服器 Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), ], ) @@ -811,7 +941,7 @@ app.use(mcpAuth.bearerAuth('jwt')); # service.py """ -簡易 Todo 服務，僅供示範。 +簡單 Todo 服務，僅供示範。 以記憶體清單儲存 todos。 """ @@ -830,7 +960,7 @@ class Todo: self.created_at = created_at def to_dict(self) -> Dict[str, Any]: - """轉換為 dict 以便 JSON 序列化。""" + """轉換為 dict 以利 JSON 序列化。""" return { "id": self.id, "content": self.content, @@ -839,7 +969,7 @@ class Todo: } class TodoService: -"""簡易 Todo 服務，僅供示範。""" +"""簡單 Todo 服務，僅供示範。""" def __init__(self): self._todos: List[Todo] = [] @@ -849,10 +979,10 @@ class TodoService: 取得所有 todos，可選擇依 owner_id 過濾。 Args: - owner_id: 若有，僅回傳該使用者的 todos + owner_id: 若有，僅回傳此使用者的 todos Returns: - todo dict 清單 + todo 字典清單 """ if owner_id: filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] @@ -883,7 +1013,7 @@ class TodoService: owner_id: 擁有者 ID Returns: - 建立的 todo dict + 建立的 todo 字典 """ todo = Todo( id=self._generate_id(), @@ -902,7 +1032,7 @@ class TodoService: todo_id: 欲刪除的 todo ID Returns: - 若找到則回傳被刪除的 todo dict，否則 None + 若找到則回傳被刪除的 todo 字典，否則 None """ for i, todo in enumerate(self._todos): if todo.id == todo_id: @@ -931,7 +1061,7 @@ type Todo = { }; /** - * 簡易 Todo 服務，僅供示範。 + * 簡單 Todo 服務，僅供示範。 * 以記憶體陣列儲存 todos */ export class TodoService { @@ -982,7 +1112,7 @@ export class TodoService { -然後在工具層根據使用者權限範圍判斷是否允許操作： +然後在工具層根據使用者權限範圍決定是否允許操作： @@ -994,14 +1124,14 @@ from typing import Any, Optional from mcpauth.errors import MCPAuthBearerAuthError def assert_user_id(auth_info: Optional[dict]) -> str: - """從 auth info 擷取並驗證 user ID。""" + """從 auth info 擷取並驗證使用者 ID。""" subject = auth_info.get('subject') if auth_info else None if not subject: raise ValueError('Invalid auth info') return subject def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """檢查使用者是否擁有所有必要權限範圍。""" + """檢查使用者是否具備所有必要權限範圍。""" return all(scope in user_scopes for scope in required_scopes) # 建立 TodoService 實例 @@ -1011,12 +1141,12 @@ todo_service = TodoService() def create_todo(content: str) -> dict[str, Any]: """建立新 todo。 - 只有擁有 'create:todos' 權限範圍的使用者才能建立 todo。 + 只有具備 'create:todos' 權限範圍的使用者可建立 todo。 """ # 取得驗證資訊 auth_info = mcp_auth.auth_info - # 驗證 user ID + # 驗證使用者 ID try: user_id = assert_user_id(auth_info) except ValueError as e: @@ -1057,7 +1187,7 @@ const assertUserId = (authInfo?: AuthInfo) => { }; /** - * 檢查使用者是否擁有所有必要權限範圍 + * 檢查使用者是否具備操作所需的所有權限範圍 */ const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { return requiredScopes.every((scope) => userScopes.includes(scope)); @@ -1071,7 +1201,7 @@ server.tool( const userId = assertUserId(authInfo); /** - * 只有擁有 'create:todos' 權限範圍的使用者才能建立 todo + * 只有具備 'create:todos' 權限範圍的使用者可建立 todo */ if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { throw new MCPAuthBearerAuthError('missing_required_scopes'); @@ -1095,9 +1225,9 @@ server.tool( ## 檢查點：執行 `todo-manager` 工具 \{#checkpoint-run-the-todo-manager-tools} -重啟 MCP 伺服器並在瀏覽器開啟 MCP inspector。點擊「Connect」後，應會被導向授權伺服器登入頁。 +重啟 MCP 伺服器並在瀏覽器開啟 MCP inspector。點擊「Connect」後，你會被導向授權伺服器的登入頁面。 -登入並返回 MCP inspector 後，重複前述步驟執行 todo manager 工具。這次你將以已驗證的使用者身分操作，工具行為會依你被指派的角色與權限而異： +登入並返回 MCP inspector 後，重複前述步驟執行 todo manager 工具。這次你將以已驗證的使用者身分使用這些工具，工具行為將依你被指派的角色與權限而異： - 若以 **User**（僅有 `create:todos` 權限範圍）登入： @@ -1112,9 +1242,9 @@ server.tool( 你可以這樣測試不同權限層級： -1. 登出目前會話（點 MCP inspector 的「Disconnect」） +1. 登出目前會話（點 MCP inspector 的「Disconnect」按鈕） 2. 以不同角色／權限的帳號登入 -3. 重複操作觀察工具行為如何隨使用者權限變化 +3. 再次嘗試相同工具，觀察行為如何隨使用者權限變化 這展示了角色型存取控制 (RBAC) 的實際運作，不同使用者對系統功能有不同存取層級。 @@ -1124,14 +1254,14 @@ server.tool( :::info -完整 MCP 伺服器（OIDC 版）程式碼請參考 [MCP Auth Python SDK repository](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py)。 +完整 MCP 伺服器（OIDC 版本）程式碼請參考 [MCP Auth Python SDK repository](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py)。 ::: :::info -完整 MCP 伺服器（OIDC 版）程式碼請參考 [MCP Auth Node.js SDK repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。 +完整 MCP 伺服器（OIDC 版本）程式碼請參考 [MCP Auth Node.js SDK repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。 ::: @@ -1139,11 +1269,11 @@ server.tool( ## 結語 (Closing notes) \{#closing-notes} -🎊 恭喜你！已順利完成本教學。讓我們回顧一下： +🎊 恭喜你！你已成功完成本教學。讓我們回顧一下： - 建立具備 todo 管理工具（`create-todo`、`get-todos`、`delete-todo`）的基本 MCP 伺服器 -- 實作不同使用者與管理員權限層級的角色型存取控制 (RBAC) +- 實作不同權限層級的角色型存取控制 (RBAC) - 透過 MCP Auth 將 MCP 伺服器與授權伺服器整合 -- 設定 MCP Inspector 以驗證使用者並用帶權限範圍的存取權杖呼叫工具 +- 設定 MCP Inspector 以驗證使用者並用帶有權限範圍的存取權杖呼叫工具 歡迎參閱其他教學與文件，充分發揮 MCP Auth 的強大功能。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx index 87b8d4f..c7e76ce 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/tutorials/whoami/README.mdx @@ -9,9 +9,9 @@ import Tabs from '@theme/Tabs'; import SetupOauth from './_setup-oauth.mdx'; import SetupOidc from './_setup-oidc.mdx'; -# 教學：我是誰？ (Tutorial: Who am I?) +# 教學：我是誰？ (Who am I?) -本教學將引導你設定 MCP Auth，以驗證 (Authentication) 使用者並從授權 (Authorization) 伺服器取得其身分資訊。 +本教學將引導你設定 MCP Auth 來驗證 (Authentication) 使用者並從授權 (Authorization) 伺服器取得其身分資訊。 完成本教學後，你將會： @@ -20,18 +20,18 @@ import SetupOidc from './_setup-oidc.mdx'; ## 概覽 (Overview) \{#overview} -本教學將涉及以下元件： +本教學將包含以下元件： - **MCP 伺服器**：一個簡單的 MCP 伺服器，使用 MCP 官方 SDK 處理請求。 - **MCP inspector**：MCP 伺服器的視覺化測試工具，同時作為 OAuth / OIDC 用戶端，啟動授權流程並取得存取權杖 (Access token)。 - **授權伺服器 (Authorization server)**：一個 OAuth 2.1 或 OpenID Connect 提供者，負責管理使用者身分並簽發存取權杖 (Access token)。 -以下是這些元件間互動的高階圖示： +以下是這些元件互動的高階流程圖： ```mermaid sequenceDiagram participant Client as MCP Inspector - participant Server as MCP Server + participant Server as MCP 伺服器 (MCP Server) participant Auth as 授權伺服器 (Authorization Server) Client->>Server: 請求工具 `whoami` @@ -47,48 +47,59 @@ sequenceDiagram Server->>Client: 回傳使用者身分 ``` -## 瞭解你的授權伺服器 (Understand your authorization server) \{#understand-your-authorization-server} +## 瞭解你的授權伺服器 (Authorization server) \{#understand-your-authorization-server} ### 取得使用者身分資訊 (Retrieving user identity information) \{#retrieving-user-identity-information} -為完成本教學，你的授權伺服器應提供 API 以取得使用者身分資訊： +為完成本教學，你的授權伺服器應提供一個 API 來取得使用者身分資訊： [Logto](https://logto.io) 是一個 OpenID Connect 提供者，支援標準的 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 來取得使用者身分資訊。 -要取得可用於 userinfo endpoint 的存取權杖 (Access token)，至少需兩個權限範圍 (Scopes)：`openid` 與 `profile`。你可以繼續閱讀，稍後會介紹權限範圍設定。 +要取得可用於存取 userinfo endpoint 的存取權杖 (Access token)，至少需要兩個權限範圍 (Scopes)：`openid` 與 `profile`。你可以繼續閱讀，稍後我們會介紹權限範圍設定。 -[Keycloak](https://www.keycloak.org) 是一個開源身分與存取管理解決方案，支援多種協議，包括 OpenID Connect (OIDC)。作為 OIDC 提供者，它實作了標準的 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 以取得使用者身分資訊。 +[Keycloak](https://www.keycloak.org) 是一套開源身分與存取管理解決方案，支援多種協議，包括 OpenID Connect (OIDC)。作為 OIDC 提供者，它實作了標準的 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 來取得使用者身分資訊。 -要取得可用於 userinfo endpoint 的存取權杖 (Access token)，至少需兩個權限範圍 (Scopes)：`openid` 與 `profile`。你可以繼續閱讀，稍後會介紹權限範圍設定。 +要取得可用於存取 userinfo endpoint 的存取權杖 (Access token)，至少需要兩個權限範圍 (Scopes)：`openid` 與 `profile`。你可以繼續閱讀，稍後我們會介紹權限範圍設定。 + + + + +[Asgardeo](https://wso2.com/asgardeo) 是一個雲原生身分即服務 (IDaaS) 平台，支援 OAuth 2.0 與 OpenID Connect (OIDC)，為現代應用程式提供強大的身分與存取管理。 + +使用者資訊會編碼在與存取權杖 (Access token) 一同回傳的 ID 權杖 (ID token) 內。但作為 OIDC 提供者，Asgardeo 也提供 [UserInfo endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/)，讓應用程式能在回應中取得已驗證使用者的宣告 (Claims)。 + +你也可以透過 [OIDC discovery endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs) 動態發現此 endpoint，或在 Asgardeo Console 的應用程式「Info」分頁中查找。 + +要取得可用於存取 userinfo endpoint 的存取權杖 (Access token)，至少需要兩個權限範圍 (Scopes)：`openid` 與 `profile`。 -大多數 OpenID Connect 提供者都支援 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 以取得使用者身分資訊。 +大多數 OpenID Connect 提供者支援 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 來取得使用者身分資訊。 -請查閱你的提供者文件，確認是否支援此 endpoint。如果你的提供者支援 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，也可檢查 discovery 文件（`.well-known/openid-configuration` 回應）中是否包含 `userinfo_endpoint`。 +請查閱你的提供者文件，確認是否支援此 endpoint。如果你的提供者支援 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，你也可以檢查 discovery 文件（`.well-known/openid-configuration` 回應）中是否包含 `userinfo_endpoint`。 -要取得可用於 userinfo endpoint 的存取權杖 (Access token)，至少需兩個權限範圍 (Scopes)：`openid` 與 `profile`。請查閱你的提供者文件，瞭解權限範圍與使用者身分宣告 (Claims) 的對應關係。 +要取得可用於存取 userinfo endpoint 的存取權杖 (Access token)，至少需要兩個權限範圍 (Scopes)：`openid` 與 `profile`。請查閱你的提供者文件，瞭解權限範圍與使用者身分宣告 (Claims) 的對應關係。 -雖然 OAuth 2.0 沒有定義標準方式來取得使用者身分資訊，許多提供者會實作自有 endpoint。請查閱你的提供者文件，瞭解如何使用存取權杖 (Access token) 取得使用者身分資訊，以及在啟動授權流程時需帶哪些參數來取得該存取權杖。 +雖然 OAuth 2.0 並未定義標準的使用者身分資訊取得方式，但許多提供者會實作自有 endpoint。請查閱你的提供者文件，瞭解如何使用存取權杖 (Access token) 取得使用者身分資訊，以及在啟動授權流程時需帶入哪些參數以取得該存取權杖。 ### 動態用戶端註冊 (Dynamic Client Registration) \{#dynamic-client-registration} -本教學不強制需要動態用戶端註冊，但如果你想自動化 MCP 用戶端在授權伺服器的註冊流程，這會很有幫助。詳情請參閱 [是否需要動態用戶端註冊？](../../provider-list.mdx#is-dcr-required)。 +本教學不強制需要動態用戶端註冊，但若你想自動化 MCP 用戶端在授權伺服器的註冊流程，這會很有幫助。詳情請參閱 [動態用戶端註冊需要嗎？](../../provider-list.mdx#is-dcr-required)。 -## 設定 MCP 伺服器 (Set up the MCP server) \{#set-up-the-mcp-server} +## 建立 MCP 伺服器 (Set up the MCP server) \{#set-up-the-mcp-server} 我們將使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 建立一個 MCP 伺服器，並實作一個 `whoami` 工具，從授權伺服器取得使用者身分資訊。 @@ -180,7 +191,7 @@ uvicorn whoami:app --host 0.0.0.0 --port 3001 :::note -由於目前 MCP inspector 尚未支援授權流程，我們將採用 SSE 方式設定 MCP 伺服器。待 MCP inspector 支援授權流程後，會更新此處程式碼。 +由於目前 MCP inspector 尚未支援授權流程，我們將採用 SSE 方式設定 MCP 伺服器。待 MCP inspector 支援授權流程後，會再更新此處程式碼。 ::: 你也可以選擇使用 `pnpm` 或 `yarn`。 @@ -205,7 +216,7 @@ server.tool('whoami', async () => { }; }); -// 以下為 MCP SDK 文件的樣板程式碼 +// 以下為 MCP SDK 文件範例程式碼 const PORT = 3001; const app = express(); @@ -246,13 +257,13 @@ npm start ## 檢查 MCP 伺服器 (Inspect the MCP server) \{#inspect-the-mcp-server} -### 下載並執行 MCP inspector (Clone and run MCP inspector) \{#clone-and-run-mcp-inspector} +### 下載並執行 MCP inspector \{#clone-and-run-mcp-inspector} -現在 MCP 伺服器已啟動，我們可以使用 MCP inspector 檢查 `whoami` 工具是否可用。 +現在 MCP 伺服器已啟動，我們可以用 MCP inspector 檢查 `whoami` 工具是否可用。 -由於目前實作上的限制，我們 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector)，讓其在驗證 (Authentication) 與授權 (Authorization) 上更靈活且可擴展。我們也已向原始倉庫提交 pull request。 +由於目前實作的限制，我們 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector)，讓其更靈活且適合驗證 (Authentication) 與授權 (Authorization) 測試。我們也已向原始倉庫提交 pull request。 -執行 MCP inspector，請使用以下指令（需安裝 Node.js）： +執行 MCP inspector，請用下列指令（需安裝 Node.js）： ```bash git clone https://github.com/mcp-auth/inspector.git @@ -261,18 +272,18 @@ npm install npm run dev ``` -然後在瀏覽器開啟 `http://localhost:6274/`（或終端機顯示的其他網址）以進入 MCP inspector。 +然後在瀏覽器開啟 `http://localhost:6274/`（或終端機顯示的其他網址）以存取 MCP inspector。 -### 連接 MCP inspector 與 MCP 伺服器 (Connect MCP inspector to the MCP server) \{#connect-mcp-inspector-to-the-mcp-server} +### 連接 MCP inspector 與 MCP 伺服器 \{#connect-mcp-inspector-to-the-mcp-server} -在繼續之前，請檢查 MCP inspector 的以下設定： +繼續前，請檢查 MCP inspector 的下列設定： -- **Transport Type**：設為 `SSE`。 -- **URL**：設為你的 MCP 伺服器網址，本例應為 `http://localhost:3001/sse`。 +- **Transport Type**：設為 `SSE` +- **URL**：設為你的 MCP 伺服器網址，本例為 `http://localhost:3001/sse` -現在你可以點擊「Connect」按鈕，檢查 MCP inspector 是否能連接 MCP 伺服器。如果一切正常，應會看到 MCP inspector 顯示「Connected」狀態。 +現在你可以點擊「Connect」按鈕，檢查 MCP inspector 是否能連線到 MCP 伺服器。若一切正常，MCP inspector 會顯示「Connected」狀態。 -### 檢查點：執行 `whoami` 工具 (Checkpoint: Run the `whoami` tool) \{#checkpoint-run-the-whoami-tool} +### 檢查點：執行 `whoami` 工具 \{#checkpoint-run-the-whoami-tool} 1. 在 MCP inspector 上方選單點選「Tools」分頁。 2. 點擊「List Tools」按鈕。 @@ -289,14 +300,14 @@ npm run dev
**你的授權伺服器簽發者 (Issuer) URL** -通常是你的授權伺服器基礎網址，例如 `https://auth.example.com`。有些提供者可能會有路徑，如 `https://example.logto.app/oidc`，請參閱你的提供者文件。 +這通常是你的授權伺服器基礎網址，例如 `https://auth.example.com`。有些提供者可能會有路徑，如 `https://example.logto.app/oidc`，請參閱你的提供者文件。
**如何取得授權伺服器中繼資料 (Metadata)** -- 若你的授權伺服器符合 [OAuth 2.0 授權伺服器中繼資料 (RFC 8414)](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，可直接用 MCP Auth 內建工具自動取得中繼資料。 +- 若你的授權伺服器符合 [OAuth 2.0 授權伺服器中繼資料](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，可用 MCP Auth 內建工具自動取得中繼資料。 - 若不符合上述標準，需手動在 MCP 伺服器設定中指定中繼資料網址或 endpoint，請查閱你的提供者文件。
@@ -304,127 +315,161 @@ npm run dev
**如何將 MCP inspector 註冊為授權伺服器用戶端** -- 若你的授權伺服器支援 [動態用戶端註冊 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)，可略過此步驟，MCP inspector 會自動註冊。 -- 若不支援，需手動將 MCP inspector 註冊為用戶端。 +- 若你的授權伺服器支援 [動態用戶端註冊 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)，MCP inspector 會自動註冊為用戶端，無需手動操作。 +- 若不支援，需手動在授權伺服器註冊 MCP inspector 為用戶端。
-**如何取得使用者身分資訊，以及如何設定授權請求參數** +**如何取得使用者身分資訊及設定授權請求參數** -- 對於 OpenID Connect 提供者：通常需在授權流程請求至少 `openid` 與 `profile` 權限範圍 (Scopes)。這可確保授權伺服器回傳的存取權杖 (Access token) 具備存取 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 所需權限。 +- 對於 OpenID Connect 提供者：通常在啟動授權流程時需請求至少 `openid` 與 `profile` 權限範圍 (Scopes)。這可確保授權伺服器回傳的存取權杖 (Access token) 具備存取 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 所需權限。 注意：部分提供者可能不支援 userinfo endpoint。 -- 對於 OAuth 2.0 / OAuth 2.1 提供者：請查閱你的提供者文件，瞭解如何用存取權杖 (Access token) 取得使用者身分資訊，以及啟動授權流程時需帶哪些參數。 +- 對於 OAuth 2.0 / OAuth 2.1 提供者：請查閱你的提供者文件，瞭解如何使用存取權杖 (Access token) 取得使用者身分資訊，以及啟動授權流程時需帶入哪些參數。
-雖然每個提供者可能有不同需求，以下步驟將引導你整合 MCP inspector 與 MCP 伺服器，並進行提供者專屬設定。 +雖然每個提供者可能有不同需求，下列步驟將引導你依各提供者設定整合 MCP inspector 與 MCP 伺服器。 -### 註冊 MCP inspector 為用戶端 (Register MCP inspector as a client) \{#register-mcp-inspector-as-a-client} +### 註冊 MCP inspector 為用戶端 \{#register-mcp-inspector-as-a-client} 與 [Logto](https://logto.io) 整合非常簡單，因為它是支援標準 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 的 OpenID Connect 提供者。 -由於 Logto 尚未支援動態用戶端註冊，你需手動將 MCP inspector 註冊為 Logto 租戶的用戶端： +由於 Logto 尚未支援動態用戶端註冊，你需手動在 Logto tenant 註冊 MCP inspector 為用戶端： -1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕。複製 **Redirect URL (auto-populated)**，例如 `http://localhost:6274/oauth/callback`。 +1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕。複製 **Redirect URL (auto-populated)**，格式類似 `http://localhost:6274/oauth/callback`。 2. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console）。 -3. 進入「應用程式」分頁，點擊「建立應用程式」。頁面底部點「不使用框架建立應用程式」。 -4. 填寫應用程式資訊，然後點擊「建立應用程式」： - - **選擇應用程式類型**：選「單頁應用程式」。 - - **應用程式名稱**：如「MCP Inspector」。 -5. 在「設定 / Redirect URIs」區塊，貼上剛才複製的 **Redirect URL (auto-populated)**，然後點擊底部「儲存變更」。 -6. 頁面上方會看到「App ID」，請複製。 +3. 前往「Applications」分頁，點擊「Create application」。頁面底部點擊「Create app without framework」。 +4. 填寫應用程式資訊，然後點擊「Create application」： + - **Select an application type**：選擇「Single-page application」 + - **Application name**：輸入應用程式名稱，例如「MCP Inspector」 +5. 在「Settings / Redirect URIs」區塊，貼上剛才複製的 **Redirect URL (auto-populated)**，然後點擊底部「Save changes」。 +6. 頁面頂部卡片會顯示「App ID」，請複製。 7. 回到 MCP inspector，將「App ID」貼到「OAuth Configuration」的「Client ID」欄位。 8. 在「Auth Params」欄位輸入 `{"scope": "openid profile email"}`，確保 Logto 回傳的存取權杖 (Access token) 具備存取 userinfo endpoint 所需權限。 -[Keycloak](https://www.keycloak.org) 是一個開源身分與存取管理解決方案，支援 OpenID Connect 協議。 +[Keycloak](https://www.keycloak.org) 是一套開源身分與存取管理解決方案，支援 OpenID Connect 協議。 雖然 Keycloak 支援動態用戶端註冊，但其註冊 endpoint 不支援 CORS，導致大多數 MCP 用戶端無法直接註冊。因此需手動註冊。 :::note -Keycloak 可用多種方式安裝（[官方說明](https://www.keycloak.org/guides#getting-started)），本教學以 Docker 快速安裝為例。 +Keycloak 可用多種方式安裝（[官方文件](https://www.keycloak.org/guides#getting-started)），本教學以 Docker 為例快速安裝。 ::: -設定 Keycloak 並進行相關配置： +設定 Keycloak 並進行必要配置： -1. 依 [官方文件](https://www.keycloak.org/getting-started/getting-started-docker) 用 Docker 啟動 Keycloak： +1. 依 [官方文件](https://www.keycloak.org/getting-started/getting-started-docker) 以 Docker 執行 Keycloak： ```bash docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev ``` -2. 進入 Keycloak 管理後台 (http://localhost:8080/admin)，以以下帳密登入： +2. 進入 Keycloak 管理後台 (http://localhost:8080/admin)，以下列帳號登入： - 使用者名稱：`admin` - 密碼：`admin` 3. 建立新 Realm： - - 左上角點「Create Realm」 - - 「Realm name」填入 `mcp-realm` - - 點「Create」 + - 左上角點擊「Create Realm」 + - 「Realm name」輸入 `mcp-realm` + - 點擊「Create」 4. 建立測試使用者： - - 左側選單點「Users」 - - 點「Create new user」 + - 左側選單點擊「Users」 + - 點擊「Create new user」 - 填寫使用者資訊： - Username：`testuser` - - 名字與姓氏可任意填 - - 點「Create」 - - 在「Credentials」分頁設定密碼並取消「Temporary」 + - First name、Last name 可任意 + - 點擊「Create」 + - 在「Credentials」分頁設定密碼，並取消勾選「Temporary」 5. 註冊 MCP Inspector 為用戶端： - - 開啟 MCP inspector，點擊「OAuth Configuration」按鈕。複製 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 - - 在 Keycloak 管理後台，左側選單點「Clients」 - - 點「Create client」 + - 開啟 MCP inspector，點擊「OAuth Configuration」按鈕。複製 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback` + - 在 Keycloak 管理後台，左側選單點擊「Clients」 + - 點擊「Create client」 - 填寫用戶端資訊： - Client type：選「OpenID Connect」 - - Client ID：填 `mcp-inspector` - - 點「Next」 + - Client ID：輸入 `mcp-inspector` + - 點擊「Next」 - 「Capability config」頁面： - 確認「Standard flow」已啟用 - - 點「Next」 + - 點擊「Next」 - 「Login settings」頁面： - - 貼上 MCP Inspector callback URL 至「Valid redirect URIs」 - - 「Web origins」填入 `http://localhost:6274` - - 點「Save」 + - 在「Valid redirect URIs」貼上 MCP Inspector callback URL + - 「Web origins」輸入 `http://localhost:6274` + - 點擊「Save」 - 複製「Client ID」（即 `mcp-inspector`） 6. 回到 MCP Inspector： - - 將複製的 Client ID 貼到「OAuth Configuration」的「Client ID」欄位 + - 將 Client ID 貼到「OAuth Configuration」的「Client ID」欄位 - 「Auth Params」欄位輸入以下內容以請求必要權限範圍： ```json { "scope": "openid profile email" } ``` - + + + +Asgardeo 支援標準 API 的動態用戶端註冊，但 endpoint 受保護，需具備相應權限的 access token。本教學將透過 Asgardeo Console 手動註冊。 + +:::note +若你尚未有 Asgardeo 帳號，可[免費註冊](https://asgardeo.io)。 +::: + +請依下列步驟設定 Asgardeo 以供 MCP Inspector 使用： + +1. 登入 [Asgardeo Console](https://console.asgardeo.io) 並選擇你的組織。 + +2. 建立新應用程式： + - 前往 **Applications** → **New Application** + - 選擇 **Single-Page Application** + - 輸入應用程式名稱，如 `MCP Inspector` + - 在 **Authorized Redirect URLs** 欄貼上從 MCP Inspector 複製的 **Redirect URL**（如：`http://localhost:6274/oauth/callback`） + - 點擊 **Create** + +3. 設定協議參數： + - 在 **Protocol** 分頁下： + - 複製自動產生的 **Client ID** + - 在 **Access Token** 區塊將 `Token Type` 切換為 `JWT` + - 點擊 **Update** + +4. 回到 MCP Inspector： + - 開啟 **OAuth Configuration** + - 貼上複製的 **Client ID** + - 在 **Auth Params** 欄輸入以下內容以請求必要權限範圍： + +```json +{ "scope": "openid profile email" } +``` + :::note -這是通用 OpenID Connect 提供者整合指引，請查閱你的提供者文件以獲得細節。 +這是通用 OpenID Connect 提供者整合指引，請查閱你的提供者文件以獲取細節。 ::: 若你的 OpenID Connect 提供者支援動態用戶端註冊，可直接跳至第 8 步設定 MCP inspector；否則需手動註冊： 1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕。複製 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 2. 登入你的 OpenID Connect 提供者後台。 -3. 進入「應用程式」或「用戶端」區塊，建立新應用程式或用戶端。 -4. 若需選擇用戶端類型，請選「單頁應用程式」或「公開用戶端」。 -5. 建立應用程式後，設定 redirect URI，貼上 MCP inspector 的 **Redirect URL (auto-populated)**。 +3. 前往「Applications」或「Clients」區，建立新應用程式或用戶端。 +4. 若需選擇用戶端型態，請選「Single-page application」或「Public client」。 +5. 建立應用程式後，需設定 redirect URI，貼上剛才複製的 **Redirect URL (auto-populated)**。 6. 找到新應用程式的「Client ID」或「Application ID」並複製。 7. 回到 MCP inspector，將「Client ID」貼到「OAuth Configuration」的「Client ID」欄位。 -8. 標準 OIDC 提供者可在「Auth Params」欄位輸入以下內容，以請求 userinfo endpoint 所需權限範圍： +8. 對於標準 OpenID Connect 提供者，可在「Auth Params」欄輸入以下內容以請求 userinfo endpoint 所需權限範圍： ```json { "scope": "openid profile email" } @@ -434,19 +479,19 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM :::note -這是通用 OAuth 2.0 / OAuth 2.1 提供者整合指引，請查閱你的提供者文件以獲得細節。 +這是通用 OAuth 2.0 / OAuth 2.1 提供者整合指引，請查閱你的提供者文件以獲取細節。 ::: 若你的 OAuth 2.0 / OAuth 2.1 提供者支援動態用戶端註冊，可直接跳至第 8 步設定 MCP inspector；否則需手動註冊： 1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕。複製 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 2. 登入你的 OAuth 2.0 / OAuth 2.1 提供者後台。 -3. 進入「應用程式」或「用戶端」區塊，建立新應用程式或用戶端。 -4. 若需選擇用戶端類型，請選「單頁應用程式」或「公開用戶端」。 -5. 建立應用程式後，設定 redirect URI，貼上 MCP inspector 的 **Redirect URL (auto-populated)**。 +3. 前往「Applications」或「Clients」區，建立新應用程式或用戶端。 +4. 若需選擇用戶端型態，請選「Single-page application」或「Public client」。 +5. 建立應用程式後，需設定 redirect URI，貼上剛才複製的 **Redirect URL (auto-populated)**。 6. 找到新應用程式的「Client ID」或「Application ID」並複製。 7. 回到 MCP inspector，將「Client ID」貼到「OAuth Configuration」的「Client ID」欄位。 -8. 請查閱你的提供者文件，瞭解如何取得用於身分資訊的存取權杖 (Access token)。你可能需指定權限範圍或參數。例如，若需 `profile` 權限範圍，可在「Auth Params」欄位輸入： +8. 請查閱你的提供者文件，瞭解如何取得用於使用者身分資訊的存取權杖 (Access token)。你可能需指定權限範圍或參數。例如，若需 `profile` 權限範圍，可在「Auth Params」欄輸入： ```json { "scope": "profile" } @@ -455,7 +500,7 @@ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADM -### 設定 MCP Auth (Set up MCP auth) \{#set-up-mcp-auth} +### 設定 MCP Auth \{#set-up-mcp-auth} 在你的 MCP 伺服器專案中，需安裝 MCP Auth SDK 並設定使用你的授權伺服器中繼資料。 @@ -482,7 +527,7 @@ npm install mcp-auth -MCP Auth 需要授權伺服器中繼資料才能初始化。根據你的提供者： +MCP Auth 需要授權伺服器中繼資料才能初始化。依你的提供者而定： @@ -496,22 +541,31 @@ MCP Auth 需要授權伺服器中繼資料才能初始化。根據你的提供 -簽發者 (Issuer) URL 可在 Keycloak 管理後台的「mcp-realm」下「Realm settings / Endpoints」區塊，點選「OpenID Endpoint Configuration」連結。JSON 文件中的 `issuer` 欄位即為你的 issuer URL，格式類似 `http://localhost:8080/realms/mcp-realm`。 +簽發者 (Issuer) URL 可在 Keycloak 管理後台的「mcp-realm」下「Realm settings / Endpoints」區塊，點擊「OpenID Endpoint Configuration」連結。JSON 文件中的 `issuer` 欄位即為你的 issuer URL，格式如 `http://localhost:8080/realms/mcp-realm`。 + + + 你可以在 Asgardeo Console 查找 issuer URL。進入已建立的應用程式，開啟 **Info** 分頁，**Issuer** 欄位即會顯示，格式如下： + `https://api.asgardeo.io/t//oauth2/token` + + + + + -以下程式碼假設授權伺服器支援 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 以取得使用者身分資訊。若你的提供者不支援，請查閱文件並以正確 URL 取代 userinfo endpoint 變數。 +以下程式碼假設授權伺服器支援 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 以取得使用者身分資訊。若你的提供者不支援此 endpoint，請查閱文件並將 userinfo endpoint 變數替換為正確網址。 -如前所述，OAuth 2.0 沒有定義標準方式來取得使用者身分資訊。以下程式碼假設你的提供者有特定 endpoint 可用存取權杖 (Access token) 取得身分資訊。請查閱文件並以正確 URL 取代 userinfo endpoint 變數。 +如前所述，OAuth 2.0 並未定義標準的使用者身分資訊取得方式。以下程式碼假設你的提供者有特定 endpoint 可用存取權杖 (Access token) 取得使用者身分資訊。請查閱文件並將 userinfo endpoint 變數替換為正確網址。 @@ -531,7 +585,7 @@ def whoami() -> dict[str, Any]: """回傳目前使用者資訊的工具。""" return ( mcp_auth.auth_info.claims - if mcp_auth.auth_info # 由 Bearer auth middleware 填入 + if mcp_auth.auth_info # 這會由 Bearer auth middleware 填入 else {"error": "Not authenticated"} ) @@ -569,11 +623,11 @@ app.use(mcpAuth.bearerAuth(verifyToken)); -## 檢查點：以驗證 (Authentication) 執行 `whoami` 工具 (Checkpoint: Run the `whoami` tool with authentication) \{#checkpoint-run-the-whoami-tool-with-authentication} +## 檢查點：以驗證 (Authentication) 執行 `whoami` 工具 \{#checkpoint-run-the-whoami-tool-with-authentication} -重新啟動 MCP 伺服器，並在瀏覽器開啟 MCP inspector。當你點擊「Connect」按鈕時，應會被導向授權伺服器的登入頁面。 +重啟 MCP 伺服器並在瀏覽器開啟 MCP inspector。當你點擊「Connect」按鈕時，應會被導向授權伺服器的登入頁面。 -登入後回到 MCP inspector，重複前述步驟執行 `whoami` 工具。這次你應該會看到授權伺服器回傳的使用者身分資訊。 +登入並返回 MCP inspector 後，重複前述步驟執行 `whoami` 工具。這次你應該會看到授權伺服器回傳的使用者身分資訊。 ![MCP inspector whoami 工具結果](/docs-assets/images/tutorials/whoami/result.png) @@ -596,16 +650,16 @@ app.use(mcpAuth.bearerAuth(verifyToken)); ## 結語 (Closing notes) \{#closing-notes} -🎊 恭喜你！已成功完成本教學。讓我們回顧一下： +🎊 恭喜你！你已成功完成本教學。讓我們回顧一下： -- 建立具備 `whoami` 工具的基本 MCP 伺服器 +- 建立一個具備 `whoami` 工具的基本 MCP 伺服器 - 透過 MCP Auth 將 MCP 伺服器與授權伺服器整合 - 設定 MCP Inspector 以驗證 (Authentication) 使用者並取得其身分資訊 你也可以進一步探索進階主題，包括： - 使用 [JWT (JSON Web Token)](https://auth.wiki/jwt) 進行驗證 (Authentication) 與授權 (Authorization) -- 利用 [資源標示符 (Resource indicators, RFC 8707)](https://auth-wiki.logto.io/resource-indicator) 指定存取資源 +- 利用 [資源標示符 (Resource indicators, RFC 8707)](https://auth-wiki.logto.io/resource-indicator) 指定存取的資源 - 實作自訂存取控制機制，如 [基於角色的存取控制 (RBAC, Role-based access control)](https://auth.wiki/rbac) 或 [屬性型存取控制 (ABAC, Attribute-based access control)](https://auth.wiki/abac) -歡迎參閱其他教學與文件，充分發揮 MCP Auth 的效能。 \ No newline at end of file +歡迎參閱其他教學與文件，充分發揮 MCP Auth 的強大功能。 \ No newline at end of file