Mastering User Authentication in Streamlit with `streamlit-authenticator`: A Comprehensive Guide
Let's linked LinkedIn

Mastering User Authentication in Streamlit with streamlit-authenticator: A Comprehensive Guide

Building secure and user-friendly web applications is a fundamental goal for developers. When using Streamlit—a popular framework for creating interactive Python applications—one critical aspect to address is user authentication. Enter streamlit-authenticator, a robust library designed to simplify the authentication process in Streamlit apps.

However, integrating streamlit-authenticator isn’t always straightforward. Developers often encounter challenges, from hashing passwords correctly to configuring the authenticator’s parameters properly. This guide aims to walk you through the process, highlighting common pitfalls and providing clear solutions to ensure a smooth setup.

Table of Contents

Introduction to streamlit-authenticator

streamlit-authenticator is a Streamlit component that provides a simple yet secure way to handle user authentication in your applications. It supports features like:

  • Login and Logout: Basic user session management.
  • Password Hashing: Securely store hashed passwords instead of plain text.
  • User Registration: Allow new users to sign up.
  • Password Reset: Enable users to reset forgotten passwords.
  • OAuth2 Integration: Support for third-party authentication providers like Google and Microsoft.

By leveraging streamlit-authenticator, you can focus more on building your app’s functionality without getting bogged down by the complexities of implementing secure authentication from scratch.

Prerequisites

Before diving into the setup, ensure you have the following:

  • Python 3.7 or higher: Streamlit and its libraries require Python 3.7+.
  • Streamlit Installed: If not, install it using pip install streamlit.
  • Virtual Environment (Recommended): To manage dependencies cleanly.

Step 1: Install Required Packages

Begin by installing the necessary packages in your virtual environment. Open your terminal and run:

pip install streamlit streamlit-authenticator bcrypt pyyaml

Package Breakdown:

  • streamlit: The core framework for building the web app.
  • streamlit-authenticator: Handles authentication processes.
  • bcrypt: Provides secure password hashing.
  • pyyaml: Facilitates reading and writing YAML configuration files.

Step 2: Hashing Plain-Text Passwords

Storing plain-text passwords is a significant security risk. Instead, we’ll hash passwords using bcrypt via streamlit-authenticator before storing them in our configuration.

Creating the Hashing Script

  1. Create a File Named hash_passwords.py:

    # hash_passwords.py
import streamlit_authenticator as stauth

def hash_passwords(passwords):
    """
    Hash a list of plain-text passwords.

    Parameters:
    - passwords (list): List of plain-text passwords.

    Returns:
    - list: List of hashed passwords.
    """
    hashed = []
    for pwd in passwords:
        # The 'hash' method is a class method that returns a single hashed password
        hashed_password = stauth.Hasher.hash(pwd)
        hashed.append(hashed_password)
    return hashed

if __name__ == "__main__":
    # Define plain-text passwords
    plain_passwords = ["admin123", "user123"]

    # Hash the passwords
    hashed_passwords = hash_passwords(plain_passwords)

    # Display hashed passwords
    print("Hashed Passwords:")
    for pwd in hashed_passwords:
        print(pwd)

  2. Run the Hashing Script:

    python hash_passwords.py

    Expected Output:

    Hashed Passwords:
$2b$12$scGPpi/4KrRV6vDuFJ9tuuCIQaHsU.L1NXoI88ydq8YAasrMpPpyS
$2b$12$Dy..X6K/D8Fm8AXyQoP2oe3qL6UOxHnVaIkwYsNMH4decxl1UMYxi

    Note: These hashes are examples. Your output will generate unique hashes each time due to the salting process inherent in bcrypt.

Why This Approach?

  • Security: Hashing ensures that even if your configuration file is compromised, attackers cannot retrieve the original passwords.
  • Simplicity: Using a separate script keeps your main application code clean and focused on functionality rather than security.

Step 3: Setting Up the Configuration File (config.yaml)

We’ll store user credentials and cookie settings in a YAML configuration file. This separation enhances security and makes it easier to manage user data.

  1. Create a File Named config.yaml:

    credentials:
  usernames:
    admin:
      email: admin@example.com
      name: Admin User
      password: "$2b$12$scGPpi/4KrRV6vDuFJ9tuuCIQaHsU.L1NXoI88ydq8YAasrMpPpyS"  # Replace with your first hash
    user:
      email: user@example.com
      name: Regular User
      password: "$2b$12$Dy..X6K/D8Fm8AXyQoP2oe3qL6UOxHnVaIkwYsNMH4decxl1UMYxi"  # Replace with your second hash

cookie:
  name: auth_cookie
  key: "a3f1c4e5d6b7a8c9d0e1f2a3b4c5d6e7f8g9h0i1j2k3l4m5n6o7p8q9r0s1t2u3"  # Replace with your secure random key
  expiry_days: 1

    Important:

    • Replace Hashed Passwords: Use the hashes generated from hash_passwords.py.
    • Secure cookie.key: Generate a strong, random string for the key. This key is crucial for securing session cookies.

  2. Generating a Secure cookie.key:

    Use Python to generate a secure key:

    import os

secure_key = os.urandom(24).hex()
print(secure_key)

    Example Output:

    a3f1c4e5d6b7a8c9d0e1f2a3b4c5d6e7f8g9h0i1j2k3l4m5n6o7p8q9r0s1t2u3
    • Usage: Replace the placeholder in config.yaml with this generated key.
    • Security Tip: Do not expose this key in public repositories or insecure environments.

  3. Secure Your Configuration File:

    • Exclude from Version Control: Add config.yaml to .gitignore to prevent accidental commits.
    echo "config.yaml" >> .gitignore
    • Environment Variables (Optional but Recommended): For enhanced security, consider loading sensitive information like cookie.key from environment variables.

Step 4: Developing the Streamlit App (auth_app.py)

Now, we’ll create the main Streamlit application that utilizes the streamlit-authenticator library for user authentication.

  1. Create a File Named auth_app.py:

    # auth_app.py
import streamlit as st
import streamlit_authenticator as stauth
import yaml
from yaml.loader import SafeLoader
import os

def load_config(path):
    with open(path) as file:
        return yaml.load(file, Loader=SafeLoader)

# Load configuration
config = load_config("config.yaml")

# Optionally, override cookie_key with environment variable if set
cookie_key = os.getenv('COOKIE_KEY', config['cookie']['key'])

# Initialize the authenticator
authenticator = stauth.Authenticate(
    credentials=config["credentials"],
    cookie_name=config["cookie"]["name"],
    cookie_key=cookie_key,  # Use environment variable if available
    cookie_expiry_days=config["cookie"]["expiry_days"]
)

# Render the login widget
name, authentication_status, username = authenticator.login(
    location="main", 
    key="LoginForm"
)

if authentication_status:
    # If authenticated, display logout button and welcome message
    authenticator.logout("Logout", "sidebar")
    st.sidebar.success("You have successfully logged out.")
    st.write(f"## Welcome, *{name}*!")
    st.write("### This is your private dashboard.")
    # Add more private content here

elif authentication_status == False:
    st.error("Username/password is incorrect.")

elif authentication_status is None:
    st.warning("Please enter your username and password.")

    Key Points:

    • Loading Configuration: The load_config function reads config.yaml.
    • Authenticator Initialization: Passes credentials and cookie settings to Authenticate.
    • Login Widget: Renders the login form in the main area (location="main") with a unique key (key="LoginForm").
    • Handling Authentication Status:
      • Success: Shows a welcome message and a logout button in the sidebar.
      • Failure: Displays an error message.
      • No Attempt: Prompts the user to log in.

  2. Understanding the login() Method:

    The login() method’s parameters are crucial. The first positional argument is location, which must be one of 'main', 'sidebar', or 'unrendered'. Passing incorrect values leads to errors.

    name, authentication_status, username = authenticator.login(
    location="main", 
    key="LoginForm"
)
    • location="main": Places the login widget in the main body of the app.
    • key="LoginForm": Assigns a unique key to avoid widget conflicts.

Step 5: Running and Testing the App

  1. Ensure Configuration is Correct:

    • Verify that config.yaml contains the correct hashed passwords and a secure cookie.key.

  2. Run the Streamlit App:

    streamlit run auth_app.py

  3. Access the App:

    • Open your browser and navigate to the URL provided in the terminal, typically http://localhost:8501.

  4. Test Login Credentials:

    • Admin:
      • Username: admin
      • Password: admin123
    • User:
      • Username: user
      • Password: user123

    Upon successful login, you should see a personalized welcome message and access to the private dashboard. Logging out will redirect you back to the login screen.

Common Errors and Troubleshooting

Even with a step-by-step guide, issues can arise. Below are common errors users encounter when setting up streamlit-authenticator and how to resolve them.

1. TypeError: Hasher.hash_passwords() missing 1 required positional argument: 'credentials'

Cause:
Attempting to use the hash_passwords() method incorrectly. This method expects a credentials dictionary, not a list of passwords.

Solution:
Use the hash_list() method instead when dealing with a list of passwords.

Corrected Hashing Script:

# hash_passwords.py
import streamlit_authenticator as stauth

def hash_passwords(passwords):
    """
    Hash a list of plain-text passwords.

    Parameters:
    - passwords (list): List of plain-text passwords.

    Returns:
    - list: List of hashed passwords.
    """
    hashed = []
    for pwd in passwords:
        # The 'hash' method is a class method that returns a single hashed password
        hashed_password = stauth.Hasher.hash(pwd)
        hashed.append(hashed_password)
    return hashed

if __name__ == "__main__":
    plain_passwords = ["admin123", "user123"]
    hashed_passwords = hash_passwords(plain_passwords)

    print("Hashed Passwords:")
    for pwd in hashed_passwords:
        print(pwd)

Run the Corrected Script:

python hash_passwords.py

2. ValueError: Location must be one of 'main' or 'sidebar' or 'unrendered'

Cause:
Passing incorrect positional arguments to the login() method, leading the method to interpret values incorrectly.

Solution:
Ensure that you pass parameters correctly, using keyword arguments where necessary. The first argument should be location, followed by other optional parameters.

Correct Usage:

name, authentication_status, username = authenticator.login(
    location="main", 
    key="LoginForm"
)

Avoid Incorrect Calls:

# Incorrect: Passing 'Login' as location
name, authentication_status, username = authenticator.login("Login", "main")

3. TypeError: cannot unpack non-iterable NoneType object

Cause:
The login() method returned None instead of the expected tuple, possibly due to version mismatches or incorrect method usage.

Solution:

  • Check Library Version: Ensure you have the latest version of streamlit-authenticator.

    pip show streamlit-authenticator

  • Upgrade if Necessary:

    pip install --upgrade streamlit-authenticator

  • Use Session State (Alternative Approach): If the method returns None, retrieve authentication details from st.session_state.

    Modified auth_app.py:

    # auth_app.py
import streamlit as st
import streamlit_authenticator as stauth
import yaml
from yaml.loader import SafeLoader
import os

def load_config(path):
    with open(path) as file:
        return yaml.load(file, Loader=SafeLoader)

config = load_config("config.yaml")

cookie_key = os.getenv('COOKIE_KEY', config['cookie']['key'])

authenticator = stauth.Authenticate(
    credentials=config["credentials"],
    cookie_name=config["cookie"]["name"],
    cookie_key=cookie_key,
    cookie_expiry_days=config["cookie"]["expiry_days"]
)

# Call login() but don't try to unpack
authenticator.login(location="main", key="LoginForm")

# Now read from session state
name = st.session_state.get("name", None)
authentication_status = st.session_state.get("authentication_status", None)
username = st.session_state.get("username", None)

if authentication_status:
    authenticator.logout("Logout", "sidebar")
    st.sidebar.success("You have successfully logged out.")
    st.write(f"Welcome, *{name}*!")
    st.write("This is your private dashboard.")

elif authentication_status == False:
    st.error("Username/password is incorrect.")

elif authentication_status is None:
    st.warning("Please enter your username and password.")

    Explanation:

    • Without Unpacking: Call login() without trying to unpack its return value.
    • Session State Retrieval: Access authentication details from st.session_state.

4. AttributeError: type object 'Hasher' has no attribute 'hash'

Cause:
Using incorrect method names based on the installed library version.

Solution:
Ensure you’re using the correct method names as per your library’s version. Refer to the official documentation or use alternative methods like hash_list() or looping through hash().

Best Practices for Secure Authentication

  1. Never Store Plain-Text Passwords:

    • Always hash passwords using strong algorithms like bcrypt before storage.

  2. Secure cookie.key:

    • Use a long, random string for cookie.key to enhance security.
    • Consider using environment variables to store sensitive keys.

  3. Protect Configuration Files:

    • Exclude config.yaml from version control (.gitignore) to prevent credential leaks.

  4. Regularly Update Dependencies:

    • Keep your packages updated to benefit from security patches and new features.

  5. Use HTTPS in Production:

    • Ensure your Streamlit app is served over HTTPS to protect data in transit.

  6. Implement Role-Based Access Control (RBAC):

    • Assign roles to users (e.g., admin, user) to control access to different parts of your app.

  7. Monitor and Log Authentication Attempts:

    • Keep track of login attempts to detect and prevent unauthorized access.

Advanced Features

Once you’ve mastered the basics, consider integrating the following advanced features:

1. User Registration and Management

Allow users to register, update their details, or reset their passwords directly from the app.

Example:

if authentication_status:
    if authenticator.register_user('Register User', 'main'):
        st.success('User registered successfully')
        # Optionally, save updated credentials to config.yaml

2. OAuth2 Integration for Guest Login

Enable users to log in using third-party providers like Google or Microsoft.

Example:

if authentication_status:
    authenticator.experimental_guest_login(
        button_name='Login with Google',
        provider='google',
        oauth2=config.get('oauth2')  # Ensure 'oauth2' is defined in config.yaml
    )

3. Password Reset Functionality

Allow users to reset forgotten passwords securely.

Example:

if authentication_status:
    if authenticator.reset_password(username, 'main'):
        st.success('Password reset successfully')
        # Update credentials file as needed

4. Role-Based Access Control (RBAC)

Assign roles to users and control access based on these roles.

Example:

credentials:
  usernames:
    admin:
      email: admin@example.com
      name: Admin User
      password: "$2b$12$..."
      roles:
        - admin
        - editor
    user:
      email: user@example.com
      name: Regular User
      password: "$2b$12$..."
      roles:
        - viewer

In auth_app.py:

if authentication_status:
    authenticator.logout("Logout", "sidebar")
    st.sidebar.success("You have successfully logged out.")
    st.write(f"## Welcome, *{name}*!")
    st.write("### This is your private dashboard.")

    user_roles = config['credentials']['usernames'][username].get('roles', [])

    if 'admin' in user_roles:
        st.write("### Admin Panel")
        # Add admin-specific content
    elif 'viewer' in user_roles:
        st.write("### Viewer Section")
        # Add viewer-specific content

Conclusion

Implementing user authentication in Streamlit using streamlit-authenticator is a powerful way to secure your applications and manage user access effectively. By following this guide, you should be able to:

  1. Hash passwords securely to protect user credentials.
  2. Configure your authentication settings using a YAML file.
  3. Develop and run a Streamlit app with robust authentication.
  4. Troubleshoot common errors to ensure a smooth setup.

Remember, security is paramount. Always adhere to best practices to safeguard your application and its users. As you become more comfortable with the basics, explore advanced features like OAuth2 integration, user registration, and role-based access control to enhance your app’s functionality and security further.

Happy coding!

Tags: Streamlit  Authentication  Streamlit-Authenticator  Bcrypt  YAML  Python  Tutorial