AWS IAM SAML Single Sign-On (SSO)

This topic provides instructions on how to deploy Amazon Web Services (AWS) to your users for single sign-on (SSO) via SAML from the User Portal. The CyberArk SSO integration works by enabling CyberArk-federated users to assume designated AWS roles. An AWS role is an Identity and Access Management (IAM) identity that has specific permissions and can be assumed by anyone who needs it. AWS IAM roles are not associated with specific users and do not have long-term credentials such as passwords or access keys. The intent of an AWS role is to provide temporary security credentials for the role session.

You can create an AWS IAM role for each set of permissions that you want to make available to your federated users. For example, you might have users who need access to just EC2, and other users who need access to just S3. In that case, create two separate AWS IAM roles with appropriate permissions policies attached. Next, create the Admin Portal roles with the same names as the AWS IAM roles, and populate the roles' members list with the desired federated users.

Once you have deployed the AWS application to the Admin Portal roles matching the AWS IAM roles, federated users who are members of those roles can launch the AWS console from their User Portal and will have access as defined by the permissions policy attached to the AWS IAM role.

If you have different subscriptions available in different AWS accounts, create a new AWS application in the Admin Portal for each AWS account.

Refer to Amazon's documentation for more information about AWS IAM terminology and concepts.

If you’re trying to configure the Amazon Web Services for SSO and provisioning using Amazon's proprietary authentication method, refer to Amazon Web Services (AWS) Amazon Specific Single Sign-On (SSO).

Amazon Web Services (SAML) requirements for SSO

Before you configure the Amazon Web Services (AWS) web application for SSO, you need an active Amazon Web Services account root user.

Configure Amazon Web Services (SAML) in the Admin Portal

To add and configure the Amazon Web Services (SAML + Provisioning) application in the Admin Portal

Add the Amazon Web Services (AWS) Console Web - SAML + Provisioning app to the Admin Portal.
1. In the Admin Portal, select Apps > Web Apps, then click Add Web Apps.
  
  The Add Web Apps screen appears.
2. On the Search tab, enter Amazon Web Services (AWS) Console (Type: Web - SAML + Provisioning) in the Search field and click the search icon.
3. Next to Amazon Web Services (AWS) Console (Type: Web - SAML + Provisioning), click Add.
4. In the Add Web App screen, click Yes to confirm.
5. Click Close to exit the Application Catalog.
  
  The Amazon Web Services (AWS) Console (Type: Web - SAML + Provisioning) application opens to the Settings page.
Open a new tab in your web browser, then go to the AWS Management Console and sign in with a root user:

https://console.aws.amazon.com
Enter your AWS Account ID (root account) on the Admin Portal Settings tab.

You can find your AWS Account ID by logging in to the management console with a root user, then click <Username> > My Account. The Account id is shown under Account Settings.
In the AWS management console, under Security, Identity, & Compliance, click IAM.
Click Identity providers.
Click the Create Provider button, and choose SAML as the provider type from the drop-down list.
Enter CyberArk as the Provider Name.
On the Trust page in the Admin Portal, find the Identity Provider Configuration > Metadata section and click Download Metadata File.

If you are using your own certificate, you must upload it before downloading the SAML metadata.
On the AWS management console, click Upload metadata, then click Choose File and select the XML file you just downloaded.
Click Next Step, and verify the provider information, then click Create.
Click Do this now in the information box at the top of the page to create an Identity and Access Management (IAM) role using this provider in the role’s trust policy.
Click Create Role.

Refer to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-console-saml.html for more information about using AWS roles to permit SAML 2.0 federated users access to the AWS Management Console.
Click SAML for the type of trusted entity.
Select the provider you just created from the SAML provider drop-down list.
Select Allow programmatic and AWS Management Console access.
Click Next: Permissions.
Select the check box for the policy you want to assign to this role.

You may need to use the search box to locate your policy name.

Refer to https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html for more information about AWS policies.
Click Next: Tags, then optionally enter tags (key-value pairs) to help you organize, track, or control access to the role.
Click Next: Review., then enter a Role name and optionally, a Role description..

Note the role name; you will have to create a matching role in the Admin Portal.
Click Create Role.

You can create additional roles using SAML as the trusted entity for different sets of permissions. For example, you might have users who need access to just EC2, and other users who need access to just S3. In that case, create two separate roles with appropriate permissions policies attached.
Create matching roles in the Admin Portal.

The roles in the Admin Portal must match the names of the AWS IAM roles exactly.
1. In the Admin Portal, click Core Services, then right-click Roles and select Open Link in New Tab.
2. Click Add Role.
3. Type the role name and an optional description.
  
  Remember to exactly match the role names in AWS that you want users to have access to.
4. Click Members > Add to add users to the role.
  
  Add the users that you want to have access to the matching AWS IAM role permissions. For example, if you are creating a role named AWS-EC2 to match an AWS IAM role of the same name, add the users that need access to AWS EC2.
Deploy the application by assigning it to the newly created roles.
1. Click Assigned Applications, then click Add.
2. Select the check box associated with each application you want to assign, then click Add.
3. Click Save.
Repeat the process of creating matching role names, adding members, and assigning the AWS application as needed.

This completes the required steps to deploy AWS to your users. Members of the roles created previously can log in to their User Portal and launch the AWS management console. If the users have access to multiple AWS IAM roles, they can select the role they want to use when they sign in.

Users can verify the AWS IAM role by clicking their username in the AWS management console; the drop-down menu shows:
```
Federated Login
<role>/<userEmail>
```

(Optional) On the AWS application's Account Mapping page, configure how the login information is mapped to the application’s user accounts.

Available options vary depending on your application type.

Option	Description
Directory Service Field	Use this option if the user accounts are based on user attributes. For example, specify an Active Directory field such as mail or userPrincipalName or a similar field from theCyberArk Cloud Directory. Also see Authentication security options for information on the option to use the password supplied by Active Directory users.
All users share one name	Use this option if you want to share access to an account (for example, some people share an application developer account). Check Allow users to view credentials to allow users to view User Identity (User Name and Password) information for an application in theUser Portal > Application Settings (select the gear icon in the application tile). Users must have the View permission enabled. This can be helpful to users who may need offline access to the application. The ability to view the User Identity information in the application is only applicable for application passwords stored in CyberArk Identity and does not apply to applications where the passwords are stored in the PAM - Self-Hosted Vault. If this option is not checked (default configuration), User Identity information for an application is not shared in the User Portal > Application Settings. Contact CyberArk Support to disable the Allow users to view credentials check box option.
Prompt for user name	Use this option if you want users to supply their own user name and password. This option only applies to some application types such as user password, custom NTLM, and browser extension applications. The first time that users launch the application, they enter their login credentials for that application. The CyberArk Cloud Directory stores the user name and password so that the next time the user launches the application, the CyberArk Cloud Directory logs in the user automatically.
Account Mapping Script	You can customize the user account mapping here by supplying a custom JavaScript. For example, you could use the following line as a script: `LoginUser.Username = LoginUser.Get('mail')+'.ad';` The script sets the login user name to the user’s mail attribute value in Active Directory and adds ‘.ad’ at the end. For example, if the user’s mail attribute value is Adele.Darwin@acme.com then the account mapping script sets LoginUser.Username to Adele.Darwin@acme.com.ad. For more information about writing a script to map user accounts, see the SAML application scripting. Also see Authentication security options for information on the option to use the password supplied by Active Directory users.

Option

Description

Directory Service Field

Use this option if the user accounts are based on user attributes.
For example, specify an Active Directory field such as mail or userPrincipalName or a similar field from theCyberArk Cloud Directory.

Also see Authentication security options for information on the option to use the password supplied by Active Directory users.

All users share one name

Use this option if you want to share access to an account (for example, some people share an application developer account).

Check Allow users to view credentials to allow users to view User Identity (User Name and Password) information for an application in theUser Portal > Application Settings (select the gear icon in the application tile). Users must have the View permission enabled. This can be helpful to users who may need offline access to the application.

The ability to view the User Identity information in the application is only applicable for application passwords stored in CyberArk Identity and does not apply to applications where the passwords are stored in the PAM - Self-Hosted Vault.

If this option is not checked (default configuration), User Identity information for an application is not shared in the User Portal > Application Settings.

Contact CyberArk Support to disable the Allow users to view credentials check box option.

Prompt for user name

Use this option if you want users to supply their own user name and password. This option only applies to some application types such as user password, custom NTLM, and browser extension applications. The first time that users launch the application, they enter their login credentials for that application. The CyberArk Cloud Directory stores the user name and password so that the next time the user launches the application, the CyberArk Cloud Directory logs in the user automatically.

Account Mapping Script

You can customize the user account mapping here by supplying a custom JavaScript. For example, you could use the following line as a script:

LoginUser.Username = LoginUser.Get('mail')+'.ad';

The script sets the login user name to the user’s mail attribute value in Active Directory and adds ‘.ad’ at the end. For example, if the user’s mail attribute value is Adele.Darwin@acme.com then the account mapping script sets LoginUser.Username to Adele.Darwin@acme.com.ad. For more information about writing a script to map user accounts, see the SAML application scripting.

Also see Authentication security options for information on the option to use the password supplied by Active Directory users.

(Optional) Add linked applications.

Amazon Web Services (SAML) has a number of pre-formatted linked apps that can be linked to it. Linked apps inherit permissions from the parent app by default. You can further refine permissions within the linked app. For example, you could deploy AWS to users in roles named Marketing, Sales, and ProductManagement. You can then add linked applications AWS EC2 and AWS S3 and set permissions on the linked apps so only the Marketing role gets AWS S3 while Sales and ProductManagement get AWS EC2.

See Add or delete linked applications for details.
Click Save in AWS application configuration the Admin Portal browser tab.

Amazon Web Services provisioning

Provisioning automatically adds or removes user accounts in AWS by syncing attributes from the source directory. Whenever you make changes to a mapped role or a source directory object in a mapped role (i.e., users or groups), CyberArk Identity automatically synchronizes the changes in AWS.

Provisioning is based on roles; users and groups must be members of a mapped role to have accounts provisioned in AWS. You can't provision individual users that are not members of a role.

CyberArk Identity can synchronize user accounts from Active Directory, LDAP, the CyberArk Cloud Directory, or any combination of those sources.

AWS provisioning maps CyberArk roles to AWS groups; members of the CyberArk roles have matching IAM users created or deleted in destination AWS groups. You can map CyberArk roles to an existing AWS group, or you can create a new AWS group based on either the CyberArk role name or a string that you manually enter.

Source directory users must have a valid email address for the CyberArk Identity to successfully provision them to Amazon Web Services.

Before you begin, complete the steps in Configure Amazon Web Services (SAML) in the Admin Portal

Create an Amazon Web Services IAM user with programmatic access to AWS.
You'll use this user's Access Key and Secret to authorize user provisioning from the Admin Portal. Refer to AWS documentation for more details about IAM users:
1. Log in to the AWS Management console at https://aws.amazon.com using an account that has Administrator access.
2. Click IAM.
3. Click Users.
4. Click Add User.
5. Enter one or more user names.
6. Select Programmatic Access and AWS Management Console Access.
7. Provide a password for users and require that they change it the first time they sign in by selecting Require password reset and choosing either an Autogenerated password or specifying a Custom password.
8. Click Next: Permissions.
9. Add the user(s) to an existing group, or create a new one.
  
  The group should have an attached policy with appropriate permissions.
10. Click Next: Tags and then optionally enter tags (key-value pairs) to help you organize, track, or control access for the user(s).
11. Click Next: Review and inspect the user you just created to make sure it looks right.
12. Click Create user.
13. Click Download .csv to download the Access Key ID and Secret Access Key for each user.
  
  A .csv file downloads containing the access keys for the users you created. This is the only time you can download the access keys, and you will need this file to copy the access keys into the Admin Portal soon when you configure provisioning.
14. Click Close.
  
  Amazon Web Services displays the Users page, including the user that you just created.
15. Click the name of the user you just created to open the user details page.
  
  The user inherits permissions from the group you added the user to when you created the user. If you did not add the user to a group, or the group does not have an attached policy, click Add Permissions to attach a policy now.

Enable provisioning in your Amazon Web Services (SAML) application in the Admin Portal.

Open your Amazon Web Services (SAML) application in the Admin Portal.
Click the Provisioning tab.
Select Enable provisioning for this application.

Select either Preview Mode or Live Mode.

Option	Description
Preview Mode	Use Preview Mode when you’re initially testing the application provisioning or making configuration changes. The identity platform does a test run to show you what changes it would make but the changes aren’t saved.
Live Mode	Use Live mode when you want to use application provisioning in your production system. The identity platform does the provisioning run and saves the changes to both the identity platform and the application’s account information.

Enter the following information for the provisioning details:

Field	Description
Access Key	Paste in the Access Key from the IAM user that you created in Amazon Web Services.
Secret Key	Paste in the Secret Key from the IAM user that you created in Amazon Web Services.

Click Verify to have the CyberArk Identity verify the connection and save the provisioning details.

Under Sync Options, specify how the CyberArk Identity handles situations when it determines that the user already has an account in the target application.

How the CyberArk Identity determines duplicate user accounts:

If the user accounts in the CyberArk Identity and the target application match for the fields that make an Amazon Web Services user unique, then the CyberArk Identity handles the user account updates according to your instructions. In many applications, the user’s email address or Active Directory userPrincipalName is the primary field used to identify a user—and in many cases, the userPrincipalName is the email address. You can look at the application’s provisioning script to see the fields that CyberArk Identity uses to match user accounts.
- Sync (overwrite): Updates account information in the target application (this includes removing data if the target account has a value for a user attribute that is not available from the CyberArk Identity).
- Do not sync (no overwrite): Keeps the target user account as it is; CyberArk Identity skips and does not update duplicate user accounts in the target application.
- Do not de-provision (deactivate or delete): The user's account in the target application is not de-provisioned when a role membership change that would trigger a de-provisioning event occurs.
- Select Deprovision users in this application when they are disabled in source directory to enable the feature.
  If checked, a user will be deprovisioned when they are marked as disabled in the source directory. Deprovisioning behavior and available deprovisioning options depend on what the target application supports.
Map the Admin Portal roles to AWS groups.
1. Scroll to the Role Mappings section.
2. Click Add to add role mappings and specify which users get provisioned to this application.
  
  The Role Mapping dialog box opens.
3. Select an the Admin PortalRole and an AWS Destination Group to map user accounts in the Admin Portal to Amazon Web Services user accounts.
  
  For best results, assign roles where users are only in one role.
  
  A Destination Group named for the selected CyberArk role automatically populates in the list of groups available from the drop-down list. If that Destination Group is selected, a group with that name is created in the target application. If you select a Destination Group that already exists in the application, provisioned users that are members of the selected role are added as members of the existing Destination Group.
  
  Alternatively, you can type in a new group name to map to the selected role; the newly created Destination Group is also created in the application.
  
  If the role is removed from the role mapping after a provisioning job runs, the Destination Group remains in the target application without any membership changes. Changing the role or role name does not affect Destination Group creation or membership, unless the Destination Group name in the role mapping is also changed.
  
  For AWS, when you delete a role from Role Mapping, the Destination Group is also removed from the target application. The role in the target application is deleted automatically if the Delete roles in this application when mapped roles are deleted in source directory check box is selected. When you modify the name of the Destination Group in Role Mapping, the Destination Group name is updated in the target application.
  
  If you create a new AWS group using provisioning, you will have to use the AWS management console to assign permissions to the group by attaching a policy.
4. Click Done to save the role mapping and return to the Provisioning tab.
5. Continue adding role mappings, as desired.
6. - To change a mapping, select the role mapping and click Modify.
  - To remove a mapping, select the role mapping and click Delete.
  - To change the order of the role mappings, select the role mapping that you want to move higher in the list and click Move Up.
7. Provisioning assigns users access and assignments based on the top-most role mapping. The order in which the roles display in the Role Mappings section matters. The role at the top of the list has priority when provisioning users. For instance, if a user is in multiple roles that you’ve mapped for provisioning, the CyberArk Identity provisions the user based on the role nearer the top of the list.
  For best results, assign roles where users are only in one role. If users are in multiple roles, rearrange the order of role mappings as desired.
8. When you’ve finished making changes, click Save to save the provisioning details.
  
  Any time that you make changes to the provisioning role mapping, the CyberArk Identity runs a synchronization automatically. You can also run a preview synchronization or a real synchronization, if desired.

CyberArk Amazon Web Services CLI utilities

CyberArk offers Python and PowerShell CLI utilities to access Amazon Web Services by leveraging CyberArk Identity. The AWS CLI utilities are available from the Downloads area of the Admin Portal.

Refer to The CyberArk Developer Program for more information about how to install and use the AWS CLI utilities.

AWS (SAML) Specifications

Each SAML application is different. The following table lists features and functionality specific to Amazon Web Services.

Capability	Supported?	Support details
Web browser client	Yes
Mobile client	Yes	iOS and Android
SAML 2.0	Yes
SP-initiated SSO	No
IdP-initiated SSO	Yes
Force user login via SSO only	No	After SSO is enabled, users can continue to log in to Amazon Web Services with their local user name and password.
Separate administrator login after SSO is enabled	Yes	After SSO is enabled, administrators can continue to log in to Amazon Web Services with their local user name and password.
User lockout	No
Administrator lockout	No
User provisioning through SAML	Yes
Multiple User Types	Yes	Refer to Amazon Web Services documentation for details.
Self-service password	Yes	Users can reset their own passwords. Note that administrators cannot reset a user’s password.
Access restriction using a corporate IP range	Yes	You can specify an IP Range in the Admin Portal Policy page to restrict access to the application.