AWS

These instructions are up-to-date at the time of writing, but you should refer back to the AWS page on SAML IdP access to check for any changes. We cannot guarantee the accuracy of our SP-specific guidance.

There are two options to integrate MIRACL Trust SSO with AWS - through IAM Single Sign-On directly or using its successor - IAM Identity Center.

# Integrate with IAM Single Sign-On

# Setting up MIRACL Trust SSO within AWS IAM Single Sign-On

AWS IAM Single Sign-On integration with external identity provider (IdP) is used to manage your user identities outside of AWS as grant the user identities permissions to use AWS resources in your AWS account. In order to integrate with MIRACL Trust SSO you need to:

  1. Log in to Amazon AWS Console. Go to Services and click on IAM under ‘Security, Identity and Compliance’.

  2. Click on Identity providers in the menu on the left.

  3. Click on the Add provider button:

    Create Provider

  4. Choose SAML as a ‘Provider Type’:

    configure provider

  5. Enter a Provider Name - e.g. ‘MyCompany’.

  6. Upload the MIRACL Trust metadata document – you should have downloaded this as an XML file (available at the following endpoint: https://<yourssoip>/metadata). Note that, for a production setup, if you manually download your IdP metadata file, the validUntil date at the top of the file needs to be edited to an appropriate date as it defaults to 48hrs from the current date.

  7. Click on Add provider. A message is displayed:

    role required

  8. You must create an IAM role using the provider in the role’s trust policy in order to use the provider. Click on Assign role button.

  9. Choose Create a new role and press Next.

  10. Choose SAML 2.0 federation type for a trusted entity.

    configure provider

  11. Ensure that the provider created in step 5 above is selected in the ‘SAML Provider’ drop-down menu.

  12. Select the Allow programmatic and AWS Management Console access radio button.

  13. Click on Next: Permissions button.

  14. On the Attach Permission Policies page, select the appropriate policies to attach to the role. These define the permissions that users granted this role have with AWS. For example, to grant your users read-only access to IAM, filter for and select the ‘IAMReadOnlyAccess’ policy. Once you are done, click Next: Tags.

  15. In the Add Tags page you can optionally enter tags (key-value pairs) to help you organize, track, or control access to the role if you consider creating a significant number of them.

  16. Click on Next: Review.

  17. Enter a Role Name - e.g. ‘SSOTest’ and a Role description and click Create role.

# Configuring Your AWS Profile (IdP-initiated Login) in the MIRACL Trust SSO

  1. Edit /etc/miracl-sso/service_providers/aws.yaml:

    profile:
  attribute:
    aws: >-
      <AttributeStatement>
        <Attribute Name="https://aws.amazon.com/SAML/Attributes/Role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
          <AttributeValue>arn:aws:iam::YOURAWSACCOUNTNUMBER:role/YOURSSOROLE,arn:aws:iam::YOURAWSACCOUNTNUMBER:saml-provider/YOURPROVIDER</AttributeValue>
        </Attribute>
        <Attribute Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
          <AttributeValue>{{.SessionUserEmail}}</AttributeValue>
        </Attribute>
      </AttributeStatement>
sp:
  aws:
    description: Amazon Web Services (AWS) Cloud Computing
    name: My AWS account
    relay_state: ""
    login_url: http://127.0.0.1:8000/login/aws
    logout_url: https://console.aws.amazon.com/iam/logout!doLogout
    metadata: >-
      <?xml version="1.0"?>
      <!-- https://signin.aws.amazon.com/static/saml-metadata.xml -->
      <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="urn:amazon:webservices" validUntil="2023-08-04T00:00:00Z">
        <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" WantAssertionsSigned="true">
            <KeyDescriptor use="signing">
                <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                    <ds:X509Data>
                        <ds:X509Certificate>MIIDbTCCAlWgAwIBAgIENK0BEjANBgkqhkiG9w0BAQsFADBnMR8wHQYDVQQDExZ1 cm46YW1hem9uOndlYnNlcnZpY2VzMSIwIAYDVQQKExlBbWF6b24gV2ViIFNlcnZp Y2VzLCBJbmMuMRMwEQYDVQQIEwpXYXNoaW5ndG9uMQswCQYDVQQGEwJVUzAeFw0y MjA4MDQwMDAwMDBaFw0yMzA4MDQwMDAwMDBaMGcxHzAdBgNVBAMTFnVybjphbWF6 b246d2Vic2VydmljZXMxIjAgBgNVBAoTGUFtYXpvbiBXZWIgU2VydmljZXMsIElu Yy4xEzARBgNVBAgTCldhc2hpbmd0b24xCzAJBgNVBAYTAlVTMIIBIjANBgkqhkiG 9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoSuM1X1R+9x5yTdQho28l3BMpF/OpM2yyJWf oDdf25RnMmrLIEFU79hfVSiYjZHG2eQ0wmF7S6cnzBR08CJrHyDgC0MmZkj3Nou/ 3BtpyldzQ4+0LWmVU/EIPyN6mu6bGIMy6Vk95hUDMgf/wIf7AyjUPSlgPQHzz3+k SAgKcAtGy5gxisGpFfi7+ZM5IPJPB5tkCRnfdSb98Q/7QE/FXxduIoTQhsLnvIOO 6x4RFZSkI4SBLDWI37G2tHiUjTsIKnKpq0taQI1CG80FdC/nSQ+Lct6HIaBlqrbM mfGbcnI4eNFiao3XYFNXt3rrYY3erX14IYBvvbmYjoidc86J5QIDAQABoyEwHzAd BgNVHQ4EFgQUDF8LkJbL5olzv8mdPhYaLf60xo0wDQYJKoZIhvcNAQELBQADggEB AA4GythTraSjwQCaUuAJ2KZ64DU8Nc+bzzOJPZe3wwi7E40QOjpUpWyxA33KX7iK ecRf0YD1d8Lo5XL2lzPC76nVQdBJ9sLQ2btaVJVFZxbtoB7XdidGQxITrR6T0LMB zNyjrn9bjeCB48sXSC49BXqf6gMX3CZkwN5OVqEELOY7sTAUjlNZgOP5r0IEjPbT ys0WbqmyRtddWBD28HwAdeSinXYeIgO0bKHs89hj4FQ7IoK33fa9nbDBBcoC0eXY RB7cDkB4pG4zzQH2U36CkB+DuWWAxIbNKgw427S1gPN13DrRsyYWamZh23Ce4i6k uTaz6YvpgOZAzoVGmZ/wT7Y=</ds:X509Certificate>
                    </ds:X509Data>
                </ds:KeyInfo>
            </KeyDescriptor>
            <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
            <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
            <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
            <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>
            <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName</NameIDFormat>
            <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName</NameIDFormat>
            <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos</NameIDFormat>
            <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:entity</NameIDFormat>
            <AssertionConsumerService index="1" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="2" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://eu-north-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="3" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://me-south-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="4" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ap-south-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="5" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://eu-west-3.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="6" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ap-southeast-3.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="7" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://us-east-2.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="8" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://af-south-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="9" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://eu-west-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="10" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://eu-central-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="11" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sa-east-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="12" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ap-east-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="13" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ap-northeast-2.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="14" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ap-northeast-3.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="15" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://eu-west-2.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="16" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://eu-south-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="17" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ap-northeast-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="18" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://us-west-2.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="19" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://us-west-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="20" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ap-southeast-1.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="21" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ap-southeast-2.signin.aws.amazon.com/saml" />
            <AssertionConsumerService index="22" isDefault="false" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://ca-central-1.signin.aws.amazon.com/saml" />
            <AttributeConsumingService index="1">
                <ServiceName xml:lang="en">AWS Management Console Single Sign-On</ServiceName>
                <RequestedAttribute isRequired="true" Name="https://aws.amazon.com/SAML/Attributes/Role" FriendlyName="RoleEntitlement" />
                <RequestedAttribute isRequired="true" Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName" FriendlyName="RoleSessionName" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" FriendlyName="eduPersonAffiliation" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.2" FriendlyName="eduPersonNickname" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.3" FriendlyName="eduPersonOrgDN" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.4" FriendlyName="eduPersonOrgUnitDN" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.5" FriendlyName="eduPersonPrimaryAffiliation" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" FriendlyName="eduPersonPrincipalName" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" FriendlyName="eduPersonEntitlement" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.8" FriendlyName="eduPersonPrimaryOrgUnitDN" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" FriendlyName="eduPersonScopedAffiliation" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" FriendlyName="eduPersonTargetedID" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.11" FriendlyName="eduPersonAssurance" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.2.1.2" FriendlyName="eduOrgHomePageURI" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.2.1.3" FriendlyName="eduOrgIdentityAuthNPolicyURI" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.2.1.4" FriendlyName="eduOrgLegalName" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.2.1.5" FriendlyName="eduOrgSuperiorURI" />
                <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.2.1.6" FriendlyName="eduOrgWhitePagesURI" />
                <RequestedAttribute isRequired="false" Name="urn:oid:2.5.4.3" FriendlyName="cn" />
            </AttributeConsumingService>
        </SPSSODescriptor>
        <Organization>
            <OrganizationName xml:lang="en">Amazon Web Services, Inc.</OrganizationName>
            <OrganizationDisplayName xml:lang="en">AWS</OrganizationDisplayName>
            <OrganizationURL xml:lang="en">https://aws.amazon.com</OrganizationURL>
        </Organization>
      </EntityDescriptor>
    sign_response: true
    sign_assertion: true
    encrypt_assertion: false
    authorize:
    - - email: ^[^@]+@example.com$
    profile:
      attribute: aws

  2. Note that the name under which the SP is registered in the sp section is used to create your IdP-initiated login url, i.e. https://<yourssoip>/login/aws.

  3. In the attribute subsection of the first profile section, replace both instances of YOURAWSACCOUNTNUMBER with your actual AWS account number, and also YOURSSOROLE and YOURPROVIDER with the values set in the AWS Console as detailed above.

    You can specify multiple roles and even accounts by just adding more values for the Role attribute like so:

    <Attribute Name="https://aws.amazon.com/SAML/Attributes/Role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<AttributeValue>arn:aws:iam::YOURAWSACCOUNTNUMBER:role/YOURSSOROLE,arn:aws:iam::YOURAWSACCOUNTNUMBER:saml-provider/YOURPROVIDER</AttributeValue>
<AttributeValue>arn:aws:iam::YOURAWSACCOUNTNUMBER:role/DIFFERENTSSOROLE,arn:aws:iam::YOURAWSACCOUNTNUMBER:saml-provider/YOURPROVIDER</AttributeValue>
<AttributeValue>arn:aws:iam::ANOTHERAWSACCOUNTNUMBER:role/ANOTHERSSOROLE,arn:aws:iam::ANOTHERAWSACCOUNTNUMBER:saml-provider/YOURPROVIDER</AttributeValue>
</Attribute>

    After authentication, AWS presents a screen to choose one of your assigned roles:

    SAML-SSO-role-selection

  4. Update the login_url value of the \sp\aws section with your SSO IP address. Note here that the AWS login URL is IdP-initiated (i.e. initiated on your IdP server as opposed to on an AWS-served URL) and, in order to work, must make use of the /login endpoint. To complete the URL the name of the service is appended to the /login endpoint. The name must match the heading of the AWS subsection in the sp config section. Looking at the config you can see that it is aws:

    aws-login-endpoint

    Note that logout_url is the standard SP logout URL which AWS makes available for SAML IdPs to use, and that the metadata is the standard SP metadata which AWS makes available for IdPs to use in order to connect with them. It has already been entered for you and can be used ‘as is’.

    The attribute value in the profile section must be set as aws, in order to invoke the correct settings made in step 2.

  5. The standard AWS metadata is entered in aws: metadata config section. It is available from https://signin.aws.amazon.com/static/saml-metadata.xml.

    If you are using JSON format for your config file, the " characters need to be escaped with \ to meet the json structure requirements. This can be achieved by running the following command on the downloaded metadata.xml file:

    echo -e "\n"$(cat metadata.xml | tr -d '\n' | sed -E 's/"/\\"/g')"\n"

    The contents are output in the terminal in a format that can be pasted into the JSON metadata field.

  6. In the authorize subsection, you can control what users are allowed to attempt login. You must use one of the following options:

    • Call up an LDAP setup from an ldap.yaml file stored in e.g /etc/miracl-sso/integrations.
    • Configure a regex list of email addresses/domains. The above config shows an example of how you would use email: ^[^@]+@example.com$ to only allow users from a certain email domain to login.

    Note that if this is not set correctly, you receives ‘unauthorized user’ messages.

    For more detailed info on using LDAP, API and/or regex to control authorized users, please see the authorization menu section.

  7. Save and close the file.

  8. In your /etc/miracl-sso/config.yaml file make sure you add aws.yaml to the list of ‘includes’:

    includes:
  - core.yaml

# service providers
  - service_providers/aws.yaml

  9. As always after config changes, restart the server.

  10. Now, you can visit https://<yourssoip>/login/aws and login.

    You are able to login using the in-browser PIN pad or with the MIRACL Trust app. When logging in to your SSO service for the first time you are asked to register an email address so as to confirm your identity and register you as a user.

# Integrate With IAM Identity Center

AWS IAM Identity Center makes it easy to centrally manage access to multiple AWS accounts and provide users with single sign-on access to all their assigned accounts from one place. You need to enabled it first as discribed here.

# Setting up MIRACL Trust SSO Within AWS IAM Identity Center

To set up an external identity provider in AWS, you need to download the MIRACL Trust SSO metadata from https://<yourssoip>/metadata and follow AWS’s Connect to your External Identity Provider guide. Note that, for a production setup, if you manually download your IdP metadata file, the validUntil date at the top of the file needs to be edited to an appropriate date as it defaults to 48hrs from the current date.

During the process you need to download the SP metadata and save AWS access portal sign-in URL for testing. It looks like:

identity-center-sp-data

# Configuring Your AWS Profile in the MIRACL Trust SSO for IAM Identity Center

  1. Edit /etc/miracl-sso/service_providers/aws_ic.yaml:

    sp:
  aws_ic:
    description: Amazon Web Services (AWS) Identity Center
    name: AWS Identity Center
    relay_state: ''
    login_url: https://<yourssoip>/login/aws_ic
    logout_url: https://<AWSIdentityStoreID>.awsapps.com/start#/signout
    metadata: >-
      <!-- insert downloaded SP metatadata here -->
    sign_response: true
    sign_assertion: true
    encrypt_assertion: false
    authorize:
      - - email: ^[^@]+@example.com$
    profile:
      nameid: email

  2. Update the login_url value of the \sp\aws_ic section with your SSO IP address. Note that this is the login URL and the name after /login should be the name of the SP section, which is aws_ic in this case.

  3. Update the logout_url with your AWS Identity store ID.

  4. Enter the downloaded metadata of the AWS Identity Center dashboard in the \sp\aws_ic\metadata config section.

  5. Note that here there is a profile setting nameid: email. It is required as AWS requires email format of the nameid to be sent.

  6. Repeat steps 6 - 10 from the AWS IAM Single Sign-on integration.

  7. You need to create desired permissions, setup users and add aws accounts for them.

Note that this integration works with both sp and idp-initiated. You could test the idp-initiated login by visit the login_url and the sp-initiated login by the AWS access portal sign-in URL from the AWS portal.