QGIS Auth Manager Setup for Secured GeoServer#

This guide explains how to configure QGIS Authentication Manager to securely connect to password-protected GeoServer instances when using connection files and project files generated by geoserver-cli.

Why Use QGIS Auth Manager?#

By default, geoserver-cli does not include credentials in generated QGIS connection XML or project files for security reasons:

  • Security: Credentials stored in plain text files can be accidentally committed to version control or shared insecurely
  • Best Practice: QGIS Auth Manager encrypts credentials and stores them securely in your user profile
  • Flexibility: Multiple users can share the same connection/project files while using their own credentials

Prerequisites#

  • QGIS 3.0 or later
  • A GeoServer instance with HTTP Basic Authentication enabled
  • Connection XML or project file generated by geoserver-cli

Step-by-Step Setup#

1. Generate QGIS Connection/Project Files#

First, generate your QGIS files using geoserver-cli:

1
2
3
4
5

# Generate connections XML (without credentials)
./geoserver-cli qgis export connections -w my_workspace -o geoserver_connections.xml

# Or generate a project file
./geoserver-cli qgis export project -w my_workspace -o geoserver_layers.qgs

Note: The generated files will not include credentials by default.

2. Open QGIS Auth Manager#

  1. Launch QGIS
  2. Go to Settings → Options → Authentication (or Edit → Options → Authentication)
  3. Click the QGIS Auth Manager button (or use Settings → Authentication → Authentication Manager)

Alternatively, use the keyboard shortcut:

  • Windows/Linux: Ctrl+Shift+A
  • macOS: Cmd+Shift+A

3. Create a New Authentication Configuration#

  1. In QGIS, go to Browser panel
  2. Right-click on WMS or WFS → New Connection
  3. Click Import and select your geoserver_connections.xml file
  4. When prompted for credentials, enter your GeoServer username and password
  5. QGIS will automatically create an authentication configuration

Method B: Manual Configuration#

  1. In QGIS Auth Manager, click Add Authentication Configuration (green plus icon)
  2. Select Basic as the authentication method
  3. Fill in the form:
    • Name: A descriptive name (e.g., “GeoServer Production”)
    • Resource: The GeoServer base URL (e.g., http://geoserver.example.com/geoserver)
    • Username: Your GeoServer username
    • Password: Your GeoServer password
  4. Click OK to save

4. Configure Authentication for Specific URLs#

If you need to configure authentication for specific workspace URLs:

  1. In QGIS Auth Manager, click Add Authentication Configuration
  2. Select Basic authentication method
  3. Configure:
    • Name: Descriptive name (e.g., “GeoServer Workspace: my_workspace”)
    • Resource: Full workspace URL (e.g., http://geoserver.example.com/geoserver/my_workspace/wms)
    • Username: Your GeoServer username
    • Password: Your GeoServer password
  4. Click OK

5. Verify Authentication#

  1. In QGIS Browser panel, expand WMS or WFS
  2. Right-click on your imported connection → Connect
  3. If authentication is configured correctly, layers should load without prompting for credentials

6. Using Project Files#

When opening a .qgs project file generated by geoserver-cli:

  1. Open the project file in QGIS: Project → Open → select geoserver_layers.qgs
  2. If authentication is already configured (via Method A or B above), layers should load automatically
  3. If prompted for credentials, enter them once and QGIS will remember them for future sessions

Advanced Configuration#

Using Authentication Configurations Across Projects#

QGIS Auth Manager stores authentication configurations in your user profile:

  • Windows: C:\Users\<username>\AppData\Roaming\QGIS\QGIS3\auth.db
  • macOS: ~/Library/Application Support/QGIS/QGIS3/auth.db
  • Linux: ~/.local/share/QGIS/QGIS3/auth.db

These configurations are shared across all QGIS projects, so you only need to configure authentication once per GeoServer instance.

Matching URLs with Authentication Configurations#

QGIS matches authentication configurations using the Resource field:

  • Exact match: http://geoserver.example.com/geoserver/my_workspace/wms
  • Prefix match: http://geoserver.example.com/geoserver (matches all workspaces)
  • Domain match: http://geoserver.example.com (matches all paths)

Tip: Use a broader Resource URL (like the base GeoServer URL) to cover multiple workspaces with a single authentication configuration.

Exporting Authentication Configurations#

To share authentication configurations securely:

  1. In QGIS Auth Manager, select your configuration
  2. Click Export (or right-click → Export)
  3. Choose a secure location and set a master password
  4. Share the exported file securely with team members
  5. They can import it using Import in QGIS Auth Manager

Warning: Never commit exported authentication files to version control.

Troubleshooting#

QGIS Still Prompts for Credentials#

  1. Check Resource URL: Ensure the Resource URL in your auth configuration matches the connection URL (case-sensitive)
  2. Check Authentication Method: Verify you’re using Basic authentication (not Digest or other methods)
  3. Clear QGIS Cache: Close QGIS and delete the cache directory, then reopen
  4. Re-import Connection: Delete the connection in Browser and re-import the XML file

Authentication Works in Browser but Not in Project#

  1. Open the project file in a text editor
  2. Check that layer URLs match the Resource URL in your auth configuration
  3. Ensure the project file uses relative URLs or URLs that match your auth configuration

“Authentication Failed” Error#

  1. Verify your GeoServer credentials are correct
  2. Check that HTTP Basic Authentication is enabled on your GeoServer instance
  3. Test the connection directly in a web browser with the same credentials
  4. Check GeoServer logs for authentication failures

Security Best Practices#

  1. Never use --include-credentials flag unless absolutely necessary for testing
  2. Use QGIS Auth Manager for all production workflows
  3. Set a master password for QGIS Auth Manager to encrypt stored credentials
  4. Rotate credentials regularly and update auth configurations accordingly
  5. Use environment-specific configurations (dev/staging/prod) with different credentials
  6. Restrict file permissions on connection XML and project files (chmod 600)

Example Workflow#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 1. Generate connection file (no credentials)
./geoserver-cli qgis export connections -w production -o prod_connections.xml

# 2. Import into QGIS and configure auth (via QGIS UI)
#    - Browser → WMS → New Connection → Import → prod_connections.xml
#    - Enter credentials when prompted

# 3. Generate project file (will use configured auth)
./geoserver-cli qgis export project -w production -o prod_layers.qgs

# 4. Open project in QGIS (auth already configured)
#    - Project → Open → prod_layers.qgs
#    - Layers load automatically with configured credentials

Additional Resources#

Backward Code Style Guide