Control API - aplicativos e métodos de autenticação

Use FoxIDs Control API para configurar os aplicativos que confiam em FoxIDs e os métodos de autenticação em que FoxIDs confiam. Em rotas e esquemas Control API, um registro de aplicativo é chamado de downparty e um método de autenticação é chamado de upparty.

Antes de chamar essas operações, configure Control API autenticação e direitos de acesso. Swagger continua sendo a referência exata para propriedades específicas de protocolo, regras de validação, operações auxiliares e esquemas de resposta:

• Swagger (OpenAPI) JSON
• Swagger UI

Base de endpoint e direitos de acesso

Os exemplos usam FoxIDs Cloud:

https://control.foxids.com/api/{tenant_name}/{track_name}

Substitua {tenant_name} e {track_name} pelos nomes técnicos tenant e do ambiente. Altere o host para uma implantação auto-hospedada. Envie o token de acesso Control API no cabeçalho Authorization: Bearer {access_token}.

Essas operações exigem um direito de acesso party para o ambiente de destino. Conceda apenas a operação necessária read, create, update ou delete por meio da Control API hierarquia de direitos de acesso.

Listar e identificar registros

Use estes endpoints para descobrir registros antes de chamar um endpoint específico do tipo:

As respostas da lista contêm resumos seguros, o tipo de registro e um token de paginação opaco. Use a operação get específica do tipo para obter a representação editável completa. Repita uma solicitação paginada com os mesmos filtros e o token retornado até que nenhum token seja retornado.

O name técnico é o identificador estável usado pelas operações de obtenção, atualização, exclusão, segredo, chave e relacionamento. Os nomes estão em letras minúsculas. Forneça um nome na criação quando uma integração exigir um identificador previsível ou deixe que FoxIDs gere um. Use o auxiliar !newpartyname quando um nome exclusivo for necessário antes da criação de um recurso.

Operações específicas de tipo

Cada tipo de recurso possui seu próprio terminal porque a configuração do protocolo é diferente. Os principais pontos finais são:

As operações usuais são GET ?name={name}, POST para criar, PUT para atualizar e DELETE ?name={name}. Anexe o endpoint à base do endpoint. Consulte Swagger para as operações suportadas por cada tipo.

A criação de aplicativos ou métodos de autenticação está sujeita ao ambiente e aos limites do plano tenant. Algumas operações de criação simultâneas limitadas pelo plano podem retornar 423 Locked; tente novamente após um pequeno atraso.

Atualize e renomeie com segurança

As operações do grupo PUT são atualizações completas, não patches. Use este fluxo de trabalho:

1. Liste os recursos ou obtenha o recurso conhecido pelo nome técnico.
2. Obtenha sua representação completa específica do tipo.
3. Preservar as propriedades que devem permanecer inalteradas e aplicar as alterações pretendidas.
4. Envie a representação editável completa para o endpoint PUT específico do tipo correspondente.

Use newName quando o nome técnico precisar ser alterado. As referências são atualizadas como parte do fluxo de renomeação. O método de autenticação de login padrão denominado login não pode ser renomeado ou excluído.

Os segredos do cliente, as chaves do cliente e alguns segredos API externos são gerenciados por endpoints dedicados. Eles deliberadamente não são retornados como texto simples na representação geral da parte e não devem ser copiados em uma solicitação de atualização normal.

Conecte aplicativos a métodos de autenticação

A coleção allowUpParties de um aplicativo controla quais métodos de autenticação podem ser usados ​​para fazer login nesse aplicativo. Os métodos de autenticação referenciados devem existir no mesmo ambiente e ser compatíveis com a configuração.

Trate esse relacionamento como parte da configuração completa do aplicativo ao atualizá-lo. A exclusão de um método de autenticação pode alterar o roteamento de login para aplicativos que o referenciam; verifique os aplicativos dependentes antes da exclusão. Use um Environment Link quando o método ou aplicativo de autenticação for conectado intencionalmente em FoxIDs ambientes.

Gerenciar segredos e chaves

Os aplicativos OAuth 2.0 e OpenID Connect fornecem operações dedicadas de segredo do cliente. Um segredo é aceito quando criado, armazenado como hash e não retornado em texto simples. A resposta da lista contém os identificadores e as informações seguras necessárias para gerenciar os segredos existentes.

Use credenciais sobrepostas para rotação:

1. Gere um novo segredo do cliente e armazene-o com segurança.
2. Crie o segredo do cliente em FoxIDs e implemente o mesmo valor no aplicativo consumidor.
3. Verifique se o aplicativo usa o novo segredo.
4. Exclua o segredo antigo por seu aplicativo e identificadores secretos.

Os métodos de autenticação OpenID Connect e OAuth 2.0 podem usar operações dedicadas de segredo do cliente ou de chave do cliente, dependendo do método de autenticação do cliente selecionado. Uma operação de chave privada aceita certificado e material de chave privada. External Login tem um endpoint secreto dedicado. Use o endpoint exato e o esquema de solicitação mostrados em Swagger para o tipo de registro selecionado.

Segredos, chaves privadas e cargas completas de certificados são confidenciais. Use TLS, conceda acesso apenas a clientes de automação confiáveis, proteja valores em repouso e não registre solicitações ou corpos de resposta.

Metadados e ajudantes de descoberta

As operações auxiliares de protocolo reduzem a configuração manual, mas não substituem a validação do recurso resultante:

• Os métodos de autenticação OpenID Connect e OAuth 2.0 podem ler metadados de descoberta e preencher configurações compatíveis.
• SAML 2.0 registros de aplicativos e métodos de autenticação podem ler metadados.
• WS-Federation registros de aplicativos e métodos de autenticação podem ler metadados.
• Os métodos de autenticação WS-Federation incluem um auxiliar de sincronização do Microsoft Entra ID.

Depois de usar um auxiliar, inspecione a configuração retornada, aplique a política local e as configurações de declaração e salve-a por meio do ponto de extremidade de criação ou atualização específico do tipo. Os metadados podem mudar ao longo do tempo, portanto defina se a sincronização é uma ação administrativa explícita ou um processo recorrente controlado.

Efeitos de exclusão e dependência

A exclusão de um aplicativo interrompe novas solicitações de protocolo para esse aplicativo. A exclusão de um método de autenticação pode impedir que os aplicativos concluam o login e pode alterar Home Realm Discovery opções. Remova ou atualize as dependências primeiro e trate ambas as operações como alterações permanentes na configuração.

As solicitações de criação, atualização, segredo/chave, auxiliar e exclusão estão incluídas no log de auditoria do Controle. As operações de leitura não são gravadas como eventos de auditoria.

Respostas de erros comuns

• 400 Bad Request quando configurações de protocolo, referências, metadados, segredos, chaves ou nomes são inválidos ou um limite do plano é atingido.
• 401 Unauthorized quando o token de acesso está ausente ou é inválido.
• 403 Forbidden quando o chamador não possui o direito de acesso necessário.
• 404 Not Found quando o registro, segredo ou chave selecionado não existe.
• 409 Conflict quando já existe um nome técnico ou identificador secreto.
• 423 Locked quando uma operação de criação limitada ao plano é temporariamente bloqueada.

Use o corpo da resposta para detalhes de validação e Swagger UI para as respostas declaradas por cada operação.

Documentação relacionada

• Control API direitos de autenticação e acesso
• Aplicativos
• Métodos de autenticação
• Environment Link
• Reivindicações e transformações de reivindicações