Guide
Guide
Keycloak, LemonLDAP::NG, Authentik, Okta, Google… : os seus utilizadores entram no SpotBooker com as credenciais da organização.
A sua organização tem um fornecedor de identidade que fala OpenID Connect (OIDC)? É o caso do Keycloak, do LemonLDAP::NG, do Authentik, do Okta ou do Google Workspace. Uma vez ligado ao SpotBooker, cada pessoa inicia sessão com as credenciais habituais, sem mais uma palavra-passe. O início de sessão OpenID Connect está incluído na subscrição; tal como o início de sessão SAML, exige acesso completo (subscrição ou período de teste em curso). Só os administradores do seu espaço o configuram, na maioria das vezes com o serviço informático.
O seu endereço (o emissor) deve ser HTTPS e estar acessível a partir da Internet: o SpotBooker recusa endereços de rede privada e os que contêm um ? ou um #.
É preciso poder declarar lá uma aplicação: um cliente confidencial (com segredo), com o fluxo de código de autorização. O SpotBooker envia sempre também PKCE (S256).
Por exemplo instituto.pt. Ao contrário do SAML, o início de sessão OpenID Connect não se ativa sem domínio: um mesmo fornecedor (Google, Okta…) pode servir muitas organizações e, sem domínio, todas as suas contas poderiam entrar.
Permite provar que o domínio é seu (ver «Provar os seus domínios» mais abaixo). Esta prova é indispensável para que os seus utilizadores cheguem à ligação a partir da página de início de sessão: sem ela, o endereço escrito não encontra a sua organização, a admissão automática não atua e uma conta já existente não pode ser associada pelo endereço.
O seu fornecedor só liga uma aplicação que conhece. A caixa «A declarar no seu fornecedor» mostra dois endereços, cada um com um botão Copiar: o URL de redirecionamento, da forma https://<o-seu-espaço>/oidc/<chave>/callback, e o URL de redirecionamento após o fim de sessão, https://<o-seu-espaço>/oidc/<chave>/logged-out. A chave é estável: estes endereços não mudam, mesmo que altere o endereço público do seu espaço.
Crie uma aplicação do tipo cliente confidencial, com o fluxo de código de autorização (authorization code). Declare o URL de redirecionamento do passo 1; declare o URL após o fim de sessão apenas se o seu fornecedor oferecer fim de sessão centralizado. Anote o identificador do cliente e o seu segredo. As receitas Keycloak e LemonLDAP::NG estão mais abaixo.
No SpotBooker, escolha o tipo de fornecedor (só preenche a ajuda), introduza o emissor tal como o fornecedor o publica e clique em «Testar o fornecedor». O teste lê /.well-known/openid-configuration e as chaves de assinatura, sem guardar nada. O segredo, esse, só é verificado no primeiro início de sessão real.
Copie o identificador do cliente e o seu segredo (cifrado ao guardar, nunca mais é mostrado). A autenticação no ponto de token é client_secret_basic por predefinição; escolha client_secret_post apenas se o seu fornecedor o exigir. Os scopes predefinidos são openid email profile; openid é sempre acrescentado.
Os claims são as informações que o fornecedor coloca no token da pessoa. Por predefinição: sub (identificador único), email, given_name (nome próprio), family_name (apelido) e groups. Um claim pode ser um caminho aninhado, por exemplo realm_access.roles. Se o endereço ou os nomes faltarem no token, o SpotBooker lê o ponto userinfo do fornecedor, depois de verificar que se trata do mesmo sub.
A ativação exige: uma descoberta do fornecedor bem-sucedida, o identificador do cliente, o segredo e pelo menos um domínio aceite. Se faltar algum, o SpotBooker indica-o e não ativa nada. Cada alteração do início de sessão fica inscrita no registo de atividade.
No seu realm, abra Clients e depois Create client. Tipo de cliente: OpenID Connect. No passo seguinte, ative Client authentication (acesso confidencial) e mantenha assinalado Standard flow (código de autorização). O segredo está depois no separador Credentials.
Em «Valid redirect URIs», cole o URL de redirecionamento copiado no passo 1. Se quiser o fim de sessão centralizado, cole o URL após o fim de sessão em «Valid post logout redirect URIs». O emissor tem a forma https://servidor/realms/nome, sem / final.
Para receber os grupos, abra o cliente, separador Client scopes, depois o scope dedicado do cliente (…-dedicated) e Add mapper > By configuration > Group Membership. Chame-lhe groups, ponha groups em «Token Claim Name» e desative «Full group path» se quiser nomes simples (labo e não /labo). Para os papéis do realm, use antes o claim realm_access.roles.
Um endereço enviado com email_verified: false não é considerado fiável para ligar uma conta SpotBooker já existente. No Keycloak, marque os endereços como verificados (utilizador: «Email verified»); caso contrário, quem já tem conta terá de iniciar sessão com a palavra-passe.
No Manager, acrescente um «OpenID Connect Relying Party» (RP) para o SpotBooker, com um identificador de cliente e um segredo. O emissor a introduzir no SpotBooker é o endereço do portal LemonLDAP::NG, por exemplo https://auth.example.fr. Para esta relação, o identificador e o segredo estão em Options → Basic (Client ID, Client secret).
Acrescente o URL de redirecionamento do passo 1 aos endereços de redirecionamento permitidos da relação (e o URL após o fim de sessão para o fim de sessão centralizado). Para a autenticação no ponto de token, mantenha client_secret_basic, que é também o valor predefinido do SpotBooker.
Nos atributos exportados da relação, associe os claims email, given_name e family_name aos atributos do seu diretório (por exemplo mail, givenName, sn) e groups se quiser gerir os grupos. Acrescente o scope correspondente no SpotBooker se o LemonLDAP::NG o exigir.
Introduza o emissor exatamente como o seu fornecedor o publica: o SpotBooker não corrige nada em silêncio. Se o emissor publicado diferir do que escreveu, mesmo por uma / final, o teste indica-o e mostra os dois valores: copie o do fornecedor. Exemplo: o Keycloak publica https://<servidor>/realms/<realm>, sem / final.
O endereço a introduzir é o do emissor, não o do documento de descoberta: sem /.well-known/openid-configuration.
HTTPS obrigatório, acessível a partir da Internet, sem ? nem #. Um endereço de rede privada é recusado: um fornecedor atrás da firewall da organização tem de ser tornado acessível a partir da Internet.
Um domínio que declara filtra os endereços assim que é guardado. Para que também encontre a sua organização a partir da página de início de sessão, certifique os endereços e admita automaticamente, tem de provar que lhe pertence. Sem essa prova, qualquer espaço poderia reivindicar o seu domínio. A prova vale para o domínio exato: institut.fr não abrange labo.institut.fr, que se declara e se prova à parte.
Sob o campo dos domínios, cada domínio guardado mostra o seu registo: tipo TXT, valor spotbooker-verification=….
O seu serviço informático adiciona-o no próprio domínio (por exemplo institut.fr) ou, se preferir, em _spotbooker.institut.fr. Pode ficar: o SpotBooker volta a verificá-lo todos os dias.
Clique em «Verificar agora». Caso contrário, o SpotBooker procura-o sozinho a cada 15 minutos durante 14 dias. Um domínio é verificado por um único espaço: se já o estiver noutro, contacte o suporte. Se o registo desaparecer 7 dias seguidos, a verificação é retirada e os seus administradores são avisados por e-mail.
Em «Correspondência de grupos», associe um valor de grupo do fornecedor a um grupo SpotBooker criado previamente. A cada início de sessão, a pessoa é acrescentada aos grupos que correspondem aos seus no fornecedor e retirada daqueles que deixou. Um grupo criado à mão no SpotBooker nunca é alterado pelo início de sessão.
O fornecedor tem de enviar o claim groups (ou o que indicou). Com o Keycloak, é o mapper «Group Membership» acima; para papéis, indique realm_access.roles. O Google não envia grupos: limite então o acesso por domínio.
Quando a pessoa termina a sessão no SpotBooker, também a termina no fornecedor (RP-Initiated Logout) e regressa à página de início de sessão com esta mensagem de confirmação: «A sua sessão foi terminada, incluindo na sua organização.». Não se esqueça de declarar o URL após o fim de sessão no fornecedor.
Se o fornecedor não publica um ponto de fim de sessão, só a sessão do SpotBooker é fechada: a pessoa continua ligada no fornecedor. A caixa de estado do início de sessão indica se o fim de sessão centralizado está disponível.
O token de identidade é sempre verificado com as chaves que o fornecedor publica (RS256, RS384, RS512, PS256, ES256, ES384). Os tokens sem assinatura (none) e as assinaturas HMAC (HS256 e outras) são recusados.
Um endereço enviado com email_verified: false não é considerado fiável para ligar uma conta existente: a pessoa é convidada a iniciar sessão com a palavra-passe.
| O que vê | O que fazer |
|---|---|
| « O início de sessão através da sua organização não está disponível. Contacte o respetivo administrador. » | O início de sessão não está ativado, está incompleto, ou não foi possível ler o fornecedor. Em Definições, verifique que está ativado e que o estado do fornecedor indica «Descoberto em» seguido de uma data (e não «Ainda não descoberto»), e execute o teste. |
| « O início de sessão através da sua organização falhou. Tente novamente. » | Causa mais frequente: o URL de redirecionamento não está declarado de forma idêntica no fornecedor, ou o segredo está errado. Verifique também o método de autenticação (client_secret_basic ou client_secret_post) e o emissor. O «Último erro» da caixa de estado dá o motivo; uma página de início de sessão aberta demasiado tempo também falha: recomece. O fornecedor pode também não ter enviado nem o endereço de e-mail nem o identificador (sub) nos claims que configurou, mesmo após a leitura do ponto userinfo: verifique os nomes em «Leitura dos claims». |
| « A sua conta não está autorizada a aceder a este espaço. Contacte o administrador da sua organização. » | O endereço da pessoa está fora dos domínios aceites, já é usado por uma conta de outro espaço SpotBooker, ou um administrador recusou o pedido de acesso desta pessoa. No primeiro caso, acrescente o domínio; nos outros, uma pessoa recusada não entra ao iniciar sessão de novo. |
| « Já existe uma conta com este endereço. Por motivos de segurança, a ligação automática não é possível: inicie sessão com a sua palavra-passe. » | Já existe uma conta SpotBooker com este endereço e o fornecedor não o declara verificado (email_verified). Marque o endereço como verificado no fornecedor, ou a pessoa inicia sessão com a palavra-passe. |
| « O seu pedido de acesso foi enviado ao administrador da sua organização. Receberá um email assim que for tratado. » | É normal quando a admissão automática está desativada ou o domínio não está provado por DNS: um administrador tem de aceitar o pedido na gestão de utilizadores. |
| « O seu pedido de acesso aguarda validação por um administrador. » | A pessoa já pediu acesso: um administrador ainda não decidiu. Aceite ou recuse o pedido. |
| « A sua conta foi desativada pela sua organização. Contacte o respetivo administrador. » | A conta foi desativada porque a pessoa saiu do diretório. Reabre-se sozinha quando o diretório a marca de novo como ativa; não se reativa à mão no SpotBooker. Veja Sincronizar utilizadores com SCIM. |
| « Obrigatório para ativar o início de sessão OpenID Connect (fornecedor descoberto, identificador, segredo e pelo menos um domínio). » | Falta uma condição: fornecedor descoberto, identificador do cliente, segredo ou pelo menos um domínio aceite. Execute o teste, complete os campos e volte a ativar. |
| « O endereço do fornecedor é recusado: não usa HTTPS, ou contém uma consulta (?), um fragmento (#) ou carateres não permitidos. » | O emissor não está em HTTPS, ou contém um ? ou um #. Introduza apenas o endereço do emissor, em HTTPS. |
| « Este endereço aponta para uma rede privada: o SpotBooker não se liga a ele. » | O endereço aponta para uma máquina de uma rede privada. Torne o fornecedor acessível a partir da Internet e use o seu endereço público. |
| « Não é possível contactar o fornecedor. Verifique o endereço e se o servidor está acessível a partir da Internet. » | Endereço mal escrito, ou servidor inacessível a partir da Internet (firewall, certificado HTTPS inválido). Verifique o endereço e abra-o num navegador fora da organização. |
| « O fornecedor respondeu com um erro. Verifique o emissor: o endereço não deve incluir /.well-known/openid-configuration. » | O endereço introduzido não é o de um fornecedor OpenID Connect. Retire /.well-known/openid-configuration e verifique o caminho (com o Keycloak: /realms/<realm>). |
| « O emissor introduzido (https://sso.example.fr/) não corresponde ao que o fornecedor publica (https://sso.example.fr). Copie-o de forma idêntica, caráter a caráter (incluindo uma « / » final). » | O emissor introduzido difere do que o fornecedor publica. Copie o valor encontrado, caráter a caráter, incluindo uma / final. O SpotBooker não o corrige por si. |
| « O documento do fornecedor está incompleto: falta um endereço indispensável (autorização, token ou chaves). » | O documento do fornecedor não contém todos os endereços necessários. Verifique a configuração do fornecedor ou do realm. |
| « O início de sessão foi guardado, mas a deteção do fornecedor falhou: … » | As definições estão guardadas, mas o início de sessão não pode ser usado enquanto a descoberta não tiver êxito. Corrija a causa indicada e execute o teste. |
| « A resposta do fornecedor não é um documento OpenID Connect legível. » | O endereço não leva a um fornecedor OpenID Connect (página web, portal, redirecionamento). Verifique o emissor. |
| « A resposta do fornecedor é anormalmente grande e foi recusada. » | Uma resposta anormalmente volumosa não é lida. Verifique que o endereço é mesmo o de um fornecedor OpenID Connect. |
| « O teste falhou. Verifique o emissor introduzido. » | A mensagem não dá pormenores: verifique o emissor introduzido e execute o teste novamente. |