# Tutorial do IAM: use um modelo de CloudFormation para criar um provedor de identidades (IdP) do SAML e um perfil do IAM federado por SAML
Para se familiarizar com a federação do SAML e seus recursos, você usará um modelo de CloudFormation para configurar um provedor de identidades (IdP) do SAML e o perfil federado do IAM associado. Este tutorial mostra como criar os dois recursos juntos em uma única pilha.
O modelo cria um IdP do SAML que pode ser usado para acesso federado aos recursos da AWS, junto com um perfil do IAM que confia no provedor de SAML. Os usuários autenticados pelo seu IdP externo podem assumir esse perfil para acessar recursos da AWS.
Os recursos implantados consistem no seguinte:
+ Um IdP do SAML configurado com o documento de metadados do seu IdP.
+ Um perfil federado do IAM que confia no IdP do SAML e pode ser assumido por usuários autenticados.
+ Políticas gerenciadas configuráveis que podem ser anexadas ao perfil para conceder permissões específicas.
## Pré-requisitos
Este tutorial pressupõe que você já tenha os seguintes itens configurados:
+ 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.
+ Um documento de metadados SAML do seu IdP externo salvo como um arquivo XML.
## Criar um IdP e um perfil do SAML usando o CloudFormation
Para criar o IdP do SAML e o perfil federado, você criará um modelo do CloudFormation e o usará para criar uma pilha contendo os dois recursos.
### Criar o modelo do
Primeiro, crie o modelo do CloudFormation.
1. Na seção [Modelo](#tutorial_saml-idp-and-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. Você pode deixar o campo **IdentityProviderName** em branco para gerar automaticamente um nome com base no nome da pilha ou inserir um nome personalizado para seu IdP do SAML.
Exemplo: `CompanyIdP` ou `EnterpriseSSO`
1. Para **IdentityProviderSAMLMetadataDocument**, você precisa formatar seu arquivo XML de metadados SAML como uma única linha antes de colá-lo nesse campo. Isso é necessário porque o console do CloudFormation exige que o conteúdo XML seja formatado como uma única linha quando passado pelos parâmetros do console.
Use o seguinte comando Python para reformatar seu arquivo XML:
```
python3 -c "import sys, re; content=open(sys.argv[1]).read(); print(re.sub(r'>\s+<', '><', content.replace('\n', '').replace('\r', '').strip()))" saml-metadata.xml
```
**nota**
O documento de metadados SAML do IdP deve ser formatado como uma única linha para entrada de parâmetros do console. O comando Python remove quebras de linha e espaços em branco extras para criar o formato necessário, mantendo todo o conteúdo e estrutura originais.
Copie a saída do comando Python e cole-a no campo **IdentityProviderSAMLMetadataDocument**.
Exemplo de documento de metadados SAML formatado (abreviado):
```
MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiIMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV...urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
```
1. Você pode deixar **RoleName** em branco para gerar automaticamente um nome com base no nome da pilha ou inserir um nome personalizado para o perfil federado 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:
+ **IdentityProviderAddPrivateKey**: chave privada opcional para descriptografar asserções do SAML
+ **IdentityProviderAssertionEncryptionMode**: modo de criptografia para asserções SAML
Valores de exemplo: `Allowed`, `Required` ou deixe em branco para sem criptografia
+ **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/`
+ **RoleManagedPolicy1-5**: ARNs opcionais de até 5 políticas gerenciadas para anexar
Exemplo de RoleManagedPolicy1: `arn:aws:iam::aws:policy/ReadOnlyAccess`
Exemplo de RoleManagedPolicy2: `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á os seguintes valores, 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).
+ **IdentityProviderARN**: o ARN do IdP do SAML criado (por exemplo, `arn:aws:iam::123456789012:saml-provider/CompanyIdP`).
Você precisará desses dois ARNs ao configurar seu IdP para enviar os atributos de SAML apropriados para assumir o perfil.
## Testar a federação do SAML
Depois que o IdP do SAML e o perfil federado forem criados, você poderá 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 **Identity providers (Provedores de identidade)**.
Você deverá ver seu IdP do SAML recém-criado na lista.
1. Selecione o nome do IdP para visualizar seus detalhes.
Na página de detalhes do IdP, você pode ver o documento de metadados do SAML e outros detalhes de configuração.
1. No painel de navegação, escolha **Perfis**.
1. Encontre e selecione seu perfil federado recém-criado.
Na página de detalhes do perfil, você pode ver a política de confiança que permite que o IdP do SAML assuma esse perfil.
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`.
## 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á os seguintes recursos em sua conta:
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-samlprovider.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-samlprovider.html): um IdP do SAML que estabeleça confiança entre AWS e seu IdP externo.
+ [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): um perfil federado do IAM que pode ser assumido por usuários autenticados por meio do IdP do SAML.
### Configuração
O modelo inclui os seguintes parâmetros configuráveis:
+ **IdentityProviderName**: nome do IdP do SAML (deixe em branco para nome gerado automaticamente)
+ **IdentityProviderSAMLMetadataDocument**: Documento de metadados SAML do seu IdP (obrigatório)
+ **IdentityProviderAddPrivateKey**: chave privada opcional para descriptografar asserções do SAML
+ **IdentityProviderAssertionEncryptionMode**: modo de criptografia para asserções SAML
+ **RoleName**: nome do perfil do IAM (deixe em branco para nome gerado automaticamente)
+ **RolePath**: caminho para o perfil do IAM (padrão /)
+ **RolePermissionsBoundary**: ARN opcional da política de limite de permissões
+ **RoleSessionDuration**: duração máxima da sessão em segundos (3600-43200, padrão 7200)
+ **RoleManagedPolicy1-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-idp-and-federated-role",
"Parameters": {
"IdentityProviderName": {
"Type": "String",
"Description": "Name of the SAML Identity Provider (leave empty for auto-generated name like '{StackName}-{UniqueId}')",
"Default": "",
"AllowedPattern": "^$|^[a-zA-Z0-9._-]+$",
"ConstraintDescription": "Must be empty or contain only alphanumeric characters, periods, underscores, and hyphens"
},
"IdentityProviderSAMLMetadataDocument": {
"Type": "String",
"Description": "SAML metadata document from identity provider"
},
"IdentityProviderAddPrivateKey": {
"Type": "String",
"Description": "Optional private key for decrypting SAML assertions. The private key must be a .pem file that uses AES-GCM or AES-CBC encryption algorithm to decrypt SAML assertions.",
"Default": ""
},
"IdentityProviderAssertionEncryptionMode": {
"Type": "String",
"Description": "Optional, sets encryption mode for SAML assertions",
"Default": "",
"AllowedValues": ["", "Allowed", "Required"]
},
"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 +=,.@-"
},
"RolePath": {
"Type": "String",
"Description": "Path for the IAM Role",
"AllowedPattern": "(^\\/$)|(^\\/.*\\/$)",
"Default": "/"
},
"RolePermissionsBoundary": {
"Type": "String",
"Description": "Optional ARN of the permissions boundary policy (leave empty for none)",
"Default": ""
},
"RoleSessionDuration": {
"Description": "The maximum session duration (in seconds) that you want to set for the specified role (3600-43200)",
"Type": "Number",
"MinValue": 3600,
"MaxValue": 43200,
"Default": 7200
},
"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": {
"HasCustomProviderName": {"Fn::Not": [{"Fn::Equals": [{"Ref": "IdentityProviderName"}, ""]}]},
"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"}, ""]}]},
"HasPrivateKey": {"Fn::Not": [{"Fn::Equals": [{"Ref": "IdentityProviderAddPrivateKey"}, ""]}]},
"HasAssertionEncryptionMode": {"Fn::Not": [{"Fn::Equals": [{"Ref": "IdentityProviderAssertionEncryptionMode"}, ""]}]}
},
"Resources": {
"SAMLProvider": {
"Type": "AWS::IAM::SAMLProvider",
"Properties": {
"Name": {"Fn::If": ["HasCustomProviderName", {"Ref": "IdentityProviderName"}, {"Ref": "AWS::NoValue"}]},
"SamlMetadataDocument": {"Ref": "IdentityProviderSAMLMetadataDocument"},
"AddPrivateKey": {"Fn::If": ["HasPrivateKey", {"Ref": "IdentityProviderAddPrivateKey"}, {"Ref": "AWS::NoValue"}]},
"AssertionEncryptionMode": {"Fn::If": ["HasAssertionEncryptionMode", {"Ref": "IdentityProviderAssertionEncryptionMode"}, {"Ref": "AWS::NoValue"}]}
}
},
"SAMLFederatedRole": {
"Type": "AWS::IAM::Role",
"Properties": {
"RoleName": {"Fn::If": ["HasCustomRoleName", {"Ref": "RoleName"}, {"Ref": "AWS::NoValue"}]},
"Path": {"Ref": "RolePath"},
"Description": "SAML federated IAM role for SSO access with specified permissions",
"MaxSessionDuration": {"Ref": "RoleSessionDuration"},
"PermissionsBoundary": {"Fn::If": ["HasPermissionsBoundary", {"Ref": "RolePermissionsBoundary"}, {"Ref": "AWS::NoValue"}]},
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": {"Ref": "SAMLProvider"}
},
"Action": [
"sts:AssumeRole",
"sts:SetSourceIdentity",
"sts:TagSession"
],
"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"}
}
},
"IdentityProviderARN": {
"Description": "ARN of the created SAML Identity Provider",
"Value": {"Ref": "SAMLProvider"},
"Export": {
"Name": {"Fn::Sub": "${AWS::StackName}-IdentityProviderARN"}
}
}
}
}
```
------
#### [ YAML ]
```
AWSTemplateFormatVersion: '2010-09-09'
Description: '[AWSDocs] IAM: tutorial_saml-idp-and-federated-role'
Parameters:
IdentityProviderName:
Type: String
Description: Name of the SAML Identity Provider (leave empty for auto-generated name like '{StackName}-{UniqueId}')
Default: ""
AllowedPattern: '^$|^[a-zA-Z0-9._-]+$'
ConstraintDescription: Must be empty or contain only alphanumeric characters, periods, underscores, and hyphens
IdentityProviderSAMLMetadataDocument:
Type: String
Description: SAML metadata document from identity provider
IdentityProviderAddPrivateKey:
Type: String
Description: Optional private key for decrypting SAML assertions. The private key must be a .pem file that uses AES-GCM or AES-CBC encryption algorithm to decrypt SAML assertions.
Default: ""
IdentityProviderAssertionEncryptionMode:
Type: String
Description: Optional, sets encryption mode for SAML assertions
Default: ""
AllowedValues:
- ""
- "Allowed"
- "Required"
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 +=,.@-"
RolePath:
Type: String
Description: Path for the IAM Role
AllowedPattern: (^\/$)|(^\/.*\/$)
Default: "/"
RolePermissionsBoundary:
Type: String
Description: Optional ARN of the permissions boundary policy (leave empty for none)
Default: ""
RoleSessionDuration:
Description: The maximum session duration (in seconds) that you want to set for the specified role (3600-43200)
Type: Number
MinValue: 3600
MaxValue: 43200
Default: 7200
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:
HasCustomProviderName: !Not [!Equals [!Ref IdentityProviderName, ""]]
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, ""]]
HasPrivateKey: !Not [!Equals [!Ref IdentityProviderAddPrivateKey, ""]]
HasAssertionEncryptionMode: !Not [!Equals [!Ref IdentityProviderAssertionEncryptionMode, ""]]
Resources:
SAMLProvider:
Type: AWS::IAM::SAMLProvider
Properties:
Name: !If
- HasCustomProviderName
- !Ref IdentityProviderName
- !Ref AWS::NoValue
SamlMetadataDocument: !Ref IdentityProviderSAMLMetadataDocument
AddPrivateKey: !If
- HasPrivateKey
- !Ref IdentityProviderAddPrivateKey
- !Ref AWS::NoValue
AssertionEncryptionMode: !If
- HasAssertionEncryptionMode
- !Ref IdentityProviderAssertionEncryptionMode
- !Ref AWS::NoValue
SAMLFederatedRole:
Type: AWS::IAM::Role
Properties:
RoleName: !If
- HasCustomRoleName
- !Ref RoleName
- !Ref AWS::NoValue
Path: !Ref RolePath
Description: "SAML federated IAM role for SSO access with specified permissions"
MaxSessionDuration: !Ref RoleSessionDuration
PermissionsBoundary: !If
- HasPermissionsBoundary
- !Ref RolePermissionsBoundary
- !Ref AWS::NoValue
AssumeRolePolicyDocument:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal:
Federated: !Ref SAMLProvider
Action:
- 'sts:AssumeRole'
- 'sts:SetSourceIdentity'
- 'sts:TagSession'
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'
IdentityProviderARN:
Description: ARN of the created SAML Identity Provider
Value: !Ref SAMLProvider
Export:
Name: !Sub '${AWS::StackName}-IdentityProviderARN'
```
------