Skip to content

Commit 9c90ec3

Browse files
pfvatterottpfvatterott
authored
Update README.md (#36)
1 parent 7762c63 commit 9c90ec3

File tree

1 file changed

+158
-4
lines changed

1 file changed

+158
-4
lines changed

‎README.md‎

Lines changed: 158 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
1-
# PropelAuth Flask SDK
2-
31
<p align="center">
4-
<a href="https://www.propelauth.com/?utm_campaign=github-flask" target="_blank" align="center">
5-
<img src="https://propelauth-logos.s3.us-west-2.amazonaws.com/logo-only.png" width="100">
2+
<a href="https://www.propelauth.com?ref=github" target="_blank" align="center">
3+
<img src="https://www.propelauth.com/imgs/lockup.svg" width="200">
64
</a>
75
</p>
86

7+
# PropelAuth Flask SDK
98

109
A Flask library for managing authentication, backed by [PropelAuth](https://www.propelauth.com/?utm_campaign=github-flask).
1110

@@ -18,6 +17,161 @@ Your frontend gets a beautiful, safe, and customizable login screen. Your backen
1817
- Full reference this library is [here](https://docs.propelauth.com/reference/backend-apis/flask)
1918
- Getting started guides for PropelAuth are [here](https://docs.propelauth.com/)
2019

20+
## Installation
21+
22+
```bash
23+
pip install propelauth_flask
24+
```
25+
26+
## Initialize
27+
28+
`init_auth` performs a one-time initialization of the library.
29+
This verifies your `api_key` and fetches the metadata needed to verify access tokens in [require_user](#require-user) and [optional_user](#optional-user).
30+
31+
32+
```py
33+
from propelauth_flask import init_auth
34+
35+
auth = init_auth("YOUR_AUTH_URL", "YOUR_API_KEY")
36+
```
37+
38+
# Protect API Routes
39+
40+
Protecting an API route is as simple as adding a decorator to the route.
41+
42+
None of the decorators make a external request to PropelAuth.
43+
They all are verified locally using the [access token](https://docs.propelauth.com/guides-and-examples/guides/access-tokens) provided in the request, making it very fast.
44+
45+
## require_user
46+
47+
A decorator that will verify the request was made by a valid user.
48+
If a valid [access token](https://docs.propelauth.com/guides-and-examples/guides/access-tokens) is provided, it will return a [User](https://docs.propelauth.com/reference/backend-apis/flask#user) Class.
49+
If not, the request is rejected with a 401 status code.
50+
51+
```py
52+
from flask import Flask
53+
from propelauth_flask import init_auth, current_user
54+
55+
app = Flask(__name__)
56+
auth = init_auth("YOUR_AUTH_URL", "YOUR_API_KEY")
57+
58+
@app.route("/api/whoami")
59+
@auth.require_user
60+
def who_am_i():
61+
"""This route is protected, current_user is always set"""
62+
return {"user_id": current_user.user_id}
63+
```
64+
65+
## optional_user
66+
67+
Similar to [require_user](#require-user), except if an access token is missing or invalid, the request is allowed to continue, but `current_user.exists()` will be `False`.
68+
69+
```py
70+
from flask import Flask
71+
from propelauth_flask import init_auth, current_user
72+
73+
app = Flask(__name__)
74+
auth = init_auth("YOUR_AUTH_URL", "YOUR_API_KEY")
75+
76+
@app.route("/api/whoami_optional")
77+
@auth.optional_user
78+
def who_am_i_optional():
79+
if current_user.exists():
80+
return {"user_id": current_user.user_id}
81+
return {}
82+
```
83+
84+
---
85+
86+
## current_user
87+
88+
A per-request value that contains user information for the user making the request. It's set by one of [require_user](#require-user) or [optional_user](#optional-user).
89+
90+
It has all the fields on the [User](https://docs.propelauth.com/reference/backend-apis/flask#user) class, as well as an `exists()` method that returns `True` if the user exists.
91+
The only time `exists()` will return `False` is if you are using [optional_user](#optional-user) and no valid access token was provided.
92+
93+
If you want to take advantage of type support, you can import the `User` class to define a new user variable.
94+
95+
```py
96+
from flask import Flask
97+
from propelauth_flask import init_auth, current_user, User
98+
99+
app = Flask(__name__)
100+
auth = init_auth("YOUR_AUTH_URL", "YOUR_API_KEY")
101+
102+
@app.route("/api/whoami")
103+
@auth.require_user
104+
def who_am_i():
105+
user: User = current_user.user
106+
return {"user_id": user.user_id}
107+
```
108+
109+
## Authorization / Organizations
110+
111+
You can also verify which organizations the user is in, and which roles and permissions they have in each organization all through the [User Class](https://docs.propelauth.com/reference/backend-apis/flask#user).
112+
113+
### Check Org Membership
114+
115+
Verify that the request was made by a valid user **and** that the user is a member of the specified organization. This can be done using the [User](https://docs.propelauth.com/reference/backend-apis/flask#user) class.
116+
117+
```py
118+
@app.route("/api/org/<org_id>", methods=['GET'])
119+
@auth.require_user
120+
def org_membership(org_id):
121+
org = current_user.get_org(org_id)
122+
if org == None:
123+
# Return a 403 error, e.g.: return "Forbidden", 403
124+
return f"You are in org {org.org_name}"
125+
```
126+
127+
### Check Org Membership and Role
128+
129+
Similar to checking org membership, but will also verify that the user has a specific Role in the organization. This can be done using either the [User](https://docs.propelauth.com/reference/backend-apis/flask#user) or [OrgMemberInfo](https://docs.propelauth.com/reference/backend-apis/flask#org-member-info) classes.
130+
131+
A user has a Role within an organization. By default, the available roles are Owner, Admin, or Member, but these can be configured. These roles are also hierarchical, so Owner > Admin > Member.
132+
133+
```py
134+
## Assuming a Role structure of Owner => Admin => Member
135+
136+
@app.route("/api/org/<org_id>", methods=['GET'])
137+
@auth.require_user
138+
def org_owner(org_id):
139+
org = current_user.get_org(org_id)
140+
if (org == None) or (org.user_is_role("Owner") == False):
141+
# return 403 error
142+
return f"You are in org {org.org_name}"
143+
```
144+
145+
### Check Org Membership and Permission
146+
147+
Similar to checking org membership, but will also verify that the user has the specified permission in the organization. This can be done using either the [User](https://docs.propelauth.com/reference/backend-apis/flask#user) or [OrgMemberInfo](https://docs.propelauth.com/reference/backend-apis/flask#org-member-info) classes.
148+
149+
Permissions are arbitrary strings associated with a role. For example, `can_view_billing`, `ProductA::CanCreate`, and `ReadOnly` are all valid permissions.
150+
You can create these permissions in the PropelAuth dashboard.
151+
152+
```py
153+
@app.route("/api/org/<org_id>", methods=['GET'])
154+
@auth.require_user
155+
def org_billing(org_id):
156+
org = current_user.get_org(org_id)
157+
if (org == None) or (org.user_has_permission("can_view_billing") == False):
158+
# return 403 error
159+
return f"You can view billing information for org {org.org_name}"
160+
```
161+
162+
## Calling Backend APIs
163+
164+
You can also use the library to call the PropelAuth APIs directly, allowing you to fetch users, create orgs, and a lot more.
165+
See the [API Reference](https://docs.propelauth.com/reference) for more information.
166+
167+
```py
168+
from propelauth_flask import init_auth
169+
170+
auth = init_auth("YOUR_AUTH_URL", "YOUR_API_KEY")
171+
172+
magic_link = auth.create_magic_link(email="test@example.com")
173+
```
174+
21175
## Questions?
22176

23177
Feel free to reach out at support@propelauth.com

0 commit comments

Comments
 (0)