diff --git a/packages/@okta/vuepress-site/docs/concepts/mcp-server/index.md b/packages/@okta/vuepress-site/docs/concepts/mcp-server/index.md index 8e52e72e92d..66b9d73f636 100644 --- a/packages/@okta/vuepress-site/docs/concepts/mcp-server/index.md +++ b/packages/@okta/vuepress-site/docs/concepts/mcp-server/index.md @@ -9,7 +9,7 @@ meta: The Okta Model Context Protocol (MCP) server securely connects AI agents and Large Language Models (LLMs) to an Okta org. This abstraction layer enables AI agents and LLMs to interact with Okta admin management APIs using natural language commands. -The Okta MCP server translates natural language instructions into structured API calls between LLM clients and an Okta org. This approach reduces security risks and complexity when connecting autonomous AI agents to Identity and Access Management (IAM) systems. The architecture ensures that AI actions remain secure, properly scoped, and fully auditable. +The Okta MCP server translates natural language instructions into structured API calls between LLM clients and an Okta org using Okta's Python SDK v3.4.1. This approach reduces security risks and complexity when connecting autonomous AI agents to Identity and Access Management (IAM) systems. The architecture ensures that AI actions remain secure, properly scoped, and fully auditable. IT admins, developers, and security professionals use the Okta MCP server to automate Okta administration through AI-powered interfaces. @@ -18,7 +18,7 @@ IT admins, developers, and security professionals use the Okta MCP server to aut The Okta MCP server addresses security, automation, and integration requirements. - **Security features:** The Okta MCP server reduces risks by acting as a security checkpoint for AI-initiated actions. -- **Access control**: The server enforces the principle of least privilege through scoped API permissions and pre-defined tool definitions. +- **Access control**: The server enforces the principle of least privilege through scope-based tool loading and pre-defined tool definitions. - **Compliance**: The system provides audit trails for compliance and security monitoring. - **Operational efficiency**: Admins execute identity operations, such as security playbooks and repetitive tasks, with natural language commands. - **Standardized communication**: The server uses a standardized protocol to eliminate the need for custom middleware or integration code. @@ -34,7 +34,7 @@ The Okta MCP server implements AI agent identity security through the following The Okta MCP server ensures AI agents possess only the minimum permissions required for specific tasks. - The server manages authentication through OAuth 2.0 scopes and environment variables. -- The server validates that requested actions match the granted API scopes of the Okta admin app created for the MCP server. +- The server dynamically registers tools based on the granted API scopes of the Okta admin app, ensuring the LLM only sees authorized capabilities. - The system blocks unauthorized API calls before those calls reach the org. ### Audibility and traceability @@ -58,7 +58,7 @@ The following process describes how an LLM translates a request and how the Okta 1. **User command**: A user or AI agent (such as GitHub Copilot or Claude Desktop) sends a natural language command through an MCP-compatible client to perform an Okta task. 1. **Client routing**: The MCP client (which hosts the AI agent) securely routes the command to the active Okta MCP server instance. 1. **Server authentication**: The Okta MCP server authenticates with the org using the pre-configured credentials, such as Device Authorization Grant or Private Key JWT. -1. **Scope validation**: The Okta MCP server translates the natural language command into structured management API calls and executes those calls. The server then verifies that the granted API scopes (permissions) in the okta admin app cover all required actions, enforcing the principle of least privilege. +1. **Scope validation**: The Okta MCP server validates scope twice. First, it filters tools during startup. Second, it uses a scope guard decorator to confirm active permissions immediately before executing a command and calling the API. 1. **Response handling**: The APIs return a technical response to the Okta MCP server. 1. **Natural language response**: The Okta MCP server passes the data to the LLM, which formats the information into a natural language response for the user. @@ -70,9 +70,10 @@ The Okta MCP server enables AI agents to perform the following actions through n | --- | --- | | User management | Create, list, retrieve, update, deactivate, delete users, and manage user profile attributes. | | Group administration | Create, list, retrieve, update, and delete groups. Add and remove users from groups, and view group memberships. | -| Application management | List, retrieve, create, update, activate and deactivate apps. View app assignments. | -| Policy and security management | Manage authentication policies, password rules, and MFA configurations. | -| System monitoring and logs | Filter System Logs and generate security audit reports. | +| App management | List, retrieve, create, update, activate and deactivate apps. View app assignments. | +| Policy and security management | Manage authentication policies, password rules, MFA configurations, and device assurance policies. | +| System monitoring and logs | Filter System Logs, generate security audit reports, and query specific sign-in failures. | +| Brands and customization | Manage brands, themes, custom pages, email templates, and custom domains. | ## Security and authentication diff --git a/packages/@okta/vuepress-site/docs/guides/configure-mcp-authentication/main/index.md b/packages/@okta/vuepress-site/docs/guides/configure-mcp-authentication/main/index.md index 3975cf986ca..c3341c45cb8 100644 --- a/packages/@okta/vuepress-site/docs/guides/configure-mcp-authentication/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/configure-mcp-authentication/main/index.md @@ -5,14 +5,15 @@ meta: content: Create an Okta admin app integration and obtain the credentials to connect your Okta MCP server. --- -Create an Okta admin app integration and configure authentication credentials to authorize the Model Context Protocol (MCP) server. +Create an Okta admin app integration, configure authentication credentials, and grant required OAuth 2.0 scopes to authorize the Model Context Protocol (MCP) server tools. --- #### Learning outcomes * Implement a device authorization grant or private key JWT to authorize the Okta MCP server. -* Get the client ID and security keys for server configuration. +* Get the client ID and security keys and identify the OAuth 2.0 scopes that are required for your specific use cases. +* Configure scope-based tool loading to match your app permissions. #### What you need @@ -47,7 +48,7 @@ To connect the Okta MCP server to an Okta org, create an Okta app integration an 1. Select **Native Application** as the app type. 1. Click **Next**. 1. Enter an **App integration name**, such as "Okta MCP Server". -1. In **Grant type**, select **Device Authorization**. +1. In the **Grant type**, select **Device Authorization**. 1. Configure the redirect URIs: * **Sign-in redirect URIs:** `com.oktapreview.{yourOktaDomain}:/callback` * **Sign-out redirect URIs:** `com.okta.{yourOktaDomain}:/` @@ -72,7 +73,7 @@ After you create the app, follow these steps to grant the required API scopes: 1. Go to the **General** tab and copy the **Client ID** and **Sign-in redirect URIs**. - > **Note:** Save these values to configure your Okta MCP server (See [Okta Device Authorization Grant Guide](/docs/guides/device-authorization-grant/main/)). + > **Note:** Save these values and the list of granted scopes to configure your Okta MCP server, see [Okta Device Authorization Grant Guide](/docs/guides/device-authorization-grant/main/).
@@ -152,7 +153,7 @@ You can either generate the key in Okta (recommended) and copy it in PEM format, ### Okta API scopes and admin role -1. Go to the **Okta API Scopes** tab and grant the required API scopes. +1. Go to the **Okta API Scopes** tab and grant the required API scopes. Ensure you grant `okta.deviceAssurance.manage` or `okta.brands.manage` if the server needs to perform write operations for security or branding. 1. Go to the **Admin roles** tab, and click **Edit assignments**. 1. Select an admin role (see [Learn about administrators](https://help.okta.com/okta_help.htm?type=oie&id=administrators-learn-about-admins)) and click **Save changes**. 1. Go to the **General** tab and copy the **Client ID**. @@ -161,6 +162,64 @@ You can either generate the key in Okta (recommended) and copy it in PEM format, You've created an app integration, configured the authentication flow, and granted the required API scopes for your Okta MCP server. +## Configure scope-based tool loading + +The Okta MCP server uses a scope-based tool loading mechanism to ensure that only the tools your app is authorized to use are exposed to the LLM. + +### How it works + +* Startup filtering: After authentication completes, the server reads the scopes listed in your `OKTA_SCOPES` environment variable. The server compares each tool's required scope against your configured scopes. Tools whose required scope isn’t present are silently removed from the tool registry and don’t appear in `tools/list`. + +* Runtime enforcement: A `@require_scopes decorator` on each tool provides a second layer of enforcement. If a scope is missing at call time (for example, if a token refreshes with fewer scopes), the tool returns an error message instead of making an API call. + +### Scope-to-tool mapping + +| OAuth 2.0 scope | Tools unlocked | +|---|---| +| `okta.users.read` | `list_users`, `get_user`, `get_user_profile_attributes` | +| `okta.users.manage` | `create_user`, `update_user`, `deactivate_user`, `delete_deactivated_user` | +| `okta.groups.read` | `list_groups`, `get_group`, `list_group_users`, `list_group_apps` | +| `okta.groups.manage` | `create_group`, `update_group`, `delete_group`, `add_user_to_group`, `remove_user_from_group` | +| `okta.apps.read` | `list_applications`, `get_application` | +| `okta.apps.manage` | `create_application`, `update_application`, `delete_application`, `activate_application`, `deactivate_application` | +| `okta.policies.read` | `list_policies`, `get_policy`, `list_policy_rules`, `get_policy_rule` | +| `okta.policies.manage` | `create_policy`, `update_policy`, `delete_policy`, `activate_policy`, `deactivate_policy`, `create_policy_rule`, `update_policy_rule`, `delete_policy_rule`, `activate_policy_rule`, `deactivate_policy_rule` | +| `okta.deviceAssurance.read` | `list_device_assurance_policies`, `get_device_assurance_policy` | +| `okta.deviceAssurance.manage` | `create_device_assurance_policy`, `replace_device_assurance_policy`, `delete_device_assurance_policy` | +| `okta.logs.read` | `get_logs` | +| `okta.brands.read` | `list_brands`, `get_brand`, `list_brand_domains`, `list_brand_themes`, `get_brand_theme`, `get_sign_in_page_resources`, `get_customized_sign_in_page`, `get_default_sign_in_page`, `get_preview_sign_in_page`, `list_sign_in_widget_versions`, `get_error_page_resources`, `get_customized_error_page`, `get_default_error_page`, `get_preview_error_page`, `get_sign_out_page_settings` | +| `okta.brands.manage` | `create_brand`, `replace_brand`, `delete_brand`, `replace_brand_theme`, `upload_brand_theme_logo`, `delete_brand_theme_logo`, `upload_brand_theme_favicon`, `delete_brand_theme_favicon`, `upload_brand_theme_background_image`, `delete_brand_theme_background_image`, `replace_customized_sign_in_page`, `delete_customized_sign_in_page`, `replace_preview_sign_in_page`, `delete_preview_sign_in_page`, `replace_customized_error_page`, `delete_customized_error_page`, `replace_preview_error_page`, `delete_preview_error_page`, `replace_sign_out_page_settings` | +| `okta.templates.read` | `list_email_templates`, `get_email_template`, `list_email_customizations`, `get_email_customization`, `get_email_customization_preview`, `get_email_default_content`, `get_email_default_content_preview`, `get_email_settings` | +| `okta.templates.manage` | `create_email_customization`, `replace_email_customization`, `delete_email_customization`, `delete_all_email_customizations`, `replace_email_settings`, `send_test_email` | +| `okta.domains.read` | `list_custom_domains`, `get_custom_domain` | +| `okta.domains.manage` | `create_custom_domain`, `replace_custom_domain`, `delete_custom_domain`, `upsert_custom_domain_certificate`, `verify_custom_domain` | +| `okta.emailDomains.read` | `list_email_domains`, `get_email_domain` | +| `okta.emailDomains.manage` | `create_email_domain`, `replace_email_domain`, `delete_email_domain`, `verify_email_domain` | + + > **Note:** Scopes follow the pattern `okta..read` for read-only access and `okta..manage` for full read and write access. The `manage` scope implicitly enables all corresponding read operations on that resource. + +### Enable a tool group + +To activate specific tools, complete the following configuration steps: + +1. Grant the scope to your Okta app: + + a. Open your app integration in the Admin Console. + b. Select the **Okta API scopes** tab and click **Grant** for each scope that you want to enable. + +1. Add the scope to client configurations: + + a. Update the `OKTA_SCOPES` value in your `mcp.json` or `settings.json` file. + b. Include the required scopes as a space-separated string: + + ``` + "OKTA_SCOPES": "okta.users.read okta.groups.read okta.brands.read okta.templates.read" + ``` + +1. Restart the client: Restart your MCP client app to apply the updated scope configurations. + + > **Note:** Start with the minimum set of scopes that your use case requires. For example, if you only need to read users and brands, use `okta.users.read okta.brands.read`. Managing scopes enables write operations, so only grant them when required. + ## Next Steps -[Configure, start, and test](/docs/guides/start-mcp-server/main/) the Okta MCP server to connect the local environment to your org. +[Configure, start, and test](/docs/guides/start-mcp-server/main/) ensuring you define the `OKTA_SCOPES` environment variable to load your authorized tools. diff --git a/packages/@okta/vuepress-site/docs/guides/mcp-server/main/index.md b/packages/@okta/vuepress-site/docs/guides/mcp-server/main/index.md index 9f75eb88dc6..ff6d2175cb8 100644 --- a/packages/@okta/vuepress-site/docs/guides/mcp-server/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/mcp-server/main/index.md @@ -8,13 +8,13 @@ sections: - main --- -Get started with the Okta Model Context Protocol (MCP) server setup and prerequisites. +Get started with the Okta Model Context Protocol (MCP) server setup, prerequisites, and Python SDK v3.4.1 requirements. --- #### Learning outcomes -* Verify the prerequisites and initialize your local Okta MCP server project. +* Verify the prerequisites, ensure SDK v3.4.1 compatibility, and initialize your local Okta MCP server project. #### What you need @@ -27,7 +27,7 @@ Get started with the Okta Model Context Protocol (MCP) server setup and prerequi ## Overview -This guide explains how to initialize the Okta MCP server project and install the required dependencies. To learn about the Okta MCP server architecture, see the [introductory page](/docs/concepts/mcp-server/) on the Okta MCP server. +This guide explains how to initialize the Okta MCP server project and install the required dependencies, including Okta's Python SDK v3.4.1. See [Manage Okta APIs with the Okta MCP server](/docs/concepts/mcp-server/). --- @@ -47,7 +47,7 @@ Install and configure the Okta MCP server project for integration with your chos cd okta-mcp-server ``` -1. Install dependencies and set up the project: +1. Install the Okta Python SDK v3.4.1 and other required dependencies and set up the project: ```shell uv sync @@ -57,4 +57,4 @@ Install and configure the Okta MCP server project for integration with your chos ## Next steps -[Set up Okta app authentication](/docs/guides/configure-mcp-authentication/main/) for the Okta MCP server to create the required credentials and grant API scopes. +[Set up Okta app authentication](/docs/guides/configure-mcp-authentication/main/) for the Okta MCP server to create the required credentials and grant the specific OAuth 2.0 scopes that are required to load tools at startup. diff --git a/packages/@okta/vuepress-site/docs/guides/start-mcp-server/index.md b/packages/@okta/vuepress-site/docs/guides/start-mcp-server/index.md index 11605008a2b..695c1a4c0f4 100755 --- a/packages/@okta/vuepress-site/docs/guides/start-mcp-server/index.md +++ b/packages/@okta/vuepress-site/docs/guides/start-mcp-server/index.md @@ -2,7 +2,7 @@ title: Configure, start, and test the Okta MCP server meta: - name: description - content: Set up your local environment variables and start the Okta Model Context Protocol (MCP) server to connect your AI agent to your org. + content: Set up your local environment variables (including OKTA_SCOPES), start the Okta Model Context Protocol (MCP) server to connect your AI agent to your org, and test connections to Device Assurance and Brand customization tools. layout: Guides sections: - main diff --git a/packages/@okta/vuepress-site/docs/guides/start-mcp-server/main/index.md b/packages/@okta/vuepress-site/docs/guides/start-mcp-server/main/index.md index cc60dfa0901..2e21e7d5a7b 100644 --- a/packages/@okta/vuepress-site/docs/guides/start-mcp-server/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/start-mcp-server/main/index.md @@ -5,7 +5,7 @@ meta: content: Set up your local environment variables and start the Okta Model Context Protocol (MCP) server to connect your AI agent to your org. --- -Set up your local environment variables and start the Okta Model Context Protocol (MCP) server to connect your AI agent to your org. +Set up your local environment variables (including OKTA_SCOPES), start the Okta Model Context Protocol (MCP) server to connect your AI agent to your org, and test connections to device assurance** and **brand customization** tools. --- @@ -14,7 +14,7 @@ Set up your local environment variables and start the Okta Model Context Protoco * Map your Okta app credentials to MCP environment variables. * Start the Okta MCP server. * Verify the connection between the Okta MCP server and your org. -* Use natural language commands to perform admin tasks (such as managing users, groups, apps, and policies). +* Use natural language commands to perform admin tasks (such as managing users, groups, apps, and policies). You can also customize your brand, maintain device compliance, and perform log analysis. #### What you need @@ -49,7 +49,7 @@ The Okta MCP server works with any MCP-compatible client. While this guide focus 1. Open the **Copilot chat** view in VS Code. 1. Enable agent mode by following the steps in the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode#_enable-agent-mode-in-vs-code). 1. Update your VS Code settings to include the Okta MCP server configuration: - * Press `Command + Shift + P` (MacOS) or `Ctrl + Shift + P` (Windows) open the command palette. + * Press `Command + Shift + P` (macOS) or `Ctrl + Shift + P` (Windows) open the command palette. * Type "Preferences: Open User Settings (JSON)" and press **Enter**. 1. Define the connection parameters for the Okta MCP server: * Create a folder named `.vscode` in your project directory. @@ -164,7 +164,7 @@ The steps to start the server vary by client. To start the Okta MCP server in VS | :--- | :--- | :--- | | `OKTA_ORG_URL` | Your Okta tenant org URL (for example, `https://integrator-1234567.okta.com`). | Yes | | `OKTA_CLIENT_ID` | The client ID copied from your Okta app. | Yes | - | `OKTA_SCOPES` | A space-separated list of API scopes you granted to the app (example: `okta.users.read okta.groups.read`). **Note:** Don't include scopes that you haven't granted to the app. | Yes | + | `OKTA_SCOPES` | A space-separated list of API scopes that you granted to the app (example: `okta.users.read okta.groups.read`). The server uses this list to dynamically load authorized tools at startup. **Note:** Don't include scopes that you haven't granted to the app. | Yes | | `OKTA_PRIVATE_KEY` | Your private key in PEM format (starts with `-----BEGIN PRIVATE KEY-----`). | Private key JWT only | | `OKTA_KEY_ID` | The key ID (KID) for your private key. | Private key JWT only | @@ -222,14 +222,19 @@ Use the following conversational prompts to interact with your Okta org: 1. Manage apps: * Show me all active apps in my org. 1. Security and auditing: - * Show me all failed sign-in attempts from the last 24 hours. + * Show me recent sign-in failures using the `login_failures` tool. * Generate a security audit report for the last 30 days. Highlight all changes to user and group memberships. 1. Policy management: - * Create a password policy that requires 12 characters with special characters for the engineering group. + * Create a macOS device assurance policy requiring OS 14.2.1 and disk encryption. * Show me a list of all active users in the **Finance** group with the Salesforce app who haven't signed in to Okta in the last 60 days. * Evaluate the policy's logic and compare it to the user's context (such as, their device, and OS) from the log. +1. Brand Customization: ->**Note:** All destructive actions such as deleting groups, apps, policies, policy rules, or deactivating and deleting users require explicit confirmation using the [MCP Elicitation API](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation). The confirmation experience depends on the client: + * Change the primary color of my brand theme to `#FF5733`. + * Show me the sign-in page preview. + + +>**Note:** All destructive actions such as deleting groups, apps, policies, device assurance policies, or deactivating and deleting users require explicit confirmation using the [MCP Elicitation API](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation). The confirmation experience depends on the client: > >* Clients that support elicitation: The user sees a native chat UI dialog to accept, decline, or cancel the request. >* Clients that don’t support elicitation: The tool returns a JSON payload describing the pending action so the LLM can relay the confirmation request to the user.