https://github.com/girardinsamuel/masonite-oauth2

Social authentication for your apps (based on OAuth 2)
https://github.com/girardinsamuel/masonite-oauth2

Last synced: 3 months ago
JSON representation

Social authentication for your apps (based on OAuth 2)

• Host: GitHub
• URL: https://github.com/girardinsamuel/masonite-oauth2
• Owner: girardinsamuel
• License: mit
• Created: 2021-05-07T12:46:54.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2023-09-04T16:36:05.000Z (over 1 year ago)
• Last Synced: 2024-10-03T09:19:54.420Z (3 months ago)
• Language: Python
• Homepage:
• Size: 147 KB
• Stars: 8
• Watchers: 3
• Forks: 3
• Open Issues: 6
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

        


    





  

    

  

  

  

  

  

  

  

  



## 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](https://docs.masoniteproject.com/).

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](https://discord.gg/TwKeFahmPZ) to ask any questions you need!

## Installation

```bash

pip install masonite-oauth2

```

## Configuration

Add OauthProvider to your project in `config/providers.py`:

```python

# config/providers.py

# ...

from masonite.oauth import OAuthProvider

# ...

PROVIDERS = [

    # ...

    # Third Party Providers

    OAuthProvider,

    # ...

]

```

Then you can publish the configuration file to your project:

```bash

python craft package:publish oauth

```

Finally you will need to add credentials for the OAuth providers your application utilizes.

```python

# 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](https://bitbucket.org/account/workspaces/) 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.

```python

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()`:

```python

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):

```python

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:

```python

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.

```python

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()`:

```python

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:

```python

revoked = OAuth.driver("gitlab").revoke(token)

```

It returned a boolean to tell if it was successful or not.

## Contributing

Please read the [Contributing Documentation](CONTRIBUTING.md) here.

Feel free to open a PR to add a new OAuth 2.0 provider 😀 !

## Maintainers

- [Samuel Girardin](https://www.github.com/girardinsamuel)

## Credits

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

## License

Masonite oauth is open-sourced software licensed under the [MIT license](LICENSE).