# Tutorial do IAM: use um modelo do CloudFormation para criar um provedor de identidades (IdP) do SAML
<a name="tutorial_saml-idp"></a>

Para configurar a federação SAML para sua conta da AWS, você precisa criar um provedor de identidades (IdP) SAML. Este tutorial mostra como usar um modelo do CloudFormation para criar um IdP do SAML que estabeleça confiança entre a AWS e seu IdP externo.

O modelo cria um IdP do SAML configurado com o documento de metadados do seu IdP. Os perfis federados do IAM podem então fazer referência a esse IdP para permitir que usuários autenticados do seu IdP externo acessem os recursos da AWS.

O recurso implantado consiste em um IdP do SAML configurado com o documento de metadados do seu IdP e configurações de criptografia opcionais.

## Pré-requisitos
<a name="tutorial_saml-idp-prereqs"></a>

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 do SAML usando o CloudFormation
<a name="tutorial_saml-idp-create"></a>

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
<a name="tutorial_saml-idp-file"></a>

Primeiro, crie o modelo do CloudFormation.

1. Na seção [Modelo](#tutorial_saml-idp-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.
<a name="tutorial_saml-idp-stack"></a>

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. Nomes personalizados devem conter apenas caracteres alfanuméricos, pontos, sublinhados e hifens.

   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):

      ```
      <?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://portal.sso.example.com/saml/assertion/CompanyIdP"><md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiIMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV...</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://portal.sso.example.com/saml/logout/CompanyIdP"/><md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat><md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://portal.sso.example.com/saml/assertion/CompanyIdP"/></md:IDPSSODescriptor></md:EntityDescriptor>
      ```

   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**: opcional, define o modo de criptografia para asserções SAML (permitido, obrigatório ou vazio)

   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**:
+ **ProviderARN**: o ARN do IdP do SAML criado (por exemplo `arn:aws:iam::123456789012:saml-provider/CompanyIdP`). Você precisará desse ARN ao criar perfis que confiem nesse provedor.
+ **ProviderName**: o nome do IdP do SAML criado (por exemplo `CompanyIdP`, se você especificou um nome personalizado ou `my-saml-stack-saml-provider` se usou a nomenclatura padrão).

Essas saídas também são exportadas, permitindo que sejam importadas por outras pilhas do CloudFormation usando o função `Fn::ImportValue`.

## Verificar o IdP do SAML
<a name="tutorial_saml-idp-using"></a>

Depois que o IdP do SAML for criado, você poderá verificar sua configuração e anotar seu ARN para uso com perfis federados.

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. Observe o **ARN do provedor** exibido na página de detalhes.

   Você precisará desse ARN ao criar perfis federados do IAM que confiam nesse IdP.

1. Revise o documento de metadados para garantir que corresponda ao que você forneceu do IdP externo.

Seu IdP do SAML agora está pronto para ser usado por perfis federadas do IAM. Você pode criar perfis que confiem nesse IdP para permitir que usuários autenticados do seu IdP externo assumam esses perfis e acessem os recursos da AWS.

## Limpeza: excluir recursos
<a name="tutorial_saml-idp-delete"></a>

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
<a name="tutorial_saml-idp-template-details"></a>

### Recursos
<a name="tutorial_saml-idp-template-resources"></a>

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-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.

### Configuração
<a name="tutorial_saml-idp-template-config"></a>

O modelo inclui os seguintes parâmetros configuráveis:
+ **IdentityProviderName**: o nome do seu IdP do SAML (deixe em branco para nome gerado automaticamente)

  Exemplo: `CompanyIdP` ou `EnterpriseSSO`
+ **IdentityProviderSAMLMetadataDocument**: o documento de metadados SAML do seu IdP externo (formatado como uma única linha)
+ **IdentityProviderAddPrivateKey**: chave privada opcional para descriptografar asserções do SAML
+ **IdentityProviderAssertionEncryptionMode**: opcional, define o modo de criptografia para asserções SAML

## Modelo do CloudFormation
<a name="tutorial_saml-idp-template"></a>

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",
  "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"]
    }
  },
  "Conditions": {
    "HasPrivateKey": {"Fn::Not": [{"Fn::Equals": [{"Ref": "IdentityProviderAddPrivateKey"}, ""]}]},
    "HasEncryptionMode": {"Fn::Not": [{"Fn::Equals": [{"Ref": "IdentityProviderAssertionEncryptionMode"}, ""]}]},
    "HasCustomName": {"Fn::Not": [{"Fn::Equals": [{"Ref": "IdentityProviderName"}, ""]}]}
  },
  "Resources": {
    "SAMLProvider": {
      "Type": "AWS::IAM::SAMLProvider",
      "Properties": {
        "Name": {"Fn::If": ["HasCustomName", {"Ref": "IdentityProviderName"}, {"Ref": "AWS::NoValue"}]},
        "SamlMetadataDocument": {"Ref": "IdentityProviderSAMLMetadataDocument"},
        "Tags": [
          {
            "Key": "Name",
            "Value": {"Fn::If": ["HasCustomName", {"Ref": "IdentityProviderName"}, {"Fn::Sub": "${AWS::StackName}-saml-provider"}]}
          }
        ],
        "AddPrivateKey": {"Fn::If": ["HasPrivateKey", {"Ref": "IdentityProviderAddPrivateKey"}, {"Ref": "AWS::NoValue"}]},
        "AssertionEncryptionMode": {"Fn::If": ["HasEncryptionMode", {"Ref": "IdentityProviderAssertionEncryptionMode"}, {"Ref": "AWS::NoValue"}]}
      }
    }
  },
  "Outputs": {
    "ProviderARN": {
      "Description": "ARN of the created SAML Identity Provider",
      "Value": {"Ref": "SAMLProvider"},
      "Export": {
        "Name": {"Fn::Sub": "${AWS::StackName}-ProviderARN"}
      }
    },
    "ProviderName": {
      "Description": "Name of the SAML Identity Provider",
      "Value": {"Fn::If": ["HasCustomName", {"Ref": "IdentityProviderName"}, {"Fn::Sub": "${AWS::StackName}-saml-provider"}]},
      "Export": {
        "Name": {"Fn::Sub": "${AWS::StackName}-ProviderName"}
      }
    }
  }
}
```

------
#### [ YAML ]

```
AWSTemplateFormatVersion: '2010-09-09'
Description: '[AWSDocs] IAM: tutorial_saml-idp'

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"

Conditions:
  HasPrivateKey: !Not [!Equals [!Ref IdentityProviderAddPrivateKey, ""]]
  HasEncryptionMode: !Not [!Equals [!Ref IdentityProviderAssertionEncryptionMode, ""]]
  HasCustomName: !Not [!Equals [!Ref IdentityProviderName, ""]]

Resources:
  SAMLProvider:
    Type: 'AWS::IAM::SAMLProvider'
    Properties:
      Name: !If
        - HasCustomName
        - !Ref IdentityProviderName
        - !Ref AWS::NoValue
      SamlMetadataDocument: !Ref IdentityProviderSAMLMetadataDocument
      Tags:
        - Key: Name
          Value: !If
            - HasCustomName
            - !Ref IdentityProviderName
            - !Sub '${AWS::StackName}-saml-provider'
      AddPrivateKey: !If
        - HasPrivateKey
        - !Ref IdentityProviderAddPrivateKey
        - !Ref AWS::NoValue
      AssertionEncryptionMode: !If
        - HasEncryptionMode
        - !Ref IdentityProviderAssertionEncryptionMode
        - !Ref AWS::NoValue

Outputs:
  ProviderARN:
    Description: 'ARN of the created SAML Identity Provider'
    Value: !Ref SAMLProvider
    Export:
      Name: !Sub '${AWS::StackName}-ProviderARN'
  
  ProviderName:
    Description: 'Name of the SAML Identity Provider'
    Value: !If
      - HasCustomName
      - !Ref IdentityProviderName
      - !Sub '${AWS::StackName}-saml-provider'
    Export:
      Name: !Sub '${AWS::StackName}-ProviderName'
```

------