This document shows an example of how to set up SSO for AWS console access with an IAM role, using Stanford production IdP service as identity provider.

By using AWS SAML integration, you don't need to create AWS accounts for users who need to access AWS console. Instead, You create a new or use an existing Stanford workgroup that contains users who will use the SSO to gain access to your account's AWS console.

Using stanford-sso.sh command line tool

The following instructions apply to MacOS. For other platforms, follow the tool links and instructions on tool sites.

• Install Jq

  $ brew install jq awscli
  

• Install and configure AWS CLI

  If you have AWSCLI installed and configured, you can skip this step.

  $ brew install awscli
  

  $ aws configure --profile <aws user>
  

You will be prompted for AWS KEY and AWS SECRET for the aws user. The profile name will be used for AWS authentication/authorizatio to make AWS CLI calls.

• Clone the repo

  $ git clone https://github.com/Stanford/AWS-SSO.git
  $ cd AWS-SSO
  

• Run help

    $ ./stanford-sso.sh -h
stanford-sso -a <action> -c <config> -n <provider name> -p <permission> -w <workgroupname> [-u <metadata url>] [-d] [-h] [-l <account-label>] [-r <role-name>]

 -a <create|show|delete>: action. create, show or delete SSO setup by this tool.
 -c <aws config>: authenticate using profile defined by configuration.
 -n <provider-name>: the name of the idp provider, for example 'stanford-idp'.
 -p <ReadOnlyAccess|AdministratorAccess|list-policies>: ReadOnlyAccess, AdministratorAccess, or list other valid AWS managed polices.
 -u <url-for-metadata>: optional. metadata url for the idp provider. Default 'https://login.stanford.edu/metadata.xml'.
 -w <workgroupname>: Stanford workgroup name to link into this saml provider setup. e.g. itlab:anchorage-admin
 -l <account-label>: Account label (alias) This will be the name displayed to users when logging in e.g. its-main-account
 -r <role-name>: This defines the name of the role that will be created e.g. ops-readonly
 -a <create|show|delete>: action. create, show or delete SSO setup by this tool.
 -d     : dryrun. print out the commands
 -h     : Help

• Create SAML provider

Dry-run:

   $ ./stanford-sso.sh -d -a create -c idg-dev -u https://login-uat.stanford.edu/metadata.xml -l aws-idg-dev -n stanford-idp-uat -p AdministratorAccess -w itservices:idg-aws -r stanford-idp-uat
Getting AWS account number ...
create stanford-idp-uat
Creating saml provider stanford-idp-uat.
aws --profile idg-dev iam create-saml-provider --name=stanford-idp-uat --output=text --saml-metadata-document file:///tmp/samlMetadata.xml
Creating account alias aws-idg-dev
aws --profile idg-dev iam create-account-alias --account-alias aws-idg-dev
Creating role stanford-idp-uat
aws --profile idg-dev iam create-role --role-name stanford-idp-uat --assume-role-policy-document file:///tmp/trust-policy.json
aws --profile idg-dev iam attach-role-policy --role-name stanford-idp-uat --policy-arn arn:aws:iam::aws:policy/AdministratorAccess
Dryrun mode. Nothing is changed.

The above command will do a dry-run to show what will be created. stanford-idp-uat is a descriptive name to identify the idp provider you use. You can pass in the medtadata url for the idp provider on the command line (see help). The default metadata is 'https://login.stanford.edu/metadata.xml'

Real run:

    $ ./stanford-sso.sh  -a create -c idg-dev -u https://login-uat.stanford.edu/metadata.xml -l aws-idg-dev -n stanford-idp-uat -p AdministratorAccess -w itservices:idg-aws -r stanford-idp-uat
Getting AWS account number ...
create stanford-idp-uat
Creating saml provider stanford-idp-uat.
arn:aws:iam::123456789012:saml-provider/stanford-idp-uat
Creating account alias aws-idg-dev
Creating role stanford-idp-uat
{
   "Role": {
       "AssumeRolePolicyDocument": {
           "Version": "2012-10-17",
           "Statement": [
               {
                   "Action": "sts:AssumeRoleWithSAML",
                   "Principal": {
                       "Federated": "arn:aws:iam::123456789012:saml-provider/stanford-idp-uat"
                   },
                   "Effect": "Allow",
                   "Condition": {
                       "StringEquals": {
                           "SAML:aud": "https://signin.aws.amazon.com/saml"
                       }
                   },
                   "Sid": ""
               }
           ]
       },
       "RoleId": "*********************",
       "CreateDate": "2016-09-13T17:24:23.675Z",
       "RoleName": "stanford-idp-uat",
       "Path": "/",
       "Arn": "arn:aws:iam::123456789012:role/stanford-idp-uat"
   }
}
aws --profile idg-dev iam attach-role-policy --role-name stanford-idp-uat --policy-arn arn:aws:iam::aws:policy/AdministratorAccess

All done! Next step. Submit the following request to https://helpsu.stanford.edu/helpsu/3.0/auth/helpsu-form?pcat=shibboleth to create idp server setup.

When idp server setup is complete, you can login to AWS console SSO through this url:
https://idp.stanford.edu/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices

• Delete SAML provider

$ ./stanford-sso.sh -a delete -c <aws profile> -n stanford-idp -p AdministratorAccess -w myworkgroup 

Manual steps

identity provider setup

Login to your AWS console.

1. Select IAM service

2. Click 'Identity Providers'

3. Click 'Create SAML Provider' Choose a name that is easy to identify which provider provides SSO, e.g. stanford-idp.

4. Upload idP-only SAML metadata document from:

   [idp-only metadata](https://login.stanford.edu/metadata.xml)
   

   Click "Create" button to finish the provider setup.

Create IAM role using this provider in the trust policy

When you finish identy provider creation, there is a link to take you to create an IAM role, or you you can go back to IAM service, select "Roles->Create New Role".

1. Create role name: e.g. admin-sso
2. Select Role for Identity Provider Access in the role type selection screen near the bottom.
3. Select Grant Web Single Sign-On (WebSSO) access to SAML providers
4. Accept the default "Verify Role Trust" policy.
5. Set permissions: assign the role a permission, e.g. Administrator, Power admin user, etc. It depends on your use case.
6. Click "Create Role" to finish

Configure relying party trust between IdP and AWS

Amazon currently only works with IdP-initiated SSO - our Unsolicited SSO Endpoints are not listed in our IdP metadata, but the handlers and decoders appear to be enabled. AWS only uses the metadata for the certificate / entity ID.

You need to submit the request to HelpSU to complete the setup with the following information.

• Attribute Resolver Settings

  Replace the account number, role-name, and workgroup with the values you created in the SSO setup steps. You can find the information from AWS console under IAM->Roles, IAM->Identity Provider sections.

    Account number: 123456789012
    Provider name (ARN): arn:aws:iam::123456789012:saml-provider/stanford-idp
    Role-name (ARN): arn:aws:iam::728004059242:role/admin-sso
    Workgroup: x-stem:y-group
  

Create a virtual host to access the your accoount's AWS console

After idp service is updated with your AWS SSO data, you can access AWS console by going to:

    https://idp.stanford.edu/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices

Note that if you have multiple accounts with the same idp provider, you will see the list of SSO accounts on AWS console. Pick the account number for which you want to login.

You can also create a virtual hostname, e.g. "my-account-aws-console.stanford.edu" and redirect it to:

    https://idp.stanford.edu/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices