Autenticação e autorização

Pipevine traz quatro esquemas de autenticação de entrada prontos para uso: jwt, oidc, mtls e basic. Todos são selecionáveis por YAML, e um esquema novo pode ser adicionado por um pacote de terceiro sem tocar no core — veja IInboundAuthScheme.

Como declarar autenticação

spec:
  auth:
    default: { scheme: jwt, ref: my-idp }        # aplica-se a toda rota sem auth: própria
    schemes:
      - { id: my-idp, scheme: jwt, authority: "${config:Idp:Authority}", audience: my-api }

  routes:
    - id: createWidget
      authorize:
        scopes: [widgets:write]
        roles:  [operator]
        expr: "input.claims.tenant = input.headers.'x-tenant-id'"   # policy em JSONata, opcional

spec.auth.default se aplica a toda rota que não declarar auth:/anonymous: true explicitamente — sem spec.auth nenhum declarado no documento, toda rota é implicitamente anônima. authorize.scopes/.roles/.claims/.expr decidem, depois que o esquema de autenticação já identificou quem está chamando, se essa identidade tem permissão para aquela rota específica. input.claims (populado a partir do que o esquema resolveu) fica disponível para qualquer expressão JSONata do pipeline, não só em authorize.

jwt

JWT Bearer — o caso mais comum, um token assinado validado por assinatura (via JWKS de um IdP ou uma chave estática).

schemes:
  - id: my-idp
    scheme: jwt
    authority: "${config:Idp:Authority}"    # URL base do emissor; JWKS descoberto automaticamente
    audience: my-api

  # sem IdP real (dev/teste): signingKey estática em vez de authority
  - id: my-idp-dev
    scheme: jwt
    issuer: my-issuer
    audience: my-api
    signingKey: "${secret:env:JWT_SIGNING_KEY}"   # chave HMAC em base64
Campo Descrição
authority URL base do emissor; JWKS é descoberto a partir dela
signingKey Chave HMAC em base64, para validar por chave estática em vez de descoberta JWKS
issuer iss esperado; assume authority quando omitido
audience aud esperado
clockSkew Tolerância de relógio na validação de expiração (padrão: 5 minutos)
requireHttpsMetadata Padrão true; só relevante junto de authority

Pelo menos um entre authority/signingKey é obrigatório. Sem um IdP real disponível, tokens de teste podem ser mintados localmente assinando com a mesma signingKey do YAML (veja samples/03-inventory-orders/tools/mint-token no repositório do Pipevine para um exemplo mínimo usando System.IdentityModel.Tokens.Jwt).

oidc

Introspecção de token (RFC 7662) para tokens de acesso opacos — o caso que uma verificação de assinatura de JWT não cobre. Tokens JWT do mesmo IdP são cobertos pelo esquema jwt acima, que já faz descoberta e cache de JWKS; oidc é deliberadamente focado em introspecção, em vez de reimplementar esse caminho. Uma aplicação que precisa aceitar os dois formatos de token na mesma rota declara os dois esquemas e escolhe qual usar por rota.

schemes:
  - id: partner-idp
    scheme: oidc
    authority: "${config:PartnerIdp:Authority}"
    clientId: my-api
    clientSecret: "${secret:env:PARTNER_IDP_CLIENT_SECRET}"
Campo Descrição
authority URL base do emissor; o endpoint de introspecção é descoberto a partir de {authority}/.well-known/openid-configuration e cacheado. Alternativa a introspectionEndpoint
introspectionEndpoint O endpoint de introspecção diretamente, pulando a descoberta
clientId Credencial deste serviço junto do IdP, enviada como HTTP Basic na chamada de introspecção
clientSecret Segredo correspondente — sempre uma referência ${secret:...}
introspectionCacheDuration Duração do cache do resultado de introspecção (padrão: 30 segundos)

Pelo menos um entre authority/introspectionEndpoint, mais clientId/clientSecret, são obrigatórios.

mtls

Autenticação por certificado de cliente.

schemes:
  - id: partner-mtls
    scheme: mtls
    caCertificatePath: /etc/pipevine/certs/partner-ca.pem
    allowedSubjects: ["CN=partner.example.com"]
    revocationMode: online
Campo Descrição
caCertificatePath Arquivo PEM/DER com o certificado da CA confiável. Obrigatório; carregado uma vez no startup
allowedThumbprints Lista opcional de thumbprints aceitos. Vazio junto de allowedSubjects aceita qualquer certificado que encadeie até a CA
allowedSubjects Lista opcional de subjects aceitos
revokedThumbprints Lista de thumbprints explicitamente revogados
revocationMode noCheck (padrão) | online | offline
trustForwardedHeader Padrão false; habilita o caminho via proxy (X-Forwarded-Client-Cert ou o header nomeado em forwardedHeaderName)
forwardedHeaderName Padrão X-Forwarded-Client-Cert

basic

HTTP Basic. Duas formas de fornecer credenciais, mutuamente exclusivas:

schemes:
  - id: partner-basic
    scheme: basic
    realm: "Partner Portal"
    users:
      - { username: acme, password: "${secret:env:ACME_BASIC_PASSWORD}" }
Campo Descrição
users Lista estática [{ username, password }], resolvida uma vez no startup. Todo password precisa ser uma referência ${secret:...} — uma senha literal no YAML derruba o build
realm Opcional, padrão "Pipevine". Ecoado no header WWW-Authenticate do desafio

Quando users não é declarado, um IBasicCredentialValidator customizado precisa estar registrado (por exemplo, para validar contra um banco de usuários) — sem um dos dois, o build falha, para que um esquema mal configurado nunca aceite toda requisição silenciosamente.

Para onde ir daqui

Edit this page