Okta MCP Server

Interaja com o sistema de gerenciamento de usuários do Okta para automação abrangente de usuários, grupos e integração.

GitHub
22
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

Okta MCP Server

Este servidor MCP permite que o Claude interaja com o sistema de gerenciamento de usuários do Okta, fornecendo recursos abrangentes de gerenciamento de usuários e grupos, além de automação de onboarding.

Okta Server MCP server

Pré-requisitos

  • Node.js (v16 ou superior)
  • Claude Desktop App
  • Okta Developer Account
  • Admin API Token do Okta

Instruções de Configuração

1. Crie uma conta de desenvolvedor Okta

  • Acesse o Okta Developer Console
  • Crie uma nova conta ou entre em uma existente
  • Anote seu domínio Okta (ex.: dev-123456.okta.com)

2. Crie um API Token

  • No Okta Developer Console, vá para Security > API > Tokens
  • Clique em "Create Token"
  • Dê ao seu token um nome significativo (ex.: "MCP Server Token")
  • Copie o valor do token (você não poderá vê-lo novamente)

3. Configuração inicial do projeto

Instale as dependências:

npm install

4. Configure o Claude Desktop

Abra o arquivo de configuração do Claude Desktop:

Para MacOS:

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

Para Windows:

code %AppData%\Claude\claude_desktop_config.json

Adicione ou atualize a configuração:

{
    "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"
            }
        }
    }
}

Salve o arquivo e reinicie o Claude Desktop.

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas:

Gerenciamento de Usuários

get_user

Recupera informações detalhadas do usuário do Okta, incluindo:

  • Detalhes do usuário (ID, Status)
  • Datas da conta (Criado, Ativado, Último login, etc.)
  • Informações pessoais (Nome, Email)
  • Detalhes de emprego
  • Informações de contato
  • Endereço
  • Preferências

find_users_by_attribute

Pesquisa usuários por qualquer atributo de perfil com filtragem avançada:

  • Atributos suportados: firstName, lastName, email, manager, department, title, division, organization, employeeNumber, costCenter, userType, city, state
  • Operadores de busca:
    • eq (correspondência exata) - Funciona para todos os atributos
    • sw (começa com) - Funciona para todos os atributos
    • ew (termina com) - Funciona para a maioria dos atributos
    • co (contém) - Funciona para alguns atributos (firstName, lastName, email)
    • pr (presente/existe) - Funciona para todos os atributos (encontra usuários com qualquer valor para esse atributo)
  • Recursos:
    • Usa a busca nativa do Okta para desempenho ideal
    • Fallback automático para filtragem no lado do cliente para operadores não suportados
    • Mascaramento de PII nos resultados de busca para atributos sensíveis
    • Filtragem por status (incluir/excluir usuários inativos)
    • Suporte a paginação com limites personalizáveis

list_users

Lista usuários do Okta com filtragem e paginação opcionais:

  • Suporta expressões de filtro SCIM (ex.: 'profile.firstName eq "John"')
  • Busca de texto livre em vários campos
  • Opções de ordenação (por status, data de criação, etc.)
  • Suporte a paginação com limites personalizáveis

activate_user

Ativa um usuário no Okta:

  • Opção de enviar email de ativação
  • Atualiza o status do usuário para ativo

suspend_user

Suspende um usuário no Okta

unsuspend_user

Reativa um usuário anteriormente suspenso no Okta

delete_user

Exclui um usuário do Okta (nota: o usuário deve ser desativado primeiro)

get_user_last_location

Recupera a última localização conhecida e informações de login de um usuário nos logs do sistema Okta

Gerenciamento de Grupos

list_groups

Lista grupos de usuários do Okta com filtragem e paginação opcionais:

  • Expressões de filtro para grupos (ex.: 'type eq "OKTA_GROUP"')
  • Busca de texto livre nos campos do grupo
  • Opções de ordenação (por nome, tipo, etc.)
  • Suporte a paginação com limites personalizáveis

create_group

Cria um novo grupo no Okta com um nome e descrição opcional

get_group

Recupera informações detalhadas sobre um grupo específico

delete_group

Exclui um grupo do Okta

assign_user_to_group

Atribui um usuário a um grupo no Okta

remove_user_from_group

Remove um usuário de um grupo no Okta

list_group_users

Lista todos os usuários em um grupo específico com suporte a paginação

Automação de Onboarding (Experimental)

Nota: As ferramentas de automação de onboarding são experimentais e podem estar sujeitas a alterações ou limitações com base nas restrições da API do Okta. Use com cautela em ambientes de produção.

bulk_user_import

Importa vários usuários a partir de uma string CSV:

  • Cria contas de usuário com base nos dados CSV
  • Ativação opcional de usuários
  • Notificações por email opcionais
  • Atribuição a grupos padrão

assign_users_to_groups

Atribui vários usuários a grupos com base em mapeamentos de atributos:

  • Mapeia atributos de usuário (department, title, etc.) para grupos específicos
  • Atribuição em massa de usuários com base em atributos

provision_applications

Provisiona acesso a aplicativos para vários usuários:

  • Atribui usuários a aplicativos
  • Suporta provisionamento em massa

run_onboarding_workflow

Executa um fluxo de trabalho completo de onboarding para vários usuários a partir de dados CSV:

  • Importação de usuários a partir de CSV
  • Ativação automática
  • Atribuição de grupos com base em atributos
  • Provisionamento de aplicativos
  • Configuração de email de boas-vindas

Exemplo de Uso no Claude

Após a configuração, você pode usar comandos como:

Gerenciamento de Usuários

  • "Mostre-me detalhes do usuário com userId XXXX"
  • "Encontre todos os usuários do departamento de engenharia"
  • "Pesquise usuários com nome começando com 'John'"
  • "Encontre usuários cujo email contenha 'gmail'"
  • "Mostre-me todos os usuários que têm um departamento atribuído"
  • "Liste usuários cujo cargo é 'Manager'"
  • "Qual é o status do usuário john.doe@company.com"
  • "Quando foi o último login do usuário jane.smith@organization.com"
  • "Encontre usuários criados no último mês"
  • "Ative o usuário com ID XXXX"
  • "Suspenda o usuário com ID XXXX"
  • "Exclua o usuário desativado com ID XXXX"
  • "De onde o usuário XXXX fez login pela última vez?"

Pesquisas Avançadas de Usuários

  • "Encontre todos os usuários do departamento de vendas" → Usa find_users_by_attribute com department eq "Sales"
  • "Mostre-me usuários cujo email começa com 'admin'" → Usa email sw "admin"
  • "Encontre usuários com qualquer gerente atribuído" → Usa manager pr
  • "Liste usuários cujo sobrenome contém 'smith'" → Usa lastName co "smith"

Gerenciamento de Grupos

  • "Mostre-me todos os grupos na minha organização Okta"
  • "Liste grupos que contenham a palavra 'admin'"
  • "Crie um novo grupo chamado 'Marketing Team'"
  • "Obtenha detalhes do grupo com ID XXXX"
  • "Exclua o grupo com ID XXXX"
  • "Adicione o usuário XXXX ao grupo YYYY"
  • "Remova o usuário XXXX do grupo YYYY"
  • "Liste todos os usuários no grupo 'Finance'"

Automação de Onboarding

  • "Importe estes usuários a partir de dados CSV: [conteúdo CSV]"
  • "Atribua usuários a grupos com base no atributo de departamento"
  • "Provisione acesso a aplicativos para estes 5 usuários"
  • "Execute um fluxo de trabalho completo de onboarding para estes novos contratados: [conteúdo CSV]"

Tratamento de Erros

O servidor inclui tratamento robusto de erros para:

  • Usuário ou grupo não encontrado (erros 404)
  • Problemas de autenticação na API
  • Perfis de usuário ausentes ou inválidos
  • Erros gerais de API
  • Problemas de análise de CSV
  • Falhas no mapeamento de atributos de usuário
  • Erros de provisionamento de aplicativos
  • Operadores de busca não suportados (fallback automático para métodos alternativos)

Solução de Problemas

Problemas Comuns

Ferramentas não aparecendo no Claude:

  • Verifique os logs do Claude Desktop: tail -f ~/Library/Logs/Claude/mcp*.log
  • Verifique se todas as variáveis de ambiente estão configuradas corretamente
  • Garanta que o caminho para index.js seja absoluto e correto

Erros de Autenticação:

  • Verifique se seu API token é válido
  • Verifique se OKTA_ORG_URL inclui a URL completa com https://
  • Garanta que seu domínio Okta esteja correto

Problemas de Conexão do Servidor:

  • Verifique se o servidor foi compilado com sucesso
  • Verifique as permissões de arquivo em build/index.js (deve ser 755)
  • Tente executar o servidor diretamente: node /path/to/build/index.js

Problemas de Pesquisa:

  • Alguns operadores de busca não são suportados para todos os atributos (ex.: contains não funciona para department)
  • O servidor automaticamente recorre a métodos alternativos de busca quando necessário
  • Verifique a mensagem de resposta para saber qual método de busca foi usado

Visualizando Logs

Para visualizar os logs do servidor:

Para MacOS/Linux:

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

Para Windows:

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

Variáveis de Ambiente

Se você estiver recebendo erros de variáveis de ambiente, verifique:

Considerações de Segurança

  • Mantenha seu API token seguro
  • Não envie credenciais para o controle de versão
  • Use variáveis de ambiente para dados sensíveis
  • Rotacione os API tokens regularmente
  • Monitore o uso da API no Okta Admin Console
  • Implemente limite de taxa para chamadas de API
  • Use as permissões mínimas necessárias para o API token
  • O mascaramento de PII está habilitado para parâmetros de busca sensíveis

Compatibilidade de Operadores de Busca

Diferentes atributos do Okta suportam diferentes operadores de busca:

Tipo de Atributoeqswewcopr
firstName, lastName✅✅✅✅✅
email, login✅✅✅✅✅
department, title✅✅❌❌*✅
division, organization✅✅❌❌*✅
Todos os atributos✅✅⚠️⚠️✅

*❌ = Não suportado, ⚠️ = Pode não ser suportado para todos os atributos

Nota: Quando um operador não é suportado, o servidor automaticamente recorre à filtragem no lado do cliente para compatibilidade.

Tipos

O servidor inclui interfaces TypeScript para dados de usuário e grupo do Okta:

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;
  };
}

Formato CSV para Onboarding

Ao usar as ferramentas de importação em massa ou fluxo de trabalho de onboarding, seu CSV deve incluir estes cabeçalhos:

  • firstName (obrigatório)
  • lastName (obrigatório)
  • email (obrigatório)
  • department (opcional)
  • title (opcional)
  • mobilePhone (opcional)

Exemplo:

firstName,lastName,email,department,title,mobilePhone
John,Doe,john.doe@example.com,Engineering,Senior Developer,+1-555-123-4567
Jane,Smith,jane.smith@example.com,Marketing,Director,+1-555-987-6543

Licença

Licença MIT - Consulte o arquivo LICENSE para obter detalhes.

Suporte

Se você encontrar algum problema:

  • Consulte a seção de solução de problemas acima
  • Revise os logs do Claude Desktop
  • Examine a saída de erros do servidor
  • Consulte a documentação de desenvolvedor do Okta

Nota: PRs são bem-vindos!