configure aws credentials
v4.0.2
Configure suas credenciais AWS e variáveis de ambiente regional para uso em outras ações do GitHub.
Essa ação implementa a cadeia de resolução de credenciais JavaScript SDK do AWS JavaScript e exporta variáveis de ambiente de sessão para suas outras ações a serem usadas. As exportações variáveis do ambiente são detectadas pelos SDKs da AWS e pela AWS CLI para chamadas da AWS API.
As chamadas da API para a AWS precisam ser assinadas com informações de credenciais; portanto, quando você usa um dos SDKs da AWS ou uma ferramenta da AWS, você deve fornecer credenciais da AWS e região da AWS. Uma maneira de fazer isso nas ações do GitHub é usar um segredo de repositório com credenciais do IAM, mas isso não segue as diretrizes de segurança da AWS sobre o uso de credenciais de longo prazo. Em vez disso, recomendamos que você use uma credencial de longo prazo ou JWT para buscar uma credencial temporária e use -o com suas ferramentas. Esta ação do Github facilita exatamente isso.
SDKs e ferramentas da AWS procuram suas credenciais em variáveis de ambiente padronizado. Em essência, essa ação segue pelo fluxo de resolução de credenciais padrão e, no final, exporta variáveis de ambiente para você usar posteriormente.
Apoiamos cinco métodos para buscar credenciais da AWS, mas recomendamos que você use o provedor OIDC do Github em conjunto com um ponto de extremidade do provedor de identidade da AWS IAM configurado.
Para obter mais informações sobre como fazer isso, continue lendo.
Parte desta documentação pode ser imprecisa se você estiver usando o GHES (Github Enterprise Server), tome nota para revisar a documentação do GitHub quando relevante.
Por exemplo, o URL da qual o OIDC JWT é emitido é diferente do token.actions.githubusercontent.com e será exclusivo do seu servidor corporativo. Como resultado, você precisará configurar isso de maneira diferente ao criar o provedor de identidade.
Atualmente, não temos um ambiente de teste do GHES para validar essa ação. Se você estiver executando em GHEs e encontra problemas, informe -nos.
Recomendamos seguir as melhores práticas do Amazon IAM para as credenciais da AWS usadas nos fluxos de trabalho das ações do GitHub, incluindo:
Existem cinco maneiras diferentes de recuperar credenciais:
AssumeRoleWithWebIdentity )AssumeRole )AssumeRoleWithWebIdentity )AssumeRole )Como usamos o AWS JavaScript SDK, sempre usaremos o fluxo de resolução de credenciais para Node.js. Dependendo de suas entradas, a ação pode substituir partes desse fluxo.
Recomendamos usar a primeira opção acima: provedor OIDC do Github. Este método usa OIDC para obter credenciais de curta duração necessárias para suas ações. Consulte OIDC para obter mais informações sobre como configurar sua conta AWS para assumir uma função no OIDC.
A tabela a seguir descreve qual método usaremos para obter suas credenciais com base em quais valores são fornecidos à ação:
| Identidade usada | aws-access-key-id | role-to-assume | web-identity-token-file | role-chaining | permissão id-token |
|---|---|---|---|---|---|
| [✅ Recomendado] Assuma a função diretamente usando o provedor Github OIDC | ✔ | ✔ | |||
| Usuário iam | ✔ | ||||
| Assuma a função usando credenciais de usuário do IAM | ✔ | ✔ | |||
| Assuma a função usando credenciais de arquivo de token webIdentity | ✔ | ✔ | |||
| Assuma o papel usando credenciais existentes | ✔ | ✔ |
NOTA: Nem sempre é necessário role-chaining para usar as credenciais existentes. Se você está recebendo um erro "Credenciais carregados pelo SDK não corresponde", tente ativar esta opção.
Consulte Action.yml para obter mais detalhes.
| Opção | Descrição | Obrigatório |
|---|---|---|
| AWS-Region | Qual região da AWS usar | Sim |
| função de assumir | Papel para que busquem credenciais. Somente necessária para alguns tipos de autenticação. | Não |
| AWS-ACCESS-ke-ID | Chave de acesso da AWS para usar. Somente necessária para alguns tipos de autenticação. | Não |
| Aws-secret-access-key | Chave secreta da AWS para usar. Somente necessária para alguns tipos de autenticação. | Não |
| AWS-Session-Token | Token de sessão da AWS para usar. Usado em cenários de autenticação incomum. | Não |
| encadeamento de papéis | Use as credenciais existentes do ambiente para assumir uma nova função. | Não |
| público | O público JWT ao usar OIDC. Usado em partições não-defensivas da AWS, como as regiões da China. | Não |
| http-proxy | Um proxy HTTP a ser usado para chamadas de API. | Não |
| máscara-aws-conta-id | Os IDs da conta da AWS não são considerados secretos. De qualquer forma, definir isso ocultará os IDs da conta da saída de qualquer maneira. | Não |
| duração de função segundos | A duração da função assumida em segundos, se assumir uma função. Padrões para 1 hora. | Não |
| ID de função-external | O ID externo da função a assumir. Somente necessário se o seu papel exigir. | Não |
| nome de sessão de função | Padrões para "githubactions", mas podem ser alterados, se necessário. | Não |
| margem-skip-ship-session | Pula a marcação da sessão se definido. | Não |
| Política de sessão em linha | Você pode restringir ainda a política de função assumida, definindo uma política em linha aqui. | Não |
| políticas de sessão gerenciada | Você pode restringir ainda a política de função assumida especificando uma política gerenciada aqui. | Não |
| CREDENCIAIS DE SAÍDA | Quando definido, as saídas buscavam credenciais como saída da etapa de ação. Padrões para false. | Não |
| Unset-Girorrent-Credenciais | Quando definido, as tentativas de desencadear quaisquer credenciais existentes em seu corredor de ação. | Não |
| desativar-retristração | Lógica de repetição/retomada desativada para assumir chamadas de função. Por padrão, as tentativas estão ativadas. | Não |
| Represente-max-atts | Limita o número de tentativas de repetição antes de desistir. Padrões para 12. | Não |
| CARACTORES ESPECIAIS TRABALHO | Incommamente, alguns ambientes não podem tolerar caracteres especiais em uma chave secreta. Esta opção voltará a repetir credenciais de busca até que a chave de acesso secreto não contenha caracteres especiais. Esta opção substitui a retomar e a tentativa de retrato-max. | Não |
A duração da sessão padrão é de 1 hora .
Se você deseja ajustar isso, pode passar uma duração para role-duration-seconds , mas a duração não pode exceder o máximo que foi definido quando o papel do IAM foi criado.
Se sua função exigir um ID externo para assumir, você poderá fornecer o ID externo com a entrada de role-external-id
O nome da sessão padrão é "githubactions" e você pode modificá-lo especificando o nome desejado no role-session-name . A sessão será marcada com as seguintes tags: (Consulte a documentação do Github para definições de variáveis do ambiente GITHUB_ )
| Chave | Valor |
|---|---|
| Github | "Ações" |
| Repositório | Github_repository |
| Fluxo de trabalho | Github_workflow |
| Ação | Github_action |
| Ator | Github_actor |
| Filial | Github_ref |
| Comprometer-se | Github_sha |
Nota: Todos os valores de tags devem estar em conformidade com os requisitos de tag. Particularmente, GITHUB_WORKFLOW será truncado se for muito longo. Se GITHUB_ACTOR ou GITHUB_WORKFLOW contiver caracteres inválidos, os caracteres serão substituídos por um '*'.
A ação usará a marcação da sessão por padrão durante a suposição de função, a menos que você siga nossa recomendação e esteja assumindo uma função com um WebIdentity. Para a suposição de função do WebIdentity, as tags de sessão devem ser incluídas no token codificado do WebIdentity. Isso significa que as tags só podem ser fornecidas pelo provedor OIDC e não podem definir durante a chamada da API do PusheroleWithWebIdentity dentro da ação. Veja #419 para obter mais informações.
Você pode pular esta marcação de sessão, fornecendo role-skip-session-tagging como verdadeira nas entradas da ação:
uses : aws-actions/configure-aws-credentials@v4
with :
role-skip-session-tagging : trueAs políticas de sessão não são necessárias, mas permitem que você limite o escopo das credenciais buscadas sem fazer alterações nas funções do IAM. Você pode especificar políticas de sessão em linha diretamente no seu arquivo de fluxo de trabalho ou consultar uma política de sessão gerenciada existente por seu ARN.
Uma política do IAM no formato JSON rigoroso que você deseja usar como uma política de sessão em linha. Dependendo das preferências, o JSON pode ser escrito em uma única linha como esta:
uses : aws-actions/configure-aws-credentials@v4
with :
inline-session-policy : ' {"Version":"2012-10-17","Statement":[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:List*","Resource":"*"}]} 'Ou também podemos ter um JSON bem formatado:
uses : aws-actions/configure-aws-credentials@v4
with :
inline-session-policy : >-
{
"Version": "2012-10-17",
"Statement": [
{
"Sid":"Stmt1",
"Effect":"Allow",
"Action":"s3:List*",
"Resource":"*"
}
]
} Os nomes de recursos da Amazon (ARNs) das políticas gerenciadas pelo IAM que você deseja usar como políticas de sessão gerenciada. As políticas devem existir na mesma conta que a função. Você pode passar por uma única política gerenciada como esta:
uses : aws-actions/configure-aws-credentials@v4
with :
managed-session-policies : arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccessE podemos passar várias políticas gerenciadas gostam disso:
uses : aws-actions/configure-aws-credentials@v4
with :
managed-session-policies : |
arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess
arn:aws:iam::aws:policy/AmazonS3OutpostsReadOnlyAccess Agora você pode definir configurações de tentativa de quando a chamada do STS falhar. Por padrão, tentamos novamente com o retorno exponencial 12 vezes. Você pode desativar esse comportamento completamente, definindo a entrada disable-retry como true , ou pode configurar o número de vezes que ele se levanta com a entrada retry-max-attempts .
O ID da sua conta não é mascarado por padrão nos logs do fluxo de trabalho, pois não é considerado informações confidenciais. No entanto, você pode true a entrada de mask-aws-account-id para mascarar o ID da sua conta nos logs do fluxo de trabalho, se desejar.
Às vezes, as credenciais existentes em seu corredor podem atrapalhar o resultado pretendido. Você pode definir a entrada da entrada unset-current-credentials como true para contornar esse problema.
Alguns casos de borda são incapazes de analisar corretamente um AWS_SECRET_ACCESS_KEY se ele contiver caracteres especiais. Para mais informações, consulte a documentação da AWS CLI. Se você definir a opção special-characters-workaround , essa ação novamente novamente novamente, a opção de busca de credenciais até obtermos uma que não possui caracteres especiais. Esta opção substitui as opções de disable-retry e retry-max-attempts . Recomendamos que você não habilite essa opção, a menos que seja necessário, porque novamente a repetição de APIs infinitamente até que tenham sucesso não seja uma prática recomendada.
Recomendamos usar o provedor OIDC do Github para obter credenciais da AWS de curta duração necessárias para suas ações. Ao usar o OIDC, você configura o IAM para aceitar o JWTS do terminal OIDC do Github. Essa ação criará um JWT exclusivo para a execução do fluxo de trabalho usando o terminal OIDC e usará o JWT para assumir a função especificada com credenciais de curto prazo.
Para fazer isso funcionar
Configure seu fluxo de trabalho para usar o id-token: write permissão.
Configure seu público, se necessário.
Na sua conta da AWS, configure o IAM para confiar no provedor de identidade OIDC do Github.
Configure uma função do IAM com limites de reivindicação apropriados e escopo de permissão.
NOTA : Foi relatado que nomear seu papel "githubactions" para não funcionar. Veja #953.
Especifique o ARN da função ao configurar essa ação.
Primeiro, para que esta ação crie o JWT, seu arquivo de fluxo de trabalho deve ter o id-token: write permissão:
permissions :
id-token : write
contents : read Quando o JWT é criado, um público precisa ser especificado. Normalmente, você usaria sts.amazonaws.com , e essa ação usa isso por padrão se você não especificar um. Isso funcionará para a maioria dos casos. Alterar o público padrão pode ser necessário ao usar partições não-defeituosas da AWS, como regiões da China. Você pode especificar o público através da entrada audience :
- name : Configure AWS Credentials for China region audience
uses : aws-actions/configure-aws-credentials@v4
with :
audience : sts.amazonaws.com.cn
aws-region : us-east-3
role-to-assume : arn:aws-cn:iam::123456789100:role/my-github-actions-rolePara usar o provedor OIDC do Github, você deve primeiro configurar a Federação com o provedor como um IDP IAM. O provedor do GitHub OIDC só precisa ser criado uma vez por conta (ou seja, várias funções do IAM que podem ser assumidas pelo OIDC do GitHub podem compartilhar um único provedor OIDC). Aqui está um exemplo de modelo de formação de nuvem que configurará essa confiança para você.
Observe que a impressão digital abaixo foi definida para todos os F porque a impressão digital não é usada ao autenticar token.actions.githubusercontent.com . Este é um caso especial usado apenas quando o OIDC do Github está autenticando para o IAM . O IAM usa sua biblioteca de CAS confiáveis para autenticar. O valor ainda é a API, portanto deve ser especificada.
Você pode copiar o modelo abaixo ou carregá-lo daqui: https://d38mtn6aq9zhn6.cloudfront.net/configure-aws-credentials-latest.yml
Parameters :
GitHubOrg :
Description : Name of GitHub organization/user (case sensitive)
Type : String
RepositoryName :
Description : Name of GitHub repository (case sensitive)
Type : String
OIDCProviderArn :
Description : Arn for the GitHub OIDC Provider.
Default : " "
Type : String
OIDCAudience :
Description : Audience supplied to configure-aws-credentials.
Default : " sts.amazonaws.com "
Type : String
Conditions :
CreateOIDCProvider : !Equals
- !Ref OIDCProviderArn
- " "
Resources :
Role :
Type : AWS::IAM::Role
Properties :
AssumeRolePolicyDocument :
Statement :
- Effect : Allow
Action : sts:AssumeRoleWithWebIdentity
Principal :
Federated : !If
- CreateOIDCProvider
- !Ref GithubOidc
- !Ref OIDCProviderArn
Condition :
StringEquals :
token.actions.githubusercontent.com:aud : !Ref OIDCAudience
StringLike :
token.actions.githubusercontent.com:sub : !Sub repo:${GitHubOrg}/${RepositoryName}:*
GithubOidc :
Type : AWS::IAM::OIDCProvider
Condition : CreateOIDCProvider
Properties :
Url : https://token.actions.githubusercontent.com
ClientIdList :
- sts.amazonaws.com
ThumbprintList :
- ffffffffffffffffffffffffffffffffffffffff
Outputs :
Role :
Value : !GetAtt Role.Arn Para se alinhar com a melhor prática da Amazon IAM de conceder menos privilégio, o documento de política de função deve conter uma Condition que especifica um sujeito ( sub ) permitido assumir a função. O GitHub também recomenda a filtragem para o público correto ( aud ). Consulte a documentação da AWS IAM sobre a qual as reivindicações você pode filtrar em suas políticas de confiança.
Sem uma condição de sujeito ( sub ), qualquer usuário ou repositório do GitHub poderia potencialmente assumir a função. O sujeito pode ser escopo para uma organização e repositório do GitHub, conforme mostrado no modelo de formação de nuvem. No entanto, o escopo de sua organização e repo pode fazer com que a suposição de função falhe em alguns casos. Consulte Exemplo de reivindicações de disciplinas para obter detalhes específicos sobre qual o valor do sujeito dependendo do seu fluxo de trabalho. Você também pode personalizar sua reivindicação de assunto se desejar controle total sobre as informações que você pode filtrar em sua política de confiança. Se você não tem certeza de qual é a chave do seu assunto ( sub ), pode adicionar a ação actions-oidc-debugger ao seu fluxo de trabalho para ver o valor da tecla ( sub ) sujeito, bem como outras reivindicações.
Condições adicionais de reivindicação podem ser adicionadas para maior especificidade, conforme explicado na documentação do GitHub. Devido aos detalhes da implementação, nem todas as reivindicações do OIDC são atualmente apoiadas pelo IAM.
Para mais informações sobre ações OIDC e Github, consulte:
Se você executar suas ações do GitHub em um corredor auto-hospedado que já tem acesso a credenciais da AWS, como uma instância do EC2, não precisará fornecer credenciais de chave de acesso ao usuário do IAM para esta ação. Usaremos os métodos padrão de resolução de credenciais do AWS JavaScript SDK para encontrar suas credenciais; portanto, se o AWS JS SDK puder se autenticar em seu corredor, essa ação também.
Se nenhuma credenciais de chave de acesso forem fornecidas nas entradas de ação, essa ação usará credenciais do ambiente do corredor usando os métodos padrão para o AWS SDK para JavaScript.
Você pode usar esta ação para simplesmente configurar a região e a ID da conta no ambiente e, em seguida, usar as credenciais do corredor para todas as chamadas da AWS da AWS feitas por suas ações fluxo de trabalho:
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2Nesse caso, as credenciais do seu corredor devem ter permissões para chamar quaisquer AWS APIs chamadas pelo seu fluxo de trabalho de ação.
Ou você pode usar essa ação para assumir uma função e, em seguida, usar as credenciais de função para todas as chamadas da AWS da AWS feitas por suas ações: fluxo de trabalho:
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : my-github-actions-roleNesse caso, as credenciais do seu corredor devem ter permissões para assumir a função.
Você também pode assumir uma função usando um arquivo de token de identidade da Web, como se estiver usando o Amazon EKS IRSA. Os pods em execução em nós do EKS que não são executados como root podem usar esse arquivo para assumir uma função com uma identidade da web.
Se necessário, use um proxy HTTP, você pode configurá -lo na ação manualmente.
Além disso, essa ação sempre considerará a variável de ambiente HTTP_PROXY .
Proxy configurado manualmente:
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : my-github-actions-role
http-proxy : " http://companydomain.com:3128 "Proxy configurado na variável de ambiente:
# Your environment configuration
HTTP_PROXY= " http://companydomain.com:3128 " Este fluxo de trabalho não instala a CLI da AWS em seu ambiente. Os corredores auto-hospedados que pretendem executar essa ação antes de executar os comandos aws precisam instalar a CLI da AWS se ainda não estiver presente. A maioria dos ambientes de corredor hospedados no GitHub deve incluir a AWS CLI por padrão.
- name : Configure AWS Credentials
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : arn:aws:iam::123456789100:role/my-github-actions-role
role-session-name : MySessionName Neste exemplo, a ação carregará o token OIDC da variável de ambiente fornecida pelo GitHub e a usará para assumir a função arn:aws:iam::123456789100:role/my-github-actions-role com o nome da sessão MySessionName .
- name : Configure AWS Credentials
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : arn:aws:iam::123456789100:role/my-github-actions-role
role-session-name : MySessionName
- name : Configure other AWS Credentials
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : arn:aws:iam::987654321000:role/my-second-role
role-session-name : MySessionName
role-chaining : true Neste exemplo de duas etapas, a primeira etapa usará OIDC para assumir a função arn:aws:iam::123456789100:role/my-github-actions-role como no exemplo anterior. Depois disso, uma segunda etapa usará essa função para assumir uma função diferente, arn:aws:iam::987654321000:role/my-second-role .
- name : Configure AWS Credentials
uses : aws-actions/configure-aws-credentials@v4
with :
aws-access-key-id : ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key : ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region : us-east-2
role-to-assume : ${{ secrets.AWS_ROLE_TO_ASSUME }}
role-external-id : ${{ secrets.AWS_ROLE_EXTERNAL_ID }}
role-duration-seconds : 1200
role-session-name : MySessionName Neste exemplo, o Secret AWS_ROLE_TO_ASSUME contém uma string como arn:aws:iam::123456789100:role/my-github-actions-role . Para assumir uma função na mesma conta que as credenciais estáticas, você pode simplesmente especificar o nome de função, como role-to-assume: my-github-actions-role .
- name : Configure AWS Credentials 1
id : creds
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : arn:aws:iam::123456789100:role/my-github-actions-role
output-credentials : true
- name : get caller identity 1
run : |
aws sts get-caller-identity
- name : Configure AWS Credentials 2
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
aws-access-key-id : ${{ steps.creds.outputs.aws-access-key-id }}
aws-secret-access-key : ${{ steps.creds.outputs.aws-secret-access-key }}
aws-session-token : ${{ steps.creds.outputs.aws-session-token }}
role-to-assume : arn:aws:iam::123456789100:role/my-other-github-actions-role
- name : get caller identity2
run : |
aws sts get-caller-identity Este exemplo mostra que você pode fazer referência às credenciais buscadas como saídas se output-credentials forem definidas como true. Este exemplo também mostra que você pode usar a contribuição aws-session-token em uma situação em que os tokens de sessão são buscados e transmitidos a essa ação.
Este código é disponibilizado sob a licença do MIT.
Se você deseja relatar um problema de segurança em potencial neste projeto, não crie um problema do GitHub. Em vez disso, siga as instruções aqui ou envie um email diretamente à AWS Security.
