Início de sessão e espaços de trabalho

Início de sessão incluído

O Campbooks é o seu próprio início de sessão e emissor de tokens. Não há nenhum serviço de identidade separado para executar. As pessoas iniciam sessão com Google, Microsoft, Zoho ou uma chave de acesso (passkey), e o servidor emite todos os tokens.

Não precisa de configuração. Deixe CAMPBOOKS_AUTH__ISSUER por definir, como faz o compose.yaml fornecido. O emissor é CAMPBOOKS_PUBLIC_URL, por isso defina-o com o endereço que as pessoas usam.

• CAMPBOOKS_PUBLIC_URL tem de ser https://. O http:// simples só funciona com CAMPBOOKS_ENV=development, para um teste na sua máquina.
• O servidor assina os tokens com chaves que gera no primeiro arranque e renova de 30 em 30 dias. Ficam no Postgres, cifradas com a chave secreta da instância.
• As chaves de acesso não precisam de configuração. Os navegadores oferecem-nas em https://, ou em http://localhost em desenvolvimento.

A chave secreta da instância

No primeiro arranque, o serviço pontual server-init gera a chave secreta da instância no volume server-secrets. O servidor lê-a como um ficheiro, nunca do .env.

A chave protege o que o Campbooks guarda por si: as chaves de assinatura do início de sessão, os tokens das sessões web e as credenciais das contas ligadas. Se a perder, não há forma de a recuperar, nem ao que ela protege. O servidor recusa-se a arrancar quando a chave não abre as chaves de assinatura guardadas.

Guarde uma cópia num sítio seguro, separada das suas cópias de segurança. Uma cópia de segurança que tenha a base de dados e a chave dá tudo o que está na base de dados a quem a encontrar. Veja Atualizações e cópias de segurança.

Como a aplicação web inicia a sua sessão

O servidor inicia a sessão dos navegadores por si. Abra a aplicação e, se não tiver sessão iniciada, envia-o para o ecrã de início de sessão e de volta. O navegador só recebe um cookie de sessão HttpOnly, SameSite=Strict. Os tokens ficam no servidor, cifrados, no Postgres.

• As sessões terminam após 48 horas sem uso, ou 30 dias no máximo, ou quando termina a sessão.
• Em https://, o cookie é Secure e tem o prefixo __Host-. Em http:// simples não é nenhum dos dois, e o servidor regista um aviso. O http simples só serve em localhost.

As definições de sessão são o bloco CAMPBOOKS_BFF__*, listado em Configuração.

Iniciar sessão com Google, Microsoft ou Zoho

Cada fornecedor é opcional. Aparece no ecrã de início de sessão quando lhe der um ID de cliente e um segredo de cliente. Sem nenhum, as pessoas podem usar uma chave de acesso.

Para cada fornecedor que quiser:

1. Registe uma aplicação OAuth na consola do fornecedor, com este URI de redirecionamento (<provider> é google, microsoft ou zoho):

   ${CAMPBOOKS_PUBLIC_URL}/auth/callback/<provider>

2. Ponha o ID de cliente no .env como CAMPBOOKS_GOOGLE__CLIENT_ID, CAMPBOOKS_MICROSOFT__CLIENT_ID ou CAMPBOOKS_ZOHO__CLIENT_ID.

3. Ponha o segredo de cliente num ficheiro em deploy/secrets/: google-client-secret, microsoft-client-secret ou zoho-client-secret. Nunca ponha segredos no .env. O compose monta a pasta só de leitura no servidor, em /run/secrets/campbooks, e o servidor corre com o uid 10001:

   sudo chown 10001:10001 secrets/google-client-secret
   sudo chmod 0400 secrets/google-client-secret

   O Docker Desktop no macOS ou no Windows não precisa do chown.

4. Aponte o servidor para o ficheiro no .env, por exemplo:

   CAMPBOOKS_GOOGLE__CLIENT_ID=your-client-id
   CAMPBOOKS_GOOGLE__CLIENT_SECRET_FILE=/run/secrets/campbooks/google-client-secret

5. Aplique:

   docker compose up -d

Notas por fornecedor:

• Google: tipo de aplicação Aplicação Web. É o mesmo cliente OAuth que liga o Gmail, por isso adicione o âmbito profile ao seu ecrã de consentimento. Publique a aplicação, porque uma aplicação em Testing emite refresh tokens que expiram ao fim de 7 dias. Até a Google verificar a aplicação, as pessoas veem o ecrã de «aplicação não verificada» ao registar-se.
• Microsoft: contas pessoais, profissionais e escolares. No centro de administração Microsoft Entra, registe uma aplicação e adicione um URI de redirecionamento Web. CAMPBOOKS_MICROSOFT__TENANT (por omissão common) limita quem pode iniciar sessão: organizations, consumers ou o ID de um tenant. A Microsoft não verifica o email que indica, por isso numa instância invite_only só conta como verificado se adicionar a declaração opcional xms_edov ao token de ID.
• Zoho: na consola da API Zoho, adicione uma Server-based application e ative Multi-DC, para que um só cliente sirva todos os centros de dados. Sem Multi-DC, defina CAMPBOOKS_ZOHO__ACCOUNTS_SERVER com o centro de dados da sua aplicação, por exemplo https://accounts.zoho.eu.

Os mesmos clientes Google e Zoho ligam também caixas de correio. Veja Ligar caixas de correio.

Para rodar um segredo, substitua o ficheiro e execute docker compose up -d.

Se a sua aplicação OAuth já registou outro caminho de retorno, defina CAMPBOOKS_<PROVIDER>__REDIRECT_PATH e faça o seu proxy inverso reescrever esse caminho para /auth/callback/<provider>. Deixe-o por definir numa aplicação nova.

Contas e associação

• Uma conta fica associada à conta do fornecedor pelo seu ID, nunca pelo endereço de email. Iniciar sessão com uma conta de fornecedor que o Campbooks não conhece oferece a criação de uma conta nova.
• Com a sessão iniciada, a pessoa pode adicionar mais formas de entrar em Definições, depois Formas de iniciar sessão. A última forma de entrar não pode ser removida.

Atrás de um proxy inverso

O início de sessão tem um limite de pedidos por endereço de cliente. Atrás de um proxy, todos os pedidos parecem vir do proxy, e todos os clientes partilham o mesmo limite. Defina CAMPBOOKS_TRUSTED_PROXIES no .env com o endereço ou a rede do proxy, como endereços ou blocos CIDR separados por vírgulas:

CAMPBOOKS_TRUSTED_PROXIES=172.18.0.0/16

Espaços de trabalho e política de registo

A primeira pessoa a iniciar sessão cria o primeiro espaço de trabalho e convida as outras em Definições, depois Membros. Quem mais pode criar um espaço de trabalho é definido por CAMPBOOKS_SIGNUP__POLICY:

Valor	O que acontece
open (por omissão)	Qualquer pessoa com uma conta pode criar um espaço de trabalho.
invite_only	Sem registo público. Só as pessoas com um convite recebem uma conta.
approval	Pedir um espaço de trabalho regista um pedido. Ninguém entra até ser aprovado.
code	Criar um espaço de trabalho exige um código de registo de CAMPBOOKS_SIGNUP__CODES.

A mesma política decide se Google, Microsoft e Zoho criam contas para pessoas novas. O primeiro utilizador da instância pode sempre criar um espaço de trabalho, por isso, numa instância nova, inicie sessão você antes de partilhar o endereço.

Os convites ainda não são enviados por email. Quem convida recebe a ligação uma só vez, logo após convidar, e envia-a. A ligação é construída a partir de CAMPBOOKS_PUBLIC_URL, por isso defina-o com o endereço que as pessoas usam.

Usar um fornecedor de identidade externo

É uma opção avançada, e nada é provisionado para ela. Definir CAMPBOOKS_AUTH__ISSUER com um emissor OpenID Connect externo faz a API confiar nos tokens desse emissor. Defina também CAMPBOOKS_AUTH__JWKS_URL e CAMPBOOKS_AUTH__AUDIENCE. A aplicação web inicia então a sessão através dele com CAMPBOOKS_BFF__CLIENT_SECRET (ou CAMPBOOKS_BFF__CLIENT_SECRET_FILE).

Enquanto o fizer, o início de sessão próprio do Campbooks, as formas de iniciar sessão, as aplicações e a ligação de caixas de correio ficam desativados. Confirme estas definições na documentação do seu fornecedor.