docs: consolidate OAuth2/OIDC authentication documentation

- Move scattered implementation notes into structured RST documentation
- Add comprehensive authentication guide covering all methods
- Add quick reference cheatsheet with provider examples
- Enhance installation guide with detailed setup and troubleshooting
- Reorganize self-hosted setup guide with provider-specific instructions
  (Keycloak, Okta, Auth0, Azure AD, Cognito)
- Update README.md with OAuth2 support summary and documentation links
- Follow repository documentation standards (lowercase .rst in /docs/)

Documentation now covers:
- Preset workspace authentication (API tokens)
- Self-hosted Superset with OAuth2/OIDC (recommended)
- Username/password authentication
- JWT token authentication
- Security best practices and troubleshooting

Author: blarghmatey

README.md

@@ -220,20 +220,74 @@ Efficient search across all entity types:
 extensively tested with Preset workspaces. All features work seamlessly with
 Preset's multi-workspace environment.
 
-### Self-Hosted Superset
-**Does it work with my Superset instance?** Most functionality should work, but
-depending on your authentication setup, you may need to tweak the code. We
-welcome contributions from the broader Superset community to improve
-compatibility.
-
-**Preset-free mode**: A future version could remove multi-workspace constructs
-for single-instance Superset deployments. If you're interested in this, please
-contribute or open an issue.
-
-### Contributing for Broader Compatibility
-We're open to contributions that enable 'sup for the entire Superset community.
-Areas that likely need work for self-hosted instances:
-- Authentication methods beyond Preset API tokens
+### Self-Hosted Superset ✨ (NEW!)
+**Phase 1 Implementation Complete:** Full support for self-hosted Superset with OAuth2/OIDC authentication!
+
+'sup now supports **self-hosted Superset instances** with multiple authentication methods:
+- **OAuth2/OIDC** - Works with Keycloak, Okta, Auth0, Dex, Azure AD, Cognito
+- **Username/Password** - Direct Superset authentication
+- **JWT Tokens** - Pre-generated JWT tokens
+
+#### Quick Setup for Self-Hosted Superset
+
+```bash
+# Configure self-hosted instance in ~/.sup/config.yml
+superset_instances:
+  production:
+    url: https://superset.example.com
+    auth_method: oauth
+    oauth_token_url: https://auth.example.com/oauth2/token
+    oauth_client_id: superset-cli
+    oauth_client_secret: ${ENV:SUPERSET_OAUTH_SECRET}
+    oauth_username: superset-service
+    oauth_password: ${ENV:SUPERSET_SERVICE_PASSWORD}
+
+# Set environment variables
+export SUPERSET_OAUTH_SECRET="your-client-secret"
+export SUPERSET_SERVICE_PASSWORD="your-service-password"
+
+# Use 'sup with your self-hosted instance
+sup dataset list
+sup chart pull --mine
+sup sql "SELECT * FROM your_table"
+```
+
+#### Authentication Methods for Self-Hosted Superset
+
+**OAuth2/OIDC (Recommended)** - For instances with external authentication:
+```yaml
+auth_method: oauth
+oauth_token_url: https://auth.example.com/oauth2/token
+oauth_client_id: your-client-id
+oauth_client_secret: ${ENV:OAUTH_SECRET}
+oauth_username: service-account
+oauth_password: ${ENV:SERVICE_PASSWORD}
+```
+
+**Username/Password** - For direct Superset authentication:
+```yaml
+auth_method: username_password
+username: admin
+password: ${ENV:SUPERSET_PASSWORD}
+```
+
+**JWT Token** - For pre-generated JWT tokens:
+```yaml
+auth_method: jwt
+jwt_token: eyJhbGc...
+```
+
+#### Complete Self-Hosted Setup Guide
+See **[Self-Hosted Superset Setup Guide](docs/self_hosted_setup.rst)** for:
+- Step-by-step OAuth2 configuration
+- Provider-specific examples (Keycloak, Okta, Auth0, Azure AD)
+- Troubleshooting guide
+- Security best practices
+
+#### Contributing for Broader Compatibility
+We're open to contributions that extend 'sup for the entire Superset community.
+Areas we're actively working on:
+- Additional authentication methods
 - Single-instance mode (removing workspace concepts)
 - Different API endpoint structures
 

docs/authentication.rst

@@ -0,0 +1,133 @@
+Authentication
+==============
+
+sup supports multiple authentication methods for Preset and self-hosted Superset instances.
+
+Preset Workspaces
+-----------------
+
+API Token (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Use API token and secret from Preset workspace settings:
+
+.. code-block:: bash
+
+   export SUP_PRESET_API_TOKEN="your-token"
+   export SUP_PRESET_API_SECRET="your-secret"
+
+Or configure in ``~/.sup/config.yml``:
+
+.. code-block:: yaml
+
+   preset:
+     api_token: ${ENV:PRESET_API_TOKEN}
+     api_secret: ${ENV:PRESET_API_SECRET}
+
+Self-Hosted Superset
+--------------------
+
+Configure instances in ``~/.sup/config.yml`` under ``superset_instances``.
+
+OAuth2/OIDC (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For instances with external identity providers (Keycloak, Okta, Auth0, Azure AD, Cognito, Dex):
+
+.. code-block:: yaml
+
+   superset_instances:
+     production:
+       url: https://superset.example.com
+       auth_method: oauth
+       oauth_token_url: https://auth.example.com/oauth2/token
+       oauth_client_id: superset-cli
+       oauth_client_secret: ${ENV:SUPERSET_OAUTH_SECRET}
+       oauth_username: superset-service
+       oauth_password: ${ENV:SUPERSET_SERVICE_PASSWORD}
+       oauth_scope: "openid profile email"
+
+Set environment variables:
+
+.. code-block:: bash
+
+   export SUPERSET_OAUTH_SECRET="your-client-secret"
+   export SUPERSET_SERVICE_PASSWORD="your-service-password"
+
+Benefits:
+
+- Centralized identity management
+- Automatic token refresh with 5-minute safety buffer
+- No passwords in config files
+- Works with service accounts
+
+Username/Password
+~~~~~~~~~~~~~~~~~
+
+For instances with built-in Superset authentication:
+
+.. code-block:: yaml
+
+   superset_instances:
+     production:
+       url: https://superset.example.com
+       auth_method: username_password
+       username: superset-service
+       password: ${ENV:SUPERSET_PASSWORD}
+
+JWT Token
+~~~~~~~~~
+
+For pre-generated JWT tokens:
+
+.. code-block:: yaml
+
+   superset_instances:
+     production:
+       url: https://superset.example.com
+       auth_method: jwt
+       jwt_token: ${ENV:SUPERSET_JWT_TOKEN}
+
+Security Best Practices
+-----------------------
+
+1. **Use environment variables for secrets**
+
+   .. code-block:: yaml
+
+      oauth_client_secret: ${ENV:SUPERSET_OAUTH_SECRET}
+      password: ${ENV:SUPERSET_PASSWORD}
+
+2. **Protect config files**
+
+   .. code-block:: bash
+
+      chmod 600 ~/.sup/config.yml
+
+3. **Create dedicated service accounts** (not personal user accounts)
+
+   - Limit permissions to required scope
+   - Use strong, unique passwords
+
+4. **Never commit secrets to git**
+
+   - Add ``.env`` files to ``.gitignore``
+   - Use secrets management in CI/CD
+
+5. **Rotate credentials regularly**
+
+   - Change client secrets in OIDC provider
+   - Update passwords periodically
+
+Provider-Specific Setup
+-----------------------
+
+See :doc:`self_hosted_setup` for step-by-step instructions for:
+
+- Keycloak
+- Okta
+- Auth0
+- Azure AD
+- Amazon Cognito
+
+Includes configuration examples, troubleshooting, and detailed security guidance.