Apache Guacamole — AWS SAML Authentication and Authorisation

By the end of this article, you’ll be able to configure a custom SAML application in AWS IAM Identity Center to allow users to authenticate to Apache Guacamole using their AWS IAM identities. You’ll also be able assign permissions to groups to authorise the users to administer Guacamole, access and create connections

Create a Custom SAML 2.0 Application

Pre-requisites: You have enabled AWS Organizations for your account and have configured an Identity source

• Navigate to IAM Identity Center and under Application assignment, click on Applications
• Add a new Custom SAML 2.0 Application

• Note down the SAML metadata URL and fill out the following 3 fields and click on submit
  Application start URL — https://your-domain/guacamole
  Application ACS URL — https://your-domain/guacamole/api/ext/saml/callback
  Application SAML Audience — https://your-domain/guacamole

• Once your SAML application has been created, edit its attribute mappings

• Add the attributes and their mappings. More information at — https://docs.aws.amazon.com/singlesignon/latest/userguide/attributemappingsconcept.html. Guacamole requires the group membership information to be present under the attribute “groups”. However, this can be changed by setting the “saml-group-attribute” environment variable.

• Grant users/groups access to the application.

• The SAML application should now be visible under your organization’s SSO page. Only the users/groups granted access in the previous step would be able to see them on their SSO login page.

Guacamole Configuration

• Guacamole SAML configuration is controlled by environment variables. Detailed information at — https://guacamole.apache.org/doc/gug/saml-auth.html#configuring-guacamole-for-saml-authentication. At the minimum, you’ll need to set the following environment variables to get the SAML integration working
  1. postgresql-auto-create-accounts: true
  2. saml-idp-metadata-url — enter the metadata url you noted in the first section of this guide
  3. saml-group-attribute — this defaults to “groups”
  4. saml-callback-url —The URL that the IdP will use once authentication has succeeded to return to the Guacamole web application and provide the authentication details to the SAML extension
• Add groups in Guacamole. Currently AWS sends group GUUID instead of group names in the SAML assertions. https://repost.aws/questions/QULRCugKTtSqyi1SnZtW-pjQ/sso-passing-group-via-assertion. In the screenshots below, the group — “guac-admins” has a group id of “01132d4a-60d1–7032-befb-96e91e89c54c” which is passed to guacamole in the SAML assertions.

<saml2:Attribute Name="groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:type="xsd:string"
                          >01132d4a-60d1-7032-befb-96e91e89c54c</saml2:AttributeValue>
</saml2:Attribute>

• In order to configure permissions for all the users belonging to the “guac-admins” group, create a group in Guacamole with its GUUID as shown below