# Tutorial do IAM: use um modelo de CloudFormation para criar um perfil do IAM federado por SAML
Quando você tem um provedor de identidades (IdP do SAML) existente configurado em sua conta da AWS, você pode criar perfis federados do IAM que confiam nesse IdP. Este tutorial mostra como usar um modelo do CloudFormation para criar um perfil federado do IAM por SAML que pode ser assumido por usuários autenticados por meio do seu IdP externo.
O modelo cria um perfil federado do IAM com uma política de confiança que permite que o IdP do SAML assuma o perfil. Os usuários autenticados pelo seu IdP externo podem assumir esse perfil para acessar recursos da AWS nas permissões anexadas ao perfil.
O recurso implantado consiste no seguinte:
+ Um perfio federada do IAM que confia em seu IdP do SAML existente.
+ Políticas gerenciadas configuráveis que podem ser anexadas ao perfil para conceder permissões específicas.
+ Configurações opcionais de limite de permissões e duração da sessão.
## Pré-requisitos
Este tutorial pressupõe que você já tenha os seguintes itens configurados:
+ Um IdP do SAML existente configurado em sua conta da AWS. Se você não tiver um, poderá criá-lo usando o tutorial [Tutorial do IAM: use um modelo do CloudFormation para criar um provedor de identidades (IdP) do SAML](tutorial_saml-idp.md).
+ O ARN do seu IdP do SAML, que você precisará especificar como parâmetro ao criar a pilha.
+ Python 3.6 ou posterior instalado em sua máquina local para executar o comando Python usado neste tutorial para formatar o arquivo XML de metadados SAML do seu IdP.
## Crie um perfil federado do SAML usando CloudFormation
Para criar o perfil federado do IdP do SAML, você criará um modelo do CloudFormation e o usará para criar uma pilha contendo o perfil.
### Criar o modelo do
Primeiro, crie o modelo do CloudFormation.
1. Na seção [Modelo](#tutorial_saml-federated-role-template), clique no ícone de cópia na guia **JSON** ou **YAML** para copiar o conteúdo do modelo.
1. Copie o conteúdo do modelo em um novo arquivo.
1. Salve o arquivo localmente.
### Crie a pilha.
Em seguida, use o arquivo de modelo que você salvou para provisionar uma pilha do CloudFormation.
1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Na página **Pilhas**, no menu **Criar pilha**, escolha **com novos recursos (padrão)**.
1. Especifique o modelo:
1. Em **Pré-requisito**, escolha **Escolher um modelo existente**.
1. Em **Especificar modelo**, escolha **Fazer upload de um arquivo de modelo**.
1. Selecione **Escolher arquivo**, navegue até o arquivo de modelo e selecione-o.
1. Escolha **Próximo**.
1. Especifique os seguintes detalhes da pilha:
1. Digite um nome de pilha.
1. Para **SAMLProviderARN**, insira o ARN do seu IdP do SAML existente. Isso deve estar no formato `arn:aws:iam::123456789012:saml-provider/YourProviderName`.
Exemplo: `arn:aws:iam::123456789012:saml-provider/CompanyIdP`
**nota**
Se você criou seu IdP do SAML usando o tutorial [Tutorial do IAM: use um modelo do CloudFormation para criar um provedor de identidades (IdP) do SAML](tutorial_saml-idp.md), poderá encontrar o ARN do provedor na guia Saídas dessa pilha do CloudFormation.
1. Para **RoleName**, é possível deixar isso em branco para gerar automaticamente um nome com base no nome da pilha ou inserir um nome personalizado para o perfil do IAM.
Exemplo: `SAML-Developer-Access` ou `SAML-ReadOnly-Role`
1. Para outros parâmetros, aceite os valores padrão ou insira seus próprios com base em seus requisitos:
+ **RoleSessionDuration**: duração máxima da sessão em segundos (3600-43200, padrão 7200)
Exemplo: `14400` (4 horas)
+ **RolePermissionsBoundary**: ARN opcional de uma política de limite de permissões
Exemplo: `arn:aws:iam::123456789012:policy/DeveloperBoundary`
+ **RolePath**: caminho para o perfil do IAM (o padrão é /)
Exemplo: `/saml-roles/`
+ **ManagedPolicy1-5**: ARNs opcionais de até 5 políticas gerenciadas para anexar
Exemplo de ManagedPolicy1: `arn:aws:iam::aws:policy/ReadOnlyAccess`
Exemplo de ManagedPolicy2: `arn:aws:iam::123456789012:policy/CustomPolicy`
1. Escolha **Próximo**.
1. Configurar as opções da pilha:
1. Em **Opções de falha de pilha**, escolha **Excluir todos os recursos recém-criados**.
**nota**
A escolha dessa opção evita que você seja cobrado por recursos cuja política de exclusão especifica que eles sejam retidos mesmo que a criação da pilha falhe.
1. Aceite todos os outros valores padrão.
1. Em **Capacidades**, marque a caixa para confirmar que o CloudFormation pode criar recursos do IAM em sua conta.
1. Escolha **Próximo**.
1. Revise os detalhes a pilha e selecione **Enviar**.
CloudFormationO cria a pilha. Quando a criação da pilha for concluída, os recursos da pilha estarão prontos para uso. Você pode usar a guia **Recursos** na página de detalhes da pilha para visualizar os recursos que foram provisionados em sua conta.
A pilha produzirá o seguinte valor, que você pode ver na guia **Saídas**:
+ **RoleARN**: o ARN do perfil do IAM criado (por exemplo, `arn:aws:iam::123456789012:role/SAML-Developer-Access` ou `arn:aws:iam::123456789012:role/stack-name-a1b2c3d4` se estiver usando um nome gerado automaticamente).
Você precisará desse ARN de perfil ao configurar seu IdP para enviar os atributos SAML apropriados para assumir o perfil.
## Teste o perfil federado do SAML
Depois que o perfil federado do SAML for criado, você pode verificar sua configuração e testar a configuração da federação.
1. Abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação, escolha **Perfis**.
1. Encontre e selecione o perfil federado recém-criado.
Se você forneceu um nome de perfil personalizado, procure esse nome. Se você deixar o parâmetro RoleName vazio, o perfil terá um nome gerado automaticamente com base no nome da pilha e um identificador exclusivo.
1. Selecione a guia **Relações de confiança** para revisar a política de confiança.
A política de confiança deve mostrar que o IdP do SAML é confiável para assumir esse perfil com a condição de que o público do SAML (`SAML:aud`) corresponda ao `https://signin.aws.amazon.com/saml`.
1. Clique na guia **Permissões** para revisar as políticas anexadas.
Você pode ver todas as políticas gerenciadas que foram anexadas ao perfil durante a criação.
1. Observe o **ARN do perfil** exibido na página de resumo do perfil.
Você precisará desse ARN para configurar seu IdP externo para permitir que os usuários assumam esse perfil.
Seu perfil federado do SAML agora está pronto para ser usado. Configure seu IdP externo para incluir o ARN desse perfil nas asserções do SAML, e os usuários autenticados poderão assumir esse perfil para acessar recursos da AWS.
## Limpeza: excluir recursos
Como etapa final, você excluirá a pilha e os recursos que ela contém.
1. Abra o CloudFormation Console.
1. Na página **Pilhas**, escolha a pilha criada a partir do modelo, escolha **Excluir** e confirme para **Excluir**.
O CloudFormation inicia a exclusão da pilha e de todos os recursos que ela inclui.
## Detalhes do modelo do CloudFormation
### Recursos
O modelo do CloudFormation para este tutorial criará o seguinte recurso em sua conta:
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html): uma perfil federado do IAM que pode ser assumido por usuários autenticados por meio do seu IdP do SAML.
### Configuração
O modelo inclui os seguintes parâmetros configuráveis:
+ **RoleName**: nome do perfil do IAM (deixe em branco para nome gerado automaticamente)
+ **SAMLProviderARN**: ARN do IdP do SAML (obrigatório)
+ **RoleSessionDuration**: duração máxima da sessão em segundos (3600-43200, padrão 7200)
+ **RolePermissionsBoundary**: ARN opcional da política de limite de permissões
+ **RolePath**: caminho para o perfil do IAM (padrão /)
+ **ManagedPolicy1-5**: ARNs opcionais de até 5 políticas gerenciadas para anexar
## Modelo do CloudFormation
Salve o código JSON ou YAML a seguir em outro arquivo para usar como modelo do CloudFormation neste tutorial.
------
#### [ JSON ]
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "[AWSDocs] IAM: tutorial_saml-federated-role",
"Parameters": {
"RoleName": {
"Type": "String",
"Description": "Name of the IAM Role (leave empty for auto-generated name like '{StackName}-{UniqueId}')",
"Default": "",
"AllowedPattern": "^$|^[\\w+=,.@-]{1,64}$",
"ConstraintDescription": "Must be empty or 1-64 characters and can contain alphanumeric characters and +=,.@-"
},
"SAMLProviderARN": {
"Type": "String",
"Description": "ARN of the SAML Identity Provider",
"AllowedPattern": "^arn:aws:iam::\\d{12}:saml-provider/[a-zA-Z0-9._-]+$",
"ConstraintDescription": "Must be a valid SAML provider ARN"
},
"RoleSessionDuration": {
"Type": "Number",
"Description": "The maximum session duration (in seconds) that you want to set for the specified role (3600-43200)",
"MinValue": 3600,
"MaxValue": 43200,
"Default": 7200
},
"RolePermissionsBoundary": {
"Type": "String",
"Description": "Optional ARN of the permissions boundary policy (leave empty for none)",
"Default": ""
},
"RolePath": {
"Type": "String",
"Description": "Path for the IAM role (must start and end with /)",
"Default": "/",
"AllowedPattern": "^\/.*\/$|^\/$",
"ConstraintDescription": "Role path must start and end with forward slash (/)"
},
"RoleManagedPolicy1": {
"Type": "String",
"Description": "Optional managed policy ARN 1",
"Default": ""
},
"RoleManagedPolicy2": {
"Type": "String",
"Description": "Optional managed policy ARN 2",
"Default": ""
},
"RoleManagedPolicy3": {
"Type": "String",
"Description": "Optional managed policy ARN 3",
"Default": ""
},
"RoleManagedPolicy4": {
"Type": "String",
"Description": "Optional managed policy ARN 4",
"Default": ""
},
"RoleManagedPolicy5": {
"Type": "String",
"Description": "Optional managed policy ARN 5",
"Default": ""
}
},
"Conditions": {
"HasCustomRoleName": {"Fn::Not": [{"Fn::Equals": [{"Ref": "RoleName"}, ""]}]},
"HasPermissionsBoundary": {"Fn::Not": [{"Fn::Equals": [{"Ref": "RolePermissionsBoundary"}, ""]}]},
"HasPolicy1": {"Fn::Not": [{"Fn::Equals": [{"Ref": "RoleManagedPolicy1"}, ""]}]},
"HasPolicy2": {"Fn::Not": [{"Fn::Equals": [{"Ref": "RoleManagedPolicy2"}, ""]}]},
"HasPolicy3": {"Fn::Not": [{"Fn::Equals": [{"Ref": "RoleManagedPolicy3"}, ""]}]},
"HasPolicy4": {"Fn::Not": [{"Fn::Equals": [{"Ref": "RoleManagedPolicy4"}, ""]}]},
"HasPolicy5": {"Fn::Not": [{"Fn::Equals": [{"Ref": "RoleManagedPolicy5"}, ""]}]}
},
"Resources": {
"SAMLFederatedRole": {
"Type": "AWS::IAM::Role",
"Properties": {
"RoleName": {"Fn::If": ["HasCustomRoleName", {"Ref": "RoleName"}, {"Ref": "AWS::NoValue"}]},
"Description": "IAM role with SAML provider trust",
"MaxSessionDuration": {"Ref": "RoleSessionDuration"},
"PermissionsBoundary": {"Fn::If": ["HasPermissionsBoundary", {"Ref": "RolePermissionsBoundary"}, {"Ref": "AWS::NoValue"}]},
"Path": {"Ref": "RolePath"},
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": {"Ref": "SAMLProviderARN"}
},
"Action": "sts:AssumeRoleWithSAML",
"Condition": {
"StringEquals": {
"SAML:aud": "https://signin.aws.amazon.com/saml"
}
}
}
]
},
"ManagedPolicyArns": {
"Fn::Split": [
",",
{
"Fn::Join": [
",",
[
{"Fn::If": ["HasPolicy1", {"Ref": "RoleManagedPolicy1"}, {"Ref": "AWS::NoValue"}]},
{"Fn::If": ["HasPolicy2", {"Ref": "RoleManagedPolicy2"}, {"Ref": "AWS::NoValue"}]},
{"Fn::If": ["HasPolicy3", {"Ref": "RoleManagedPolicy3"}, {"Ref": "AWS::NoValue"}]},
{"Fn::If": ["HasPolicy4", {"Ref": "RoleManagedPolicy4"}, {"Ref": "AWS::NoValue"}]},
{"Fn::If": ["HasPolicy5", {"Ref": "RoleManagedPolicy5"}, {"Ref": "AWS::NoValue"}]}
]
]
}
]
}
}
}
},
"Outputs": {
"RoleARN": {
"Description": "ARN of the created IAM Role",
"Value": {"Fn::GetAtt": ["SAMLFederatedRole", "Arn"]},
"Export": {
"Name": {"Fn::Sub": "${AWS::StackName}-RoleARN"}
}
}
}
}
```
------
#### [ YAML ]
```
AWSTemplateFormatVersion: '2010-09-09'
Description: '[AWSDocs] IAM: tutorial_saml-federated-role'
Parameters:
RoleName:
Type: String
Description: 'Name of the IAM Role (leave empty for auto-generated name like ''{StackName}-{UniqueId}'')'
Default: ""
AllowedPattern: '^$|^[\w+=,.@-]{1,64}$'
ConstraintDescription: 'Must be empty or 1-64 characters and can contain alphanumeric characters and +=,.@-'
SAMLProviderARN:
Type: String
Description: 'ARN of the SAML Identity Provider'
AllowedPattern: '^arn:aws:iam::\d{12}:saml-provider/[a-zA-Z0-9._-]+$'
ConstraintDescription: 'Must be a valid SAML provider ARN'
RoleSessionDuration:
Type: Number
Description: 'The maximum session duration (in seconds) that you want to set for the specified role (3600-43200)'
MinValue: 3600
MaxValue: 43200
Default: 7200
RolePermissionsBoundary:
Type: String
Description: Optional ARN of the permissions boundary policy (leave empty for none)
Default: ""
RolePath:
Type: String
Description: 'Path for the IAM role (must start and end with /)'
Default: "/"
AllowedPattern: '^\/.*\/$|^\/$'
ConstraintDescription: 'Role path must start and end with forward slash (/)'
RoleManagedPolicy1:
Type: String
Description: Optional managed policy ARN 1
Default: ""
RoleManagedPolicy2:
Type: String
Description: Optional managed policy ARN 2
Default: ""
RoleManagedPolicy3:
Type: String
Description: Optional managed policy ARN 3
Default: ""
RoleManagedPolicy4:
Type: String
Description: Optional managed policy ARN 4
Default: ""
RoleManagedPolicy5:
Type: String
Description: Optional managed policy ARN 5
Default: ""
Conditions:
HasCustomRoleName: !Not [!Equals [!Ref RoleName, ""]]
HasPermissionsBoundary: !Not [!Equals [!Ref RolePermissionsBoundary, ""]]
HasPolicy1: !Not [!Equals [!Ref RoleManagedPolicy1, ""]]
HasPolicy2: !Not [!Equals [!Ref RoleManagedPolicy2, ""]]
HasPolicy3: !Not [!Equals [!Ref RoleManagedPolicy3, ""]]
HasPolicy4: !Not [!Equals [!Ref RoleManagedPolicy4, ""]]
HasPolicy5: !Not [!Equals [!Ref RoleManagedPolicy5, ""]]
Resources:
SAMLFederatedRole:
Type: 'AWS::IAM::Role'
Properties:
RoleName: !If
- HasCustomRoleName
- !Ref RoleName
- !Ref AWS::NoValue
Description: 'IAM role with SAML provider trust'
MaxSessionDuration: !Ref RoleSessionDuration
PermissionsBoundary: !If
- HasPermissionsBoundary
- !Ref RolePermissionsBoundary
- !Ref AWS::NoValue
Path: !Ref RolePath
AssumeRolePolicyDocument:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal:
Federated: !Ref SAMLProviderARN
Action: 'sts:AssumeRoleWithSAML'
Condition:
StringEquals:
'SAML:aud': 'https://signin.aws.amazon.com/saml'
ManagedPolicyArns:
!Split
- ','
- !Join
- ','
- - !If [HasPolicy1, !Ref RoleManagedPolicy1, !Ref 'AWS::NoValue']
- !If [HasPolicy2, !Ref RoleManagedPolicy2, !Ref 'AWS::NoValue']
- !If [HasPolicy3, !Ref RoleManagedPolicy3, !Ref 'AWS::NoValue']
- !If [HasPolicy4, !Ref RoleManagedPolicy4, !Ref 'AWS::NoValue']
- !If [HasPolicy5, !Ref RoleManagedPolicy5, !Ref 'AWS::NoValue']
Outputs:
RoleARN:
Description: 'ARN of the created IAM Role'
Value: !GetAtt SAMLFederatedRole.Arn
Export:
Name: !Sub '${AWS::StackName}-RoleARN'
```
------