From 6302fa0661b319a819b57c5a83202ec63766095c Mon Sep 17 00:00:00 2001
From: Michele Cereda <cereda.michele@gmail.com>
Date: Mon, 12 Jan 2026 13:08:59 +0100
Subject: [PATCH] chore(kb/redash): dump authentication notes

---
 knowledge base/redash.md | 84 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 83 insertions(+), 1 deletion(-)

diff --git a/knowledge base/redash.md b/knowledge base/redash.md
index 3ed2acc..ccec898 100644
--- a/knowledge base/redash.md	
+++ b/knowledge base/redash.md	
@@ -8,12 +8,21 @@ Intro
 ## Table of contents <!-- omit in toc -->
 
 1. [TL;DR](#tldr)
+1. [Authentication](#authentication)
+   1. [Password](#password)
+   1. [Google OAuth](#google-oauth)
+   1. [LDAP or Active Directory](#ldap-or-active-directory)
 1. [API](#api)
 1. [Further readings](#further-readings)
    1. [Sources](#sources)
 
 ## TL;DR
 
+Settings are read by `redash.settings` from environment variables.<br/>
+Most installations set them in `/opt/redash/.env`. Official container images require that `.env` file in the root
+directory.<br/>
+Reference available variables from [Environment Variables Settings].
+
 <!-- Uncomment if used
 <details>
   <summary>Setup</summary>
@@ -44,6 +53,71 @@ Intro
 </details>
 -->
 
+Refer [How to Upgrade] when upgrading a self-hosted instance.
+
+Updating dependencies (DB, redis cache) versions directly seems to work, but mind that they do require downtime.<br/>
+Redash will temporarily lose connection to them during the update's downtime period, then properly connect back to them
+without issues once they are up again.
+
+## Authentication
+
+Refer [Authentication Settings].
+
+Authentication options are configured through **a mix** of Environment variables and UI (under _Settings_ > _General_).
+
+> [!important]
+> Only admins can view and change authentication settings.<br/>
+> Some authentication options will **not** appear in the UI until the corresponding environment variables have been set.
+
+Redash uses the [Password] method by default.
+
+### Password
+
+Redash authenticates users with their email address and password.
+
+This is configured in the settings' `Password Login` section.<br/>
+After one enables an alternative authentication method, they can disable login via password.
+
+Redash stores the hashes of those user passwords that were created through its default password configuration.
+
+Authenticating through SAML or Google Login for the first time creates a user record, but does **not** store a password
+hash.<br/>
+This is called Just-in-Time (JIT) provisioning.<br/>
+These users can **only** log-in through third-party authentication services.
+
+When using Password Login and subsequently enable Google OAuth or SAML 2.0, it is possible for that user to log-in to
+Redash using a single email address but two passwords (their Google/SAML password, and their local Redash password).
+
+> [!tip]
+> Prefer disabling Password Login if users are expected to authenticate through third-party authentication services.
+
+### Google OAuth
+
+Allow any user with a Google account from the designated domains to login to Redash.<br/>
+If the user doesn't have an account yet, Redash will create one automatically.
+
+To enable this method:
+
+1. Register the Redash instance with your Google organization by:
+   1. Creating a developers project if one does not exist already, and following the _Create Credentials_ flow in that
+      case.<br/>
+      The setup will give back a client id and a client secret. Note them down, as those will be used later.
+   1. Setting the _Authorized Redirect URLs_ to `http(s)://${REDASH_BASEURL}/oauth/google_callback`.
+   1. Set the instance's `REDASH_GOOGLE_CLIENT_ID` and `REDASH_GOOGLE_CLIENT_SECRET` environment variables to the
+      credentials given back by the setup step above.
+   1. Restart the Redash instance.
+
+Only visitors with an existing Redash account can sign-in using the Google Login flow.<br/>
+As for the [Password] method, visitors without an account cannot login unless they receive an invitation from an admin.
+
+Optionally configure Redash to allow any user from a specified domain to login by completing the
+_Allowed Google Apps Domains_ box in _Settings_ > _General_.<br/>
+Redash will create an account automatically for them on first login, if one does not already exist.
+
+### LDAP or Active Directory
+
+Refer [LDAP/AD Authentication].
+
 ## API
 
 Refer [API].
@@ -115,6 +189,7 @@ response: Response = redash.create_data_source(data_source_name, data_source_typ
 ### Sources
 
 - [Documentation]
+- [Setting up a Redash Instance]
 - [API]
 
 <!--
@@ -123,13 +198,20 @@ response: Response = redash.create_data_source(data_source_name, data_source_typ
   -->
 
 <!-- In-article sections -->
+[Password]: #password
+
 <!-- Knowledge base -->
 <!-- Files -->
 <!-- Upstream -->
 [API]: https://redash.io/help/user-guide/integrations-and-api/api/
+[Authentication Settings]: https://redash.io/help/user-guide/users/authentication-options/
 [Codebase]: https://github.com/getredash/redash
 [Documentation]: https://redash.io/help/
-[Website]: https://redash.io/
+[Environment Variables Settings]: https://redash.io/help/open-source/admin-guide/env-vars-settings/
 [getredash/redash-toolbelt]: https://github.com/getredash/redash-toolbelt
+[How to Upgrade]: https://redash.io/help/open-source/admin-guide/how-to-upgrade/
+[LDAP/AD Authentication]: https://redash.io/help/open-source/admin-guide/ldap-authentication/
+[Setting up a Redash Instance]: https://redash.io/help/open-source/setup/
+[Website]: https://redash.io/
 
 <!-- Others -->