Skip to main content
Version: v4.16

AWS IAM Role based authentication

Cyral supports user authentication based on AWS IAM roles. At a high level (see below for more details), users assume an AWS IAM role (with username or email specified as the role session name) that is configured in the AWS IAM integration with Cyral, and Cyral authenticates the user by verifying the role credentials.

This document describes the process for creating an AWS IAM integration. Instructions on how to use the integration as the authentication mechanism for a repo can be found here

note

Using AWS IAM for authentication is currently enabled only for MongoDB repositories

Creating an AWS IAM integration​

Go to the Integrations tab in the left navigation bar and look for the AWS IAM tile:

From there, click on New Integration and fill the required fields:

  • Name: the name you want to give to this integration
  • IAM Role ARN(s): a list of AWS IAM role ARNs that Cyral will use for authentication. In particular, if the caller's AWS IAM role is in this list, authentication will succeed.
  • Description (optional)

Using an AWS IAM role to authenticate to Cyral​

In order to authenticate to Cyral using an IAM role, users need to assume the role. While assuming the role, the "role session name" must be of the form {USER_ID}[,USER_ACCOUNT]. The {USER_ID} is either the user's username or email address. Note that, since Cyral extracts the user identity from the role session name, care must be taken to ensure that users cannot specify arbitrary role session names while assuming this role. This can be enforced by specifying appropriate conditions in the trust policy associated with the role in AWS.

An example Condition block of a trust policy might look like this:

"Condition": {
    "StringLike": {
        "sts:RoleSessionName": [
            "${saml:sub}",
            "${saml:sub},*"
        ]
    }
}

This condition requires that the role session name must be the same as the Subject in the SAML assertion that AWS received when the user logged in to AWS. Depending on how users log in to AWS, a variation of the above policy may be required. Please refer to the AWS documentation for more information.

The optional {USER_ACCOUNT} is used to specify the user account within the Cyral repository that the user wishes to access. If only one user account can be accessed by the user (this is dictated by access rules) then this parameter can be omitted.

Here is an example AWS CLI command to assume a role:

aws sts assume-role --role-arn {ARN} --role-session-name frank.hardy@hhiu.us,engineering

Configuring an AWS IAM integration as authentication for a repository​

Configure your AWS IAM integration as the authentication mechanism for a repository. See this page for instructions.