Package: masonite-oauth2
IntroductionSocial authentication for your Masonite app (OAuth 2).FeaturesOfficially supports GitHub, GitLab, BitBucket, Google, Apple and Facebook providersOfficial Masonite DocumentationNew to Masonite ? Please first read theOfficial 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 onMasonite Discord Communityto ask any questions you need!Installationpipinstallmasonite-oauth2ConfigurationAdd OauthProvider to your project inconfig/providers.py:# config/providers.py# ...frommasonite.oauthimportOAuthProvider# ...PROVIDERS=[# ...# Third Party ProvidersOAuthProvider,# ...]Then you can publish the configuration file to your project:pythoncraftpackage:publishoauthFinally you will need to add credentials for the OAuth providers your application utilizes.# config/oauth.pyDRIVERS={"github":{"client_id":env("GITHUB_CLIENT_ID"),"client_secret":env("GITHUB_CLIENT_SECRET"),"redirect":"auth.callback",}}redirectcan 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 firstcreate a workspaceand then inSettingsadd anOAuth consumerherehttps://bitbucket.org/{your-workspace-slug}/workspace/settings/api...UsageTo 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 accessOAuthfacade 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 aOAuthUserinstance containing user informations.frommasonite.oauthimportOAuthclassYourController(Controller):defauth(self):returnOAuth.driver("github").redirect()defcallback(self):user=OAuth.driver("github").user()# you now have a user object with data and a tokenGet user dataWhen retrieving user data withuser()method, you will get aOAuthUserwith the following
fields:idnamenicknameemailavatartokenGet user data from a tokenIf you already have a valid access token for a user, you can retrieve user data usinguser_from_token():user=OAuth.driver("github").user_from_token(token)ScopesOAuth providers have default scopes used when redirecting to OAuth provider screen:GitHub:user:emailBitBucket:emailGitlab:read_userGoogle:openid,profile,emailApple:name,emailFacebook:emailYou can add new scopes in the redirect request by usingscopes()method (merged with default scopes):user=OAuth.driver("github").scopes(["admin:org","read:discussion"]).redirect()# scopes will be: user:email, admin:org, read:discussionYou can override all scopes in the redirect request by usingset_scopes()method:user=OAuth.driver("github").set_scopes(["user:email","user:follow"]).redirect()# scopes will be: user:email, user:followOptional parametersSome OAuth providers support optional parameters. To include those in the redirect request, you can usewith_data()method.returnOAuth.driver("github").with_data({"key":"value"})Refresh tokenSome OAuth providers support refreshing token (GitLab, BitBucket and Google at least). For that
you need arefresh_tokenobtained when callinguser():new_user=OAuth.driver("gitlab").refresh(user.refresh_token)new_user.token#== is a new tokenRevoke token programmaticallySome OAuth providers support revoking token programmatically. For that
you need to pass the token to therevoke()method:revoked=OAuth.driver("gitlab").revoke(token)It returned a boolean to tell if it was successful or not.ContributingPlease read theContributing Documentationhere.
Feel free to open a PR to add a new OAuth 2.0 provider 😀 !MaintainersSamuel GirardinCreditsBased on non maintained packagehttps://github.com/hellomasonite/masonite-socialite.LicenseMasonite oauth is open-sourced software licensed under theMIT license.