Skip to content

Vitepress docs #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Aug 20, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
name: docs

on:
push:
branches: [ master ]

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Run deployment script on server
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.HOST }}
username: ${{ secrets.USERNAME }}
key: ${{ secrets.KEY_ED25519 }}
port: ${{ secrets.PORT }}
script: sh ~/fastapi-oauth2/docs/deploy.sh
89 changes: 11 additions & 78 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,74 +4,17 @@
[![Python](https://img.shields.io/pypi/pyversions/fastapi-oauth2.svg?logoColor=white)](https://pypi.org/project/fastapi-oauth2/)
[![FastAPI](https://img.shields.io/badge/fastapi-%E2%89%A50.68.1-009486)](https://pypi.org/project/fastapi-oauth2/)
[![Tests](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/tests.yml/badge.svg)](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/tests.yml)
[![License](https://img.shields.io/pypi/l/fastapi-oauth2.svg)](https://github.com/pysnippet/fastapi-oauth2/blob/master/LICENSE)
[![Docs](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/docs.yml/badge.svg)](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/docs.yml)

FastAPI OAuth2 is a middleware-based social authentication mechanism supporting several auth providers. It depends on
the [social-core](https://github.com/python-social-auth/social-core) authentication backends.

## Installation

```shell
python -m pip install fastapi-oauth2
```

## Configuration

Configuration requires you to provide the JWT requisites and define the clients of the particular providers. The
middleware configuration is declared with the `OAuth2Config` and `OAuth2Client` classes.

### OAuth2Config

- `allow_http` - Allow insecure HTTP requests. Defaults to `False`.
- `jwt_secret` - The secret key used to sign the JWT. Defaults to `None`.
- `jwt_expires` - The expiration time of the JWT in seconds. Defaults to `900`.
- `jwt_algorithm` - The algorithm used to sign the JWT. Defaults to `HS256`.
- `clients` - The list of the OAuth2 clients. Defaults to `[]`.

### OAuth2Client

- `backend` - The [social-core](https://github.com/python-social-auth/social-core) authentication backend classname.
- `client_id` - The OAuth2 client ID for the particular provider.
- `client_secret` - The OAuth2 client secret for the particular provider.
- `redirect_uri` - The OAuth2 redirect URI to redirect to after success. Defaults to the base URL.
- `scope` - The OAuth2 scope for the particular provider. Defaults to `[]`.
- `claims` - Claims mapping for the certain provider.

It is also important to mention that for the configured clients of the auth providers, the authorization URLs are
accessible by the `/oauth2/{provider}/auth` path where the `provider` variable represents the exact value of the auth
provider backend `name` attribute.

```python
from fastapi_oauth2.claims import Claims
from fastapi_oauth2.client import OAuth2Client
from fastapi_oauth2.config import OAuth2Config
from social_core.backends.github import GithubOAuth2

oauth2_config = OAuth2Config(
allow_http=False,
jwt_secret=os.getenv("JWT_SECRET"),
jwt_expires=os.getenv("JWT_EXPIRES"),
jwt_algorithm=os.getenv("JWT_ALGORITHM"),
clients=[
OAuth2Client(
backend=GithubOAuth2,
client_id=os.getenv("OAUTH2_CLIENT_ID"),
client_secret=os.getenv("OAUTH2_CLIENT_SECRET"),
redirect_uri="https://pysnippet.org/",
scope=["user:email"],
claims=Claims(
picture="avatar_url",
identity=lambda user: "%s:%s" % (user.get("provider"), user.get("id")),
),
),
]
)
```
FastAPI OAuth2 is a middleware-based social authentication mechanism supporting several OAuth2 providers. It leverages
the [social-core](https://github.com/python-social-auth/social-core) authentication backends and integrates seamlessly
with FastAPI applications.

## Integration

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

```python
from fastapi import FastAPI
Expand All @@ -80,24 +23,14 @@ from fastapi_oauth2.router import router as oauth2_router

app = FastAPI()
app.include_router(oauth2_router)
app.add_middleware(OAuth2Middleware, config=oauth2_config)
```

After adding the middleware, the `user` attribute will be available in the request context. It will contain the user
data provided by the OAuth2 provider.

```jinja2
{% if request.user.is_authenticated %}
<a href="/oauth2/logout">Sign out</a>
{% else %}
<a href="/oauth2/github/auth">Sign in</a>
{% endif %}
app.add_middleware(OAuth2Middleware, config=OAuth2Config(...))
```

## Contribute

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

## License

Expand Down
45 changes: 45 additions & 0 deletions docs/.vitepress/config.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 7 additions & 0 deletions docs/deploy.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
#!/bin/bash
cd ~/fastapi-oauth2/
git restore .
git pull
sudo rm -r /var/www/docs/fastapi-oauth2/
cd ~/fastapi-oauth2/docs/ && npm install && npm run build
sudo cp -r ~/fastapi-oauth2/docs/.vitepress/dist/ /var/www/docs/fastapi-oauth2/
33 changes: 33 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
layout: home
sidebar: false

title: FastAPI OAuth2
titleTemplate: OAuth2 authentication with support for several identity providers

hero:
name: FastAPI OAuth2
text: OAuth2 has never been that simple
tagline: Easy to integrate OAuth2 authentication with support for several identity providers.
image:
src: /logo.png
alt: PySnippet
actions:
- theme: brand
text: Get Started
link: /integration/
- theme: alt
text: View on GitHub
link: https://github.com/pysnippet/fastapi-oauth2

features:
- icon: 🛠️
title: Free and open source
details: Enjoy the freedom of our OSS project, giving you full access to its source code and allowing you to contribute to its development.
- icon: 🧩
title: Easy to integrate
details: Incorporate FastAPI OAuth2 into your existing projects with its straightforward integration process, saving you time.
- icon: ⚡
title: Compatible with FastAPI 0.68.1+
details: The package is fully compatible with FastAPI v0.68.1 and above, ensuring smooth operation and integration with your application.
---
Loading