- Os cabeçalhos PF27 conectam as solicitações OAuth ao contexto do token, do cliente e do servidor de recursos.
- Os cabeçalhos JWT identificam a chave de assinatura e o algoritmo usados para proteger a integridade do token.
- O gerenciamento de tokens de acesso controla o tipo, a validade, as declarações e o comportamento de assinatura do token.
- As concessões persistentes mantêm dados de autorização além da curta validade de um token de acesso.
- O fluxo de testes usa um cliente configurado, o Postman ou uma aplicação de teste OAuth.
Cabeçalhos PF27: o que eles controlam
Os cabeçalhos PF27 são mais bem compreendidos como os metadados de solicitação e de token que envolvem uma implantação OAuth no PingFederate. Eles não substituem a concessão OAuth, o registro do cliente, o gerenciador de tokens de acesso ou o contrato de atributos. Em vez disso, ajudam cada componente a identificar como uma solicitação deve ser interpretada e como um token deve ser validado.
Em uma configuração típica, o PingFederate atua como o servidor de autorização. Um cliente OAuth solicita autorização ou um token, enquanto um servidor de recursos valida posteriormente o token de acesso resultante. Os cabeçalhos e as declarações envolvidos nessa troca devem ser consistentes com a concessão selecionada, a configuração de assinatura e as expectativas do cliente.
| Área | Responsabilidade principal | Foco da configuração |
|---|---|---|
| Solicitação OAuth | Transporta o contexto do cliente e da concessão | ID do cliente, URI de redirecionamento, escopo, tipo de resposta |
| Resposta de autorização | Retorna um resultado de autorização | Código, estado, tratamento do redirecionamento |
| Token de acesso | Comprova a autorização delegada | Tipo do token, validade, declarações, emissor |
| Cabeçalho JWT | Descreve a proteção do token | Algoritmo e ID da chave |
| Solicitação de recurso | Apresenta o token de acesso a uma API | Esquema de autorização e token bearer |
Contexto da solicitação
As solicitações OAuth identificam o cliente, a concessão solicitada, o destino do redirecionamento e o escopo solicitado. Valide esses valores antes de testar a emissão de tokens.
Proteção JWT
Um JWT assinado normalmente contém um identificador de algoritmo e uma referência de chave em seu cabeçalho protegido. O serviço receptor usa esses valores para localizar a chave de verificação.
Mapeamento de tokens
O mapeamento de tokens de acesso transfere valores como nome de usuário, e-mail, nome, sobrenome ou grupos para o contrato do token.
Trate cabeçalhos, declarações e atributos do contrato como camadas separadas. Um JWT assinado corretamente ainda pode falhar na autorização se o assunto, o público, o escopo ou os atributos do usuário mapeados não corresponderem às expectativas do servidor de recursos.
Objetos OAuth principais por trás dos cabeçalhos
O fluxo de trabalho mais confiável para os cabeçalhos PF27 começa pelos objetos OAuth subjacentes. O armazenamento de concessões persistentes, o mapeamento de concessões do contrato de política, o gerenciamento de tokens de acesso e o mapeamento de tokens de acesso desempenham funções diferentes. Configurá-los na ordem correta reduz erros de validação confusos.
Uma concessão persistente armazena informações relacionadas à autorização por um período maior que o de um token de acesso de curta duração. Sua validade pode ser controlada por regras de inatividade, validade máxima, expiração, revogação ou limpeza. O PingFederate pode usar um banco de dados ou servidor de diretório para armazenamento de longo prazo, enquanto uma opção HSQLDB interna é mais adequada para testes do que para cargas de trabalho de produção.
| Objeto OAuth | O que armazena ou controla | Por que é importante |
|---|---|---|
| Concessão persistente | Dados de autorização de longa duração | Permite solicitações posteriores de tokens e continuidade da concessão |
| Contrato de concessão persistente | Atributos do usuário e da autorização | Define os valores mantidos com a concessão |
| Mapeamento de concessão do contrato de política | Mapeia resultados de autenticação para dados da concessão | Conecta o usuário autenticado à autorização OAuth |
| Gerenciador de tokens de acesso | Emite e valida tokens de acesso | Define o tipo, a validade e o comportamento de assinatura do token |
| Mapeamento de tokens de acesso | Atende ao contrato de atributos do token | Insere valores de identidade no token |
Armazenamento de concessões persistentes
O armazenamento de concessões persistentes deve ser selecionado de acordo com o ambiente. Um banco de dados integrado pode ser útil durante uma prova de conceito local, mas as implantações de produção geralmente exigem um banco de dados ou serviço de diretório durável, com procedimentos operacionais de backup, controle de acesso e manutenção.
A validade da concessão também deve ser planejada com cuidado. Um tempo limite de inatividade pode remover concessões após um período sem uso, enquanto uma validade máxima estabelece um limite superior para o tempo durante o qual a concessão permanece válida. O comportamento de revogação e limpeza deve ser testado antes de um cliente sair do ambiente de desenvolvimento.
Mapeamento de concessões do contrato de política
O mapeamento de concessões do contrato de política conecta o contrato de política de autenticação ao contrato de concessão persistente. O mapeamento pode incluir uma chave de usuário, como um nome de usuário ou endereço de e-mail. Ele também pode transportar valores necessários posteriormente pelo mapeamento de tokens de acesso.
| Valor do mapeamento | Finalidade típica | Pergunta de revisão |
|---|---|---|
| Nome de usuário | Identificador de usuário estável | O valor é exclusivo no diretório? |
| Identidade voltada ao usuário ou para auditoria | O valor é preenchido de forma consistente? | |
| Nome | Declaração de perfil | Ele é exigido pelo cliente ou pela API? |
| Sobrenome | Declaração de perfil | O atributo do diretório usa o nome esperado? |
| Grupos | Dados de autorização ou direitos | Os valores dos grupos são filtrados e definidos no escopo correto? |
Não trate um banco de dados de testes local como um plano de armazenamento para produção. Confirme a retenção, a limpeza, a replicação, o backup e o comportamento de revogação das concessões antes de usar concessões persistentes em um ambiente ativo.
Gerenciador de tokens de acesso e configuração do cabeçalho JWT
O gerenciador de tokens de acesso é o ponto central de configuração para a emissão e a validação de tokens. Um gerenciador baseado em JWT define como o token é assinado, por quanto tempo permanece válido e quais declarações ou atributos são incluídos. O cabeçalho protegido do JWT normalmente identifica o algoritmo de assinatura por meio de alg e a chave de assinatura por meio de kid.
Uma configuração típica usa um certificado X.509 para assinatura baseada em RSA ou em curva elíptica. O certificado de assinatura ativo deve estar disponível para o gerenciador de tokens, e a chave pública correspondente deve ser localizável pelos serviços que validam o token.
| Configuração do JWT ou token | Função | Revisão prática |
|---|---|---|
| Tipo de token | Determina o formato do token | Confirme que o cliente e a API oferecem suporte a JWTs |
| Certificado de assinatura | Assina o token | Verifique a validade, a confiança e o planejamento de rotação |
| ID da chave | Identifica a chave de assinatura ativa | Garanta que o verificador possa selecionar a chave pública correspondente |
| Algoritmo JWS | Protege a integridade do token | Use um algoritmo compatível com todos os participantes |
| Validade do token | Define a validade do token de acesso | Mantenha-a alinhada ao risco da aplicação |
| Declaração do emissor | Identifica o emissor do token | Corresponda ao valor esperado pelo servidor de recursos |
| Endpoint JWKS | Publica as chaves de verificação | Use um caminho de endpoint exclusivo e acessível |
Sequência de configuração recomendada
Crie o gerenciador de tokens de acesso
Abra a área de gerenciamento de tokens de acesso OAuth e crie uma instância nomeada. Selecione o tipo de token exigido pela integração, como um JSON Web Token, e registre o nome da instância para o mapeamento posterior.
Adicione o certificado de assinatura
Adicione ou selecione o certificado usado para assinar os tokens. Atribua o certificado de assinatura ativo ou o ID da chave e confirme que a chave pública pode ser distribuída aos validadores de tokens.
Defina a validade do token
Escolha uma validade de token adequada ao cliente e à API. Uma validade curta pode limitar a exposição, enquanto o comportamento de atualização ou da concessão deve lidar com a autorização contínua quando houver suporte.
Defina as declarações JWT
Configure as informações do emissor e amplie o contrato de atributos com valores como nome de usuário, e-mail, grupos ou assunto. Inclua apenas as declarações necessárias para a integração.
Salve e replique
Salve o gerenciador de tokens de acesso e replique a configuração no cluster quando for usado um ambiente PingFederate em cluster. Depois, teste a emissão e a validação.
O valor kid merece atenção especial durante a rotação de certificados. Um servidor de recursos pode receber um novo token antes que seu cache de chaves seja atualizado. Publicar um endpoint JWKS estável e planejar uma sobreposição entre as chaves antigas e novas pode reduzir falhas de validação evitáveis.
Antes de solucionar problemas no código da aplicação, inspecione o cabeçalho JWT decodificado e confirme os valores alg e kid. Em seguida, verifique se a chave pública referenciada está disponível por meio da configuração esperada do conjunto de chaves.
Mapeamento de tokens de acesso e testes de solicitações
Depois que o gerenciador de tokens de acesso é criado, o mapeamento de tokens de acesso atende ao seu contrato de atributos. Selecione o contrato de política de autenticação relevante e mapeie seus valores para o gerenciador de tokens. É nesse ponto que os atributos do diretório ou os resultados da autenticação se tornam declarações utilizáveis no token.
Um mapeamento prático pode incluir um nome de usuário como assunto, um endereço de e-mail para identidade e grupos para decisões de autorização. Os nomes exatos dos atributos dependem do contrato de política configurado e do esquema do diretório, portanto o mapeamento deve ser verificado, e não presumido.
| Atributo do token | Origem sugerida | Objetivo da validação |
|---|---|---|
| Assunto | Contrato de política de autenticação | Identifica o proprietário autorizado do recurso |
| Nome de usuário | Contrato de política de autenticação | Corresponde à chave de usuário da aplicação |
| Diretório ou contrato de política | Fornece um valor de identidade consistente | |
| Nome | Diretório ou contrato de política | Oferece suporte a aplicações conscientes do perfil |
| Sobrenome | Diretório ou contrato de política | Oferece suporte às necessidades de exibição ou auditoria |
| Grupos | Diretório ou contrato de política | Oferece suporte a uma lógica de autorização controlada |
Lista de verificação dos cabeçalhos
Antes dos testes:
- Confirme o ID do cliente, a URI de redirecionamento e a concessão OAuth selecionada
- Verifique se o gerenciador de tokens de acesso usa o certificado de assinatura pretendido
- Confira se os valores alg e kid do JWT correspondem à chave de verificação publicada
- Confirme que os mapeamentos de assunto, nome de usuário, e-mail e grupos estão preenchidos
- Teste a expiração e a revogação do token, além do comportamento da concessão persistente
Ao testar com o Postman ou com um ambiente de testes OAuth, comece com uma concessão e um cliente. Os fluxos de código de autorização e código de autorização com PKCE exigem atenção cuidadosa ao tratamento do redirecionamento e do verificador. Os testes de credenciais do cliente são mais diretos porque representam a identidade de uma aplicação, e não de um usuário final. As credenciais de senha do proprietário do recurso e os fluxos implícitos só devem ser testados quando forem explicitamente compatíveis com os requisitos de segurança da implantação.
| Etapa do teste | O que enviar ou inspecionar | Resultado esperado |
|---|---|---|
| Registro do cliente | ID do cliente, segredo, URI de redirecionamento | O cliente é reconhecido |
| Solicitação de autorização | Tipo de resposta, escopo, estado | A autorização prossegue corretamente |
| Solicitação de token | Tipo de concessão, código, verificador ou segredo | O endpoint de token emite um token |
| Inspeção do JWT | Cabeçalho, declarações, expiração | Os valores correspondem aos contratos configurados |
| Solicitação à API | Token de acesso bearer | O servidor de recursos aceita ou rejeita claramente o token |
| Teste de expiração | Token expirado ou concessão revogada | O acesso é negado com um erro útil |
Altere uma variável por vez. Se uma solicitação de token falhar, confirme primeiro os parâmetros do cliente e da concessão. Se a emissão for bem-sucedida, mas a API rejeitar o token, inspecione separadamente o cabeçalho JWT, o emissor, o assunto, o público, a expiração e a chave de assinatura.
Solução de problemas dos cabeçalhos PF27
A maioria das falhas relacionadas aos cabeçalhos OAuth se enquadra em um pequeno número de categorias: a solicitação não corresponde ao cliente registrado, o gerenciador de tokens não consegue assinar ou validar o token, o contrato de mapeamento está incompleto ou o servidor de recursos não consegue localizar a chave de verificação correta.
Use a tabela de sintomas abaixo para restringir o problema antes de alterar vários valores de configuração.
| Sintoma | Causa provável | Primeira verificação |
|---|---|---|
| Falha na autenticação do cliente | ID, segredo ou método do cliente incorreto | Compare o cliente registrado com a solicitação |
| Erro de redirecionamento | Incompatibilidade na URI de redirecionamento | Verifique exatamente o esquema, o host, o caminho e a porta |
| O token é emitido, mas a API o rejeita | Incompatibilidade de declaração ou assinatura | Inspecione o emissor, o assunto, o público, a expiração e a chave |
| Não é possível verificar a assinatura do JWT | kid incorreto ou chave pública indisponível | Verifique o endpoint JWKS e o certificado |
| As declarações do usuário estão vazias | Mapeamento de atributos incompleto | Revise os mapeamentos de política e de tokens de acesso |
| A concessão desaparece inesperadamente | Tempo limite de inatividade, validade máxima ou limpeza | Revise as configurações da concessão persistente |
| Os nós do cluster se comportam de forma diferente | A configuração não foi replicada | Compare e replique as configurações do cluster |
Mantenha um registro escrito dos valores esperados para cada ambiente. No mínimo, documente o emissor, o endpoint de token, o endpoint de autorização, a localização do JWKS, o algoritmo de assinatura, o ID da chave ativa, a validade do token, o identificador do cliente, a URI de redirecionamento e as declarações obrigatórias.
Referências oficiais consultadas em 2026-11-08:
Decodifique tokens apenas em um ambiente controlado e evite inserir segredos reais ou tokens de produção em ferramentas públicas. Um token decodificado não comprova sua validade; a assinatura, o emissor, o público, a expiração e as verificações de autorização continuam sendo importantes.
Perguntas frequentes sobre os cabeçalhos PF27
Q: Para que servem os cabeçalhos PF27?
Os cabeçalhos PF27 descrevem um contexto importante de OAuth e JWT, incluindo o algoritmo de assinatura e a identificação da chave. Eles funcionam em conjunto com as configurações do cliente, o gerenciamento de tokens de acesso, o mapeamento de atributos e a validação do servidor de recursos.
Q: Quais valores do cabeçalho JWT devo inspecionar primeiro?
Comece com alg e kid. O valor alg identifica o método de assinatura, enquanto kid identifica a chave de assinatura. Em seguida, inspecione as declarações do token e confirme que a chave pública correspondente está disponível para o validador.
Q: Por que um token assinado corretamente ainda pode falhar na API?
Uma assinatura válida apenas comprova que o token foi assinado por uma chave confiável. A API ainda pode rejeitar um emissor, público, assunto ou escopo incorretos, um valor de expiração inválido, uma declaração ausente ou um grupo não autorizado.
Q: O armazenamento de concessões persistentes é igual ao armazenamento de tokens de acesso?
Não. Uma concessão persistente retém dados relacionados à autorização e pode sobreviver a um token de acesso. O gerenciador de tokens de acesso emite e valida tokens, enquanto o armazenamento de concessões oferece suporte à continuidade, à revogação e a comportamentos de autorização relacionados.
Nunca aprove uma integração OAuth apenas porque um token foi emitido. Confirme conjuntamente o contrato do token, a verificação da assinatura, o comportamento de expiração, o ciclo de vida da concessão e as decisões de autorização do servidor de recursos.