# Streamlit-Authenticator-Ru [](https://pepy.tech/project/streamlit-authenticator-ru)
<!--- [](https://www.buymeacoffee.com/khorasani) --->
**A secure authentication module to validate user credentials in a Streamlit application.**
<a href="https://amzn.to/3eQwEEn"><img src="https://raw.githubusercontent.com/mkhorasani/streamlit_authenticator_test/main/Web%20App%20Web%20Dev%20with%20Streamlit%20-%20Cover.png" width="300" height="450">
###### _To learn more please refer to my book [Web Application Development with Streamlit](https://amzn.to/3eQwEEn)._
## Installation
Streamlit-Authenticator is distributed via [PyPI](https://pypi.org/project/streamlit-authenticator-ru/):
```python
pip install streamlit-authenticator-ru
```
## Example
Using Streamlit-Authenticator is as simple as importing the module and calling it to verify your predefined users' credentials.
```python
import streamlit as st
import streamlit_authenticator_ru as stauth
```
### 1. Hashing passwords
* Initially create a YAML configuration file and define your users' credentials (names, usernames, and plain text passwords). In addition, enter a name, random key, and number of days to expiry for a JWT cookie that will be stored on the client's browser to enable passwordless reauthentication. If you do not require reauthentication, you may set the number of days to expiry to 0. Finally, define a list of preauthorized emails of users who can register and add their credentials to the configuration file with the use of the **register_user** widget.
```python
credentials:
usernames:
jsmith:
email: jsmith@gmail.com
name: John Smith
password: abc # To be replaced with hashed password
rbriggs:
email: rbriggs@gmail.com
name: Rebecca Briggs
password: def # To be replaced with hashed password
cookie:
expiry_days: 30
key: some_signature_key # Must be string
name: some_cookie_name
preauthorized:
emails:
- melsby@gmail.com
```
* Then use the Hasher module to convert the plain text passwords into hashed passwords.
```python
hashed_passwords = stauth.Hasher(['abc', 'def']).generate()
```
* Finally replace the plain text passwords in the configuration file with the hashed passwords.
### 2. Creating a login widget
* Subsequently import the configuration file into your script and create an authentication object.
```python
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'],
config['preauthorized']
)
```
* Then finally render the login module as follows. Here you will need to provide a name for the login form, and specify where the form should be located i.e. main body or sidebar (will default to main body).
```python
name, authentication_status, username = authenticator.login('Login', 'main')
```
### 3. Authenticating users
* You can then use the returned name and authentication status to allow your verified user to proceed to any restricted content. In addition, you have the ability to add an optional logout button at any location on your main body or sidebar (will default to main body). The optional **key** parameter for the logout widget should be used with multipage applications to prevent Streamlit from throwing duplicate key errors.
```python
if authentication_status:
authenticator.logout('Logout', 'main', key='unique_key')
st.write(f'Welcome *{name}*')
st.title('Some content')
elif authentication_status is False:
st.error('Username/password is incorrect')
elif authentication_status is None:
st.warning('Please enter your username and password')
```
* Should you require access to the persistent name, authentication status, and username variables, you may retrieve them through Streamlit's session state using **st.session_state["name"]**, **st.session_state["authentication_status"]**, and **st.session_state["username"]**. This way you can use Streamlit-Authenticator to authenticate users across multiple pages.
```python
if st.session_state["authentication_status"]:
authenticator.logout('Logout', 'main', key='unique_key')
st.write(f'Welcome *{st.session_state["name"]}*')
st.title('Some content')
elif st.session_state["authentication_status"] is False:
st.error('Username/password is incorrect')
elif st.session_state["authentication_status"] is None:
st.warning('Please enter your username and password')
```
* Or prompt an unverified user to enter a correct username and password.
* Please note that logging out will revert the authentication status to **None** and will delete the associated reauthentication cookie as well.
### 4. Creating a password reset widget
* You may use the **reset_password** widget to allow a logged in user to modify their password as shown below.
```python
if authentication_status:
try:
if authenticator.reset_password(username, 'Reset password'):
st.success('Password modified successfully')
except Exception as e:
st.error(e)
```
_Please remember to update the config file (as shown in step 9) after you use this widget._
### 5. Creating a new user registration widget
* You may use the **register_user** widget to allow a user to sign up to your application as shown below. If you require the user to be preauthorized, set the **preauthorization** argument to True and add their email to the **preauthorized** list in the configuration file. Once they have registered, their email will be automatically removed from the **preauthorized** list in the configuration file. Alternatively, to allow anyone to sign up, set the **preauthorization** argument to False.
```python
try:
if authenticator.register_user('Register user', preauthorization=False):
st.success('User registered successfully')
except Exception as e:
st.error(e)
```
_Please remember to update the config file (as shown in step 9) after you use this widget._
### 6. Creating a forgot password widget
* You may use the **forgot_password** widget to allow a user to generate a new random password. This password will be automatically hashed and saved in the configuration file. The widget will return the username, email, and new random password of the user which should then be transferred to them securely.
```python
try:
username_forgot_pw, email_forgot_password, random_password = authenticator.forgot_password('Forgot password')
if username_forgot_pw:
st.success('New password sent securely')
# Random password to be transferred to user securely
else:
st.error('Username not found')
except Exception as e:
st.error(e)
```
_Please remember to update the config file (as shown in step 9) after you use this widget._
### 7. Creating a forgot username widget
* You may use the **forgot_username** widget to allow a user to retrieve their forgotten username. The widget will return the username and email of the user which should then be transferred to them securely.
```python
try:
username_forgot_username, email_forgot_username = authenticator.forgot_username('Forgot username')
if username_forgot_username:
st.success('Username sent securely')
# Username to be transferred to user securely
else:
st.error('Email not found')
except Exception as e:
st.error(e)
```
### 8. Creating an update user details widget
* You may use the **update_user_details** widget to allow a logged in user to update their name and/or email. The widget will automatically save the updated details in both the configuration file and reauthentication cookie.
```python
if authentication_status:
try:
if authenticator.update_user_details(username, 'Update user details'):
st.success('Entries updated successfully')
except Exception as e:
st.error(e)
```
_Please remember to update the config file (as shown in step 9) after you use this widget._
### 9. Updating the configuration file
* Please ensure that the configuration file is resaved anytime the credentials are updated or whenever the **reset_password**, **register_user**, **forgot_password**, or **update_user_details** widgets are used.
```python
with open('../config.yaml', 'w') as file:
yaml.dump(config, file, default_flow_style=False)
```
## Credits
- Mohamed Abdou for the highly versatile cookie manager in [Extra-Streamlit-Components](https://github.com/Mohamed-512/Extra-Streamlit-Components).
Raw data
{
"_id": null,
"home_page": "https://github.com/RuslanLat/Streamlit-Authenticator-Ru",
"name": "streamlit-authenticator-ru",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "Python,Streamlit,Authentication,Components",
"author": "Mohammad Khorasani",
"author_email": "khorasani.mohammad@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/40/19/1b8e43b22f0300717f4b8cc6b54b11c9f5af1c3e0bc04285734e0b0f2add/streamlit-authenticator_ru-0.2.2.tar.gz",
"platform": null,
"description": "# Streamlit-Authenticator-Ru [](https://pepy.tech/project/streamlit-authenticator-ru)\r\n<!--- [](https://www.buymeacoffee.com/khorasani) --->\r\n**A secure authentication module to validate user credentials in a Streamlit application.**\r\n\r\n<a href=\"https://amzn.to/3eQwEEn\"><img src=\"https://raw.githubusercontent.com/mkhorasani/streamlit_authenticator_test/main/Web%20App%20Web%20Dev%20with%20Streamlit%20-%20Cover.png\" width=\"300\" height=\"450\">\r\n\r\n###### _To learn more please refer to my book [Web Application Development with Streamlit](https://amzn.to/3eQwEEn)._\r\n\r\n\r\n## Installation\r\n\r\nStreamlit-Authenticator is distributed via [PyPI](https://pypi.org/project/streamlit-authenticator-ru/):\r\n\r\n```python\r\npip install streamlit-authenticator-ru\r\n```\r\n\r\n## Example\r\n\r\nUsing Streamlit-Authenticator is as simple as importing the module and calling it to verify your predefined users' credentials.\r\n\r\n```python\r\nimport streamlit as st\r\nimport streamlit_authenticator_ru as stauth\r\n```\r\n\r\n### 1. Hashing passwords\r\n\r\n* Initially create a YAML configuration file and define your users' credentials (names, usernames, and plain text passwords). In addition, enter a name, random key, and number of days to expiry for a JWT cookie that will be stored on the client's browser to enable passwordless reauthentication. If you do not require reauthentication, you may set the number of days to expiry to 0. Finally, define a list of preauthorized emails of users who can register and add their credentials to the configuration file with the use of the **register_user** widget.\r\n\r\n```python\r\ncredentials:\r\n usernames:\r\n jsmith:\r\n email: jsmith@gmail.com\r\n name: John Smith\r\n password: abc # To be replaced with hashed password\r\n rbriggs:\r\n email: rbriggs@gmail.com\r\n name: Rebecca Briggs\r\n password: def # To be replaced with hashed password\r\ncookie:\r\n expiry_days: 30\r\n key: some_signature_key # Must be string\r\n name: some_cookie_name\r\npreauthorized:\r\n emails:\r\n - melsby@gmail.com\r\n```\r\n\r\n* Then use the Hasher module to convert the plain text passwords into hashed passwords.\r\n\r\n```python\r\nhashed_passwords = stauth.Hasher(['abc', 'def']).generate()\r\n```\r\n\r\n* Finally replace the plain text passwords in the configuration file with the hashed passwords.\r\n\r\n### 2. Creating a login widget\r\n\r\n* Subsequently import the configuration file into your script and create an authentication object.\r\n\r\n```python\r\nimport yaml\r\nfrom yaml.loader import SafeLoader\r\n\r\nwith open('../config.yaml') as file:\r\n config = yaml.load(file, Loader=SafeLoader)\r\n\r\nauthenticator = stauth.Authenticate(\r\n config['credentials'],\r\n config['cookie']['name'],\r\n config['cookie']['key'],\r\n config['cookie']['expiry_days'],\r\n config['preauthorized']\r\n)\r\n```\r\n\r\n* Then finally render the login module as follows. Here you will need to provide a name for the login form, and specify where the form should be located i.e. main body or sidebar (will default to main body).\r\n\r\n```python\r\nname, authentication_status, username = authenticator.login('Login', 'main')\r\n```\r\n\r\n\r\n### 3. Authenticating users\r\n\r\n* You can then use the returned name and authentication status to allow your verified user to proceed to any restricted content. In addition, you have the ability to add an optional logout button at any location on your main body or sidebar (will default to main body). The optional **key** parameter for the logout widget should be used with multipage applications to prevent Streamlit from throwing duplicate key errors.\r\n\r\n```python\r\nif authentication_status:\r\n authenticator.logout('Logout', 'main', key='unique_key')\r\n st.write(f'Welcome *{name}*')\r\n st.title('Some content')\r\nelif authentication_status is False:\r\n st.error('Username/password is incorrect')\r\nelif authentication_status is None:\r\n st.warning('Please enter your username and password')\r\n```\r\n\r\n* Should you require access to the persistent name, authentication status, and username variables, you may retrieve them through Streamlit's session state using **st.session_state[\"name\"]**, **st.session_state[\"authentication_status\"]**, and **st.session_state[\"username\"]**. This way you can use Streamlit-Authenticator to authenticate users across multiple pages.\r\n\r\n```python\r\nif st.session_state[\"authentication_status\"]:\r\n authenticator.logout('Logout', 'main', key='unique_key')\r\n st.write(f'Welcome *{st.session_state[\"name\"]}*')\r\n st.title('Some content')\r\nelif st.session_state[\"authentication_status\"] is False:\r\n st.error('Username/password is incorrect')\r\nelif st.session_state[\"authentication_status\"] is None:\r\n st.warning('Please enter your username and password')\r\n```\r\n\r\n\r\n\r\n* Or prompt an unverified user to enter a correct username and password.\r\n\r\n\r\n\r\n* Please note that logging out will revert the authentication status to **None** and will delete the associated reauthentication cookie as well.\r\n\r\n### 4. Creating a password reset widget\r\n\r\n* You may use the **reset_password** widget to allow a logged in user to modify their password as shown below.\r\n\r\n```python\r\nif authentication_status:\r\n try:\r\n if authenticator.reset_password(username, 'Reset password'):\r\n st.success('Password modified successfully')\r\n except Exception as e:\r\n st.error(e)\r\n```\r\n\r\n\r\n\r\n_Please remember to update the config file (as shown in step 9) after you use this widget._\r\n\r\n### 5. Creating a new user registration widget\r\n\r\n* You may use the **register_user** widget to allow a user to sign up to your application as shown below. If you require the user to be preauthorized, set the **preauthorization** argument to True and add their email to the **preauthorized** list in the configuration file. Once they have registered, their email will be automatically removed from the **preauthorized** list in the configuration file. Alternatively, to allow anyone to sign up, set the **preauthorization** argument to False.\r\n\r\n```python\r\ntry:\r\n if authenticator.register_user('Register user', preauthorization=False):\r\n st.success('User registered successfully')\r\nexcept Exception as e:\r\n st.error(e)\r\n```\r\n\r\n\r\n\r\n_Please remember to update the config file (as shown in step 9) after you use this widget._\r\n\r\n### 6. Creating a forgot password widget\r\n\r\n* You may use the **forgot_password** widget to allow a user to generate a new random password. This password will be automatically hashed and saved in the configuration file. The widget will return the username, email, and new random password of the user which should then be transferred to them securely.\r\n\r\n```python\r\ntry:\r\n username_forgot_pw, email_forgot_password, random_password = authenticator.forgot_password('Forgot password')\r\n if username_forgot_pw:\r\n st.success('New password sent securely')\r\n # Random password to be transferred to user securely\r\n else:\r\n st.error('Username not found')\r\nexcept Exception as e:\r\n st.error(e)\r\n```\r\n\r\n\r\n\r\n_Please remember to update the config file (as shown in step 9) after you use this widget._\r\n\r\n### 7. Creating a forgot username widget\r\n\r\n* You may use the **forgot_username** widget to allow a user to retrieve their forgotten username. The widget will return the username and email of the user which should then be transferred to them securely.\r\n\r\n```python\r\ntry:\r\n username_forgot_username, email_forgot_username = authenticator.forgot_username('Forgot username')\r\n if username_forgot_username:\r\n st.success('Username sent securely')\r\n # Username to be transferred to user securely\r\n else:\r\n st.error('Email not found')\r\nexcept Exception as e:\r\n st.error(e)\r\n```\r\n\r\n\r\n\r\n### 8. Creating an update user details widget\r\n\r\n* You may use the **update_user_details** widget to allow a logged in user to update their name and/or email. The widget will automatically save the updated details in both the configuration file and reauthentication cookie.\r\n\r\n```python\r\nif authentication_status:\r\n try:\r\n if authenticator.update_user_details(username, 'Update user details'):\r\n st.success('Entries updated successfully')\r\n except Exception as e:\r\n st.error(e)\r\n```\r\n\r\n\r\n\r\n_Please remember to update the config file (as shown in step 9) after you use this widget._\r\n\r\n### 9. Updating the configuration file\r\n\r\n* Please ensure that the configuration file is resaved anytime the credentials are updated or whenever the **reset_password**, **register_user**, **forgot_password**, or **update_user_details** widgets are used.\r\n\r\n```python\r\nwith open('../config.yaml', 'w') as file:\r\n yaml.dump(config, file, default_flow_style=False)\r\n```\r\n\r\n## Credits\r\n- Mohamed Abdou for the highly versatile cookie manager in [Extra-Streamlit-Components](https://github.com/Mohamed-512/Extra-Streamlit-Components).\r\n",
"bugtrack_url": null,
"license": "",
"summary": "A secure authentication module to validate user credentials in a Streamlit application.",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/RuslanLat/Streamlit-Authenticator-Ru"
},
"split_keywords": [
"python",
"streamlit",
"authentication",
"components"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "40191b8e43b22f0300717f4b8cc6b54b11c9f5af1c3e0bc04285734e0b0f2add",
"md5": "04b3ceb30208749570c764b7aced5dfb",
"sha256": "8cf3662449c3e37cfb488d9ef73a8f3e798228d88735d5c9a2e58bf3e40a6835"
},
"downloads": -1,
"filename": "streamlit-authenticator_ru-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "04b3ceb30208749570c764b7aced5dfb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 15890,
"upload_time": "2023-05-25T12:52:24",
"upload_time_iso_8601": "2023-05-25T12:52:24.197665Z",
"url": "https://files.pythonhosted.org/packages/40/19/1b8e43b22f0300717f4b8cc6b54b11c9f5af1c3e0bc04285734e0b0f2add/streamlit-authenticator_ru-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-25 12:52:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RuslanLat",
"github_project": "Streamlit-Authenticator-Ru",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "streamlit-authenticator-ru"
}
JSON
