Streamlit-Authenticator: login and user management for Streamlit apps backed by a YAML file

Adding authentication to Streamlit without a separate service or database

Streamlit's execution model has no concept of a logged-in user. Every script re-run starts without session state, and there is no middleware layer that restricts which user can trigger a re-run or reads credentials from a session store. Streamlit-Authenticator fills that gap for developers who want password protection on a Streamlit application without standing up a separate identity service or a relational database.

Credentials live in a YAML file on the filesystem, and the Authenticate object reads that file at startup, renders login and user management widgets as Streamlit components, and writes changes back to the same file when users register, reset passwords or update their profiles. This file-based approach suits an internal tool or a small proof-of-concept where one person administers accounts by editing a text file and the application runs on a single server.

Four top-level blocks in the YAML config and what each one controls

Four top-level keys make up the config file: credentials, cookie, oauth2 and pre-authorized. Under credentials sits a usernames map where each entry holds email, first_name, last_name, password and an optional roles list. Three role strings appear in the config example: admin, editor and viewer. Those role values carry no documented behavior inside the package; the application code decides what they mean.

Two fields per entry are managed automatically at runtime. A failed_login_attempts counter increments on each failed login, and a logged_in flag flips when a session starts or ends. Both should be initialised to their defaults in the YAML file; the package takes ownership of them after the first run.

Cookie behavior is controlled by three fields: a name string, a key string, and expiry_days as a float. Setting expiry_days to 0 disables re-authentication cookies entirely, so every new browser session requires a password.

The oauth2 block is optional. Google and Microsoft are the two documented providers: Google requires client_id, client_secret and redirect_uri, while Microsoft requires those three plus a tenant_id. A pre-authorized list holds email addresses whose owners may register through the register_user widget without a prior addition to the credentials block.

Installing the package and constructing the Authenticate object

Streamlit-Authenticator is published on PyPI.

pip install streamlit-authenticator

The setup.py file sets a minimum of Python 3.6. Seven declared dependencies carry minimum versions: bcrypt at 3.1.7, captcha at 0.5.0, cryptography at 42.0.5, extra-streamlit-components at 0.1.70, PyJWT at 2.3.0, PyYAML at 5.3.1, and streamlit at 1.37.0.

With the config YAML in place, load it and pass it to the Authenticate constructor.

import yaml
from yaml.loader import SafeLoader

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

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

The constructor takes four positional arguments: the credentials dictionary, the cookie name, the signing key and the expiry days value. By default the object hashes plain text passwords in the credentials on first load, adding time at startup proportional to the number of users. For large credential sets, the documented approach is to pre-hash once by calling stauth.Hasher.hash_passwords(config['credentials']) before the first run, then construct with auto_hash=False on subsequent startups.

Re-authentication cookies, the expiry_days setting and the key placeholder

After a successful login, the package stores a signed cookie in the browser. On the next visit within the expiry window, the app reads that cookie and restores the session without prompting for a password. The cookie_key parameter specifies the string used to hash the signature of the re-authentication cookie, as the constructor's documented parameters explain.

The example config marks the key field with a comment placeholder: key: # To be filled with any string. That placeholder must be replaced before deployment, and the documentation gives no minimum length or format requirement for the key value.

Setting expiry_days to 0 disables the cookie mechanism entirely, making every session require a fresh login. That option is documented explicitly for situations where persistent sessions are not appropriate.

The experimental_guest_login button and what OAuth2 setup requires

The table of contents labels section 6 as a new addition, and the config documentation refers to it by the method name experimental_guest_login. That method name is a signal from the author that the interface may change between versions without a deprecation period.

Configuring this feature requires filling in the oauth2 block with credentials obtained from each provider's developer console. Google and Microsoft are the two documented providers. The project links to Google's OAuth2 setup guide at developers.google.com/identity/protocols/oauth2 and to Microsoft's app registration guide at learn.microsoft.com/en-us/graph/auth-register-app-v2, but neither registration process is reproduced in the package documentation itself.

The full parameter set is covered in the API reference at streamlit-authenticator.readthedocs.io/en/stable/. What the package does with the token the provider returns after authentication, and whether a guest user's record lands in the credentials YAML alongside password-based users, is not addressed in the repository's README.

Two-factor authentication and the API key were both phased out

The table of contents includes section 8 under the heading 'Enabling two factor authentication (phased out)'. The Quickstart carries the entry 'Subscribe to receive a free API key (phased out)'. Both entries remain in the current documentation but the functionality they describe is no longer available.

The YAML config schema still contains an api_key field, shown in the example as 'api_key: # Optional - (phased out)'. Its presence in the schema alongside the active credentials, cookie and oauth2 blocks is easy to miss when reading an older tutorial that treats 2FA as a live feature.

Password login against the YAML credentials file and the experimental_guest_login route through a configured OAuth2 provider are the two authentication paths the current documentation covers. No replacement for the removed two-factor capability is mentioned in the repository.

The config update requirement and what file-based credential storage means for deployment

Updating the config file after every widget interaction is a requirement stated prominently across multiple README sections. Registration, password reset, username recovery and profile updates each modify the in-memory credentials dictionary, and the application code must write that dictionary back to the YAML file after each such call. Failing to do so leaves the stored state out of sync with what happened during the session, so a registration that appeared to succeed would be lost on the next app restart.

No database adapter appears in the dependency list, and there is no connection string in the config schema. Credentials remain in the YAML file for as long as the application runs on that server, with no documented migration path to a different backend if usage grows beyond what a flat file can handle.

The last push to the repository was on 2026-07-01, and the most recent tagged release is v0.4.2 from 2025-03-01, a gap of sixteen months during which commits reached the repository without producing a new packaged version on PyPI.

Editorial conclusion

This package suits a Streamlit app that a small team uses internally, where a YAML file is an acceptable credential store. It is the wrong choice for a project that needs two-factor authentication (listed as phased out in the current version) or that relies on the OAuth2 guest login (still labeled experimental). Before deploying, replace the cookie key placeholder in the config, read the requirement to re-save the YAML after every widget call, and check whether to pre-hash credentials with Hasher.hash_passwords before setting auto_hash=False.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mkhorasani/Streamlit-Authenticator on GitHub
4. README
5. Releases