duber000 / masonite-oauth2

Social authentication for your apps (based on OAuth 2)

Introduction

Social authentication for your Masonite app (OAuth 2).

Features

• Officially supports GitHub, GitLab, BitBucket, Google, Apple and Facebook providers

Official Masonite Documentation

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!

Installation

pip install masonite-oauth2

Configuration

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.

Configuration of your OAuth app:

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 an OAuth consumer here https://bitbucket.org/{your-workspace-slug}/workspace/settings/api
• ...

Usage

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 provider
• user() is the route callback the user will be redirected to after entering its credentials through the OAuth provider screen. This method is returning a OAuthUser 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

Get user data

When retrieving user data with user() method, you will get a OAuthUser with the following fields:

• id
• name
• nickname
• email
• avatar
• token

Get user data from a 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)

Scopes

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

Optional parameters

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"})

Refresh token

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

Revoke token programmatically

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.

Contributing

Please read the Contributing Documentation here. Feel free to open a PR to add a new OAuth 2.0 provider 😀 !

Maintainers

• Samuel Girardin

Credits

Based on non maintained package https://github.com/hellomasonite/masonite-socialite.

License

Masonite oauth is open-sourced software licensed under the MIT license.