Authentik: set custom username for OAuth application (e.g. for Apache Guacamole) via a property mapping

If you use Authentik ( as an OAuth authentication provider for your Apache Guacamole ( instance and you’d like to customize usernames for Guacamole, here’s how you can achieve this. The steps described below may work for other applications, wired with Authentik via OAuth, too—not just Guacamole.

This guide assumes that you’ve already set up Authentik integration with Guacamole. If you haven’t done so, follow the guide from Authentik documentation.

Step 1

In Authentik, go to Directory -> Users -> click the Edit button of a user who needs access to your Guacamole instance. In the attributes field, set:

guacamole_username: billgates

Assuming billgates is a username already known to Guacamole.

Step 2

In Authentik, go to Customisation -> Property Mappings -> Create -> Scope Mapping. Set:

  • Name: Guacamole preferred_username (can be anything)
  • Scope name: profile
  • Expression:
return {
    "preferred_username": request.user.attributes.get("guacamole_username", "")

Step 3

In Authentik, go to Providers -> click the Edit button of your Guacamole OAuth provider, then expand “Advanced protocol settings” and in Scopes:

  • deselect authentik default OAuth Mapping: OpenID ‘profile’
  • select Guacamole preferred_username
  • do not deselect other two selected scopes

The field will look like so:

Possibly you also want to tick “Include claims in id_token” if it’s not ticked already.

Step 4

To your Guacamole properties file (/etc/guacamole/ add:

openid-username-claim-type: preferred_username

Restart Tomcat (or your Guacamole Docker container):

systemctl restart tomcat9

Step 5

Try logging in to Guacamole via Authentik. Confirm that you’ve logged in with the username specified in the Step 1:

* * *

If something doesn’t work, examine Authentik logs (Events -> Logs) and Guacamole logs (tail -f /var/log/tomcat9/catalina.out).

Relevant links:

This entry was posted in How to’s and tagged , . Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *