Overview

For this exercise we will use a basic password file method for authenticating - this is probably not a very useful method in production, but it demonstrates how the proxy server can be configured to provide the correct header to Galaxy, and how Galaxy integrates with upstream authentication providers. This same method can be used with NGINX and Apache modules for CAS or SAML authentication.

Agenda

1. Overview
2. Configuring Authentication
3. Testing
4. API access
5. Reverting

Configuring Authentication

Hands-on: Configuring everything

1. Edit the galaxy.j2 template file in the templates/nginx directory and update the main location block defined for serving galaxy. Add the parameters:
   • auth_basic galaxy;
   • auth_basic_user_file /etc/nginx/passwd;
   • proxy_set_header HTTP_REMOTE_USER $remote_user;
   • proxy_set_header HTTP_GX_SECRET SOME_SECRET_STRING;

   It should look like:

   @@ -14,6 +14,10 @@
   +        auth_basic           galaxy;
   +        auth_basic_user_file /etc/nginx/passwd;
   +        proxy_set_header          HTTP_REMOTE_USER $remote_user;
   +        proxy_set_header          HTTP_GX_SECRET SOME_SECRET_STRING;
        }
       
        # Static files can be more efficiently served by Nginx. Why send the
   

   Tip: How to read a Diff

   If you haven’t worked with diffs before, this can be something quite new or different.

   If we have two files, let’s say a grocery list, in two files. We’ll call them ‘a’ and ‘b’.

   Old

   $ cat old
   🍎
   🍐
   🍊
   🍋
   🍒
   🥑
   

   New

   $ cat new
   🍎
   🍐
   🍊
   🍋
   🍍
   🥑
   

   We can see that they have some different entries. We’ve removed 🍒 because they’re awful, and replaced them with an 🍍

   Diff lets us compare these files

   $ diff old new
   5c5
   < 🍒
   ---
   > 🍍
   

   Here we see that 🍒 is only in a, and 🍍 is only in b. But otherwise the files are identical.

   There are a couple different formats to diffs, one is the ‘unified diff’

   $ diff -U2 old new
   --- old	2022-02-16 14:06:19.697132568 +0100
   +++ new	2022-02-16 14:06:36.340962616 +0100
   @@ -3,4 +3,4 @@
    🍊
    🍋
   -🍒
   +🍍
    🥑
   

   This is basically what you see in the training materials which gives you a lot of context about the changes:

   • --- old is the ‘old’ file in our view
   • +++ new is the ‘new’ file
   • @@ these lines tell us where the change occurs and how many lines are added or removed.
   • Lines starting with a - are removed from our ‘new’ file
   • Lines with a + have been added.

   So when you go to apply these diffs to your files in the training:

   1. Ignore the header
   2. Remove lines starting with - from your file
   3. Add lines starting with + to your file

   The other lines (🍊/🍋 and 🥑) above just provide “context”, they help you know where a change belongs in a file, but should not be edited when you’re making the above change. Given the above diff, you would find a line with a 🍒, and replace it with a 🍍

   Added & Removed Lines

   Removals are very easy to spot, we just have removed lines

   --- old	2022-02-16 14:06:19.697132568 +0100
   +++ new	2022-02-16 14:10:14.370722802 +0100
   @@ -4,3 +4,2 @@
    🍋
    🍒
   -🥑
   

   And additions likewise are very easy, just add a new line, between the other lines in your file.

   --- old	2022-02-16 14:06:19.697132568 +0100
   +++ new	2022-02-16 14:11:11.422135393 +0100
   @@ -1,3 +1,4 @@
    🍎
   +🍍
    🍐
    🍊
   

   Completely new files

   Completely new files look a bit different, there the “old” file is /dev/null, the empty file in a Linux machine.

   $ diff -U2 /dev/null old
   --- /dev/null	2022-02-15 11:47:16.100000270 +0100
   +++ old	2022-02-16 14:06:19.697132568 +0100
   @@ -0,0 +1,6 @@
   +🍎
   +🍐
   +🍊
   +🍋
   +🍒
   +🥑
   

   And removed files are similar, except with the new file being /dev/null

   --- old	2022-02-16 14:06:19.697132568 +0100
   +++ /dev/null	2022-02-15 11:47:16.100000270 +0100
   @@ -1,6 +0,0 @@
   -🍎
   -🍐
   -🍊
   -🍋
   -🍒
   -🥑
   

   Tip: Running this tutorial just for Reports?

   Add the auth_basic and auth_basic_user_file lines to your location /reports/

   auth_basic enables validation of username and password using the “HTTP Basic Authentication” protocol. Its value galaxy is used as a realm name to be displayed to the user when prompting for credentials. auth_basic_user_file specifies the file that keeps usernames and passwords. proxy_set_header adds HTTP_REMOTE_USER to the special variables passed by nginx to Galaxy, with value $remote_user, which is a nginx embedded variable containing the username supplied with the Basic authentication.

   GX_SECRET is added as a header for security purposes, to prevent any other users on the system impersonating nginx and sending requests to Galaxy. NGINX and other webservers like Apache will strip any user-sent REMOTE_USER headers, as that header defines the authenticated user. If you can talk directly to Galaxy (e.g. via curl) and provide the REMOTE_USER header, you can impersonate any other use. While having Galaxy listen on 127.0.0.1 prevents any requests from outside of the system reaching Galaxy, anyone on the system can still send requests to that port. Here you can choose to switch to a unix socket with permissions only permitting Galaxy and Nginx to connect. GX_SECRET adds additional security as it needs to match remote_user_secret in your galaxy configutation.

   Tip: Proxy bypass

   Users can bypass the authentication only if they can talk directly to the gunicorn processes (if you have socket/http: 0.0.0.0, or if it is directly responsible for serving galaxy, and there is no proxy.) This can happen mostly when some users have command line access to the Galaxy server, which is considered a bad practice.

2. Add a pre_task using the pip module which installs the library passlib, which is required for htpasswd.

   Add a pre_task using the htpasswd module which sets up a password file in /etc/nginx/passwd, with owner and group set to root, and a name and password, and a mode of 0640.

   Question

   How does your final configuration look?

   Solution

   @@ -7,6 +7,15 @@
            name: galaxy
            state: restarted
      pre_tasks:
   +    - pip:
   +        name: passlib
   +    - htpasswd:
   +        path: /etc/nginx/passwd
   +        name: user1        # Pick a username
   +        password: changeme # and a password
   +        owner: www-data    # nginx on centos
   +        group: root
   +        mode: 0640
        - name: Install Dependencies
          package:
            name: ['git', 'make', 'python3-psycopg2', 'virtualenv']
   

3. Galaxy needs to be instructed to expect authentication to come from the upstream proxy. In order to do this, set the following two options in your Galaxy group variables:

   ...
   galaxy_config:
     galaxy:
       ...
       use_remote_user: true
       remote_user_maildomain: "{{ inventory_hostname }}"
       remote_user_secret: SOME_SECRET_STRING
   

   Tip: Running this tutorial just for Reports?

   You don’t need to make the above changes for Galaxy then.

   Set the remote_user_maildomain option to the appropriate domain name for your site.

4. Run the playbook

Comment: Access denied

If you see this message, it is because nginx is not correctly sending the REMOTE_USER or the GX_SECRET values.

Testing

You should now be presented with a password dialog when attempting to load the Galaxy UI.

Hands-on: Testing

1. Log in using the username and password you provided when creating the passwd file. If your username and the value of remote_user_maildomain match an existing user, you will be logged in to that account. If not, a new account will be created for that user.

2. Click on the “User” menu at the top, to see how the username appears.

3. Note that some user features are not available when remote user support is enabled.

   Try logging out by selecting User -> Logout. You will discover that when returning to the user interface, you are still logged in. This is because Galaxy has no way of logging you out of the proxy’s authentication system. Instead, you should set remote_user_logout_href in galaxy.yml to point to the URL of your authentication system’s logout page.

API access

If you wish your Galaxy to be accessible to command line clients (e.g. bioblend, blend4j, parsec), you will need to add an exception for authentication on the API. Galaxy will still be secure and protected, but non-browser access will be permitted with an API key.

location /api/ {
    satisfy any;
    allow all;
}

Tip: Notification of Registration

There is no built-in way to be notified if users are registered, with external authentication or built-in. However, you could automate this easily. There is a gxadmin command we use called gxadmin query latest-users which Björn uses often. Other sites have other methods, e.g. Nicola’s cron script which runs daily on his server, to add new users to a group according to their email domain name.

Reverting

We don’t want to leave Galaxy this way for the rest of our workshop.

Hands-on: Reverting the changes

1. Edit your group variables file and comment out:

   • the NGINX changes
   • use_remote_user: true

2. Run the playbook

Key points

• Remote auth is not complex to set up and can help you meet institutional requirements

Frequently Asked Questions

Feedback

Did you use this material as an instructor? Feel free to give us feedback on how it went.
Did you use this material as a learner or student? Click the form below to leave feedback.

Citing this Tutorial

1. Nate Coraor, Nicola Soranzo, Helena Rasche, 2022 External Authentication (Galaxy Training Materials). https://training.galaxyproject.org/training-material/topics/admin/tutorials/external-auth/tutorial.html Online; accessed TODAY
2. Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012

BibTeX

@misc{admin-external-auth,
author = "Nate Coraor and Nicola Soranzo and Helena Rasche",
title = "External Authentication (Galaxy Training Materials)",
year = "2022",
month = "10",
day = "18"
url = "\url{https://training.galaxyproject.org/training-material/topics/admin/tutorials/external-auth/tutorial.html}",
note = "[Online; accessed TODAY]"
}
@article{Batut_2018,
    doi = {10.1016/j.cels.2018.05.012},
    url = {https://doi.org/10.1016%2Fj.cels.2018.05.012},
    year = 2018,
    month = {jun},
    publisher = {Elsevier {BV}},
    volume = {6},
    number = {6},
    pages = {752--758.e1},
    author = {B{\'{e}}r{\'{e}}nice Batut and Saskia Hiltemann and Andrea Bagnacani and Dannon Baker and Vivek Bhardwaj and Clemens Blank and Anthony Bretaudeau and Loraine Brillet-Gu{\'{e}}guen and Martin {\v{C}}ech and John Chilton and Dave Clements and Olivia Doppelt-Azeroual and Anika Erxleben and Mallory Ann Freeberg and Simon Gladman and Youri Hoogstrate and Hans-Rudolf Hotz and Torsten Houwaart and Pratik Jagtap and Delphine Larivi{\`{e}}re and Gildas Le Corguill{\'{e}} and Thomas Manke and Fabien Mareuil and Fidel Ram{\'{\i}}rez and Devon Ryan and Florian Christoph Sigloch and Nicola Soranzo and Joachim Wolff and Pavankumar Videm and Markus Wolfien and Aisanjiang Wubuli and Dilmurat Yusuf and James Taylor and Rolf Backofen and Anton Nekrutenko and Björn Grüning},
    title = {Community-Driven Data Analysis Training for Biology},
    journal = {Cell Systems}
}