Skip to content

Commit c6c23ea

Browse files
ArtyomVancyanArtyomVancyan
authored
Create and deploy VitePress docs (GH-16)
2 parents 17eb243 + 1573b4c commit c6c23ea

File tree

18 files changed

+381
-93
lines changed

18 files changed

+381
-93
lines changed

‎.github/workflows/docs.yml

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: docs
2+
3+
on:
4+
push:
5+
branches: [ master ]
6+
7+
jobs:
8+
deploy:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Run deployment script on server
12+
uses: appleboy/ssh-action@master
13+
with:
14+
host: ${{ secrets.HOST }}
15+
username: ${{ secrets.USERNAME }}
16+
key: ${{ secrets.KEY_ED25519 }}
17+
port: ${{ secrets.PORT }}
18+
script: sh ~/fastapi-oauth2/docs/deploy.sh

‎README.md

+11-78
Original file line numberDiff line numberDiff line change
@@ -4,74 +4,17 @@
44
[![Python](https://img.shields.io/pypi/pyversions/fastapi-oauth2.svg?logoColor=white)](https://pypi.org/project/fastapi-oauth2/)
55
[![FastAPI](https://img.shields.io/badge/fastapi-%E2%89%A50.68.1-009486)](https://pypi.org/project/fastapi-oauth2/)
66
[![Tests](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/tests.yml/badge.svg)](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/tests.yml)
7-
[![License](https://img.shields.io/pypi/l/fastapi-oauth2.svg)](https://github.com/pysnippet/fastapi-oauth2/blob/master/LICENSE)
7+
[![Docs](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/docs.yml/badge.svg)](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/docs.yml)
88

9-
FastAPI OAuth2 is a middleware-based social authentication mechanism supporting several auth providers. It depends on
10-
the [social-core](https://github.com/python-social-auth/social-core) authentication backends.
11-
12-
## Installation
13-
14-
```shell
15-
python -m pip install fastapi-oauth2
16-
```
17-
18-
## Configuration
19-
20-
Configuration requires you to provide the JWT requisites and define the clients of the particular providers. The
21-
middleware configuration is declared with the `OAuth2Config` and `OAuth2Client` classes.
22-
23-
### OAuth2Config
24-
25-
- `allow_http` - Allow insecure HTTP requests. Defaults to `False`.
26-
- `jwt_secret` - The secret key used to sign the JWT. Defaults to `None`.
27-
- `jwt_expires` - The expiration time of the JWT in seconds. Defaults to `900`.
28-
- `jwt_algorithm` - The algorithm used to sign the JWT. Defaults to `HS256`.
29-
- `clients` - The list of the OAuth2 clients. Defaults to `[]`.
30-
31-
### OAuth2Client
32-
33-
- `backend` - The [social-core](https://github.com/python-social-auth/social-core) authentication backend classname.
34-
- `client_id` - The OAuth2 client ID for the particular provider.
35-
- `client_secret` - The OAuth2 client secret for the particular provider.
36-
- `redirect_uri` - The OAuth2 redirect URI to redirect to after success. Defaults to the base URL.
37-
- `scope` - The OAuth2 scope for the particular provider. Defaults to `[]`.
38-
- `claims` - Claims mapping for the certain provider.
39-
40-
It is also important to mention that for the configured clients of the auth providers, the authorization URLs are
41-
accessible by the `/oauth2/{provider}/auth` path where the `provider` variable represents the exact value of the auth
42-
provider backend `name` attribute.
43-
44-
```python
45-
from fastapi_oauth2.claims import Claims
46-
from fastapi_oauth2.client import OAuth2Client
47-
from fastapi_oauth2.config import OAuth2Config
48-
from social_core.backends.github import GithubOAuth2
49-
50-
oauth2_config = OAuth2Config(
51-
allow_http=False,
52-
jwt_secret=os.getenv("JWT_SECRET"),
53-
jwt_expires=os.getenv("JWT_EXPIRES"),
54-
jwt_algorithm=os.getenv("JWT_ALGORITHM"),
55-
clients=[
56-
OAuth2Client(
57-
backend=GithubOAuth2,
58-
client_id=os.getenv("OAUTH2_CLIENT_ID"),
59-
client_secret=os.getenv("OAUTH2_CLIENT_SECRET"),
60-
redirect_uri="https://pysnippet.org/",
61-
scope=["user:email"],
62-
claims=Claims(
63-
picture="avatar_url",
64-
identity=lambda user: "%s:%s" % (user.get("provider"), user.get("id")),
65-
),
66-
),
67-
]
68-
)
69-
```
9+
FastAPI OAuth2 is a middleware-based social authentication mechanism supporting several OAuth2 providers. It leverages
10+
the [social-core](https://github.com/python-social-auth/social-core) authentication backends and integrates seamlessly
11+
with FastAPI applications.
7012

7113
## Integration
7214

73-
To integrate the package into your FastAPI application, you need to add the `OAuth2Middleware` with particular configs
74-
in the above-represented format and include the router to the main router of the application.
15+
For integrating the package into an existing FastAPI application, the router with OAuth2 routes and
16+
the `OAuth2Middleware` with particular [configs](https://docs.pysnippet.org/fastapi-oauth2/integration/configuration)
17+
should be added to the application.
7518

7619
```python
7720
from fastapi import FastAPI
@@ -80,24 +23,14 @@ from fastapi_oauth2.router import router as oauth2_router
8023

8124
app = FastAPI()
8225
app.include_router(oauth2_router)
83-
app.add_middleware(OAuth2Middleware, config=oauth2_config)
84-
```
85-
86-
After adding the middleware, the `user` attribute will be available in the request context. It will contain the user
87-
data provided by the OAuth2 provider.
88-
89-
```jinja2
90-
{% if request.user.is_authenticated %}
91-
<a href="/oauth2/logout">Sign out</a>
92-
{% else %}
93-
<a href="/oauth2/github/auth">Sign in</a>
94-
{% endif %}
26+
app.add_middleware(OAuth2Middleware, config=OAuth2Config(...))
9527
```
9628

9729
## Contribute
9830

99-
Any contribution is welcome. If you have any ideas or suggestions, feel free to open an issue or a pull request. And
100-
don't forget to add tests for your changes.
31+
Any contribution is welcome. Always feel free to open an issue or a discussion if you have any questions not covered by
32+
the documentation. If you have any ideas or suggestions, please, open a pull request. Your name will shine in our
33+
contributors' list. Be proud of what you build!
10134

10235
## License
10336

‎docs/.vitepress/config.js

+45
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/deploy.sh

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#!/bin/bash
2+
cd ~/fastapi-oauth2/
3+
git restore .
4+
git pull
5+
sudo rm -r /var/www/docs/fastapi-oauth2/
6+
cd ~/fastapi-oauth2/docs/ && npm install && npm run build
7+
sudo cp -r ~/fastapi-oauth2/docs/.vitepress/dist/ /var/www/docs/fastapi-oauth2/

‎docs/index.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
layout: home
3+
sidebar: false
4+
5+
title: FastAPI OAuth2
6+
titleTemplate: OAuth2 authentication with support for several identity providers
7+
8+
hero:
9+
name: FastAPI OAuth2
10+
text: OAuth2 has never been that simple
11+
tagline: Easy to integrate OAuth2 authentication with support for several identity providers.
12+
image:
13+
src: /logo.png
14+
alt: PySnippet
15+
actions:
16+
- theme: brand
17+
text: Get Started
18+
link: /integration/
19+
- theme: alt
20+
text: View on GitHub
21+
link: https://github.com/pysnippet/fastapi-oauth2
22+
23+
features:
24+
- icon: 🛠️
25+
title: Free and open source
26+
details: Enjoy the freedom of our OSS project, giving you full access to its source code and allowing you to contribute to its development.
27+
- icon: 🧩
28+
title: Easy to integrate
29+
details: Incorporate FastAPI OAuth2 into your existing projects with its straightforward integration process, saving you time.
30+
- icon: ⚡
31+
title: Compatible with FastAPI 0.68.1+
32+
details: The package is fully compatible with FastAPI v0.68.1 and above, ensuring smooth operation and integration with your application.
33+
---

0 commit comments

Comments
 (0)