Skip to main content

Configuring Amazon Cognito on the Guacamole Bastion Host

This document describes how to enable single sign-on with Amazon Cognito. With Amazon Cognito, your users can sign in through self-registration, social identity providers such as Apple, Google and Facebook or through enterprise identity providers such as Microsoft Active Directory via SAML or OpenID.

Access to Guacamole can further be restricted to only allow Cognito users that are members of a certain group. Additionally, Cognito provides Multi-Factor Authentication (MFA) via SMS text messages or time-based one-time passwords (TOTP).

Step by Step Instructions​

  1. Before you start with the integration, make sure that users in Cognito and Guacamole share the same username and your user has administrative permission. By default, Guacamole will use the email attribute of the Cognito user to identify the local user. The users in Guacamole have be be named accordingly (i.e. same email address).
    • Log into Guacamole as administrator, by default that's the guacadmin user and the instance ID as password.
    • Create a new user, as username use the email address of your user in Cognito. Leave the password field empty. Grant Administer system permissions and click Save.
  2. In the Cognito User Pool console (https://console.aws.amazon.com/cognito/users/ ), open your user pool and select Domain name from the left menu. Make sure a Domain prefix or a custom domain has been configured and remember it for later (e.g. my-company.auth.us-east-1.amazoncognito.com).
  3. Click on App Clients in the left menu. Create a new Cognito client (Create another app client at the bottom of the page).
    • Provide a name for the client (such as guacamole) and remove all checkboxes except the last from the Auth Flows Configuration section.
    • Click Create app client and make a note of the App client id. Cognito App Client
  4. Click on the App client settings menu item in the left menu bar and find the app client you just created.
    • Select the Identity Providers you want to enable for this app.
    • Add the public hostname of the Guacamole EC2 instance to the Callback URL(s) (e.g. https://ec2-00-00-00-00.compute-1.amazonaws.com/).
    • Under Allowed OAuth Flows enable implicit grant and select openid from the Allowed OAuth scopes.
    • Click Save changes and we are done with the configuration of Cognito. Cognito App Client
  5. Connect to the EC2 instance running Guacamole via SSH (user is ec2-user).
    • Enable the Cognito extension by linking the extension into the extensions folder. The destination file name (guacamole-auth-0-cognito-1.2.0.jar) is important because Guacamole processes the authentication extensions in alphabetical order. 
      sudo ln -s ../available-extensions/guacamole-auth-cognito-1.2.0/guacamole-auth-cognito-1.2.0.jar \
        /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-cognito-1.2.0.jar
    • Open /home/ec2-user/guaws/guacamole/etc/guacamole.properties and add these properties 
      # Domain name of the user pool from step 2, do not include the https:// prefix
      cognito-domain=my-company.auth.us-east-1.amazoncognito.com

      # User Pool ID
      cognito-user-pool-id=us-east-1_123abc987

      # Client ID from step 3
      cognito-client-id=1vkit2iqem9dmEXAMPLE

      # Redirect URI used in step 4
      cognito-redirect-uri=https://ec2-00-00-00-00.compute-1.amazonaws.com/

      # Optional: If you wish to restrict access to users that belong to a certain Cognito group, provide that group name here

      # cognito-restrict-to-group=guacamole
    • Restart Guacamole by executing guawsctl restart guac. If Guacamole does not come back after the restart command or if signing in fails, review the log files by executing guawsctl logs -f guac.
  6. Visit the public hostname of your EC2 instance and you will be redirected to Cognito for authentication.

Configuration Options​

Guacamole will only reread guacamole.properties and load newly-installed extensions during startup, so Guacamole will need to be restarted before Cognito authentication can be used. Doing this will disconnect all active users, so be sure that it is safe to do so prior to attempting installation. When ready, restart Guacamole with guawsctl restart guac and give the new authentication a try.

Required Options​

cognito-domain

The hostname where the Cognito user pool hosts its authentication endpoints. This domain name needs to be set by the administrator of the user pool. It can either be a subdomain of auth.[region].amazoncognito.com or a custom domain name. Do not provide the protocol (e.g. https://), only the domain name.

cognito-user-pool-id

The ID of the Cognito user pool that Guacamole will authenticate against.

cognito-client-id

The Cognito app client ID which should be submitted to Cognito service when necessary. This value is provided to you by Cognito when you create an new app client.

cognito-redirect-uri

The URI that should be submitted to Cognito such that they can redirect the authenticated user back to Guacamole after the authentication process is complete. This must be the full URL that a user would enter into their browser to access Guacamole. It must also match the redirect URLs in the app client settings.

Optional Options​

cognito-scope Defaults to openid

The space-separated list of OpenID scopes to request. OpenID scopes determine the information returned within the OpenID token, and thus affect what values can be used as an authenticated user's username.

cognito-username-claim-type Defaults to email

The claim type which contains the authenticated user's username within any valid JWT. By default, the email is used. Alternatively, sub can be used which is a unique UUID of the user which is constant even if the email address changes.

cognito-restrict-to-group Defaults to undefined

By default, any user that successfully authenticates against the Cognito user pool is granted access to Guacamole. Access can restricted to users that belong to a certain group in Cognito. To do so, provide the name of the Cognito user group as value.

cognito-identity-provider Defaults to undefined

Used to directly authenticate with a specific provider. For social sign-in the valid values are Facebook, Google, LoginWithAmazon and SignInWithApple. For Amazon Cognito user pools, the value is COGNITO. For other identity providers this would be the name you assigned to the IdP in your user pool.

cognito-idp-identifier Defaults to undefined

Used to map to a provider name without exposing the provider name.

Automating Deployment​

The configuration of the authentication extension for Cognito can be fully automated. This allows the deployment through CloudFormation or Terraform templates and cluster configurations. When launching the instance, provide the following UserData script. This will enable the Cognito authentication extension and write the configuration file. Since the IP address and hostname of the instance are not known at the time of the launch (required for the cognito-redirect-uri parameter), we recommend to attach an Elastic IP to the instance, create a DNS record that will point at the newly launched instance or attach the instance to an Application Load Balancer.

#cloud-config
runcmd:
  - >
    ln -s ../available-extensions/guacamole-auth-cognito-1.2.0/guacamole-auth-cognito-1.2.0.jar
    /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-cognito-1.2.0.jar
write_files:
- content: |
    cognito-domain=my-company.auth.us-east-1.amazoncognito.com
    cognito-user-pool-id=us-east-1_123abc987
    cognito-client-id=1vkit2iqem9dmEXAMPLE
    cognito-redirect-uri=https://129.254.129.254/
  owner: root:root
  permissions: '0644'
  path: /home/ec2-user/guaws/guacamole/etc/guacamole.properties

Debugging Issues​

I'm not being redirected to Cognito for authentication

Please check the Guacamole logs for any errors. Run guawsctl logs -f guac to dump the logs to your terminal session. Shortly after restarting the service (guawsctl restart guac) you should see the following line:

guac_1   | 14:46:40.448 [localhost-startStop-1] INFO  o.a.g.extension.ExtensionModule - Extension "Cognito Authentication Extension" loaded.
guac_1   | 14:46:41.715 [localhost-startStop-1] INFO  o.a.g.extension.ExtensionModule - Extension "MySQL Authentication" loaded.
guac_1   | 14:46:41.720 [localhost-startStop-1] INFO  o.a.g.extension.ExtensionModule - Extension "Adhoc Guacamole Connections" loaded.

Make sure that the "Cognito Authentication Extension" is loaded before the "MySQL Authentication" extension. If the order is different, make sure that the extension JAR file in /home/ec2-user/guaws/guacamole/etc/extensions/ is called guacamole-auth-0-cognito-1.2.0.jar Mind the -auth-0- part which ensures that the extension is loaded before any other auth extension).

If you don't see the "Cognito Authentication Extension" at all, make sure the link in /home/ec2-user/guaws/guacamole/etc/extensions/ resolves properly to the actual JAR file in /home/ec2-user/guaws/guacamole/etc/available-extensions/.