Duas portas, dois mundos

Um servidor PingFederate responde em duas portas, e qualquer dúvida sobre endpoints se resolve sabendo a que mundo cada caminho pertence. O mundo administrativo fica na porta do console (9999 por padrão): pessoas e automações configurando o servidor. O mundo de runtime fica na porta do engine, o motor de runtime do servidor (9031 por padrão): navegadores, parceiros e clientes fazendo de fato (single sign-on) e . As duas famílias nunca se misturam (um caminho de admin não responde na porta de runtime, e vice-versa), e é exatamente por isso que essa distinção cai sempre na prova e é a primeira bifurcação de qualquer diagnóstico de conectividade.

A família administrativa

A própria aplicação do console é o endpoint que as pessoas usam. Ao lado dela fica a API administrativa, em /pf-admin-api. É a interface REST (Representational State Transfer) que permite fazer via código tudo o que o console faz: conexões, adapters, clientes, políticas. Ela vem com documentação interativa, então dá para explorar a API de admin pelo navegador antes de automatizá-la num pipeline. Na prática, implantar o PingFederate como infrastructure as code é implantar contra essa API, e ela fica na porta de admin, protegida pela mesma autenticação administrativa e pelos mesmos papéis (roles) do console.

A família de runtime

A porta de runtime atende três grupos de caminhos.

Os endpoints de aplicação de SSO ficam em /idp e /sp: os endpoints de início, que disparam os fluxos (SSO iniciado pelo e pelo SP, e os equivalentes de single logout), e os endpoints de protocolo, que recebem as mensagens (Security Assertion Markup Language) que esses inícios de fluxo colocam em movimento. As variáveis desses endpoints e as formas de iniciação que eles atendem são tratadas no artigo sobre iniciação de SSO; para o mapa de endpoints, o que importa é simplesmente que essa família inteira é de runtime.

O servidor de autorização OAuth fica em /as: autorização, token, introspecção, revogação, os endpoints de toda conversa OAuth. O (OpenID Connect) amplia esse mesmo mundo com o endpoint de UserInfo, as chaves de assinatura publicadas e o discovery, no caminho well-known de configuração, onde um cliente lê o mapa completo de endpoints do provedor numa única requisição: é a versão autodescritiva de tudo o que este artigo lista à mão.

E ainda tem o endpoint menor e mais vigiado do servidor: /pf/heartbeat.ping. Ele responde na porta de runtime dizendo se o servidor está vivo (liveness), e existe para as máquinas: o health monitor do load balancer, o uptime check, o orquestrador que decide se este engine recebe tráfego. Quando um engine sai de um pool sem explicação, a resposta está na conversa entre o load balancer e o heartbeat.

Como usar o mapa

Três hábitos transformam o mapa em habilidade prática. Quando um parceiro avisar que um endpoint não responde, primeiro classifique o caminho (admin ou runtime) e confira a porta e a regra de firewall correspondentes antes de investigar qualquer coisa mais a fundo. Ao automatizar, lembre que a API de admin é configuração e deve ficar atrás de controles administrativos, nunca exposta junto com o tráfego de runtime. E, ao montar o monitoramento, aponte as checagens de liveness para o heartbeat e as checagens funcionais para os fluxos de runtime: as duas respondem a perguntas diferentes, e implantações saudáveis monitoram as duas.