# reflex-magic-link-auth
Generate and verify "magic link" one time passwords for user authentication without
complex registration flows.
## Installation
```bash
pip install reflex-magic-link-auth
```
## Usage
See
[`magic_link_auth_demo/magic_link_auth_demo.py`](magic_link_auth_demo/magic_link_auth_demo.py)
for a complete example.
### 1. Collect the User email
You can use a simple form with a single input field and button, like the
example, or present a form prompting for more information, such as a name,
address, zip code, etc. Any additional data should be associated with the
provided email as the main key for the account.
### 2. Substate from MagicLinkAuthState
The substate which handles the authentication form submission should be
a substate of `reflex_magic_link_auth.MagicLinkAuthState` (alternatively, it
may get an instance of this state via `.get_state` API).
### 3. Generate the OTP
When the user submits the form, generate a one time password by calling
`._generate_otp` and providing the email address.
This function returns a 2-tuple:
* The latest record associated with the email address
* The one time password in plaintext
If the record is None, then the email address was invalid, or some other problem
occured (ensure database migration has been applied).
If the record is returned, but the OTP is None, then the user has exceeded the
configured rate limit and cannot receive a new token for a while.
### 4. Send the Magic Link
Either on page `on_load` or some component `on_mount` should trigger
`reflex_magic_link_auth.MagicLinkAuthState.get_base_url` to ensure the state
knows the correct frontend URL when formatting the magic links.
Pass the `record` and `otp` to
`reflex_magic_link_auth.MagicLinkAuthState._get_magic_link` to get a URL that,
when accessed will log the user in to the app.
While this component contains an example mailgun provider, generally it is
up to you to actually email the link to the user.
### 5. User Accesses the Magic Link
The user clicks the link in their email, and the page mounted at
`reflex_magic_link_auth.constants.AUTH_ROUTE` will validate the token and
redirect to the URL specified in the query param `redir`.
### 6. Verifying Access
Any event handlers which depend on user session validity should check the computed var
`reflex_magic_link_auth.MagicLinkAuthState.session_is_valid` to determine if the user is
logged in and the session has not expired.
A persistent external identifier hashed over the email address is provided at
`reflex_magic_link_auth.MagicLinkAuthState.auth_session.persistent_id`. When interoperating
with other user information systems, this ID can be used to uniquely identifer a user
originating from reflex-magic-link-auth.
### 7. Logout
To log the user out, trigger the event handler
`reflex_magic_link_auth.MagicLinkAuthState.logout`.
Raw data
{
"_id": null,
"home_page": null,
"name": "reflex-magic-link-auth",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "reflex, reflex-custom-components",
"author": null,
"author_email": "Masen Furer <m_github@0x26.net>",
"download_url": "https://files.pythonhosted.org/packages/a4/d4/6cda0763ef777c5ce31322f259b056a192385f6ed4a98b2fe58d472b2881/reflex_magic_link_auth-0.0.4.tar.gz",
"platform": null,
"description": "# reflex-magic-link-auth\n\nGenerate and verify \"magic link\" one time passwords for user authentication without\ncomplex registration flows.\n\n## Installation\n\n```bash\npip install reflex-magic-link-auth\n```\n\n## Usage\n\nSee\n[`magic_link_auth_demo/magic_link_auth_demo.py`](magic_link_auth_demo/magic_link_auth_demo.py)\nfor a complete example.\n\n### 1. Collect the User email\n\nYou can use a simple form with a single input field and button, like the\nexample, or present a form prompting for more information, such as a name,\naddress, zip code, etc. Any additional data should be associated with the\nprovided email as the main key for the account.\n\n### 2. Substate from MagicLinkAuthState\n\nThe substate which handles the authentication form submission should be\na substate of `reflex_magic_link_auth.MagicLinkAuthState` (alternatively, it\nmay get an instance of this state via `.get_state` API).\n\n### 3. Generate the OTP\n\nWhen the user submits the form, generate a one time password by calling\n`._generate_otp` and providing the email address.\n\nThis function returns a 2-tuple:\n\n* The latest record associated with the email address\n* The one time password in plaintext\n\nIf the record is None, then the email address was invalid, or some other problem\noccured (ensure database migration has been applied).\n\nIf the record is returned, but the OTP is None, then the user has exceeded the\nconfigured rate limit and cannot receive a new token for a while.\n\n### 4. Send the Magic Link\n\nEither on page `on_load` or some component `on_mount` should trigger\n`reflex_magic_link_auth.MagicLinkAuthState.get_base_url` to ensure the state\nknows the correct frontend URL when formatting the magic links.\n\nPass the `record` and `otp` to\n`reflex_magic_link_auth.MagicLinkAuthState._get_magic_link` to get a URL that,\nwhen accessed will log the user in to the app.\n\nWhile this component contains an example mailgun provider, generally it is\nup to you to actually email the link to the user.\n\n### 5. User Accesses the Magic Link\n\nThe user clicks the link in their email, and the page mounted at\n`reflex_magic_link_auth.constants.AUTH_ROUTE` will validate the token and\nredirect to the URL specified in the query param `redir`.\n\n### 6. Verifying Access\n\nAny event handlers which depend on user session validity should check the computed var\n`reflex_magic_link_auth.MagicLinkAuthState.session_is_valid` to determine if the user is\nlogged in and the session has not expired.\n\nA persistent external identifier hashed over the email address is provided at\n`reflex_magic_link_auth.MagicLinkAuthState.auth_session.persistent_id`. When interoperating\nwith other user information systems, this ID can be used to uniquely identifer a user\noriginating from reflex-magic-link-auth.\n\n### 7. Logout\n\nTo log the user out, trigger the event handler\n`reflex_magic_link_auth.MagicLinkAuthState.logout`.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Login with magic links sent via email",
"version": "0.0.4",
"project_urls": {
"Homepage": "https://github.com/masenf/reflex-magic-link-auth"
},
"split_keywords": [
"reflex",
" reflex-custom-components"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d3cb1a30ebccde8bc50317211e1565f583a73b111ff5da1b99dc26397e4afd5c",
"md5": "b51af0f796b2e3dae085c214c40836a0",
"sha256": "fc570d2f7696c0f70883db2b06dbbf23f0ce2852accf5b4711d34e10f17d46ef"
},
"downloads": -1,
"filename": "reflex_magic_link_auth-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b51af0f796b2e3dae085c214c40836a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9070,
"upload_time": "2024-09-19T18:22:39",
"upload_time_iso_8601": "2024-09-19T18:22:39.852296Z",
"url": "https://files.pythonhosted.org/packages/d3/cb/1a30ebccde8bc50317211e1565f583a73b111ff5da1b99dc26397e4afd5c/reflex_magic_link_auth-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a4d46cda0763ef777c5ce31322f259b056a192385f6ed4a98b2fe58d472b2881",
"md5": "42f74a6e216d45ca2abff418046ed0bd",
"sha256": "cb04d79c5a1393cf9dbad338b22f08a88a38b7a0107f53b78b330eae80a4abf2"
},
"downloads": -1,
"filename": "reflex_magic_link_auth-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "42f74a6e216d45ca2abff418046ed0bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8056,
"upload_time": "2024-09-19T18:22:41",
"upload_time_iso_8601": "2024-09-19T18:22:41.234543Z",
"url": "https://files.pythonhosted.org/packages/a4/d4/6cda0763ef777c5ce31322f259b056a192385f6ed4a98b2fe58d472b2881/reflex_magic_link_auth-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-19 18:22:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "masenf",
"github_project": "reflex-magic-link-auth",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "reflex-magic-link-auth"
}
JSON
