AWS

Setting up MIRACL Trust SSO as an Identity Provider within 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.

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

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

  3. Click on the Create Provider button:

  4. Choose SAML from the ‘Provider Type’ dropdown: 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: http://<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 will need to be edited to an appropriate date (it defaults to 48hrs from the current date)

  7. Click on Next Step.
    The ‘Verify Provider Information’ page is displayed.

  8. Click on Create.
    A message is displayed: “To use this provider, you must create an IAM role using this provider in the role’s trust policy. Do this now.”

  9. Click on Do this now.

  10. Click on Create New Role.

  11. Choose SAML 2.0 federation type of trusted entity. configure provider

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

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

  14. Click on Next: Permissions button.

  15. Choose an appropriate permissions policy template, i.e. ‘AmazonEC2ContainerRegistryReadOnly’.

  16. Click on Next Review.

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

Configuring your AWS Service Provider profile with MIRACL Trust SSO (IdP-initiated login)

  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
    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="2017-11-16T00: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>***</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>
          <AssertionConsumerService index="1" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://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
  1. Note that sp name is used to create your IdP-initiated login url, i.e. https://<yourssoip>/login/aws

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

Note that 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 will present a screen to choose one of your assigned roles: SAML-SSO-role-selection

  1. In the sp: aws: entry in the file, update login_url 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.

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

If you ever need to download the metadata, the downloaded metadata file must be converted to a single line with a command such as:

echo -e "\n"$(cat metadata.xml | tr -d '\n')"\n"

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

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 will then be output in the terminal in a format that can be pasted into the JSON metadata field.

  1. 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 will receive ‘unauthorized user’ messages.

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

  1. Save and close the file.

  2. 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
  1. As always after config changes, restart the server with sudo service miracl-sso restart

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

You will be 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 will be asked to register an email address so as to confirm your identity and register you as a user.