Deployment Task

Once you've successfully integrated Aqua with your Okta identity provider, you may want to begin provisioning user access control to the Aqua console based on existing groups within Okta.  Follow the procedure below to achieve this.  This document assumes that you have already configured Aqua to integrate with Okta.  If you haven't performed this step yet, please visit this documentation

Deployment Steps

  1. Find your Aqua application under Applications on the Okta administration interface. 
  2. Click the General tab, and then click the Edit button next to SAML Settings. 
  3. On the General Settings screen, click next and the Edit SAML Integration screen appears.
  4. There are two ways to add an attribute to the SAML response which will map to an Aqua role. 
    1. Using the Group Attribute Statements field.  This field allows you to define a new attribute in the SAML response, which will return one or more group names that match the criteria that you provide.  If you choose this option, this means that the role in the SAML response will be mapped to the exact name of the group on the Okta side if it matches your regular expression or criteria.  This also means that the exact name of the group on the Okta side would have to match the name of the group on the Aqua side.You will want the regular expression to allow for multiple roles, assuming you'll have multiple Okta groups that you would like to map to multiple Aqua roles.  The example, in the screen shot above, there is a simple regex matching the Okta group name exactly (case-sensitive).  



    2. If you’d rather not synchronize the name of the group on the Okta side to the name of the group on the Aqua side, then we recommend using the Okta Expression Language, and construct an expression for a new attribute instead of using the "Group Attribute Statement" field.  According the Okta Expression Language documentation, we can use the following format:
      [Condition] ? [Value if TRUE] : [Value if FALSE]

      We can use the “isMemberofGroupName()” built-in function to match the user’s group to a target string.   You can also use any of the Boolean functions documented here



      isMemberOfGroupName("Engineering-Team") ? "Engineeering" : null

      This will return the value Engineering in the SAML Response to Aqua, if the logged in user is a member of the Okta group Engineering-Team.


      Mapping roles for multiple groups

      isMemberOfGroupName("Engineering-Team") ? "Engineeering": isMemberOfGroupName("Security-Auditors") ? "auditor" : null

      This is a nested conditional statement, where we first check to see if the user is a member of Engineering-Team  (return “Engineering”). We then check to see if the user is a member of Security-Auditors (return “auditor”), else return null.  ("Engineering" and "auditor" would be the names of pre-defined roles available on the Aqua side.


      Okta Configuration

Edit the Aqua SAML Integration

  1. In the Aqua UI, navigate to System → Integration → SAML Authentication
  2. Scroll down to the buttons under "Authorize using:".  Click the "Aqua role" button.
  3. Input the name of the attribute you created in the section above. 
  4. Ensure that you have also mapped a username attribute.


Make sure that you have created a custom Aqua role under System → Users and Roles or that you are sending a role name from Okta that matches one of the built-in Aqua roles.  

If you find that things are not working, follow this SAML tracing article to get a look at the SAML response.  Check to see that Okta is sending a group role, and if it is, make sure that it matches the name of an existing role within Aqua. 

Related information