> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Federação OIDC

> Troque identidades de workloads por credenciais temporárias sem distribuir chaves de acesso de longa duração.

Use OIDC quando um workload já tem uma identidade e precisa de credenciais temporárias em outro sistema. O emissor assina um JWT de curta duração. O destino verifica a assinatura, o emissor, a audiência e o sujeito antes de emitir suas próprias credenciais.

| Workload | Prova de identidade | Troca |
| - | - | - |
| GitHub Actions → Basaltic | JWT OIDC do job GitHub | [GitHub Actions](https://docs.basaltic.sh/pt/iam/github-actions.md) |
| Sessão da API Basaltic → plataforma externa | `GetWebIdentityToken` com a audiência de destino | [API de tokens](#generate-a-token-through-the-api) |
| Workload externo → Basaltic | JWT de um emissor OIDC registrado na conta | `AssumeRoleWithWebIdentity` do Basaltic |
| Workload AWS → Basaltic | JWT de `GetWebIdentityToken` do AWS STS | [AWS para Basaltic](https://docs.basaltic.sh/pt/iam/aws-federation.md#aws-to-basaltic) |
| VM Basaltic → AWS | JWT de identidade da VM pelo serviço de metadados | [Basaltic para AWS](https://docs.basaltic.sh/pt/iam/aws-federation.md#basaltic-to-aws) |
| VM Basaltic → outro serviço que confia em OIDC | O mesmo endpoint de identidade da VM, com a audiência desse serviço | [Tokens de identidade de VM](https://docs.basaltic.sh/pt/iam/vm-identity.md) |

Uma prova de identidade e um token de acesso à API têm finalidades diferentes. O JWT OIDC comprova a identidade durante a troca. As credenciais resultantes autorizam requisições de acordo com as permissões da role no destino. Os tokens bearer da API Basaltic usam uma chave de assinatura separada e não substituem os tokens de identidade de VM.

## Gerar um token pela API

Uma service account autenticada ou uma sessão de role assumida pode chamar `GetWebIdentityToken`. Usuários humanos primeiro assumem uma role da conta. A conta selecionada deve corresponder ao workload autenticado. Os metadados continuam disponíveis para a VM obter sua prova diretamente.

Conceda `iam:GetWebIdentityToken` no CRN da própria role ou service account do chamador. Restrinja `basalt:IdentityTokenAudience` ao destino. Por exemplo:

```json theme={null}
{
  "version": "2024-01-01",
  "statements": [{
    "effect": "allow",
    "actions": ["iam:GetWebIdentityToken"],
    "resources": ["crn:iam::production:service-account/deploy-bot"],
    "conditions": [{
      "operator": "equals",
      "key": "basalt:IdentityTokenAudience",
      "values": ["https://deploy.example.com"]
    }]
  }]
}
```

Use um token bearer válido da API Basaltic em `BASALTIC_TOKEN`. Mantenha a resposta privada:

```bash theme={null}
umask 077
curl --fail --silent --show-error \
  -H "Authorization: Bearer $BASALTIC_TOKEN" \
  -H 'X-Account-Id: production' \
  -H 'Content-Type: application/json' \
  -d '{"audience":"https://deploy.example.com","duration_seconds":300}' \
  https://iam.basaltic.sh/v1/get-web-identity-token > identity-response.json
jq -r .token identity-response.json > identity.jwt
rm -f identity-response.json
```

A resposta contém `token` e `expires_at`. A duração padrão é de 300 segundos; valores explícitos vão de 60 a 300. A sessão de origem deve continuar válida por esse período. `basalt:IdentityTokenDurationSeconds` pode restringi-lo ainda mais. Renove chamando o endpoint novamente.

O sujeito é derivado da identidade autenticada. Nomes, sujeitos escolhidos pelo chamador e claims JWT arbitrários não são aceitos:

```text theme={null}
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:role:ROLE_UUID
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:service-account:SERVICE_ACCOUNT_UUID
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:instance:INSTANCE_UUID
```

Uma sessão direta de metadados da VM preserva o sujeito da VM. Uma sessão encadeada representa sua role de destino. Revogar a sessão de origem ou remover sua permissão bloqueia novas emissões pela API. Desanexar a role da VM bloqueia a emissão pelos metadados; revogue também as sessões Basaltic existentes para interromper a emissão pela API. Provas já emitidas continuam válidas até expirarem.

## Escolher a audiência de destino

A `audience` é escolhida para a plataforma de destino, não é fixa para AWS. Use o valor esperado pela plataforma e configure permissões de emissão e confiança correspondentes. Os exemplos AWS usam `sts.amazonaws.com`; outro serviço pode exigir uma URL, identificador de cliente ou URN. A audiência `basaltic` é reservada para tokens da API Basaltic.

O claim JWT é `aud`. A forma `iam.basaltic.sh:aud` é uma chave de condição de confiança AWS que referencia esse claim. Outras plataformas usam sua própria configuração de mapeamento de claims. Elas precisam aceitar JWTs externos de workloads e as assinaturas ES256 do Basaltic; apenas uma integração de login OIDC interativo não basta.

## Aceitar uma identidade externa

Três verificações independentes precisam passar:

1. Registre o emissor na **mesma conta da role de destino**, com as audiências aceitas pela conta.
2. Adicione o CRN do provedor à política de confiança da role e restrinja o sujeito.
3. Anexe à role as políticas de permissão para as operações necessárias ao workload.

O registro não concede permissões. A confiança permite que o workload assuma a role; as políticas de permissão determinam o que a sessão resultante pode fazer.

Consulte [como registrar um provedor](https://docs.basaltic.sh/pt/iam/roles.md#trusting-an-oidc-provider) pelo Console e pela API. A URL do emissor deve usar HTTPS. O documento de descoberta e o JWKS devem estar acessíveis pela internet pública. A descoberta deve indicar o mesmo emissor e os algoritmos de assinatura compatíveis. O emissor e o nome do provedor são imutáveis; audiências, descrição e tags podem ser atualizadas.

O Basaltic valida a assinatura e a expiração do JWT e exige que pelo menos uma audiência corresponda à lista atual do provedor. Um emissor registrado em outra conta não estabelece confiança na sua conta.

## Restringir a confiança

Sempre vincule a confiança ao sujeito desejado. Use também uma condição de audiência quando o provedor aceitar várias audiências, mas a role deva aceitar apenas uma.

```json theme={null}
{
  "principals": ["crn:iam::production:oidc-provider/workload-issuer"],
  "conditions": [
    {
      "operator": "equals",
      "key": "basalt:webidentity:Subject",
      "values": ["YOUR_EXACT_WORKLOAD_SUBJECT"]
    },
    {
      "operator": "equals",
      "set_operator": "for_any_value",
      "key": "basalt:webidentity:Audience",
      "values": ["urn:example:basaltic:production"]
    }
  ]
}
```

`Subject` é uma string. `Audience` é um conjunto, mesmo quando o JWT contém uma só audiência: sua condição precisa de `set_operator: "for_any_value"` para verificar pertinência. Uma condição escalar `equals` em `Audience` não corresponde a esse conjunto.

Provedores genéricos de clientes disponibilizam o emissor, o sujeito e a audiência verificados para avaliar a confiança. Claims personalizados arbitrários do JWT não estão disponíveis como chaves de política. Não presuma que um claim de instância EC2, um rótulo de job de CI ou outro campo personalizado restrinja a confiança, a menos que o próprio sujeito compatível forneça essa restrição.

Para GitHub Actions, use o sujeito exato emitido para o workflow, incluindo os IDs imutáveis do proprietário e do repositório quando presentes. Restrinja a organização ou o repositório e a branch ou o ambiente desejado. Provedores GitHub exigem uma restrição positiva de organização ou repositório no sujeito. O nome da sessão é um rótulo de auditoria; ele não altera o sujeito verificado.

## Trocar a prova

Envie o JWT e o CRN completo da role de destino ao endpoint público de IAM. A troca usa o próprio JWT e não exige uma chave de acesso ou token bearer Basaltic existente.

```http theme={null}
POST https://iam.basaltic.sh/v1/assume-role-with-web-identity
Content-Type: application/json

{
  "role": "crn:iam::production:role/deploy",
  "web_identity_token": "SIGNED_OIDC_JWT",
  "session_name": "deploy-main",
  "duration_seconds": 900
}
```

O CRN completo da role seleciona a conta. Não existe campo `account` na requisição. A resposta contém credenciais temporárias de chave de acesso e um token bearer. Use o bearer nas APIs Basaltic e as credenciais temporárias no endpoint compatível com S3. Consulte [autenticação](https://docs.basaltic.sh/pt/authentication.md).

Sessões de role Basaltic duram uma hora por padrão. Uma duração explícita deve ser de pelo menos 900 segundos e respeitar o máximo configurado na role, até 12 horas. A expiração da prova determina até quando ela pode ser trocada; não encurta uma sessão já emitida.

## Renovação e revogação

Obtenha uma nova prova de identidade do emissor e troque-a antes de a sessão Basaltic expirar. Essa troca não possui refresh token OIDC.

Atualizar as audiências de um provedor ou excluí-lo impede novas trocas que deixem de atender ao registro. Alterar a confiança da role afeta novas trocas. Sessões existentes permanecem válidas até expirarem ou serem revogadas. [Revogue uma sessão](https://docs.basaltic.sh/pt/iam/roles.md) para encerrar seu bearer e suas credenciais temporárias. Recriar um provedor com o mesmo nome não restaura o vínculo de confiança anterior; atualize a política da role para autorizar o novo provedor.

Provedores marcados como `is_system` são gerenciados pela plataforma e não podem ser alterados nem excluídos. Workloads de clientes devem registrar seu próprio emissor acessível publicamente.

## Descoberta e chaves

O Basaltic publica dois documentos de metadados com finalidades diferentes:

| URL | Finalidade |
| - | - |
| `https://iam.basaltic.sh/.well-known/openid-configuration` | Federação externa de identidade de workloads |
| `https://iam.basaltic.sh/.well-known/workload-jwks.json` | Chaves públicas de verificação dos JWTs de identidade de workloads |
| `https://iam.basaltic.sh/.well-known/oauth-authorization-server` | Metadados do servidor de autorização OAuth da API Basaltic |
| `https://iam.basaltic.sh/.well-known/jwks.json` | Chaves públicas dos tokens da API Basaltic |

Descubra e armazene em cache o JWKS adequado; não fixe uma única chave de assinatura. Durante a rotação, várias chaves públicas podem ser publicadas. Verifique `kid`, algoritmo, emissor, audiência, sujeito e expiração do JWT.

## Solução de problemas

| Resultado | Verifique |
| - | - |
| A troca retorna `401` | Registro do emissor na conta de destino, assinatura, expiração, audiência permitida e acesso à descoberta e ao JWKS |
| A troca retorna `403` | Confiança da role, sujeito exato, operador de conjunto da audiência e estado da conta ou organização |
| A troca funciona, mas uma requisição à API retorna `403` | Permissões da role, limites de permissão e CRN do recurso autorizado |
| A sessão continua funcionando após excluir o provedor | Revogue a sessão existente; excluir o provedor bloqueia novas trocas |
| Um workload recriado não consegue assumir a role anterior | Compare o sujeito imutável e atualize explicitamente a confiança se o substituto deve ter acesso |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.