This document outlines how to manually configure an AWS account to authenticate with Columbia University's existing authentication infrastructure.

"UNI" authentication, known as Federated authentication within Amazon Web Services, can be configured for any AWS account affiliated with the University for business purposes. Accounts provisioned by CUIT via a request made from the Service Desk are automatically configured with such authentication enabled by default. "Linked" accounts, those not created by CUIT, can be manually configured by the account owner or administrator to also make use of UNI authentication.

Federated logins make use of SAML authentication via CUIT's Shibboleth identity provider, with access controlled via CUIT's Grouper service. Grouper manages LDAP affiliations assigned to members of a specific grouper group. Those affiliations are passed to Amazon during logon, and users are given a role selection interface to choose which AWS account and IAM role they would like to access. IAM role names configured to use UNI authentication must not exceed 15 characters in length (see: Federated AWS account access with Grouper#Appendix).

For each AWS account configured with UNI access, there must be a corresponding Grouper folder. The folder name matches the 12-digit AWS Account Id. Groups within the folder must match the IAM role names configured within the account.

Steps to enable UNI authentication

The high-level steps to enable UNI authentication are:

Create SAML Identity Provider
Create or edit IAM roles
Create & populate Grouper groups

Create SAML Identity Provider

If the SAML provider does not already exist in the account, it will need to be created. This step is required only once per account, not per-role.
Download & save the CUIT SAML Metadata Document to a local file
Login to your AWS Account console as a user with full IAM Administrator privileges
Open the IAM console
In the pane on the left, click Identity Providers
Click Create
On the Configure Provider page, choose provider type SAML
Set the Provider Name to “ColumbiaProdShibboleth”
Click Choose File next to the Metadata Document field
Select the you downloaded, and click Next Step
On the Verify Provider Information page, click Create

Create or edit IAM roles

Create roles

If the desired access role does not already exist, it must be created.

Open the IAM console
In the left pane, click Roles
In the right pane, click Create.
Select SAML 2.0 federation as the trusted entity type
Select the ColumbiaProdShibboleth provider from the provider drop-down
Select Allow programmatic and AWS Management Console access
Click Next: Permissions
Select an existing policy or create an inline policy for the role
Click Next: Tags
Add tags if desired, click Next: Review
Enter a role name with a maximum of 15 characters
Click Create role

Apply Trust Policy to existing role(s):

If you have just created a role, or a role already exists but is not SAML enabled, the SAML provider trust policy must be assigned to the role.

Open the IAM console
In the left pane, click Roles
Click on a role name
Click the Trust Relationships tab
Click Edit trust relationship
If the role has no existing trust relationship, paste the following policy, replacing "<12-digitAccountId>" with your own AWS Account ID:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
	  "Principal": {
	  "Federated": "arn:aws:iam::<12-digitAccountId>:saml-provider/ColumbiaProdShibboleth"
	  },
	  "Action": "sts:AssumeRoleWithSAML",
	  "Condition": {
	    "StringEquals": {
	      "SAML:aud": "https://signin.aws.amazon.com/saml"
		}
	  }
	}
  }
}

If the role has an existing trust relationship, you must append the Statement portion below to the Statement list of the existing policy (separate list items with a comma), replacing "<12-digitAccountId>" with your own AWS Account ID:

{
  "Effect": "Allow",
  "Principal": {
    "Federated": "arn:aws:iam::<12-digitAccountId>:saml-provider/ColumbiaProdShibboleth"
  },
  "Action": "sts:AssumeRoleWithSAML",
  "Condition": {
    "StringEquals": {
      "SAML:aud": "https://signin.aws.amazon.com/saml"
    }
  }
}

Create & populate Grouper groups

Note: before Grouper groups can be created, CUIT will need to create a default folder for the account and apply permissions to permit the account owner or administrator to create and edit groups.

Once someone from CUIT has confirmed that a Grouper folder has been created for your account, you will have the ability to create and edit groups that match the IAM roles configured for federated access. To create and populate a group:

Open grouper by visiting https://grouper.cc.columbia.edu/
Browse to your account folder by searching for your 12-digit Account Id in the search box (you can also add the folder as a favorite)
Once at the folder, in the upper right, click More actions then Create new group
In the Group Name field, enter the name of your IAM role, enter a description if desired, then click Save
On the resulting group properties page, click Add members in the upper right
In the Member name or ID field, enter the UNI or full name of the person to add, wait for the username field to populate, then select the user ID. The format should resemble "idm - <uni> - LastName, FirstName (<uni>)".
Click Add

Members can also be imported as a comma separated list of UNIs.

More information on use of Grouper can be found here: https://cuit.columbia.edu/grouper

Appendix:

Note on Grouper Group Name Limitations

Grouper manages LDAP affiliations which are mapped to match AWS account and role combinations upon logging in. Format for the account and role are <12-digit Account IdFolder>:<RoleName>, e.g. cu:app:access:aws:012345678901:Admin or cu:app:access:aws:012345678901:SecAudit.

Affiliations are limited in length to 32 characters. Any portion of the Grouper ID (note “ID” and not “Name”) for a group is included in the affiliation. The default affiliation length is 32-('AWS_')-(12 digit account ID)-('-' separator) = 15, leaving 15 characters for use as the <RoleName> portion.

Creation of owners Grouper groups

A script for CUIT staff to create the default grouper owners/administrators groups exists in the cu-aws Gitlab repository under the "automation" directory:

create_owner_group_and_privs.py.

The script requires a valid configuration file for using the aws_operations.py module, a valid configuration file for the mGrouper.py module, and valid Grouper service account credentials. The script reads & writes to/from our aws_requests.json file, creates a default account folder/stem if one does not exist, creates an "owners group" with the owners specified in the request data of from command line options, and assigns the create & update privileges to the account folder and any existing groups within it.

More information

Shibboleth/SAML Integration at CUIT

Web Authentication and Federation at CUIT

AWS & SAML 2.0-based federation

Zuckerman Institute

Federated AWS account access with Grouper

Analytics