Tutorial do IAM: use um modelo do AWS CloudFormation para criar um provedor de identidades (IdP) do SAML - AWS Identity and Access Management
Pré-requisitosCriar o IdPVerificar o IdPExcluir recursosDetalhes do modeloModelo

Tutorial do IAM: use um modelo do AWS CloudFormation para criar um provedor de identidades (IdP) do SAML

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

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 AWS 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, clique no ícone de cópia na guia JSON ou YAML para copiar o conteúdo do modelo.

  2. Copie o conteúdo do modelo em um novo arquivo.

  3. Salve o arquivo localmente.

Crir a pilha

Em seguida, use o arquivo de modelo que você salvou para provisionar uma pilha do CloudFormation.

  1. Abra o console do AWS CloudFormation em https://console.aws.amazon.com/cloudformation.

  2. Na página Pilhas, no menu Criar pilha, escolha com novos recursos (padrão).

  3. Especifique o modelo:

    1. Em Pré-requisito, escolha Escolher um modelo existente.

    2. Em Especificar modelo, escolha Fazer upload de um arquivo de modelo.

    3. Selecione Escolher arquivo, navegue até o arquivo de modelo e selecione-o.

    4. Escolha Próximo.

  4. Especifique os seguintes detalhes da pilha:

    1. Digite um nome de pilha.

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

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

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

    5. Escolha Próximo.

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

    2. Aceite todos os outros valores padrão.

    3. Em Capacidades, marque a caixa para confirmar que o CloudFormation pode criar recursos do IAM em sua conta.

    4. Escolha Próximo.

  6. Revise os detalhes a pilha e selecione Enviar.

O AWS CloudFormation 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 AWS CloudFormation usando o função Fn::ImportValue.

Verificar o IdP do SAML

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

  2. No painel de navegação, escolha Identity providers (Provedores de identidade).

    Você deverá ver seu IdP do SAML recém-criado na lista.

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

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

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

Como etapa final, você excluirá a pilha e os recursos que ela contém.

  1. Abra o console do AWS CloudFormation.

  2. 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 AWS CloudFormation para este tutorial criará o seguinte recurso em sua conta:

AWS::IAM::SAMLProvider: um IdP do SAML que estabeleça confiança entre AWS e seu IdP externo.

Configuração

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

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'