Social authentication for your Masonite app (OAuth 2).
- Officially supports GitHub, GitLab, BitBucket, Google, Apple and Facebook providers
New to Masonite ? Please first read the Official Documentation. Masonite strives to have extremely comprehensive documentation π. It would be wise to go through the tutorials there. If you find any discrepencies or anything that doesn't make sense, be sure to comment directly on the documentation to start a discussion!
Hop on Masonite Discord Community to ask any questions you need!
pip install masonite-oauth2
Add OauthProvider to your project in config/providers.py
:
# config/providers.py
# ...
from masonite.oauth import OAuthProvider
# ...
PROVIDERS = [
# ...
# Third Party Providers
OAuthProvider,
# ...
]
Then you can publish the configuration file to your project:
python craft package:publish oauth
Finally you will need to add credentials for the OAuth providers your application utilizes.
# config/oauth.py
DRIVERS = {
"github": {
"client_id": env("GITHUB_CLIENT_ID"),
"client_secret": env("GITHUB_CLIENT_SECRET"),
"redirect": "auth.callback",
}
}
redirect
can be a route name or a path.
Then you should create an OAuth App on your provider dashboard. Here are some links:
- GitHub:
- GitLab:
- BitBucket (Atlassian): you must first create a workspace and then in
Settings
add anOAuth consumer
here https://bitbucket.org/{your-workspace-slug}/workspace/settings/api - ...
To authenticate users using an OAuth provider, you will need two routes: one for redirecting the user to the OAuth provider, and another for receiving the callback from the provider after authentication.
In your controller, you can then easily access OAuth
facade methods:
redirect()
is redirecting to the OAuth endpoint provideruser()
is the route callback the user will be redirected to after entering its credentials through the OAuth provider screen. This method is returning aOAuthUser
instance containing user informations.
from masonite.oauth import OAuth
class YourController(Controller):
def auth(self):
return OAuth.driver("github").redirect()
def callback(self):
user = OAuth.driver("github").user()
# you now have a user object with data and a token
When retrieving user data with user()
method, you will get a OAuthUser
with the following
fields:
- id
- name
- nickname
- avatar
- token
If you already have a valid access token for a user, you can retrieve user data using user_from_token()
:
user = OAuth.driver("github").user_from_token(token)
OAuth providers have default scopes used when redirecting to OAuth provider screen:
- GitHub:
user:email
- BitBucket:
email
- Gitlab:
read_user
- Google:
openid
,profile
,email
- Apple:
name
,email
- Facebook:
email
You can add new scopes in the redirect request by using scopes()
method (merged with default scopes):
user = OAuth.driver("github").scopes(["admin:org", "read:discussion"]).redirect()
# scopes will be: user:email, admin:org, read:discussion
You can override all scopes in the redirect request by using set_scopes()
method:
user = OAuth.driver("github").set_scopes(["user:email", "user:follow"]).redirect()
# scopes will be: user:email, user:follow
Some OAuth providers support optional parameters. To include those in the redirect request, you can use with_data()
method.
return OAuth.driver("github").with_data({"key": "value"})
Some OAuth providers support refreshing token (GitLab, BitBucket and Google at least). For that
you need a refresh_token
obtained when calling user()
:
new_user = OAuth.driver("gitlab").refresh(user.refresh_token)
new_user.token #== is a new token
Some OAuth providers support revoking token programmatically. For that
you need to pass the token to the revoke()
method:
revoked = OAuth.driver("gitlab").revoke(token)
It returned a boolean to tell if it was successful or not.
Please read the Contributing Documentation here. Feel free to open a PR to add a new OAuth 2.0 provider π !
Based on non maintained package https://github.com/hellomasonite/masonite-socialite.
Masonite oauth is open-sourced software licensed under the MIT license.