> ## 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. # Assumir função com identidade web > Troque um token de identidade emitido por um provedor de federação em que esta plataforma confia por credenciais temporárias. O resultado é a mesma sessão de função assumida `POST /v1/assume-role` mints, e é usado da mesma maneira. Essa solicitação carrega **sem assinatura** e é a única chamada de venda de credenciais que não o faz. Um chamador federado ainda não possui credenciais do Basaltic — é para isso que serve a troca — então o token no corpo *é* a credencial que está sendo apresentada. Uma assinatura enviada de qualquer maneira é ignorada, e nada é retirado do contexto da requisição: `role` e `account` são lidos do corpo como qualquer outro campo. Isso não deixa o ponto final aberto. Dois portões independentes têm que passar, e eles falham de forma diferente. **O token precisa ser verificado.** Isso acontece antes que qualquer função seja lida, portanto, um token forjado nunca alcança uma política de confiança. A assinatura deve ser encadeada a uma chave que o provedor publica, o público deve ser aquele que esta plataforma aceita, e `exp` deve ser no futuro. Um signatário errado, um token cunhado para outro consumidor e um token expirado respondem todos com `401` com a mesma mensagem — a resposta não diz qual verificação falhou. **A função tem que concordar.** A verificação do token estabelece quem está chamando; não concede nada. A função nomeada em `role` é assumida somente se sua própria política de confiança admite essa identidade. Seus `principals` devem nomear o provedor de federação, escrito `crn:iam:::oidc-provider/` — o único caso em que um principal de política de confiança não é o próprio CRN do chamador, porque uma identidade federada não tem CRN e o que é confiável é a fonte que a garantiu. Cada entrada em `conditions` deve então ser mantida contra as reivindicações do token: `basalt:webidentity:Subject` carrega o token `sub` e `basalt:webidentity:Audience` seu `aud`, então uma função pode vincular uma identidade em vez de aceitar tudo o que o provedor irá emitir. Uma condição em uma reivindicação que o token não carrega falha fechada. Uma função cuja política de confiança não nomeie nenhum provedor, portanto, não pode ser assumida dessa maneira, por mais bom que o token seja. Essa é a linha entre as duas falhas: `401` significa que o token não é confiável, `403` significa que é e a função ainda não o terá. As credenciais retornam com o escopo para `account`, carregando as próprias permissões da função. Não há nenhum campo `policy` aqui — ao contrário de `POST /v1/assume-role`, uma sessão federada não pode ser escopo down no momento da troca, então as políticas anexadas da função são a concessão inteira. Dimensione o papel de acordo. Como não requer credenciais, as solicitações são limitadas por taxa por IP do cliente. Quais provedores são confiáveis faz parte da própria configuração da plataforma. Ainda não há uma API para registrar um provedor de identidade próprio, portanto, essa operação está ativa, mas não tem um provedor externo cujos tokens aceitaria; as funções que a usam hoje são gerenciadas pela plataforma. Requer **nenhuma ação do IAM**. O acesso é decidido pelas próprias regras do endpoint, e não por uma política — consulte a descrição acima. ## OpenAPI ````yaml /pt/api-reference/specs/iam.yaml post /v1/assume-role-with-web-identity openapi: 3.0.3 info: title: API do Basaltic IAM version: 1.0.0 description: > Gerenciamento de identidade e acesso de conta: contas de serviço, funções, políticas de conta e sessões temporárias com escopo de conta. A autenticação e o login pessoal permanecem no IAM. Organizações, contas, usuários, grupos e políticas da organização são gerenciados pela API do Workspace. As funções e políticas personalizadas pertencem à conta selecionada.Seus CRNs globais usam uma região vazia e o identificador da conta proprietária. Políticas de sistema compartilhadas usam crn:iam:::policy/As entradas de relacionamento são classificadas uma vez como CRN, UUID ou nome, sem fallback de sintaxe. AssumeRole resolve a conta de propriedade da função de destino. O chamador precisa de permissão de origem e a função de destino deve confiar no chamador; a sessão resultante usa somente as permissões da função de destino, sujeita a limites e restrições de sessão. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://iam.basaltic.sh description: Endpoint global da API security: - BearerAuth: [] paths: /v1/assume-role-with-web-identity: post: tags: - IAM summary: Assumir função com identidade web description: > Troque um token de identidade emitido por um provedor de federação em que esta plataforma confia por credenciais temporárias. O resultado é a mesma sessão de função assumida `POST /v1/assume-role` mints, e é usado da mesma maneira. Essa solicitação carrega **sem assinatura** e é a única chamada de venda de credenciais que não o faz. Um chamador federado ainda não possui credenciais do Basaltic — é para isso que serve a troca — então o token no corpo *é* a credencial que está sendo apresentada. Uma assinatura enviada de qualquer maneira é ignorada, e nada é retirado do contexto da requisição: `role` e `account` são lidos do corpo como qualquer outro campo. Isso não deixa o ponto final aberto. Dois portões independentes têm que passar, e eles falham de forma diferente. **O token precisa ser verificado.** Isso acontece antes que qualquer função seja lida, portanto, um token forjado nunca alcança uma política de confiança. A assinatura deve ser encadeada a uma chave que o provedor publica, o público deve ser aquele que esta plataforma aceita, e `exp` deve ser no futuro. Um signatário errado, um token cunhado para outro consumidor e um token expirado respondem todos com `401` com a mesma mensagem — a resposta não diz qual verificação falhou. **A função tem que concordar.** A verificação do token estabelece quem está chamando; não concede nada. A função nomeada em `role` é assumida somente se sua própria política de confiança admite essa identidade. Seus `principals` devem nomear o provedor de federação, escrito `crn:iam:::oidc-provider/` — o único caso em que um principal de política de confiança não é o próprio CRN do chamador, porque uma identidade federada não tem CRN e o que é confiável é a fonte que a garantiu. Cada entrada em `conditions` deve então ser mantida contra as reivindicações do token: `basalt:webidentity:Subject` carrega o token `sub` e `basalt:webidentity:Audience` seu `aud`, então uma função pode vincular uma identidade em vez de aceitar tudo o que o provedor irá emitir. Uma condição em uma reivindicação que o token não carrega falha fechada. Uma função cuja política de confiança não nomeie nenhum provedor, portanto, não pode ser assumida dessa maneira, por mais bom que o token seja. Essa é a linha entre as duas falhas: `401` significa que o token não é confiável, `403` significa que é e a função ainda não o terá. As credenciais retornam com o escopo para `account`, carregando as próprias permissões da função. Não há nenhum campo `policy` aqui — ao contrário de `POST /v1/assume-role`, uma sessão federada não pode ser escopo down no momento da troca, então as políticas anexadas da função são a concessão inteira. Dimensione o papel de acordo. Como não requer credenciais, as solicitações são limitadas por taxa por IP do cliente. Quais provedores são confiáveis faz parte da própria configuração da plataforma. Ainda não há uma API para registrar um provedor de identidade próprio, portanto, essa operação está ativa, mas não tem um provedor externo cujos tokens aceitaria; as funções que a usam hoje são gerenciadas pela plataforma. operationId: assumeRoleWithWebIdentity requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssumeRoleWithWebIdentityRequest' responses: '200': description: Função assumida com sucesso content: application/json: schema: $ref: '#/components/schemas/AssumeRoleResponse' '400': $ref: '#/components/responses/BadRequest' '401': description: > O token não foi verificado — um signatário não confiável, um público que esta plataforma não aceita ou um token expirado. Uma mensagem abrange os três. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: invalid web identity token request_id: 550e8400-e29b-41d4-a716-446655440000 '403': description: > O token foi verificado, mas a política de confiança da função não o admite — o provedor não está entre seus `principals`, ou uma condição nas reivindicações do token não foi atendida. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IAM_CANNOT_ASSUME_ROLE message: You are not authorized to assume this role request_id: 550e8400-e29b-41d4-a716-446655440000 '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '501': description: > A federação de identidade da Web não está configurada nesta região, portanto, não há provedor para verificar um token. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_IMPLEMENTED message: web identity federation is not configured request_id: 550e8400-e29b-41d4-a716-446655440000 '503': description: > A credencial não foi recusada — uma dependência de plataforma não pôde concluir a troca. Tente novamente em vez de rodar a função ou a chave. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: SERVICE_UNAVAILABLE message: >- The service is temporarily unavailable. Please try again later. request_id: 550e8400-e29b-41d4-a716-446655440000 security: [] components: schemas: AssumeRoleWithWebIdentityRequest: type: object additionalProperties: false description: > A troca que um chamador federado envia. Ele não carrega nenhuma assinatura — o token é a credencial — então cada campo é lido do corpo e nada é inferido do contexto da solicitação. required: - web_identity_token - role - account properties: web_identity_token: type: string description: > O token de identidade a ser trocado, como um JWT assinado. É verificado antes de qualquer função ser lida: a assinatura deve ser encadeada a uma chave que o provedor confiável publica, o público deve ser aquele que esta plataforma foi configurada para aceitar e `exp` deve ser no futuro. example: eyJhbGciOiJSUzI1NiIsImtpZCI6... role: $ref: '#/components/schemas/RoleReference' account: $ref: '#/components/schemas/AccountReference' session_name: type: string description: > Um rótulo registrado na sessão e na trilha de auditoria. Por padrão, a reivindicação `sub` do token, de modo que uma sessão sem nome ainda registra de qual identidade ela veio. example: reports-exporter duration_seconds: type: integer minimum: 900 maximum: 43200 default: 3600 description: > Duração da validade da credencial (15 min a 12 horas). Um valor acima do próprio `max_session_duration` da função é rejeitado em vez de ser fixado. example: 3600 AssumeRoleResponse: type: object description: > As credenciais de uma sessão de função, em ambas as formas que podem ser apresentadas. `access_token` é um token de portador para esta API — envie-o como `Authorization: Bearer `. Os outros quatro campos são credenciais do AWS SigV4 para o endpoint de armazenamento de objetos compatível com o S3, que não diz mais nada. Ambos vêm da mesma sessão e compartilham sua expiração, portanto, revogar a sessão interrompe ambos de uma só vez. Use o que o endpoint que você está chamando precisa; não há necessidade de escolher um no momento da solicitação. properties: access_token: type: string description: > Token de portador para a API Basaltic. Esteja presente em cada sessão de função. example: eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9... token_type: type: string description: Sempre `Bearer` quando `access_token` está presente. example: Bearer expires_in: type: integer description: Segundos até que o `access_token` expire. example: 3600 access_key_id: type: string description: ID da chave de acesso SigV4, para o endpoint S3. example: AKIA... secret_access_key: type: string description: SigV4 secreto, para o endpoint S3. example: wJalrXUtnFEMI... session_token: type: string description: > Token de sessão SigV4, para o endpoint S3. Envie como `X-Amz-Security-Token` e inclua-o em `SignedHeaders`. example: FwoGZXIvYXdzE... expiration: type: string format: date-time description: > Quando a sessão — e, portanto, ambos os formulários de credenciais — expira. example: '2026-01-15T09:30:00Z' account_id: type: string description: UUID da conta proprietária da função de destino. format: uuid account_handle: type: string description: O identificador da conta proprietária da função de destino. role_id: type: string description: UUID imutável da função assumida. format: uuid Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Código de erro identificando o tipo de erro example: INVALID_INPUT message: type: string description: Mensagem de erro legível pelo ser humano example: Invalid request parameters params: type: object additionalProperties: true description: >- Valores não sensíveis opcionais para interpolação de erros localizados, codificados por código de erro. Nunca presente para erros de servidor. example: instances: 2 pools: 0 request_id: type: string format: uuid description: Solicitar ID para depuração example: 550e8400-e29b-41d4-a716-446655440000 RoleReference: type: string description: >- UUID da função da conta, nome imutável na conta selecionada, ou crn:iam:::papel/. AssumeRole pode usar um CRN qualificado para direcionar outra conta na mesma organização.A sessão resultante é vinculada à conta de função de destino. example: crn:iam::production:role/reports AccountReference: type: string description: >- UUID da conta, identificador imutável ou CRN de uma conta do Workspace (crn:workspace:::account/A conta estabelece a organização proprietária para a federação e deve corresponder à conta de função de destino. example: crn:workspace:::account/9f8b1c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d responses: BadRequest: description: Parâmetros de solicitação inválidos content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Página não encontrada content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 TooManyRequests: description: > Limite de taxa excedido. O orçamento é uma janela fixa contada por endpoint e por chamador — o principal autenticado quando a solicitação carrega credenciais, o IP do cliente caso contrário — para que um endpoint limitado nunca gaste o orçamento de outro e um locatário nunca gaste o de outro. Aguarde `Retry-After` segundos, em seguida, tente novamente. Os cabeçalhos `X-RateLimit-*` também são baseados nas respostas bem-sucedidas de um endpoint com taxa limitada, para que um cliente possa se adaptar ao invés de descobrir o limite ao atingi-lo. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMITED message: Too many requests, please try again later request_id: 550e8400-e29b-41d4-a716-446655440000 headers: Retry-After: description: Segundos para aguardar antes de tentar novamente. Nunca zero. required: true schema: type: integer minimum: 1 example: 42 X-RateLimit-Limit: description: Solicitações permitidas por janela neste endpoint. required: true schema: type: integer minimum: 1 example: 5 X-RateLimit-Remaining: description: Solicitações deixadas na janela atual. Sempre 0 em um 429. required: true schema: type: integer minimum: 0 example: 0 X-RateLimit-Reset: description: >- Segundos até que a janela seja redefinida — uma duração, não um carimbo de data/hora, portanto, não precisa de acordo de clock entre cliente e servidor. required: true schema: type: integer minimum: 1 example: 42 InternalServerError: description: Erro interno do servidor content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >+ Um token bearer OAuth 2.0, enviado como `Authorization: Bearer `. Esta é a forma recomendada de autenticação. Obtenha o token trocando o par de chaves de acesso de uma conta de serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`. Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis com OAuth podem obter e renovar o token para você. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso também serve como credencial AWS SigV4 para o endpoint de objetos compatível com S3, que aceita somente esse método de autenticação. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.