Streamlit-Authenticator

A secure authentication module to manage user access in a Streamlit application

Table of Contents

• Quickstart
• Installation
• Creating a config file
• Setup
• Creating a login widget
• Creating a guest login widget 🚀 NEW
• Authenticating users
• Enabling two factor authentication
• Creating a reset password widget
• Creating a new user registration widget
• Creating a forgot password widget
• Creating a forgot username widget
• Creating an update user details widget
• Updating the config file
• License

1. Quickstart

• Subscribe to receive a free API key (phased out).
• Check out the demo app.
• Feel free to visit the API reference.
• And finally follow the tutorial below.

2. Installation

Streamlit-Authenticator is distributed via PyPI:

pip install streamlit-authenticator

Using Streamlit-Authenticator is as simple as importing the module and calling it to verify your user's credentials.

import streamlit as st
import streamlit_authenticator as stauth

3. Creating a config file

• Create a YAML config file and add to it your user's credentials: including username, email, first name, last name, and password (plain text passwords will be hashed automatically).
• Enter a name, random key, and number of days to expiry, for a re-authentication cookie that will be stored on the client's browser to enable password-less re-authentication. If you do not require re-authentication, you may set the number of days to expiry to 0.
• Define an optional list of pre-authorized emails of users who are allowed to register and add their credentials to the config file using the register_user widget.
• Add the optional configuration parameters for OAuth2 if you wish to use the experimental_guest_login button.
• Please remember to update the config file (as shown in step 14) whenever the contents are modified or after using any of the widgets or buttons.

cookie:
  expiry_days: 30
  key: # To be filled with any string
  name: # To be filled with any string
credentials:
  usernames:
    jsmith:
      email: jsmith@gmail.com
      failed_login_attempts: 0 # Will be managed automatically
      first_name: John
      last_name: Smith
      logged_in: False # Will be managed automatically
      password: abc # Will be hashed automatically
      roles: # Optional
      - admin
      - editor
      - viewer
    rbriggs:
      email: rbriggs@gmail.com
      failed_login_attempts: 0 # Will be managed automatically
      first_name: Rebecca
      last_name: Briggs
      logged_in: False # Will be managed automatically
      password: def # Will be hashed automatically
      roles: # Optional
      - viewer
oauth2: # Optional
  google: # Follow instructions: https://developers.google.com/identity/protocols/oauth2
    client_id: # To be filled
    client_secret: # To be filled
    redirect_uri: # URL to redirect to after OAuth2 authentication
  microsoft: # Follow instructions: https://learn.microsoft.com/en-us/graph/auth-register-app-v2
    client_id: # To be filled
    client_secret: # To be filled
    redirect_uri: # URL to redirect to after OAuth2 authentication
    tenant_id: # To be filled
pre-authorized: # Optional
  emails:
  - melsby@gmail.com
api_key: # Optional - (phased out)

• Please note that the 'failed_login_attempts' and 'logged_in' fields corresponding to each user's number of failed login attempts and log-in status in the credentials will be added and managed automatically.

4. Setup

• Subsequently import the config file into your script and create an authentication object.

import yaml
from yaml.loader import SafeLoader

with open('../config.yaml') as file:
    config = yaml.load(file, Loader=SafeLoader)

# Pre-hashing all plain text passwords once
# stauth.Hasher.hash_passwords(config['credentials'])

authenticator = stauth.Authenticate(
    config['credentials'],
    config['cookie']['name'],
    config['cookie']['key'],
    config['cookie']['expiry_days']
)

• Plain text passwords will be hashed automatically by default, however, for a large number of users it is recommended to pre-hash the passwords in the credentials using the Hasher.hash_passwords function.
• If you choose to pre-hash the passwords, please set the auto_hash parameter in the Authenticate class to False.

Hasher.hash_passwords

Parameters:

• credentials: dict
  • The credentials dict with plain text passwords.

Returns:

• dict
  • The credentials dict with hashed passwords.

Authenticate

Parameters:

• credentials: dict, str
  • Dictionary with the usernames, names, passwords, and emails, and other user data, or path pointing to the location of the config file.
• cookie_name: str
  • Specifies the name of the re-authentication cookie stored on the client's browser for password-less re-authentication.
• cookie_key: str
  • Specifies the key that will be used to hash the signature of the re-authentication cookie.
• cookie_expiry_days: float, default 30.0
  • Specifies the number of days before the re-authentication cookie automatically expires on the client's browser.
• validator: Validator, optional, default None
  • Provides a validator object that will check the validity of the username, name, and email fields.
• auto_hash: bool, default True
  • Automatic hashing requirement for passwords, True: plain text passwords will be hashed automatically, False: plain text passwords will not be hashed automatically.
• api_key: str, optional, default None
  • API key used to connect to the cloud server to send two factor authorization codes, reset passwords, and forgotten usernames to the user by email.
• **kwargs: dict, optional
  • Arguments to pass to the Authenticate class.

• Please remember to pass the authenticator object to each and every page in a multi-page application as a session state variable.

5. Creating a login widget

• You can render the login widget as follows.

try:
    authenticator.login()
except Exception as e:
    st.error(e)

Authenticate.login

Parameters:

• location: str, {'main', 'sidebar', 'unrendered'}, default 'main'
  • Specifies the location of the login widget.
• max_concurrent_users: int, optional, default None
  • Limits the number of concurrent users. If not specified there will be no limit to the number of concurrently logged in users.
• max_login_attempts: int, optional, default None
  • Limits the number of failed login attempts. If not specified there will be no limit to the number of failed login attempts.
• fields: dict, optional, default {'Form name':'Login', 'Username':'Username', 'Password':'Password', 'Login':'Login', 'Captcha':'Captcha'}
  • Customizes the text of headers, buttons and other fields.
• captcha: bool, default False
  • Specifies the captcha requirement for the login widget, True: captcha required, False: captcha removed.
• single_session: bool, default False
  • Disables the ability for the same user to log in multiple sessions, True: single session allowed, False: multiple sessions allowed.
• clear_on_submit: bool, default False
  • Specifies the clear on submit setting, True: clears inputs on submit, False: keeps inputs on submit.
• key: str, default 'Login'
  • Unique key provided to widget to avoid duplicate WidgetID errors.
• callback: callable, optional, default None
  • Callback function that will be invoked on form submission with a dict as a parameter.

• Please remember to re-invoke an 'unrendered' login widget on each and every page in a multi-page application.
• Please remember to update the config file (as shown in step 14) after you use this widget.

6. Creating a guest login widget

• You may use the experimental_guest_login button to log in non-registered users with their Google or Microsoft accounts using OAuth2.
• To create the client ID and client secret parameters for Google OAuth2 please refer to Google's documentation.
• To create the client ID, client secret, and tenant ID parameters for Microsoft OAuth2 please refer to Microsoft's documentation.
• Once you have created the OAuth2 configuration parameters, add them to the config file as shown in step 3.

try:
    authenticator.experimental_guest_login('Login with Google',
                                           provider='google',
                                           oauth2=config['oauth2'])
    authenticator.experimental_guest_login('Login with Microsoft',
                                           provider='microsoft',
                                           oauth2=config['oauth2'])
except Exception as e:
    st.error(e)

Authenticate.experimental_guest_login

Parameters:

• button_name: str, default 'Guest login'
  • Rendered name of the guest login button.
• location: str, {'main', 'sidebar'}, default 'main'
  • Specifies the location of the guest login button.
• provider: str, {'google', 'microsoft'}, default 'google'
  • Selection for OAuth2 provider, Google or Microsoft.
• oauth2: dict, optional, default None
  • Configuration parameters to implement an OAuth2 authentication.
• max_concurrent_users: int, optional, default None
  • Limits the number of concurrent users. If not specified there will be no limit to the number of concurrently logged in users.
• single_session: bool, default False
  • Disables the ability for the same user to log in multiple sessions, True: single session allowed, False: multiple sessions allowed.
• roles: list, optional, default None
  • User roles for guest users.
• **use_contai