Variáveis de ambiente necessárias em cada componente do sistema de gestão de acessos.
4. Configuração — Variáveis de ambiente
Quatro intervenientes, quatro superfícies de configuração distintas. Esta secção é a referência canónica para a configuração do framework.
4.1 Access Management (AM)
Caminho: access-management/backend/access-management-api/src/main/resources/application.properties.
4.1.1 Base de dados (obrigatório)
| Variável de ambiente | Propriedade | Valor por omissão | Notas |
|---|---|---|---|
DATABASE_URL | spring.datasource.url | — | Alternativamente, use as três variáveis POSTGRES_* abaixo. |
POSTGRES_HOST | (composto) | — | Usado quando DATABASE_URL não está definida. |
POSTGRES_PORT | (composto) | 5432 | |
POSTGRES_DATABASE | (composto) | — | |
DATABASE_USERNAME / POSTGRES_USER | spring.datasource.username | — | |
DATABASE_PASSWORD / POSTGRES_PASSWORD | spring.datasource.password | — | Segredo. |
O Flyway é executado automaticamente durante o arranque da aplicação. Não desative este comportamento, exceto se o ciclo de vida das migrações for gerido externamente.
4.1.2 Cache de sessão (opcional mas recomendado)
| Variável de ambiente | Propriedade | Valor por omissão | Notas |
|---|---|---|---|
REDIS_HOST | spring.data.redis.host | — | Se não definida, a cache de sessão recorre a memória interna (apenas para deployments de um único pod). |
REDIS_PORT | spring.data.redis.port | 6379 | |
REDIS_PASSWORD | spring.data.redis.password | — | Segredo. |
4.1.3 Servidor de autorização OAuth2 — chaves e emissor (obrigatório)
| Variável de ambiente | Propriedade | Valor por omissão | Notas |
|---|---|---|---|
IGRP_OAUTH_ISSUER | igrp.oauth.issuer | http://localhost:8080 | Correspondência ao carácter com a claim iss do JWT. Inclua o prefixo do proxy inverso, se existir (https://api.example.com/igrp-access-management). |
IGRP_OAUTH_PUBLIC_KEY | igrp.oauth.keys.public | valor por omissão do classpath | Caminho para a chave pública RSA primária. |
IGRP_OAUTH_PRIVATE_KEY | igrp.oauth.keys.private | valor por omissão do classpath | Caminho para a chave privada RSA primária. Segredo. |
IGRP_OAUTH_KEY_ID | igrp.oauth.keys.kid | igrp-oauth-key | Anunciado como kid no JWKS e nos JWTs emitidos. |
IGRP_OAUTH_SECONDARY_* | igrp.oauth.keys.secondary.* | — | Slot opcional de rotação de chaves sem período de indisponibilidade (pública, privada, kid). |
AUTH_JWT_ISSUER | spring.security.oauth2.resourceserver.jwt.issuer-uri | — | Emissor que o próprio AM usa para validar os JWTs recebidos que não emitiu (raro — normalmente igual a IGRP_OAUTH_ISSUER). |
Quando o emissor (issuer) tiver de ser ajustado: se o AM estiver atrás de um proxy que reescreve o URL, IGRP_OAUTH_ISSUER deve corresponder ao URL público utilizado pela SPA e pelos backends das aplicações, e não ao URL interno do serviço. Caso contrário, os resource servers rejeitarão os tokens devido a uma incompatibilidade no valor da claim iss.
4.1.4 Cliente OAuth2 por omissão (semeado automaticamente)
| Variável de ambiente | Propriedade | Notas |
|---|---|---|
IGRP_OAUTH_DEFAULT_CLIENT_ID | igrp.oauth.default-client.client-id | Deixar em branco → sem semear. |
IGRP_OAUTH_DEFAULT_CLIENT_SECRET | igrp.oauth.default-client.secret | Segredo. |
Utilizado para inicializar o primeiro cliente OAuth2 numa base de dados vazia, permitindo que o Application Center comunique com o AM.
Na prática, este cliente é configurado apenas uma vez. Após a inicialização, os restantes clientes OAuth2 devem ser geridos através da interface do Application Center (ver Gestão de Aplicações); no workspace local esse registo é automático — ver Registo de clientes OAuth.
4.1.5 Federação com o IdP a montante (opcional — ativa o SSO)
| Variável de ambiente | Propriedade | Valor por omissão | Notas |
|---|---|---|---|
IGRP_OAUTH_EXTERNAL_IDP_ENABLED | igrp.oauth.external-idp.enabled | true | Defina como false para executar o AM como emissor de identidade autónomo, sem federação a montante. |
IGRP_OAUTH_EXTERNAL_IDP_ISSUER_URI | igrp.oauth.external-idp.issuer-uri | — | URL do emissor OIDC do IdP a montante. |
IGRP_OAUTH_EXTERNAL_IDP_CLIENT_ID | igrp.oauth.external-idp.client-id | — | Cliente do AM no IdP a montante. |
IGRP_OAUTH_EXTERNAL_IDP_CLIENT_SECRET | igrp.oauth.external-idp.client-secret | — | Segredo. |
IGRP_OAUTH_LOGOUT_CASCADE | igrp.oauth.external-idp.logout-cascade | true | O RP-Initiated Logout propaga-se ao IdP a montante em /connect/logout. |
IGRP_OAUTH_REQUIRE_EMAIL_VERIFIED | igrp.oauth.external-idp.require-email-verified | true | Recusa logins em que o IdP a montante não tenha verificado a claim de email. OWASP A07. |
IGRP_OAUTH_ALLOWED_EMAIL_DOMAINS | igrp.oauth.allowed-email-domains | — | Separados por vírgula. P. ex. nosi.cv,gov.cv. Vazio = qualquer domínio. |
IGRP_OAUTH_REQUIRED_ACR_VALUES | igrp.oauth.required-acr-values | — | Aplica autenticação reforçada (step-up). P. ex. mfa exige um ACR com capacidade MFA no IdP a montante. |
4.1.6 CORS
| Variável de ambiente | Propriedade | Valor por omissão | Notas |
|---|---|---|---|
IGRP_CORS_ALLOWED_ORIGINS | igrp.security.cors.allowed-origins | http://localhost:3000,http://localhost:8080 | Separados por vírgula. O wildcard * é proibido, porque o AM envia Access-Control-Allow-Credentials: true. Liste as origens exatas das SPAs. |
4.1.7 Inicialização do superadministrador
| Variável de ambiente | Propriedade | Notas |
|---|---|---|
IGRP_SUPERADMIN_EMAIL | igrp.superadmin.email | Email do superadministrador de inicialização. |
IGRP_SUPERADMIN_USER_EXTERNAL_ID | igrp.superadmin.user-external-id | O sub da mesma pessoa no IdP a montante. Só é usado no primeiro arranque para semear o registo; as pesquisas em runtime são agora baseadas em perfil (DEPT_IGRP.superadmin) — ver o histórico do refactor(users). |
4.1.8 Armazenamento (MinIO ou S3)
| Variável de ambiente | Propriedade | Valor por omissão | Notas |
|---|---|---|---|
IGRP_STORAGE_PROVIDER | igrp.storage-provider | minio | minio ou s3. |
IGRP_STORAGE_ENDPOINT | igrp.minio.endpoint | — | Anfitrião (host). |
IGRP_STORAGE_PORT | igrp.minio.port | — | Porta. |
IGRP_STORAGE_ACCESS_KEY | igrp.minio.access-key | — | Segredo. |
IGRP_STORAGE_SECRET_KEY | igrp.minio.secret-key | — | Segredo. |
IGRP_STORAGE_BUCKET_NAME | igrp.minio.bucket-name | igrp | |
IGRP_STORAGE_PRESIGNED_URL_EXPIRATION_TIME | igrp.minio.url-expiration-time | 300 |
4.1.9 SMTP + notificações
| Variável de ambiente | Propriedade | Valor por omissão | Notas |
|---|---|---|---|
IGRP_NOTIFICATIONS_ENABLED | igrp.notifications.enabled | none | none desativa todo o correio de saída. Defina smtp em produção. |
SMTP_HOST | igrp.mail.host | — | |
SMTP_PORT | igrp.mail.port | 587 | |
SMTP_USERNAME | igrp.mail.username | — | |
SMTP_PASSWORD | igrp.mail.password | — | Segredo. |
IGRP_MAIL_SMTP_AUTH | igrp.mail.auth | true | |
IGRP_MAIL_SMTP_STARTTLS_ENABLE | igrp.mail.starttls.enable | true | |
IGRP_MAIL_INVITE_TEMPLATE | igrp.mail.invite.template | — | Modelo HTML para o email de convite. |
4.1.10 Aplicação de sessão
| Variável de ambiente | Propriedade | Valor por omissão | Notas |
|---|---|---|---|
IGRP_SESSION_ABSOLUTE_TIMEOUT_SECONDS | igrp.session.absolute-timeout-seconds | 28800 | 8 h. Limite máximo absoluto da sessão, independentemente da atividade. |
IGRP_SESSION_MAX_PER_USER | igrp.session.max-per-user | 5 | Sessões ativas simultâneas por utilizador. A mais antiga é terminada quando excedido. |
IGRP_SESSION_HEARTBEAT_DEBOUNCE_SECONDS | igrp.session.heartbeat-debounce-seconds | 30 | Intervalo mínimo entre escritas na base de dados do heartbeat de sessão. |
IGRP_SESSION_ENFORCEMENT_ENABLED | igrp.session.enforcement-enabled | true | false desativa as verificações de vivacidade da sessão (o JWT bearer continua a ser validado). |
4.1.11 Observabilidade + sistema
| Variável de ambiente | Propriedade | Valor por omissão | Notas |
|---|---|---|---|
SERVICE_PORT | server.port | 8080 | |
IGRP_APP_CENTER_URL | igrp.app-center.url | — | URL público do Application Center; usado nos emails de saída (os convites remetem para aqui). |
OTEL_COLLECTOR_ENDPOINT | otel.exporter.otlp.endpoint | — | Se definido, os traces e métricas OTEL são enviados para o coletor. |
OTEL_DISABLED | otel.sdk.disabled | true | Desativado por omissão; defina false para ativar em produção. |
server.forward-headers-strategy | (propriedade) | framework | Não altere sem compreender o bug de ciclo que já encontrámos; os matchers em AuthorizationServerConfig dependem da configuração atual. |
How is this guide?
Última atualização: