Checklist de integração

O que um sistema precisa fazer, e o que é recomendado, para usar a Central de Identidade como login sem quebrar quando as pessoas mudam de email, de empresa ou saem.

Esta página complementa Para quem desenvolve, que explica o protocolo (endpoints, tokens, claims). Aqui está o que fazer com ele. Cada item é:

• Obrigatório: sem ele, a integração quebra ou abre uma falha de segurança.
• Recomendado: a integração funciona sem ele, mas pior para quem usa ou para quem mantém.

Identidade#

Identifique a pessoa pelo sub#

Obrigatório.

O sub (o id da pessoa na central, como vlidc_usr_…) é único e universal: identifica a mesma pessoa em todos os sistemas ligados à central, e nunca muda. É o mesmo id que a API usa.

Guarde o sub no usuário do seu sistema e use só ele para encontrar a pessoa a cada login. Nunca use email para isso, nem o principal nem os confirmados: a pessoa troca de email, um administrador corrige, e o mesmo endereço pode passar de uma pessoa para outra com o tempo.

Associe os usuários que já existiam#

Obrigatório, se o seu sistema já tinha usuários antes da integração.

Um usuário antigo ainda não tem sub, e pode estar cadastrado com um email diferente do email principal dele na central. Para encontrá-lo:

1. Peça o scope verified_emails. A claim verified_emails traz todos os emails confirmados da pessoa, inclusive o principal. Use sempre essa lista, e não a claim email.
2. No login, procure primeiro pelo sub. Achou: é essa pessoa.
3. Não achou: procure, só entre os usuários sem sub, os que têm algum email da lista verified_emails.
   • Achou exatamente um: grave o sub nele. A partir daí, ele é encontrado pelo sub.
   • Achou mais de um: não associe automaticamente. Escolher um em silêncio junta duas pessoas numa só. Recuse o login ou marque o caso para alguém resolver na mão.
   • Não achou nenhum: é uma pessoa nova (veja Não peça cadastro).

Depois que um usuário tem sub, o email nunca mais entra na busca dele.

A associação também pode ser feita de uma vez, antes de qualquer login, pela API: GET /api/v1/users lista as pessoas com os emails de cada uma (use só os que vêm com verified: true), seguindo as mesmas regras acima.

Cadastro e dados#

Não peça cadastro#

Recomendado.

No primeiro login, crie o usuário do seu sistema com os dados que vêm da central (nome, email, foto). A pessoa não deveria preencher um formulário com o que a central já sabe.

Use os dados da central#

Recomendado.

Nome, email, foto e vínculo profissional vêm da central. Atualize a sua cópia a cada login (pelo ID token ou por /userinfo) e não deixe a pessoa editar esses dados no seu sistema: as duas versões se desencontram, e a da central é a que os outros sistemas veem. Para corrigir algo, a pessoa fala com um administrador da central.

Não exija email único#

Recomendado.

Um email pode mudar de dono: alguém sai da empresa e, anos depois, o mesmo endereço é dado a outra pessoa. Na central, as duas são pessoas diferentes, com subs diferentes. Se o seu sistema exige email obrigatório e único, a segunda pessoa não consegue ser cadastrada.

Afrouxe essa regra: deixe o email opcional, ou sem unicidade. E se aparecer uma pessoa nova (um sub que você não conhece) com um email que já está num usuário do seu sistema, apague o email do usuário antigo: o endereço provavelmente mudou de dono. É raro, mas acontece. Isso só acontece com usuários que já têm sub: um usuário sem sub com esse email teria sido associado à pessoa no passo de associação.

Não presuma que um campo vem preenchido#

Obrigatório.

• employer é null para freelancers.
• picture, job_title e department podem vir null.
• served_organizations e verified_emails podem vir vazios.

Peça só os scopes que usa#

Recomendado.

Cada scope libera mais dados da pessoa. Peça os de que o sistema precisa de verdade.

Acesso e segurança#

Mantenha as permissões no seu sistema#

Obrigatório.

A central diz quem é a pessoa, não o que ela pode fazer no seu sistema. Quem pode o quê continua sendo decidido pelo seu sistema. Os papéis da central (administrador de pessoas, global etc.) servem só para administrar a própria central e não aparecem nas claims.

Desligue o login próprio do sistema#

Recomendado.

Uma senha local é uma porta paralela: quando um administrador desativa alguém na central, essa porta continua aberta. Depois da integração, a central deve ser o único jeito de entrar. Se precisar de uma conta de emergência, mantenha uma só, documentada.

Reaja à desativação#

Obrigatório.

Quando alguém é desativado, a central revoga os tokens da pessoa, mas o seu sistema só fica sabendo se perguntar. Não mantenha uma sessão local por muito mais que 1 hora (a validade do access token) sem renovar o token. Se o refresh for recusado, encerre a sessão local.

Ofereça a saída pela central#

Recomendado.

Sair do seu sistema não tira a pessoa da central, e ela continua entrando direto nos outros sistemas. Ofereça a saída por /end-session (veja Para quem desenvolve), pelo menos como opção.

Valide os tokens com uma biblioteca#

Obrigatório.

Use uma biblioteca cliente de OIDC da sua linguagem para o fluxo e para validar o ID token (assinatura, iss, aud, validade e nonce). Não escreva a validação à mão: os erros sutis aqui viram falha de segurança.

Na página inicial da central#

Faça a URL do app já iniciar o login#

Recomendado.

A página inicial da central lista os sistemas da empresa. Quem clica num deles já está logado na central, então a URL cadastrada para o app deveria levar direto ao login pela central, não a uma tela de "entrar" do seu sistema. Combine essa URL com o administrador de diretório que cadastra o app.