{"id":8927,"library":"dash-auth","title":"Dash Authorization Package","description":"Dash-auth is a Python library providing HTTP Basic Auth functionality for Dash applications. It enables developers to secure their Dash dashboards with simple username and password authentication. The current version is 2.3.0, and the package is actively maintained by Plotly, focusing on seamless integration within the Dash ecosystem.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/plotly/dash-auth","tags":["dash","authentication","basic auth","plotly","web app","security"],"install":[{"cmd":"pip install dash-auth","lang":"bash","label":"Install latest version"},{"cmd":"pip install dash>=2.0.0 dash-auth==2.3.0","lang":"bash","label":"Install with Dash 2.x+"}],"dependencies":[{"reason":"Required as dash-auth integrates directly with Dash applications. Version 2.0.0+ is recommended for full compatibility with dash-auth 2.x.x.","package":"dash"}],"imports":[{"note":"Directly importing `dash_auth` as a module is less common than importing specific classes like `BasicAuth`.","wrong":"import dash_auth","symbol":"BasicAuth","correct":"from dash_auth import BasicAuth"},{"note":"As of Dash 2.0, importing `Dash` directly from the `dash` package is the recommended pattern.","wrong":"import dash","symbol":"Dash","correct":"from dash import Dash"}],"quickstart":{"code":"import os\nfrom dash import Dash, html, dcc\nfrom dash_auth import BasicAuth\n\n# Keep this out of source code repository - save in a file or a database\nVALID_USERNAME_PASSWORD_PAIRS = {\n    'dash_user': os.environ.get('DASH_PASSWORD', 's3cr3t_p@ssw0rd!'),\n    'another_user': 'another_secret_password'\n}\n\napp = Dash(__name__)\n\n# Important: Set a secret key for the Flask server to avoid warnings,\n# especially if using sessions or other Flask-related features.\n# While not strictly required for basic_auth, it's good practice.\napp.server.secret_key = os.environ.get('SECRET_KEY', 'a_very_secret_key_that_should_be_randomly_generated')\n\nauth = BasicAuth(app, VALID_USERNAME_PASSWORD_PAIRS)\n\napp.layout = html.Div([\n    html.H1('Welcome to the Protected Dash App!'),\n    html.Div('This content is only visible to authenticated users.'),\n    dcc.Graph(\n        id='example-graph',\n        figure={\n            'data': [\n                {'x': [1, 2, 3], 'y': [4, 1, 2], 'type': 'bar', 'name': 'SF'},\n                {'x': [1, 2, 3], 'y': [2, 4, 5], 'type': 'bar', 'name': 'Montréal'},\n            ],\n            'layout': {\n                'title': 'Dash Data Visualization'\n            }\n        }\n    )\n])\n\nif __name__ == '__main__':\n    app.run_server(debug=True)","lang":"python","description":"This quickstart demonstrates how to add HTTP Basic Authentication to a Dash application using `dash-auth`. It defines a set of valid username-password pairs (with one password loaded from an environment variable for security best practices), initializes `BasicAuth` with the Dash app, and protects the entire application. It also includes setting `app.server.secret_key` to avoid potential Flask session warnings."},"warnings":[{"fix":"For more advanced authentication (e.g., custom UI, user management, SSO, OAuth), consider `dash-enterprise-auth` (for Dash Enterprise users) or third-party solutions like `dash-auth-external` or `PropelAuth`.","message":"HTTP Basic Auth (provided by dash-auth) has inherent limitations: users cannot log out of applications, cannot create accounts or change passwords, and the authentication prompt is browser-native and not customizable. Credentials are typically hardcoded or managed externally.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade `dash-auth` to version 2.0.0 or later (e.g., `pip install dash-auth>=2.0.0`) when using Dash 2.0+ applications. `dash-auth` 2.0.0 removed `PlotlyAuth` entirely and updated dependencies for modern Dash versions.","message":"Prior to `dash-auth` version 2.0.0, the library was coupled with `PlotlyAuth` and had imports that caused deprecation warnings with Dash 2.0+ (e.g., `dash_html_components`). `dash-auth` versions < 2.0.0 are not fully compatible with Dash 2.0+.","severity":"breaking","affected_versions":"< 2.0.0"},{"fix":"Avoid using colons in passwords when supplying them as part of the `VALID_USERNAME_PASSWORD_PAIRS` dictionary or list. If you need to handle complex passwords, consider using an `auth_func` instead of a dictionary for validation.","message":"If a password in `VALID_USERNAME_PASSWORD_PAIRS` contains a colon (`:`), `BasicAuth` will fail with a `ValueError: too many values to unpack (expected 2)` because it uses `username_password_utf8.split(':')`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Configure your health check to accept `401 Unauthorized` as a valid status, or implement a separate 'public' endpoint that bypasses authentication and returns `200 OK` for health checks.","message":"When deploying Dash apps with `dash-auth`, external health check systems expecting a `200 OK` status for the root path might fail. `dash-auth` intentionally returns a `401 Unauthorized` status on initial access to trigger the browser's Basic Auth prompt, which can conflict with simple health checks.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change the problematic password to remove the colon character. Alternatively, implement a custom `auth_func` for `BasicAuth` that handles password parsing more robustly, rather than relying on the default dictionary/list behavior.","cause":"A password supplied in the `VALID_USERNAME_PASSWORD_PAIRS` dictionary or list contains a colon (`:`), which `dash-auth` incorrectly parses as a separator.","error":"ValueError: too many values to unpack (expected 2)"},{"fix":"Set a unique and strong `secret_key` for your Flask server: `app.server.secret_key = 'your_strong_random_secret_key'`. It is best practice to load this from an environment variable for production.","cause":"The underlying Flask application (which Dash runs on) requires a `SECRET_KEY` for session management, even if `dash-auth` BasicAuth itself doesn't directly use Flask sessions. This warning appears when `app.server.secret_key` is not set.","error":"WARNING:root:Session is not available. Have you set a secret key?"},{"fix":"Check your deployment environment's proxy and server configurations. Ensure `WWW-Authenticate` headers are not being stripped or renamed. For AWS API Gateway, a custom authorizer might be needed as API Gateway can rename headers.","cause":"Deployment environments or reverse proxies (like Nginx, AWS API Gateway) might interfere with HTTP Basic Auth headers, such as renaming `WWW-Authenticate` or not passing the `Authorization` header correctly, preventing the browser from prompting for credentials or the app from receiving them.","error":"dash_auth not working when app is deployed (e.g., on Google Cloud, Heroku, AWS Lambda behind API Gateway)"}]}