Sign-in and authentication: SSO, OAuth, OIDC and friends.

Resumo (TL;DR)Summary (TL;DR)

1. Autenticar é provar quem você é; autorizar é decidir o que você pode fazer. São perguntas diferentes e protocolos diferentes.Authenticating is proving who you are; authorizing is deciding what you may do. They are different questions with different protocols.
2. OAuth 2.0 cuida de autorização (tokens com escopo); OIDC e SAML cuidam de autenticação; SSO é a experiência de entrar uma vez só; MFA reforça a prova de identidade.OAuth 2.0 handles authorization (scoped tokens); OIDC and SAML handle authentication; SSO is the log-in-once experience; MFA strengthens the proof of identity.
3. Em CI/CD, use OIDC para o GitHub Actions entrar na AWS com credenciais temporárias, sem chaves de acesso fixas guardadas em secrets.In CI/CD, use OIDC so GitHub Actions signs in to AWS with temporary credentials, with no fixed access keys stored in secrets.

Autenticação vs. autorizaçãoAuthentication vs. authorization

Dois conceitos que parecem um só e são a fonte da maior parte da confusão nesta área.Two concepts that look like one and cause most of the confusion in this area.

A ordem importa: primeiro se autentica, depois se autoriza. Um sistema que autoriza sem autenticar libera acesso para qualquer um; um que autentica sem autorizar deixa todo mundo logado ver tudo.Order matters: authenticate first, then authorize. A system that authorizes without authenticating gives access to anyone; one that authenticates without authorizing lets every logged-in user see everything.

Formas de provar identidadeWays to prove identity

Os métodos se agrupam em três tipos de fator: algo que você sabe, algo que você tem e algo que você é.Methods fall into three kinds of factor: something you know, something you have and something you are.

WebAuthn, FIDO2 e passkeys: quem é quemWebAuthn, FIDO2 and passkeys: who is who

• WebAuthn: API do navegador (padrão do W3C) que cria e usa as credenciais de chave pública.WebAuthn: the browser API (a W3C standard) that creates and uses public-key credentials.
• FIDO2: conjunto da FIDO Alliance formado por WebAuthn (navegador ↔ site) e CTAP (navegador ↔ chave de segurança).FIDO2: the FIDO Alliance set made of WebAuthn (browser ↔ site) and CTAP (browser ↔ security key).
• Passkey: o nome amigável de uma credencial FIDO/WebAuthn, muitas vezes sincronizada entre os dispositivos do usuário.Passkey: the friendly name for a FIDO/WebAuthn credential, often synced across the user’s devices.

Protocolos e padrõesProtocols and standards

SSO: um conceito, não um protocoloSSO: a concept, not a protocol

Single Sign-On é a experiência de entrar uma vez e usar vários sistemas sem digitar a senha de novo. Não existe um “protocolo SSO”: ele é implementado com OIDC, SAML ou Kerberos. O que as apps têm em comum é confiar no mesmo provedor de identidade.Single Sign-On is the experience of signing in once and using several systems without typing the password again. There is no “SSO protocol”: it is implemented with OIDC, SAML or Kerberos. What the apps share is trusting the same identity provider.

OAuth 2.0 (autorização)OAuth 2.0 (authorization)

Framework (RFC 6749) para um app obter acesso limitado a algo seu sem receber a sua senha. É a analogia da chave de manobrista: ela liga o carro, mas não abre o porta-malas. O resultado é um access token com escopos.A framework (RFC 6749) for an app to get limited access to something of yours without receiving your password. Think of a valet key: it starts the car but does not open the trunk. The result is an access token with scopes.

OpenID Connect, OIDC (autenticação)OpenID Connect, OIDC (authentication)

Camada de identidade sobre o OAuth 2.0. Acrescenta o escopo openid, o ID token (um JWT com claims sobre o usuário e sobre o login), o endpoint userinfo e um documento de descoberta em /.well-known/openid-configuration. Responde “quem é este usuário?”.An identity layer on top of OAuth 2.0. It adds the openid scope, the ID token (a JWT with claims about the user and the login), the userinfo endpoint and a discovery document at /.well-known/openid-configuration. It answers “who is this user?”.

SAML 2.0 (autenticação, mundo corporativo)SAML 2.0 (authentication, enterprise world)

Padrão mais antigo, baseado em XML. O provedor de identidade devolve uma assertion assinada ao app via navegador. Muito comum em ferramentas corporativas (SaaS B2B). Faz o mesmo papel do OIDC; apps novas costumam preferir OIDC por ser mais simples (JSON/JWT).An older standard based on XML. The identity provider returns a signed assertion to the app through the browser. Very common in enterprise tools (B2B SaaS). It plays the same role as OIDC; new apps usually prefer OIDC because it is simpler (JSON/JWT).

LDAP e Active DirectoryLDAP and Active Directory

LDAP (RFC 4511) é um protocolo para consultar e autenticar contra um diretório de usuários, grupos e dispositivos. Active Directory (AD) é o serviço de diretório da Microsoft, que fala LDAP e Kerberos; Microsoft Entra ID (antigo Azure AD) é a versão em nuvem, acessada com OIDC e SAML.LDAP (RFC 4511) is a protocol to query and authenticate against a directory of users, groups and devices. Active Directory (AD) is Microsoft’s directory service, which speaks LDAP and Kerberos; Microsoft Entra ID (formerly Azure AD) is the cloud version, reached with OIDC and SAML.

KerberosKerberos

Autenticação por tickets dentro de uma rede corporativa (RFC 4120). Você prova a identidade uma vez a um servidor central (o KDC) e recebe um ticket que as outras máquinas aceitam. É a base do “login do Windows que vale para tudo” em domínios AD.Authentication by tickets inside a corporate network (RFC 4120). You prove your identity once to a central server (the KDC) and get a ticket that other machines accept. It is the base of the “Windows login that works everywhere” in AD domains.

GlossárioGlossary

Fluxo completo: “Entrar com Google”Full flow: “Sign in with Google”

Usa OIDC sobre OAuth 2.0, com o fluxo Authorization Code + PKCE. O app é a Relying Party; o Google, o IdP.Uses OIDC on top of OAuth 2.0, with the Authorization Code + PKCE flow. The app is the Relying Party; Google is the IdP.

1. O usuário clica em Entrar com Google no app.The user clicks Sign in with Google in the app.
2. O app gera state (anti-CSRF), nonce (anti-replay do ID token) e um par PKCE (code_verifier secreto e code_challenge derivado).The app generates state (anti-CSRF), nonce (ID-token anti-replay) and a PKCE pair (secret code_verifier and derived code_challenge).
3. O app redireciona o navegador para o endpoint de autorização do Google com client_id, redirect_uri, response_type=code, scope=openid email profile, state, nonce e code_challenge.The app redirects the browser to Google’s authorization endpoint with client_id, redirect_uri, response_type=code, scope=openid email profile, state, nonce and code_challenge.
4. [Autenticação] O Google verifica quem é o usuário: senha, MFA ou passkey. Se já há sessão ativa no Google, é aqui que o SSO acontece e nada é digitado.[Authentication] Google checks who the user is: password, MFA or passkey. If there is already an active Google session, this is where SSO happens and nothing is typed.
5. [Autorização] O Google mostra a tela de consentimento: “o app quer ver seu nome e e-mail”. O usuário aprova os escopos.[Authorization] Google shows the consent screen: “the app wants to see your name and email”. The user approves the scopes.
6. O Google redireciona de volta ao redirect_uri com um code de uso único e o state.Google redirects back to the redirect_uri with a one-time code and the state.
7. O app confere que o state é o mesmo que enviou. Se não for, aborta.The app checks that state is the one it sent. If not, it aborts.
8. O backend do app troca o code por tokens no endpoint de token do Google, enviando também o code_verifier.The app’s backend exchanges the code for tokens at Google’s token endpoint, also sending the code_verifier.
9. O Google devolve o ID token (JWT, diz quem é), o access token (autoriza chamar APIs do Google) e, às vezes, um refresh token.Google returns the ID token (JWT, says who it is), the access token (authorizes calling Google APIs) and, sometimes, a refresh token.
10. O app valida o ID token: assinatura (chaves públicas do IdP), iss, aud igual ao seu client_id, exp e nonce.The app validates the ID token: signature (the IdP’s public keys), iss, aud equal to your client_id, exp and nonce.
11. O app cria a sessão própria (cookie HttpOnly). A partir daí o Google já saiu de cena; o access token só é usado se o app precisar chamar APIs do Google.The app creates its own session (HttpOnly cookie). From then on Google is out of the picture; the access token is only used if the app needs to call Google APIs.

Regra de bolsoRule of thumb

• OAuth 2.0 = autorização. “Este app pode acessar isto, com estes escopos.”OAuth 2.0 = authorization. “This app may access this, with these scopes.”
• OIDC = autenticação, em cima do OAuth. “Este usuário é fulano.”OIDC = authentication, on top of OAuth. “This user is so-and-so.”
• SAML = autenticação, com XML, no mundo corporativo.SAML = authentication, with XML, in the enterprise world.
• SSO = experiência: entrar uma vez, usar várias apps. Implementado com OIDC, SAML ou Kerberos.SSO = experience: sign in once, use several apps. Implemented with OIDC, SAML or Kerberos.
• MFA = reforço: mais de um fator para provar a identidade.MFA = reinforcement: more than one factor to prove identity.
• JWT = formato do token, não um protocolo.JWT = the token format, not a protocol.
• LDAP / AD = o diretório de usuários; Kerberos = tickets na rede interna.LDAP / AD = the user directory; Kerberos = tickets on the internal network.

Prática: OIDC no GitHub Actions → AWSPractice: OIDC from GitHub Actions → AWS

Aqui o “usuário” é um job de CI/CD. O GitHub é o IdP, a AWS é quem confia, e o resultado são credenciais temporárias no lugar de uma chave de acesso fixa (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY) guardada em secrets. A troca de credenciais é autenticação (o token prova qual repositório e branch pediram) seguida de autorização (a role define o que pode ser feito).Here the “user” is a CI/CD job. GitHub is the IdP, AWS is the one that trusts it, and the result is temporary credentials instead of a fixed access key (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY) stored in secrets. The exchange is authentication (the token proves which repository and branch asked) followed by authorization (the role defines what may be done).

Diagrama do fluxoFlow diagram

Passo 0: criar o provedor OIDC na AWS (uma vez por conta)Step 0: create the OIDC provider in AWS (once per account)

• Provider URL: https://token.actions.githubusercontent.comProvider URL: https://token.actions.githubusercontent.com
• Audience: sts.amazonaws.comAudience: sts.amazonaws.com

O passo a passo completo (console e CLI, duas contas, environments, secrets) está na nota GitHub para AWS com OIDC. Aqui ficam o mínimo e a teoria.The full walkthrough (console and CLI, two accounts, environments, secrets) is in the note GitHub to AWS with OIDC. Here you get the minimum and the theory.

Trust policy da role IAMIAM role trust policy

A trust policy diz quem pode assumir a role. As duas condições são o coração da segurança: aud garante que o token foi feito para a AWS e sub garante que veio do seu repositório e da sua branch.The trust policy says who may assume the role. The two conditions are the heart of the security: aud makes sure the token was meant for AWS and sub makes sure it came from your repository and your branch.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:<ORG>/<REPO>:ref:refs/heads/main"
        }
      }
    }
  ]
}

Workflow do GitHub ActionsGitHub Actions workflow

name: deploy

on:
  push:
    branches: [main]

permissions:
  id-token: write   # lets the job request the OIDC token
  contents: read    # lets actions/checkout read the repo

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Configure AWS credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::<ACCOUNT_ID>:role/github-deploy-main
          aws-region: sa-east-1

      - name: Who am I?
        run: aws sts get-caller-identity

Sem permissions: id-token: write o job não consegue pedir o token e a ação falha. A action configure-aws-credentials faz o passo 3 do diagrama e exporta as credenciais temporárias para os passos seguintes. Confira na página da action as versões e opções atuais.Without permissions: id-token: write the job cannot request the token and the action fails. The configure-aws-credentials action performs step 3 of the diagram and exports the temporary credentials to the following steps. Check the action’s page for current versions and options.

Claims do tokenToken claims

Esse é o payload de um token do GitHub (valores de exemplo). É isso que a AWS compara com a trust policy.This is the payload of a GitHub token (example values). This is what AWS compares against the trust policy.

{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "sts.amazonaws.com",
  "sub": "repo:<ORG>/<REPO>:ref:refs/heads/main",
  "repository": "<ORG>/<REPO>",
  "repository_owner": "<ORG>",
  "ref": "refs/heads/main",
  "sha": "<commit sha>",
  "workflow": "deploy",
  "event_name": "push",
  "actor": "<github user>",
  "job_workflow_ref": "<ORG>/<REPO>/.github/workflows/deploy.yml@refs/heads/main",
  "iat": 1760000000,
  "nbf": 1760000000,
  "exp": 1760003600
}

Para ver os claims reais do seu job, decodifique o token em um passo de teste do workflow (o payload do JWT é Base64URL). Faça isso só em um repositório de teste, e não publique o token inteiro nos logs.To see the real claims of your job, decode the token in a test step of the workflow (the JWT payload is Base64URL). Do this only in a test repository, and do not publish the whole token in the logs.

Boas práticas de segurançaSecurity best practices

• Uma role por ambiente (develop, production), cada uma com a sua trust policy e o mínimo de permissões (menor privilégio).One role per environment (develop, production), each with its own trust policy and minimum permissions (least privilege).
• Restrinja o sub ao máximo: repositório e branch/environment exatos. Use StringEquals sempre que der.Restrict sub as much as possible: exact repository and branch/environment. Use StringEquals whenever you can.
• Environments com aprovação para produção: o deploy só segue depois de um revisor aprovar.Environments with approval for production: the deploy only proceeds after a reviewer approves.
• Permissões mínimas no workflow: declare permissions explicitamente em vez de herdar o padrão.Minimal workflow permissions: declare permissions explicitly instead of inheriting the default.
• Cuidado com PRs de forks e com pull_request_target: não dê a role de deploy para código que você não revisou.Careful with fork PRs and pull_request_target: do not hand the deploy role to code you have not reviewed.
• Fixe versões de actions de terceiros (por SHA do commit, quando possível), porque elas rodam no job que tem a role.Pin third-party action versions (by commit SHA when possible), because they run in the job that holds the role.
• Remova as chaves antigas: depois de migrar, apague o usuário IAM e as chaves fixas que existiam.Remove the old keys: after migrating, delete the IAM user and the fixed keys that existed.
• Audite: o CloudTrail registra AssumeRoleWithWebIdentity com o token usado; monitore usos inesperados.Audit: CloudTrail records AssumeRoleWithWebIdentity with the token used; monitor unexpected uses.

Erros comuns e como resolverCommon errors and how to fix them

Cola e revisãoCheat sheet and review

ColaCheat sheet

Perguntas de revisãoReview questions