Okta MCP Server

Okta MCP 服务

此 MCP 服务使 Claude 能够与 Okta 的用户管理系统交互，提供全面的用户和群组管理功能以及入职自动化。

前置条件

• Node.js（v16 或更高版本）
• Claude 桌面应用
• Okta 开发者账户
• Okta 管理员 API 令牌

设置说明

1. 创建 Okta 开发者账户

• 前往 Okta 开发者控制台
• 创建新账户或登录现有账户
• 记下你的 Okta 域名（例如，dev-123456.okta.com）

2. 创建 API 令牌

• 在 Okta 开发者控制台中，前往 Security > API > Tokens
• 点击“Create Token”
• 为令牌起一个有意义的名称（例如，“MCP Server Token”）
• 复制令牌值（之后将无法再次查看）

3. 初始项目设置

安装依赖项：

npm install

4. 配置 Claude 桌面应用

打开 Claude 桌面应用配置文件：

对于 MacOS：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

对于 Windows：

code %AppData%\Claude\claude_desktop_config.json

添加或更新配置：

{
    "mcpServers": {
        "okta": {
            "command": "node",
            "args": [
                "PATH_TO_PROJECT_DIRECTORY/dist/index.js"
            ],
            "env": {
                "OKTA_ORG_URL": "https://your-domain.okta.com",
                "OKTA_API_TOKEN": "your-api-token"
            }
        }
    }
}

保存文件并重启 Claude 桌面应用。

可用工具

此服务提供以下工具：

用户管理

get_user

从 Okta 获取详细的用户信息，包括：

• 用户详情（ID、状态）
• 账户日期（创建、激活、上次登录等）
• 个人信息（姓名、电子邮件）
• 雇佣详情
• 联系信息
• 地址
• 偏好设置

find_users_by_attribute

通过任意个人资料属性搜索用户，并支持高级筛选：

• 支持的属性：firstName、lastName、email、manager、department、title、division、organization、employeeNumber、costCenter、userType、city、state
• 搜索运算符：
  • eq（精确匹配）- 适用于所有属性
  • sw（以……开头）- 适用于所有属性
  • ew（以……结尾）- 适用于大多数属性
  • co（包含）- 适用于部分属性（firstName、lastName、email）
  • pr（存在）- 适用于所有属性（查找该属性具有任意值的用户）
• 功能：
  • 使用 Okta 原生搜索以获得最佳性能
  • 对不支持的运算符自动回退到客户端筛选
  • 对搜索结果中的敏感属性进行 PII 脱敏
  • 状态筛选（包含或排除非活跃用户）
  • 支持分页，并可自定义限制

list_users

列出 Okta 中的用户，并支持可选筛选和分页：

• 支持 SCIM 筛选表达式（例如，'profile.firstName eq "John"'）
• 跨多个字段进行自由文本搜索
• 排序选项（按状态、创建日期等）
• 支持分页，并可自定义限制

activate_user

在 Okta 中激活用户：

• 可选择发送激活电子邮件
• 将用户状态更新为活跃

suspend_user

在 Okta 中暂停用户

unsuspend_user

取消暂停之前在 Okta 中暂停的用户

delete_user

从 Okta 删除用户（注意：必须先停用用户）

get_user_last_location

从 Okta 系统日志中获取用户最后已知的位置和登录信息

群组管理

list_groups

列出 Okta 中的用户群组，并支持可选筛选和分页：

• 群组筛选表达式（例如，'type eq "OKTA_GROUP"'）
• 跨群组字段进行自由文本搜索
• 排序选项（按名称、类型等）
• 支持分页，并可自定义限制

create_group

在 Okta 中创建新群组，并指定名称和可选描述

get_group

获取特定群组的详细信息

delete_group

从 Okta 删除群组

assign_user_to_group

将用户分配到 Okta 中的群组

remove_user_from_group

从 Okta 中将用户移出群组

list_group_users

列出特定群组中的所有用户，支持分页

入职自动化（实验性）

注意： 入职自动化工具处于实验阶段，可能会受到 Okta API 限制的影响，或有所变更。在生产环境中使用时请谨慎。

bulk_user_import

从 CSV 字符串导入多个用户：

• 根据 CSV 数据创建用户账号
• 可选：激活用户
• 可选：发送电子邮件通知
• 分配到默认群组

assign_users_to_groups

根据属性映射将多个用户分配到群组：

• 将用户属性（部门、职务等）映射到特定群组
• 根据属性批量分配用户

provision_applications

为多个用户配置应用访问权限：

• 将用户分配到应用
• 支持批量配置

run_onboarding_workflow

根据 CSV 数据为多个用户运行完整的入职工作流：

• 从 CSV 导入用户
• 自动激活
• 根据属性分配群组
• 配置应用访问权限
• 配置欢迎邮件

在 Claude 中的示例用法

完成设置后，你可以使用如下命令：

用户管理

• “显示 userId XXXX 对应用户的详细信息”
• “查找工程部门的所有用户”
• “搜索名字以 ‘John’ 开头的用户”
• “查找电子邮件中包含 ‘gmail’ 的用户”
• “显示所有已分配部门的用户”
• “列出职务为 ‘Manager’ 的用户”
• “用户 [email protected] 的状态是什么？”
• “用户 [email protected] 上次登录是什么时候？”
• “查找上个月创建的用户”
• “激活 ID 为 XXXX 的用户”
• “暂停 ID 为 XXXX 的用户”
• “删除 ID 为 XXXX 的已停用用户”
• “用户 XXXX 上次从哪里登录？”

高级用户搜索

• “查找 Sales 部门的所有用户” → 使用 find_users_by_attribute，条件为 department eq "Sales"
• “显示电子邮件以 ‘admin’ 开头的用户” → 使用 email sw "admin"
• “查找已分配任意经理的用户” → 使用 manager pr
• “列出姓氏中包含 ‘smith’ 的用户” → 使用 lastName co "smith"

群组管理

• “显示我的 Okta 组织中的所有群组”
• “列出包含 ‘admin’ 一词的群组”
• “创建一个名为 ‘Marketing Team’ 的新群组”
• “获取 ID 为 XXXX 的群组的详细信息”
• “删除 ID 为 XXXX 的群组”
• “将用户 XXXX 添加到群组 YYYY”
• “将用户 XXXX 从群组 YYYY 中移除”
• “列出 ‘Finance’ 群组中的所有用户”

入职自动化

• “从以下 CSV 数据导入这些用户：[CSV 内容]”
• “根据用户的部门属性将用户分配到群组”
• “为这 5 位用户配置应用访问权限”
• “为以下新员工运行完整的入职工作流：[CSV 内容]”

错误处理

服务包含完善的错误处理机制，可处理：

• 未找到用户或群组（404 错误）
• API 身份验证问题
• 用户个人资料缺失或无效
• 一般 API 错误
• CSV 解析问题
• 用户属性映射失败
• 应用配置错误
• 不支持的搜索运算符（自动回退到其他方法）

故障排除

常见问题

Claude 中未显示工具：

• 检查 Claude Desktop 日志：tail -f ~/Library/Logs/Claude/mcp*.log
• 确认所有环境变量均已正确设置
• 确保 index.js 的路径是正确的绝对路径

身份验证错误：

• 确认 API 令牌有效
• 检查 OKTA_ORG_URL 是否包含完整的 https:// URL
• 确保 Okta 域名正确

服务连接问题：

• 检查服务是否已成功构建
• 确认 build/index.js 的文件权限（应为 755）
• 尝试直接运行服务：node /path/to/build/index.js

搜索问题：

• 某些搜索运算符不适用于所有属性（例如，contains 不适用于 department）
• 需要时，服务会自动回退到其他搜索方法
• 查看响应消息，了解使用了哪种搜索方法

查看日志

查看服务日志：

对于 MacOS/Linux：

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

对于 Windows：

Get-Content -Path "$env:AppData\Claude\Logs\mcp*.log" -Wait -Tail 20

环境变量

如果遇到环境变量错误，请确认：

• OKTA_ORG_URL：应为完整的 URL（例如，“https://dev-123456.okta.com”）
• OKTA_API_TOKEN：应为有效的 API 令牌

安全注意事项

• 妥善保管 API 令牌
• 不要将凭据提交到版本控制系统
• 使用环境变量存储敏感数据
• 定期轮换 API 令牌
• 在 Okta Admin Console 中监控 API 使用情况
• 对 API 调用实施速率限制
• 为 API 令牌使用所需的最低权限
• 已为敏感搜索参数启用 PII 屏蔽

搜索运算符兼容性

不同的 Okta 属性支持不同的搜索运算符：

Attribute Type	eq	sw	ew	co	pr
firstName, lastName	✅	✅	✅	✅	✅
email, login	✅	✅	✅	✅	✅
department, title	✅	✅	❌	❌*	✅
division, organization	✅	✅	❌	❌*	✅
All attributes	✅	✅	⚠️	⚠️	✅

*❌ = 不支持，⚠️ = 可能不适用于所有属性

注意： 如果不支持某个运算符，服务会自动回退到客户端筛选，以确保兼容性。

类型

服务包含用于 Okta 用户和群组数据的 TypeScript 接口：

interface OktaUserProfile {
  login: string;
  email: string;
  secondEmail?: string;
  firstName: string;
  lastName: string;
  displayName: string;
  nickName?: string;
  organization: string;
  title: string;
  division: string;
  department: string;
  employeeNumber: string;
  userType: string;
  costCenter: string;
  mobilePhone?: string;
  primaryPhone?: string;
  streetAddress: string;
  city: string;
  state: string;
  zipCode: string;
  countryCode: string;
  preferredLanguage: string;
  profileUrl?: string;
}

interface OktaUser {
  id: string;
  status: string;
  created: string;
  activated: string;
  lastLogin: string;
  lastUpdated: string;
  statusChanged: string;
  passwordChanged: string;
  profile: OktaUserProfile;
}

interface OktaGroup {
  id: string;
  created: string;
  lastUpdated: string;
  lastMembershipUpdated: string;
  type: string;
  objectClass: string[];
  profile: {
    name: string;
    description: string;
  };
}

入职 CSV 格式

使用批量导入或入职工作流工具时，CSV 应包含以下表头：

• firstName（必填）
• lastName（必填）
• email（必填）
• department（可选）
• title（可选）
• mobilePhone（可选）

示例：

firstName,lastName,email,department,title,mobilePhone
John,Doe,[email protected],Engineering,Senior Developer,+1-555-123-4567
Jane,Smith,[email protected],Marketing,Director,+1-555-987-6543

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

如果遇到任何问题：

• 查看上方的故障排除部分
• 查看 Claude Desktop 日志
• 检查服务的错误输出
• 查看 Okta 开发者文档

注意：欢迎提交 PR！