├── docs ├── requirements.txt ├── backends │ ├── line.rst │ ├── aol.rst │ ├── belgium_eid.rst │ ├── pocket.rst │ ├── launchpad.rst │ ├── drip.rst │ ├── podio.rst │ ├── mapmyfitness.rst │ ├── runkeeper.rst │ ├── withings.rst │ ├── xing.rst │ ├── suse.rst │ ├── taobao.rst │ ├── wunderlist.rst │ ├── orbi.rst │ ├── meetup.rst │ ├── clef.rst │ ├── tumblr.rst │ ├── kakao.rst │ ├── sketchfab.rst │ ├── strava.rst │ ├── foursquare.rst │ ├── tripit.rst │ ├── stocktwits.rst │ ├── arcgis.rst │ ├── lastfm.rst │ ├── disqus.rst │ ├── flickr.rst │ ├── stackoverflow.rst │ ├── livejournal.rst │ ├── thisismyjam.rst │ ├── twilio.rst │ ├── angel.rst │ ├── udata.rst │ ├── beats.rst │ ├── lifescience.rst │ ├── twitch.rst │ ├── justgiving.rst │ ├── spotify.rst │ ├── eventbrite.rst │ ├── readability.rst │ ├── quizlet.rst │ ├── docker.rst │ ├── vend.rst │ ├── patreon.rst │ ├── changetip.rst │ ├── dribbble.rst │ ├── shimmering.rst │ ├── edmodo.rst │ ├── slack.rst │ ├── uber.rst │ ├── skyrock.rst │ ├── instagram.rst │ ├── steam.rst │ ├── box.rst │ ├── coinbase.rst │ ├── upwork.rst │ ├── discogs.rst │ ├── evernote.rst │ ├── microsoftgraph.rst │ ├── kick.rst │ ├── jawbone.rst │ ├── mineid.rst │ ├── naver.rst │ ├── zotero.rst │ ├── weibo.rst │ ├── discord.rst │ ├── mailru.rst │ ├── gitea.rst │ ├── trello.rst │ ├── yammer.rst │ ├── eveonline.rst │ ├── mailchimp.rst │ ├── vimeo.rst │ ├── dailymotion.rst │ ├── naszaklasa.rst │ ├── flat.rst │ ├── khanacademy.rst │ ├── live.rst │ ├── auth0_openidconnect.rst │ ├── pinterest.rst │ ├── fedora.rst │ ├── openstreetmap.rst │ ├── qiita.rst │ ├── yahoo.rst │ ├── soundcloud.rst │ ├── coursera.rst │ ├── gitlab.rst │ ├── lyft.rst │ ├── qq.rst │ ├── moves.rst │ ├── amazon.rst │ ├── grafana.rst │ ├── nationbuilder.rst │ ├── digitalocean.rst │ ├── stripe.rst │ ├── simplelogin.rst │ ├── rdio.rst │ ├── okta.rst │ ├── untappd.rst │ ├── mixcloud.rst │ ├── cognito.rst │ ├── behance.rst │ ├── mediawiki.rst │ ├── fitbit.rst │ ├── oauth.rst │ ├── pixelpin.rst │ ├── twitter_oauth2.rst │ ├── mendeley.rst │ ├── ngpvan_actionid.rst │ ├── auth0.rst │ ├── reddit.rst │ ├── appsfuel.rst │ ├── battlenet.rst │ ├── discourse.rst │ ├── facebook_limited_login.rst │ ├── orcid.rst │ ├── salesforce.rst │ ├── douban.rst │ ├── etsy.rst │ ├── telegram.rst │ ├── persona.rst │ ├── dropbox.rst │ ├── cas.rst │ ├── twitter.rst │ ├── oidc.rst │ ├── openstreetmap_oauth2.rst │ ├── openid.rst │ ├── shopify.rst │ ├── odnoklassnikiru.rst │ ├── nfdi.rst │ ├── apple.rst │ ├── loginradius.rst │ ├── seznam.rst │ ├── bitbucket.rst │ ├── osso.rst │ ├── username.rst │ ├── github_enterprise.rst │ ├── email.rst │ ├── bitbucket_datacenter_oauth2.rst │ ├── keycloak.rst │ ├── vault.rst │ ├── index.rst │ ├── linkedin.rst │ ├── github.rst │ ├── bungie.rst │ └── facebook.rst ├── maintainers.rst ├── copyright.rst ├── configuration │ ├── index.rst │ ├── webpy.rst │ ├── cherrypy.rst │ └── pyramid.rst ├── conf.py ├── index.rst ├── logging_out.rst ├── images │ └── logo.svg ├── tests.rst ├── exceptions.rst ├── strategies.rst ├── installing.rst └── Makefile ├── .readthedocs.yaml ├── .github ├── workflows │ └── pre-commit.yml └── renovate.json ├── .gitignore ├── pyproject.toml ├── README.md ├── LICENSE └── .pre-commit-config.yaml /docs/requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx==9.0.4 2 | furo==2025.12.19 3 | -------------------------------------------------------------------------------- /docs/backends/line.rst: -------------------------------------------------------------------------------- 1 | Line.me 2 | ======= 3 | 4 | Fill App Id and Secret in your project settings:: 5 | 6 | SOCIAL_AUTH_LINE_KEY = '...' 7 | SOCIAL_AUTH_LINE_SECRET = '...' 8 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | version: 2 2 | 3 | sphinx: 4 | configuration: docs/conf.py 5 | fail_on_warning: true 6 | 7 | python: 8 | install: 9 | - requirements: docs/requirements.txt 10 | 11 | build: 12 | os: ubuntu-22.04 13 | tools: 14 | python: '3.11' 15 | -------------------------------------------------------------------------------- /.github/workflows/pre-commit.yml: -------------------------------------------------------------------------------- 1 | name: pre-commit check 2 | 3 | on: 4 | push: 5 | pull_request: 6 | 7 | permissions: 8 | contents: read 9 | 10 | jobs: 11 | pre-commit: 12 | uses: python-social-auth/social-core/.github/workflows/pre-commit-shared.yml@master 13 | -------------------------------------------------------------------------------- /docs/backends/aol.rst: -------------------------------------------------------------------------------- 1 | AOL 2 | === 3 | 4 | AOL OpenID doesn't require major settings beside being defined on 5 | ``AUTHENTICATION_BACKENDS```:: 6 | 7 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 8 | ... 9 | 'social_core.backends.aol.AOLOpenId', 10 | ... 11 | ) 12 | -------------------------------------------------------------------------------- /docs/backends/belgium_eid.rst: -------------------------------------------------------------------------------- 1 | Belgium EID 2 | =========== 3 | 4 | Belgium EID OpenID doesn't require major settings beside being defined on 5 | ``AUTHENTICATION_BACKENDS```:: 6 | 7 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 8 | ... 9 | 'social_core.backends.belgiumeid.BelgiumEIDOpenId', 10 | ... 11 | ) 12 | -------------------------------------------------------------------------------- /docs/backends/pocket.rst: -------------------------------------------------------------------------------- 1 | Pocket 2 | ====== 3 | 4 | Pocket uses a weird variant of OAuth v2 that only defines a consumer key. 5 | 6 | - Register a new application at the `Pocket API`_, and 7 | 8 | - fill ``consumer key`` value in the settings:: 9 | 10 | SOCIAL_AUTH_POCKET_KEY = '' 11 | 12 | .. _Pocket API: http://getpocket.com/developer/ 13 | -------------------------------------------------------------------------------- /docs/backends/launchpad.rst: -------------------------------------------------------------------------------- 1 | Launchpad 2 | ========= 3 | 4 | `Ubuntu Launchpad `_ OpenID doesn't require 5 | major settings beside being defined on ``AUTHENTICATION_BACKENDS```:: 6 | 7 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 8 | ... 9 | 'social_core.backends.launchpad.LaunchpadOpenId', 10 | ... 11 | ) 12 | -------------------------------------------------------------------------------- /docs/backends/drip.rst: -------------------------------------------------------------------------------- 1 | Drip 2 | ==== 3 | 4 | Drip uses OAuth v2 for Authentication. 5 | 6 | - Register a new application with `Drip`_, and 7 | 8 | - fill ``Client ID`` and ``Client Secret`` from getdrip.com values in 9 | the settings:: 10 | 11 | SOCIAL_AUTH_DRIP_KEY = '' 12 | SOCIAL_AUTH_DRIP_SECRET = '' 13 | 14 | .. _Drip: https://www.getdrip.com/user/applications 15 | -------------------------------------------------------------------------------- /docs/backends/podio.rst: -------------------------------------------------------------------------------- 1 | Podio 2 | ===== 3 | 4 | Podio offers OAuth2 as their auth mechanism. In order to enable it, follow: 5 | 6 | - Register a new application at `Podio API Keys`_ 7 | 8 | - Fill **Client Id** and **Client Secret** values:: 9 | 10 | SOCIAL_AUTH_PODIO_KEY = '' 11 | SOCIAL_AUTH_PODIO_SECRET = '' 12 | 13 | .. _Podio API Keys: https://developers.podio.com/api-key 14 | -------------------------------------------------------------------------------- /docs/backends/mapmyfitness.rst: -------------------------------------------------------------------------------- 1 | MapMyFitness 2 | ============ 3 | 4 | MapMyFitness uses OAuth v2 for authentication. 5 | 6 | - Register a new application at the `MapMyFitness API`_, and 7 | 8 | - fill ``key`` and ``secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_MAPMYFITNESS_KEY = '' 11 | SOCIAL_AUTH_MAPMYFITNESS_SECRET = '' 12 | 13 | .. _MapMyFitness API: https://www.mapmyapi.com 14 | -------------------------------------------------------------------------------- /docs/backends/runkeeper.rst: -------------------------------------------------------------------------------- 1 | RunKeeper 2 | ========= 3 | 4 | RunKeeper uses OAuth v2 for authentication. 5 | 6 | - Register a new application at the `RunKeeper API`_, and 7 | 8 | - fill ``Client Id`` and ``Client Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_RUNKEEPER_KEY = '' 11 | SOCIAL_AUTH_RUNKEEPER_SECRET = '' 12 | 13 | .. _RunKeeper API: http://developer.runkeeper.com/healthgraph 14 | -------------------------------------------------------------------------------- /docs/maintainers.rst: -------------------------------------------------------------------------------- 1 | Maintainers 2 | =========== 3 | 4 | This project is maintained by: 5 | 6 | * `Matías Aguirre`_ 7 | * `Michal Čihař`_ 8 | 9 | The project is open for mainteners, take a look to `issue #539`_ for details. 10 | 11 | .. _Matías Aguirre: https://github.com/omab 12 | .. _Michal Čihař: https://github.com/nijel 13 | .. _issue #539: https://github.com/python-social-auth/social-core/issues/539 14 | -------------------------------------------------------------------------------- /docs/backends/withings.rst: -------------------------------------------------------------------------------- 1 | Withings 2 | ======== 3 | 4 | Withings uses OAuth v1 for Authentication. 5 | 6 | - Register a new application at the `Withings API`_, and 7 | 8 | - fill ``Client ID`` and ``Client Secret`` from withings.com values in the settings:: 9 | 10 | SOCIAL_AUTH_WITHINGS_KEY = '' 11 | SOCIAL_AUTH_WITHINGS_SECRET = '' 12 | 13 | .. _Withings API: https://oauth.withings.com/partner/add 14 | -------------------------------------------------------------------------------- /docs/backends/xing.rst: -------------------------------------------------------------------------------- 1 | XING 2 | ==== 3 | 4 | XING uses OAuth1 for their auth mechanism, in order to enable the backend 5 | follow: 6 | 7 | - Register a new application at `XING Apps Dashboard`_, 8 | 9 | - Fill **Consumer Key** and **Consumer Secret** values:: 10 | 11 | SOCIAL_AUTH_XING_KEY = '' 12 | SOCIAL_AUTH_XING_SECRET = '' 13 | 14 | .. _XING Apps Dashboard: https://dev.xing.com/applications 15 | -------------------------------------------------------------------------------- /docs/backends/suse.rst: -------------------------------------------------------------------------------- 1 | SUSE 2 | ==== 3 | 4 | This section describes how to setup the different services provided by SUSE and openSUSE. 5 | 6 | 7 | openSUSE OpenID 8 | --------------- 9 | 10 | openSUSE OpenID works straightforward, not settings are needed. Domains or emails 11 | whitelists can be applied too, check the whitelists_ settings for details. 12 | 13 | .. _whitelists: ../configuration/settings.html#whitelists 14 | -------------------------------------------------------------------------------- /docs/backends/taobao.rst: -------------------------------------------------------------------------------- 1 | Taobao OAuth 2 | ============ 3 | 4 | Taobao OAuth 2.0 workflow. 5 | 6 | - Register a new application at Open `Open Taobao`_. 7 | 8 | - Fill ``Consumer Key`` and ``Consumer Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_TAOBAO_KEY = '' 11 | SOCIAL_AUTH_TAOBAO_SECRET = '' 12 | 13 | By default ``token`` is stored in ``extra_data`` field. 14 | 15 | .. _Open Taobao: http://open.taobao.com 16 | -------------------------------------------------------------------------------- /docs/backends/wunderlist.rst: -------------------------------------------------------------------------------- 1 | Wunderlist 2 | ========== 3 | 4 | Wunderlist uses OAuth v2 for Authentication. 5 | 6 | - Register a new application at `Wunderlist Developer Portal`_, and 7 | 8 | - fill ``Client Id`` and ``Client Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_WUNDERLIST_KEY = '' 11 | SOCIAL_AUTH_WUNDERLIST_SECRET = '' 12 | 13 | .. _Wunderlist Developer Portal: https://developer.wunderlist.com/applications 14 | -------------------------------------------------------------------------------- /docs/backends/orbi.rst: -------------------------------------------------------------------------------- 1 | Orbi 2 | ==== 3 | 4 | Orbi OAuth v2 for Authentication. 5 | 6 | - Register a new applicationat the `Orbi API`_, and 7 | 8 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_ORBI_KEY = '' 11 | SOCIAL_AUTH_ORBI_SECRET = '' 12 | 13 | - Also it's possible to define extra permissions with:: 14 | 15 | SOCIAL_AUTH_KAKAO_SCOPE = ['all'] 16 | 17 | .. _Orbi API: http://orbi.kr 18 | -------------------------------------------------------------------------------- /docs/backends/meetup.rst: -------------------------------------------------------------------------------- 1 | Meetup 2 | ====== 3 | 4 | Meetup.com uses OAuth2 for its auth mechanism. 5 | 6 | - Register a new OAuth Consumer at `Meetup Consumer Registration`_, set your 7 | consumer name, redirect uri. 8 | 9 | - Fill ``key`` and ``secret`` values in the settings:: 10 | 11 | SOCIAL_AUTH_MEETUP_KEY = '' 12 | SOCIAL_AUTH_MEETUP_SECRET = '' 13 | 14 | .. _Meetup Consumer Registration: https://secure.meetup.com/meetup_api/oauth_consumers/create 15 | -------------------------------------------------------------------------------- /docs/backends/clef.rst: -------------------------------------------------------------------------------- 1 | Clef 2 | ====== 3 | 4 | Clef works similar to Facebook (OAuth). 5 | 6 | - Register a new application at `Clef Developers`_, set the callback URL to 7 | ``http://example.com/complete/clef/`` replacing ``example.com`` with your 8 | domain. 9 | 10 | - Fill ``App Id`` and ``App Secret`` values in the settings:: 11 | 12 | SOCIAL_AUTH_CLEF_KEY = '' 13 | SOCIAL_AUTH_CLEF_SECRET = '' 14 | 15 | .. _Clef Developers: https://getclef.com/developer 16 | -------------------------------------------------------------------------------- /docs/backends/tumblr.rst: -------------------------------------------------------------------------------- 1 | Tumblr 2 | ====== 3 | 4 | Tumblr uses OAuth 1.0a for authentication. 5 | 6 | - Register a new application at http://www.tumblr.com/oauth/apps 7 | 8 | - Set the ``Default callback URL`` to http://[your domain]/ 9 | 10 | - fill ``OAuth Consumer Key`` and ``Secret Key`` values in your Django 11 | settings:: 12 | 13 | SOCIAL_AUTH_TUMBLR_KEY = '' 14 | SOCIAL_AUTH_TUMBLR_SECRET = '' 15 | 16 | .. _Tumblr API: http://www.tumblr.com/docs/en/api/v2 17 | -------------------------------------------------------------------------------- /docs/backends/kakao.rst: -------------------------------------------------------------------------------- 1 | Kakao 2 | ====== 3 | 4 | Kakao uses OAuth v2 for Authentication. 5 | 6 | - Register a new applicationat the `Kakao API`_, and 7 | 8 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_KAKAO_KEY = '' 11 | SOCIAL_AUTH_KAKAO_SECRET = '' 12 | 13 | - Also it's possible to define extra permissions with:: 14 | 15 | SOCIAL_AUTH_KAKAO_SCOPE = [...] 16 | 17 | .. _Kakao API: https://developers.kakao.com/docs/restapi 18 | -------------------------------------------------------------------------------- /docs/backends/sketchfab.rst: -------------------------------------------------------------------------------- 1 | Sketchfab 2 | ========= 3 | 4 | Sketchfab uses OAuth 2 for authentication. 5 | 6 | To use: 7 | 8 | - Follow the steps at `Sketchfab Oauth`_, and ask for an 9 | ``Authorization code`` grant type. 10 | 11 | - Fill the ``Client id/key`` and ``Client Secret`` values you received 12 | in your django settings:: 13 | 14 | SOCIAL_AUTH_SKETCHFAB_KEY = '' 15 | SOCIAL_AUTH_SKETCHFAB_SECRET = '' 16 | 17 | .. _Sketchfab Oauth: https://sketchfab.com/developers/oauth 18 | -------------------------------------------------------------------------------- /docs/backends/strava.rst: -------------------------------------------------------------------------------- 1 | Strava 2 | ========= 3 | 4 | Strava uses OAuth v2 for Authentication. 5 | 6 | - Register a new application at the `Strava API`_, and 7 | 8 | - fill ``Client ID`` and ``Client Secret`` from strava.com values in the settings:: 9 | 10 | SOCIAL_AUTH_STRAVA_KEY = '' 11 | SOCIAL_AUTH_STRAVA_SECRET = '' 12 | 13 | - extra scopes can be defined by using:: 14 | 15 | SOCIAL_AUTH_STRAVA_SCOPE = ['view_private'] 16 | 17 | .. _Strava API: https://www.strava.com/settings/api 18 | -------------------------------------------------------------------------------- /docs/backends/foursquare.rst: -------------------------------------------------------------------------------- 1 | Foursquare 2 | ========== 3 | 4 | Foursquare uses OAuth2. In order to enable the backend follow: 5 | 6 | - Register an application at `Foursquare Developers Portal`_, 7 | set the ``Redirect URI`` to ``http:///complete/foursquare/`` 8 | 9 | - Fill in the **Client Id** and **Client Secret** values in your settings:: 10 | 11 | SOCIAL_AUTH_FOURSQUARE_KEY = '' 12 | SOCIAL_AUTH_FOURSQUARE_SECRET = '' 13 | 14 | .. _Foursquare Developers Portal: https://foursquare.com/developers/register 15 | -------------------------------------------------------------------------------- /docs/copyright.rst: -------------------------------------------------------------------------------- 1 | Copyrights and Licence 2 | ====================== 3 | 4 | ``python-social-auth`` is protected by BSD licence. Check the LICENCE_ for 5 | details. 6 | 7 | The base work was derived from django-social-auth_ work and copyrighted too, 8 | check `django-social-auth LICENCE`_ for details: 9 | 10 | .. _LICENCE: https://github.com/python-social-auth/social-core/blob/master/LICENSE 11 | .. _django-social-auth: https://github.com/omab/django-social-auth 12 | .. _django-social-auth LICENCE: https://github.com/omab/django-social-auth/blob/master/LICENSE 13 | -------------------------------------------------------------------------------- /docs/backends/tripit.rst: -------------------------------------------------------------------------------- 1 | TripIt 2 | ====== 3 | 4 | TripIt offers per application keys named ``API Key`` and ``API Secret``. 5 | To enable TripIt these two keys are needed. Further documentation at 6 | `TripIt Developer Center`_: 7 | 8 | - Register a new application at `TripIt App Registration`_, 9 | 10 | - fill **API Key** and **API Secret** values:: 11 | 12 | SOCIAL_AUTH_TRIPIT_KEY = '' 13 | SOCIAL_AUTH_TRIPIT_SECRET = '' 14 | 15 | .. _TripIt Developer Center: https://www.tripit.com/developer 16 | .. _TripIt App Registration: https://www.tripit.com/developer/create 17 | -------------------------------------------------------------------------------- /docs/backends/stocktwits.rst: -------------------------------------------------------------------------------- 1 | StockTwits 2 | ========== 3 | 4 | StockTwits uses OAuth 2 for authentication. 5 | 6 | - Register a new application at https://stocktwits.com/developers/apps 7 | 8 | - Set the Website URL to http://[your domain]/ 9 | 10 | - fill ``Consumer Key`` and ``Consumer Secret`` values in your django settings:: 11 | 12 | SOCIAL_AUTH_STOCKTWITS_KEY = '' 13 | SOCIAL_AUTH_STOCKTWITS_SECRET = '' 14 | 15 | .. _StockTwits authentication docs: http://stocktwits.com/developers/docs/authentication 16 | .. _StockTwits API: http://stocktwits.com/developers/docs/api 17 | -------------------------------------------------------------------------------- /docs/backends/arcgis.rst: -------------------------------------------------------------------------------- 1 | ArcGIS 2 | ====== 3 | 4 | ArcGIS uses OAuth2 for authentication. 5 | 6 | - Register a new application at `ArcGIS Developer Center`_. 7 | 8 | 9 | OAuth2 10 | ------ 11 | 12 | 1. Add the OAuth2 backend to your settings page:: 13 | 14 | AUTHENTICATION_BACKENDS = ( 15 | ... 16 | 'social_core.backends.arcgis.ArcGISOAuth2', 17 | ... 18 | ) 19 | 20 | 2. Fill ``Client Id`` and ``Client Secret`` values in the settings:: 21 | 22 | SOCIAL_AUTH_ARCGIS_KEY = '' 23 | SOCIAL_AUTH_ARCGIS_SECRET = '' 24 | 25 | .. _ArcGIS Developer Center: https://developers.arcgis.com/ 26 | -------------------------------------------------------------------------------- /docs/backends/lastfm.rst: -------------------------------------------------------------------------------- 1 | Last.fm 2 | ======= 3 | 4 | Last.fm uses a similar authentication process than OAuth2 but it's not. In 5 | order to enable the support for it just: 6 | 7 | - Register an application at `Get an API Account`_, set the Last.fm callback to 8 | something sensible like http://your.site/complete/lastfm 9 | 10 | - Fill in the **API Key** and **API Secret** values in your settings:: 11 | 12 | SOCIAL_AUTH_LASTFM_KEY = '' 13 | SOCIAL_AUTH_LASTFM_SECRET = '' 14 | 15 | - Enable the backend in ``AUTHENTICATION_BACKENDS`` setting. 16 | 17 | .. _Get an API Account: http://www.last.fm/api/account/create 18 | -------------------------------------------------------------------------------- /docs/backends/disqus.rst: -------------------------------------------------------------------------------- 1 | Disqus 2 | ====== 3 | 4 | Disqus uses OAuth v2 for Authentication. 5 | 6 | - Register a new application at the `Disqus API`_, and 7 | 8 | - fill ``Client Id`` and ``Client Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_DISQUS_KEY = '' 11 | SOCIAL_AUTH_DISQUS_SECRET = '' 12 | 13 | - extra scopes can be defined by using:: 14 | 15 | SOCIAL_AUTH_DISQUS_AUTH_EXTRA_ARGUMENTS = {'scope': 'likes comments relationships'} 16 | 17 | Check `Disqus Auth API`_ for details. 18 | 19 | .. _Disqus Auth API: http://disqus.com/api/docs/auth/ 20 | .. _Disqus API: http://disqus.com/api/applications/ 21 | -------------------------------------------------------------------------------- /docs/backends/flickr.rst: -------------------------------------------------------------------------------- 1 | Flickr 2 | ====== 3 | 4 | Flickr uses OAuth v1.0 for authentication. 5 | 6 | - Register a new application at the `Flickr App Garden`_, and 7 | 8 | - fill ``Key`` and ``Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_FLICKR_KEY = '' 11 | SOCIAL_AUTH_FLICKR_SECRET = '' 12 | 13 | - Flickr might show a messages saying "Oops! Flickr doesn't recognise the 14 | permission set.", if encountered with this error, just define this setting:: 15 | 16 | SOCIAL_AUTH_FLICKR_AUTH_EXTRA_ARGUMENTS = {'perms': 'read'} 17 | 18 | 19 | .. _Flickr App Garden: http://www.flickr.com/services/apps/create/ 20 | -------------------------------------------------------------------------------- /docs/backends/stackoverflow.rst: -------------------------------------------------------------------------------- 1 | Stackoverflow 2 | ============= 3 | 4 | Stackoverflow uses OAuth 2.0 5 | 6 | - "Register For An App Key" at the `Stack Exchange API`_ site. Set your OAuth 7 | domain and application website settings. 8 | 9 | - Add the ``Client Id``, ``Client Secret`` and ``API Key`` values in settings:: 10 | 11 | SOCIAL_AUTH_STACKOVERFLOW_KEY = '' 12 | SOCIAL_AUTH_STACKOVERFLOW_SECRET = '' 13 | SOCIAL_AUTH_STACKOVERFLOW_API_KEY = '' 14 | 15 | - You can ask for extra permissions with:: 16 | 17 | SOCIAL_AUTH_STACKOVERFLOW_SCOPE = [...] 18 | 19 | .. _Stack Exchange API: https://api.stackexchange.com/ 20 | -------------------------------------------------------------------------------- /docs/backends/livejournal.rst: -------------------------------------------------------------------------------- 1 | LiveJournal 2 | =========== 3 | 4 | LiveJournal provides OpenID, it doesn't require any major settings in order to 5 | work, beside being defined on ``AUTHENTICATION_BACKENDS```:: 6 | 7 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 8 | ... 9 | 'social_core.backends.aol.AOLOpenId', 10 | ... 11 | ) 12 | 13 | LiveJournal OpenID is provided by URLs in the form ``http://.livejournal.com``, 14 | this application retrieves the ``username`` from the data in the current 15 | request by checking a parameter named ``openid_lj_user`` which can be sent by 16 | ``POST`` or ``GET``. 17 | -------------------------------------------------------------------------------- /docs/backends/thisismyjam.rst: -------------------------------------------------------------------------------- 1 | ThisIsMyJam 2 | =========== 3 | 4 | ThisIsMyJam uses OAuth1 for its auth mechanism. 5 | 6 | - Register a new application at `ThisIsMyJam App Registration`_, set your 7 | application name, website and redirect URI. 8 | 9 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 10 | 11 | SOCIAL_AUTH_THISISMYJAM_KEY = '' 12 | SOCIAL_AUTH_THISISMYJAM_SECRET = '' 13 | 14 | Check the rest of their doc at `ThisIsMyJam API Docs`_. 15 | 16 | .. _ThisIsMyJam App Registration: https://www.thisismyjam.com/developers 17 | .. _ThisIsMyJam API Docs: https://www.thisismyjam.com/developers/docs 18 | -------------------------------------------------------------------------------- /docs/backends/twilio.rst: -------------------------------------------------------------------------------- 1 | Twilio 2 | ====== 3 | 4 | - Register a new application at `Twilio Connect Api`_ 5 | 6 | - Fill ``SOCIAL_AUTH_TWILIO_KEY`` and ``SOCIAL_AUTH_TWILIO_SECRET`` values in 7 | the settings:: 8 | 9 | SOCIAL_AUTH_TWILIO_KEY = '' 10 | SOCIAL_AUTH_TWILIO_SECRET = '' 11 | 12 | - Add desired authentication backends to Django's ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS`` 13 | setting:: 14 | 15 | 'social_core.backends.twilio.TwilioAuth', 16 | 17 | - Usage example:: 18 | 19 | Enter using Twilio 20 | 21 | 22 | .. _Twilio Connect API: https://www.twilio.com/user/account/connect/apps 23 | -------------------------------------------------------------------------------- /docs/backends/angel.rst: -------------------------------------------------------------------------------- 1 | Angel List 2 | ========== 3 | 4 | Angel uses OAuth v2 for Authentication. 5 | 6 | - Register a new application at the `Angel List API`_, and 7 | 8 | - fill ``Client Id`` and ``Client Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_ANGEL_KEY = '' 11 | SOCIAL_AUTH_ANGEL_SECRET = '' 12 | 13 | - extra scopes can be defined by using:: 14 | 15 | SOCIAL_AUTH_ANGEL_AUTH_EXTRA_ARGUMENTS = {'scope': 'email messages'} 16 | 17 | **Note:** 18 | Angel List does not currently support returning ``state`` parameter used to 19 | validate the auth process. 20 | 21 | .. _Angel List API: https://angel.co/api/oauth/faq 22 | -------------------------------------------------------------------------------- /docs/backends/udata.rst: -------------------------------------------------------------------------------- 1 | Udata 2 | ===== 3 | 4 | Datagouvfr OAuth2 5 | ----------------- 6 | 7 | `Datagouvfr`_ supports OAuth2 for their API. In order to set it up: 8 | 9 | - Go get your `your API key`_ (previous account creation is required). 10 | 11 | - Fill **Consumer Key** and **Consumer Secret** values in settings:: 12 | 13 | SOCIAL_AUTH_DATAGOUVFR_KEY = '' 14 | SOCIAL_AUTH_DATAGOUVFR_SECRET = '' 15 | 16 | - Add ``'social_core.backends.udata.DatagouvfrOAuth2'`` into your 17 | ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS``. 18 | 19 | .. _your API key: https://www.data.gouv.fr/fr/admin/me/ 20 | .. _Datagouvfr: https://www.data.gouv.fr/ 21 | -------------------------------------------------------------------------------- /docs/configuration/index.rst: -------------------------------------------------------------------------------- 1 | Configuration 2 | ============= 3 | 4 | All the apps share the settings names, some settings for Django framework are 5 | special (like ``AUTHENTICATION_BACKENDS``). 6 | 7 | Below there's a main settings document detailing each configuration and its 8 | purpose, plus sections detailed for each framework and their particularities. 9 | 10 | Support for more frameworks will be added in the future, pull-requests are very 11 | welcome. 12 | 13 | Contents: 14 | 15 | .. toctree:: 16 | :maxdepth: 2 17 | 18 | settings 19 | django 20 | flask 21 | pyramid 22 | cherrypy 23 | webpy 24 | porting_from_dsa 25 | -------------------------------------------------------------------------------- /docs/backends/beats.rst: -------------------------------------------------------------------------------- 1 | Beats 2 | ===== 3 | 4 | Beats supports OAuth 2. 5 | 6 | - Register a new application at `Beats Music API`_, and follow the 7 | instructions below. 8 | 9 | OAuth2 10 | ------ 11 | 12 | Add the Beats OAuth2 backend to your settings page:: 13 | 14 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 15 | ... 16 | 'social_core.backends.beats.BeatsOAuth2', 17 | ... 18 | ) 19 | 20 | - Fill ``App Key`` and ``App Secret`` values in the settings:: 21 | 22 | SOCIAL_AUTH_BEATS_OAUTH2_KEY = '' 23 | SOCIAL_AUTH_BEATS_OAUTH2_SECRET = '' 24 | 25 | .. _Beats Music API: https://developer.beatsmusic.com/docs 26 | -------------------------------------------------------------------------------- /docs/backends/lifescience.rst: -------------------------------------------------------------------------------- 1 | Lifescience AAI 2 | =============== 3 | 4 | Lifescience's OpenID Connect (OIDC) backend requires the following minimum 5 | configuration:: 6 | 7 | SOCIAL_AUTH_LIFESCIENCE_OIDC_KEY = '' 8 | SOCIAL_AUTH_LIFESCIENCE_OIDC_SECRET = '' 9 | 10 | Scopes 11 | ------ 12 | 13 | The default scopes will include the user's email. 14 | You can request additional claims, for example:: 15 | 16 | SOCIAL_AUTH_LIFESCIENCE_OIDC_SCOPE = ['eduperson_entitlement'] 17 | 18 | and you can prevent the inclusion of the default scopes using:: 19 | 20 | SOCIAL_AUTH_LIFESCIENCE_OIDC_IGNORE_DEFAULT_SCOPE = True 21 | -------------------------------------------------------------------------------- /docs/backends/twitch.rst: -------------------------------------------------------------------------------- 1 | Twitch 2 | ====== 3 | 4 | Twitch works similar to Facebook (OAuth). 5 | 6 | - Register a new application in the `connections tab`_ of your Twitch settings 7 | page, set the callback URL to ``http://example.com/complete/twitch/`` 8 | replacing ``example.com`` with your domain. 9 | 10 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 11 | 12 | SOCIAL_AUTH_TWITCH_KEY = '' 13 | SOCIAL_AUTH_TWITCH_SECRET = '' 14 | 15 | - Also it's possible to define extra permissions with:: 16 | 17 | SOCIAL_AUTH_TWITCH_SCOPE = [...] 18 | 19 | .. _connections tab: http://www.twitch.tv/settings/connections 20 | -------------------------------------------------------------------------------- /docs/backends/justgiving.rst: -------------------------------------------------------------------------------- 1 | Just Giving 2 | =========== 3 | 4 | OAuth2 5 | ------ 6 | 7 | Follow the steps at `Just Giving API Docs`_ to register your 8 | application and get the needed keys. 9 | 10 | - Add the Just Giving OAuth2 backend to your settings page:: 11 | 12 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 13 | ... 14 | 'social_core.backends.justgiving.JustGivingOAuth2', 15 | ... 16 | ) 17 | 18 | - Fill ``App Key`` and ``App Secret`` values in the settings:: 19 | 20 | SOCIAL_AUTH_JUSTGIVING_KEY = '' 21 | SOCIAL_AUTH_JUSTGIVING_SECRET = '' 22 | 23 | .. _Just Giving API Docs: https://api.justgiving.com/docs 24 | -------------------------------------------------------------------------------- /docs/backends/spotify.rst: -------------------------------------------------------------------------------- 1 | Spotify 2 | ======= 3 | 4 | Spotify supports OAuth 2. 5 | 6 | - Register a new application at `Spotify Web API`_, and follow the 7 | instructions below. 8 | 9 | OAuth2 10 | ------ 11 | 12 | Add the Spotify OAuth2 backend to your settings page:: 13 | 14 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 15 | ... 16 | 'social_core.backends.spotify.SpotifyOAuth2', 17 | ... 18 | ) 19 | 20 | - Fill ``App Key`` and ``App Secret`` values in the settings:: 21 | 22 | SOCIAL_AUTH_SPOTIFY_KEY = '' 23 | SOCIAL_AUTH_SPOTIFY_SECRET = '' 24 | 25 | .. _Spotify Web API: https://developer.spotify.com/spotify-web-api 26 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.py[cod] 2 | 3 | # C extensions 4 | *.so 5 | 6 | # Packages 7 | *.egg 8 | *.egg-info 9 | dist 10 | build 11 | eggs 12 | parts 13 | bin 14 | var 15 | sdist 16 | develop-eggs 17 | .installed.cfg 18 | lib 19 | lib64 20 | 21 | # Installer logs 22 | pip-log.txt 23 | 24 | # Unit test / coverage reports 25 | .coverage 26 | .tox 27 | nosetests.xml 28 | 29 | # Translations 30 | *.mo 31 | 32 | # Mr Developer 33 | .mr.developer.cfg 34 | .project 35 | .pydevproject 36 | 37 | # PyCharm 38 | .idea/ 39 | 40 | test.db 41 | local_settings.py 42 | sessions/ 43 | _build/ 44 | fabfile.py 45 | changelog.sh 46 | 47 | .DS_Store 48 | .\#* 49 | \#*\# 50 | 51 | .python-version 52 | -------------------------------------------------------------------------------- /docs/backends/eventbrite.rst: -------------------------------------------------------------------------------- 1 | Eventbrite OAuth 2 | ================ 3 | 4 | Eventbrite OAuth 2.0 for its authentication workflow. 5 | 6 | - Register a new application at `Account Settings` in `App Management`_. 7 | 8 | - Fill ``Consumer Key`` and ``Consumer Secret`` values in the settings 9 | using ``Application Key`` and ``OAuth Client Secret`` provided by 10 | Eventbrite's created app:: 11 | 12 | SOCIAL_AUTH_EVENTBRITE_KEY = '' 13 | SOCIAL_AUTH_EVENTBRITE_SECRET = '' 14 | 15 | 16 | .. _Eventbrite API docs: https://www.eventbrite.com/developer/v3/ 17 | .. _App Management: https://www.eventbrite.com/myaccount/apps/ 18 | -------------------------------------------------------------------------------- /docs/backends/readability.rst: -------------------------------------------------------------------------------- 1 | Readability 2 | =========== 3 | 4 | Readability works similarly to Twitter, in that you'll need a ``Consumer Key`` 5 | and ``Consumer Secret``. These can be obtained in the ``Connections`` section 6 | of your ``Account`` page. 7 | 8 | - Fill the **Consumer Key** and **Consumer Secret** values in your settings:: 9 | 10 | SOCIAL_AUTH_READABILITY_KEY = '' 11 | SOCIAL_AUTH_READABILITY_SECRET = '' 12 | 13 | That's it! By default you'll get back:: 14 | 15 | username 16 | first_name 17 | last_name 18 | 19 | with EXTRA_DATA, you can get:: 20 | 21 | date_joined 22 | kindle_email_address 23 | avatar_url 24 | email_into_address 25 | -------------------------------------------------------------------------------- /docs/backends/quizlet.rst: -------------------------------------------------------------------------------- 1 | Quizlet 2 | ======= 3 | 4 | Quizlet uses OAuth v2 for Authentication. 5 | 6 | - Register a new application at the `Quizlet API`_, and 7 | 8 | - Add the Quizlet backend to ``AUTHENTICATION_SETTINGS``:: 9 | 10 | AUTHENTICATION_SETTINGS = ( 11 | ... 12 | 'social_core.backends.quizlet.QuizletOAuth2', 13 | ... 14 | ) 15 | 16 | - fill ``Client Id`` and ``Client Secret`` values in the settings:: 17 | 18 | SOCIAL_AUTH_QUIZLET_KEY = '' 19 | SOCIAL_AUTH_QUIZLET_SECRET = '' 20 | SOCIAL_AUTH_QUIZLET_SCOPE = ['read', 'write_set'] # 'write_group' is also available 21 | 22 | .. _Quizlet API: https://quizlet.com/api-dashboard 23 | -------------------------------------------------------------------------------- /docs/backends/docker.rst: -------------------------------------------------------------------------------- 1 | Docker 2 | ====== 3 | 4 | Docker.io OAuth2 5 | ---------------- 6 | 7 | Docker.io now supports OAuth2 for their API. In order to set it up: 8 | 9 | - Register a new application by following the instructions in their website: 10 | `Register Your Application`_ 11 | 12 | - Fill **Consumer Key** and **Consumer Secret** values in settings:: 13 | 14 | SOCIAL_AUTH_DOCKER_KEY = '' 15 | SOCIAL_AUTH_DOCKER_SECRET = '' 16 | 17 | - Add ``'social_core.backends.docker.DockerOAuth2'`` into your 18 | ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS``. 19 | 20 | .. _Register Your Application: http://docs.docker.io/en/latest/reference/api/docker_io_oauth_api/#register-your-application 21 | -------------------------------------------------------------------------------- /docs/backends/vend.rst: -------------------------------------------------------------------------------- 1 | Vend 2 | ==== 3 | 4 | Vend supports OAuth 2. 5 | 6 | - Register a new application at `Vend Developers Portal`_ 7 | 8 | - Add the Vend OAuth2 backend to your settings page:: 9 | 10 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 11 | ... 12 | 'social_core.backends.vend.VendOAuth2', 13 | ... 14 | ) 15 | 16 | - Fill ``App Key`` and ``App Secret`` values in the settings:: 17 | 18 | SOCIAL_AUTH_VEND_OAUTH2_KEY = '' 19 | SOCIAL_AUTH_VEND_OAUTH2_SECRET = '' 20 | 21 | More details on their docs_. 22 | 23 | .. _Vend Developers Portal: https://developers.vendhq.com/developer/applications 24 | .. _docs: https://developers.vendhq.com/documentation 25 | -------------------------------------------------------------------------------- /docs/backends/patreon.rst: -------------------------------------------------------------------------------- 1 | Patreon 2 | ======= 3 | 4 | Patreon supports OAuth 2.0 5 | 6 | 1. Register a new application at `Patreon Developer Portal`_. 7 | 2. Use the ``social.backends.patreon.PatreonOAuth2``, either by adding it to 8 | your ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS`` or instantiating it directly. 9 | 3. Fill in the the ``Client ID`` and ``Client Secret``:: 10 | 11 | SOCIAL_AUTH_PATREON_KEY = '' 12 | SOCIAL_AUTH_PATREON_SECRET = '' 13 | 14 | 4. Checkout the `Patreon API Docs`_ for more information. 15 | 16 | .. _Patreon Developer Portal: https://www.patreon.com/portal/registration/register-clients 17 | .. _Patreon API Docs: https://docs.patreon.com/ 18 | -------------------------------------------------------------------------------- /docs/backends/changetip.rst: -------------------------------------------------------------------------------- 1 | ChangeTip 2 | ========= 3 | 4 | ChangeTip 5 | 6 | - Register a new application at ChangeTip_, set the callback URL to 7 | ``http://example.com/complete/changetip/`` replacing ``example.com`` with your 8 | domain. 9 | 10 | - Fill ``Client ID`` and ``Client Secret`` values in the settings:: 11 | 12 | SOCIAL_AUTH_CHANGETIP_KEY = '' 13 | SOCIAL_AUTH_CHANGETIP_SECRET = '' 14 | 15 | - Also it's possible to define extra permissions with:: 16 | 17 | SOCIAL_AUTH_CHANGETIP_SCOPE = [...] 18 | 19 | See auth scopes at `ChangeTip OAuth docs`_. 20 | 21 | .. _ChangeTip: https://www.changetip.com/api 22 | .. _ChangeTip OAuth docs: https://www.changetip.com/api/auth/#!#scopes 23 | -------------------------------------------------------------------------------- /docs/backends/dribbble.rst: -------------------------------------------------------------------------------- 1 | Dribbble 2 | ======== 3 | 4 | Dribbble 5 | 6 | - Register a new application at Dribbble_, set the callback URL 7 | to ``http://example.com/complete/dribbble/`` replacing 8 | ``example.com`` with your domain. 9 | 10 | - Fill ``Client ID`` and ``Client Secret`` values in the settings:: 11 | 12 | SOCIAL_AUTH_DRIBBBLE_KEY = '' 13 | SOCIAL_AUTH_DRIBBBLE_SECRET = '' 14 | 15 | - Also it's possible to define extra permissions with:: 16 | 17 | SOCIAL_AUTH_DRIBBBLE_SCOPE = [...] 18 | 19 | See auth scopes at `Dribbble Developer docs`_. 20 | 21 | 22 | .. _Dribbble: https://dribbble.com/account/applications/new 23 | .. _Dribbble Developer docs: http://developer.dribbble.com/v1/oauth/ 24 | -------------------------------------------------------------------------------- /docs/backends/shimmering.rst: -------------------------------------------------------------------------------- 1 | Shimmering Verify 2 | ================= 3 | 4 | Shimmering implemented OAuth2 protocol for their authentication mechanism. To 5 | enable ``python-social_core-auth`` support follow this steps: 6 | 7 | 1. Go to `Shimmering Developer Console`_ and create an application. 8 | 9 | 2. Fill App Id and Secret in your project settings:: 10 | 11 | SOCIAL_AUTH_SHIMMERING_KEY = '...' 12 | SOCIAL_AUTH_SHIMMERING_SECRET = '...' 13 | 14 | 3. Enable the backend:: 15 | 16 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 17 | ... 18 | 'social_core.backends.shimmering.ShimmeringOAuth2', 19 | ... 20 | ) 21 | 22 | .. _Shimmering Developer Console: http://developers.shimmeringverify.com 23 | -------------------------------------------------------------------------------- /docs/backends/edmodo.rst: -------------------------------------------------------------------------------- 1 | Edmodo 2 | ====== 3 | 4 | Edmodo supports OAuth 2. 5 | 6 | - Register a new application at `Edmodo Connect API`_, and follow the 7 | instructions below. 8 | - Add the Edmodo OAuth2 backend to your settings page:: 9 | 10 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 11 | ... 12 | 'social_core.backends.edmodo.EdmodoOAuth2', 13 | ... 14 | ) 15 | 16 | - Fill ``App Key``, ``App Secret`` and ``App Scope`` values in the settings:: 17 | 18 | SOCIAL_AUTH_EDMODO_OAUTH2_KEY = '' 19 | SOCIAL_AUTH_EDMODO_OAUTH2_SECRET = '' 20 | SOCIAL_AUTH_EDMODO_SCOPE = ['basic'] 21 | 22 | .. _Edmodo Connect API: https://developers.edmodo.com/edmodo-connect/edmodo-connect-overview-getting-started/ 23 | -------------------------------------------------------------------------------- /docs/backends/slack.rst: -------------------------------------------------------------------------------- 1 | Slack 2 | ===== 3 | 4 | Slack 5 | 6 | - Register a new application at Slack_, set the callback URL to 7 | ``http://example.com/complete/slack/`` replacing ``example.com`` with your 8 | domain. 9 | 10 | - Fill ``Client ID`` and ``Client Secret`` values in the settings:: 11 | 12 | SOCIAL_AUTH_SLACK_KEY = '' 13 | SOCIAL_AUTH_SLACK_SECRET = '' 14 | 15 | - Also it's possible to define extra permissions with:: 16 | 17 | SOCIAL_AUTH_SLACK_SCOPE = [...] 18 | 19 | See auth scopes at `Slack OAuth docs`_. 20 | 21 | - Limiting by team is possible by:: 22 | 23 | SOCIAL_AUTH_SLACK_TEAM = '' 24 | 25 | .. _Slack: https://api.slack.com/applications 26 | .. _Slack OAuth docs: https://api.slack.com/docs/oauth 27 | -------------------------------------------------------------------------------- /docs/backends/uber.rst: -------------------------------------------------------------------------------- 1 | Uber 2 | ==== 3 | 4 | Uber uses OAuth v2 for Authentication. 5 | 6 | - Register a new application at the `Uber API`_, and follow the instructions below 7 | 8 | OAuth2 9 | ------ 10 | 11 | 1. Add the Uber OAuth2 backend to your settings page:: 12 | 13 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 14 | ... 15 | 'social_core.backends.uber.UberOAuth2', 16 | ... 17 | ) 18 | 19 | 2. Fill ``Client Id`` and ``Client Secret`` values in the settings:: 20 | 21 | SOCIAL_AUTH_UBER_KEY = '' 22 | SOCIAL_AUTH_UBER_SECRET = '' 23 | 24 | 3. Scope should be defined by using:: 25 | 26 | SOCIAL_AUTH_UBER_SCOPE = ['profile', 'request'] 27 | 28 | .. _Uber API: https://developer.uber.com/dashboard 29 | -------------------------------------------------------------------------------- /docs/backends/skyrock.rst: -------------------------------------------------------------------------------- 1 | Skyrock 2 | ======= 3 | 4 | OAuth based Skyrock Connect. 5 | 6 | Skyrock offers per application keys named ``Consumer Key`` and ``Consumer 7 | Secret``. To enable Skyrock these two keys are needed. Further documentation 8 | at `Skyrock developer resources`_: 9 | 10 | - Register a new application at `Skyrock App Creation`_, 11 | 12 | - Your callback domain should match your application URL in your application 13 | configuration. 14 | 15 | - Fill **Consumer Key** and **Consumer Secret** values:: 16 | 17 | SOCIAL_AUTH_SKYROCK_KEY = '' 18 | SOCIAL_AUTH_SKYROCK_SECRET = '' 19 | 20 | .. _Skyrock developer resources: http://www.skyrock.com/developer/ 21 | .. _Skyrock App Creation: https://wwwskyrock.com/developer/application 22 | -------------------------------------------------------------------------------- /docs/backends/instagram.rst: -------------------------------------------------------------------------------- 1 | Instagram 2 | ========= 3 | 4 | Instagram uses OAuth v2 for Authentication. 5 | 6 | - Register a new application at the `Instagram API`_, and 7 | 8 | - Add instagram backend to ``AUTHENTICATION_SETTINGS``:: 9 | 10 | AUTHENTICATION_SETTINGS = ( 11 | ... 12 | 'social_core.backends.instagram.InstagramOAuth2', 13 | ... 14 | ) 15 | 16 | - fill ``Client Id`` and ``Client Secret`` values in the settings:: 17 | 18 | SOCIAL_AUTH_INSTAGRAM_KEY = '' 19 | SOCIAL_AUTH_INSTAGRAM_SECRET = '' 20 | 21 | - extra scopes can be defined by using:: 22 | 23 | SOCIAL_AUTH_INSTAGRAM_AUTH_EXTRA_ARGUMENTS = {'scope': 'likes comments relationships'} 24 | 25 | .. _Instagram API: http://instagr.am/developer/ 26 | -------------------------------------------------------------------------------- /docs/backends/steam.rst: -------------------------------------------------------------------------------- 1 | Steam OpenID 2 | ============ 3 | 4 | Steam OpenID works quite straightforward, but to retrieve some user data (known 5 | as ``player`` on Steam API) a Steam API Key is needed. 6 | 7 | Configurable settings: 8 | 9 | 10 | 1. Supply a Steam API Key from `Steam Dev`_ 11 | 12 | 2. Fill key in your project settings:: 13 | 14 | SOCIAL_AUTH_STEAM_API_KEY = '...' 15 | 16 | 3. To save ``player`` data provided by Steam into ``extra_data``:: 17 | 18 | SOCIAL_AUTH_STEAM_EXTRA_DATA = ['player'] 19 | 20 | 4. Enable the backend:: 21 | 22 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 23 | ... 24 | 'social_core.backends.steam.SteamOpenId', 25 | ... 26 | ) 27 | 28 | .. _Steam Dev: http://steamcommunity.com/dev/apikey 29 | -------------------------------------------------------------------------------- /docs/backends/box.rst: -------------------------------------------------------------------------------- 1 | Box.net 2 | ======= 3 | 4 | Box works similar to Facebook (OAuth2). 5 | 6 | - Register an application at `Manage Box Applications`_ 7 | 8 | - Fill the **Consumer Key** and **Consumer Secret** values in your settings:: 9 | 10 | SOCIAL_AUTH_BOX_KEY = '' 11 | SOCIAL_AUTH_BOX_SECRET = '' 12 | 13 | - By default the token is not permanent, it will last an hour. To refresh the 14 | access token just do:: 15 | 16 | from social_django.utils import load_strategy 17 | 18 | strategy = load_strategy(backend='box') 19 | user = User.objects.get(pk=foo) 20 | social = user.social_auth.filter(provider='box')[0] 21 | social.refresh_token(strategy=strategy) 22 | 23 | .. _Manage Box Applications: https://app.box.com/developers/services 24 | -------------------------------------------------------------------------------- /docs/backends/coinbase.rst: -------------------------------------------------------------------------------- 1 | Coinbase 2 | ======== 3 | 4 | Coinbase uses OAuth2. 5 | 6 | - Register an application at Coinbase_ 7 | 8 | - Fill in the **Client Id** and **Client Secret** values in your settings:: 9 | 10 | SOCIAL_AUTH_COINBASE_KEY = '' 11 | SOCIAL_AUTH_COINBASE_SECRET = '' 12 | 13 | - Set the ``redirect_url`` on coinbase. Make sure to include the trailing 14 | slash, eg. ``http://hostname/complete/coinbase/`` 15 | 16 | - Specify scopes with:: 17 | 18 | SOCIAL_AUTH_COINBASE_SCOPE = [...] 19 | 20 | By default the scope is set to ``balance``. 21 | 22 | - extra scopes can be defined by using:: 23 | 24 | SOCIAL_AUTH_COINBASE_AUTH_EXTRA_ARGUMENTS = {'account': 'all'} 25 | 26 | .. _Coinbase: https://coinbase.com/oauth/applications/new 27 | -------------------------------------------------------------------------------- /docs/backends/upwork.rst: -------------------------------------------------------------------------------- 1 | Upwork 2 | ====== 3 | 4 | Upwork supports only OAuth 1. 5 | 6 | - Register a new application at `Upwork Developers`_. 7 | 8 | OAuth1 9 | ------ 10 | 11 | Add the Upwork OAuth backend to your settings page:: 12 | 13 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 14 | ... 15 | 'social_core.backends.upwork.UpworkOAuth', 16 | ... 17 | ) 18 | 19 | - Fill ``App Key`` and ``App Secret`` values in the settings:: 20 | 21 | SOCIAL_AUTH_UPWORK_KEY = '' 22 | SOCIAL_AUTH_UPWORK_SECRET = '' 23 | 24 | 25 | **Note:** For more information please go to `Upwork API Reference`_. 26 | 27 | .. _Upwork Developers: https://www.upwork.com/services/api/apply 28 | .. _Upwork API Reference: https://developers.upwork.com/?lang=python 29 | -------------------------------------------------------------------------------- /docs/backends/discogs.rst: -------------------------------------------------------------------------------- 1 | Discogs 2 | ======= 3 | 4 | Discogs uses OAuth v1 for Authentication. 5 | 6 | - Register a new application int the `Discogs API settings <_discogs_settings>`_, and 7 | 8 | - Add the Discogs backend to your settings page:: 9 | 10 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 11 | ... 12 | "social_core.backends.discogs.DiscogsOAuth1", 13 | ... 14 | ) 15 | 16 | - Add the ``Client Id`` and ``Client Secret`` values in the settings:: 17 | 18 | SOCIAL_AUTH_DISCOGS_KEY = '' 19 | SOCIAL_AUTH_DISCOGS_SECRET = '' 20 | 21 | Check `Discogs API documentation <_discogs_docs>`_ for details. 22 | 23 | .. _discogs_settings: https://www.discogs.com/settings/developers 24 | .. _discogs_docs: https://www.discogs.com/developers/ 25 | -------------------------------------------------------------------------------- /docs/backends/evernote.rst: -------------------------------------------------------------------------------- 1 | Evernote OAuth 2 | ============== 3 | 4 | Evernote OAuth 1.0 for its authentication workflow. 5 | 6 | - Register a new application at `Evernote API Key form`_. 7 | 8 | - Fill ``Consumer Key`` and ``Consumer Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_EVERNOTE_KEY = '' 11 | SOCIAL_AUTH_EVERNOTE_SECRET = '' 12 | 13 | 14 | Sandbox 15 | ------- 16 | 17 | Evernote supports a sandbox mode for testing, there's a custom backend for it 18 | which name is ``evernote-sandbox`` instead of ``evernote``. Same settings apply 19 | but use these instead:: 20 | 21 | SOCIAL_AUTH_EVERNOTE_SANDBOX_KEY = '' 22 | SOCIAL_AUTH_EVERNOTE_SANDBOX_SECRET = '' 23 | 24 | .. _Evernote API Key form: http://dev.evernote.com/support/api_key.php 25 | -------------------------------------------------------------------------------- /docs/backends/microsoftgraph.rst: -------------------------------------------------------------------------------- 1 | Microsoft Graph 2 | =============== 3 | 4 | 5 | 1. Go to `Azure portal`_ and create an application. 6 | 7 | 2. Fill App Id and Secret in your project settings:: 8 | 9 | SOCIAL_AUTH_MICROSOFT_GRAPH_KEY = '...' 10 | SOCIAL_AUTH_MICROSOFT_GRAPH_SECRET = '...' 11 | 12 | 13 | 3. Enable the backend:: 14 | 15 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 16 | ... 17 | 'social_core.backends.microsoft.MicrosoftOAuth2', 18 | ... 19 | ) 20 | 21 | `Register an application with the Microsoft identity platform`_. 22 | 23 | .. _Azure portal: https://portal.azure.com/ 24 | .. _Register an application with the Microsoft identity platform: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app 25 | -------------------------------------------------------------------------------- /docs/backends/kick.rst: -------------------------------------------------------------------------------- 1 | Kick 2 | ==== 3 | 4 | Kick works similar to Facebook (OAuth) but with Oauth2.1. 5 | 6 | - Register a new application in the `developer tab`_ of your Kick settings 7 | page, set the callback URL to ``http://example.com/complete/kick/`` 8 | replacing ``example.com`` with your domain. 9 | 10 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 11 | 12 | SOCIAL_AUTH_KICK_KEY = '' 13 | SOCIAL_AUTH_KICK_SECRET = '' 14 | 15 | - Also it's possible to define extra permissions with:: 16 | 17 | SOCIAL_AUTH_KICK_SCOPE = [...] 18 | 19 | Further documentation at `Developer Guide`_. 20 | 21 | .. _developer tab: https://kick.com/settings/developer 22 | .. _Developer Guide: https://docs.kick.com/getting-started/generating-tokens-oauth2-flow 23 | -------------------------------------------------------------------------------- /docs/backends/jawbone.rst: -------------------------------------------------------------------------------- 1 | Jawbone 2 | ======= 3 | 4 | Jawbone uses OAuth2. In order to enable the backend follow: 5 | 6 | - Register an application at `Jawbone Developer Portal`_, set the ``OAuth 7 | redirect URIs`` to ``http:///complete/jawbone/`` 8 | 9 | - Fill in the **Client Id** and **Client Secret** values in your settings:: 10 | 11 | SOCIAL_AUTH_JAWBONE_KEY = '' 12 | SOCIAL_AUTH_JAWBONE_SECRET = '' 13 | 14 | - Specify scopes with:: 15 | 16 | SOCIAL_AUTH_JAWBONE_SCOPE = [...] 17 | 18 | Available scopes are listed in the `Jawbone Authentication Reference`_, 19 | "socpes" section. 20 | 21 | .. _Jawbone Developer Portal: https://jawbone.com/up/developer/account/ 22 | .. _Jawbone Authentication Reference: https://jawbone.com/up/developer/authentication 23 | -------------------------------------------------------------------------------- /docs/backends/mineid.rst: -------------------------------------------------------------------------------- 1 | MineID 2 | ====== 3 | 4 | MineID works similar to Facebook (OAuth). 5 | 6 | - Register a new application at `MineID.org`_, set the callback URL to 7 | ``http://example.com/complete/mineid/`` replacing ``example.com`` with your 8 | domain. 9 | 10 | - Fill ``Client ID`` and ``Client Secret`` values in the settings:: 11 | 12 | SOCIAL_AUTH_MINEID_KEY = '' 13 | SOCIAL_AUTH_MINEID_SECRET = '' 14 | 15 | 16 | Self-hosted MineID 17 | ------------------ 18 | 19 | Since MineID is an Open Source software and can be self-hosted, you can 20 | change settings to point to your instance:: 21 | 22 | SOCIAL_AUTH_MINEID_HOST = 'www.your-mineid-instance.com' 23 | SOCIAL_AUTH_MINEID_SCHEME = 'https' # or 'http' 24 | 25 | .. _MineID.org: https://www.mineid.org/ 26 | -------------------------------------------------------------------------------- /docs/backends/naver.rst: -------------------------------------------------------------------------------- 1 | Naver 2 | ===== 3 | 4 | Naver uses OAuth v2 for Authentication. 5 | 6 | - Register a new application at the `Naver API`_, and 7 | 8 | - add naver oauth backend to your settings page:: 9 | 10 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 11 | ... 12 | 'social_core.backends.naver.NaverOAuth2', 13 | ... 14 | ) 15 | 16 | - fill ``Client ID`` and ``Client Secret`` from developer.naver.com 17 | values in the settings:: 18 | 19 | SOCIAL_AUTH_NAVER_KEY = '' 20 | SOCIAL_AUTH_NAVER_SECRET = '' 21 | 22 | - you can get EXTRA_DATA:: 23 | 24 | SOCIAL_AUTH_NAVER_EXTRA_DATA = ['nickname', 'gender', 'age', 25 | 'birthday', 'profile_image'] 26 | 27 | .. _Naver API: https://nid.naver.com/devcenter/docs.nhn?menu=API 28 | -------------------------------------------------------------------------------- /docs/backends/zotero.rst: -------------------------------------------------------------------------------- 1 | Zotero 2 | ====== 3 | 4 | Zotero implements OAuth1 as their authentication mechanism for their Web API v3. 5 | 6 | 7 | 1. Go to the `Zotero app registration page`_ to register your application. 8 | 9 | 2. Fill the **Client ID** and **Client Secret** in your project settings:: 10 | 11 | SOCIAL_AUTH_ZOTERO_KEY = '...' 12 | SOCIAL_AUTH_ZOTERO_SECRET = '...' 13 | 14 | 3. Enable the backend:: 15 | 16 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 17 | ... 18 | 'social_core.backends.zotero.ZoteroOAuth', 19 | ... 20 | ) 21 | 22 | Further documentation at `Zotero Web API v3 page`_. 23 | 24 | .. _Zotero app registration page: https://www.zotero.org/oauth/apps 25 | .. _Zotero Web API v3 page: https://www.zotero.org/support/dev/web_api/v3/start 26 | -------------------------------------------------------------------------------- /docs/backends/weibo.rst: -------------------------------------------------------------------------------- 1 | Weibo OAuth 2 | =========== 3 | 4 | Weibo OAuth 2.0 workflow. 5 | 6 | - Register a new application at Weibo_. 7 | 8 | - Fill ``Consumer Key`` and ``Consumer Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_WEIBO_KEY = '' 11 | SOCIAL_AUTH_WEIBO_SECRET = '' 12 | 13 | By default ``account id``, ``profile_image_url`` and ``gender`` are stored in 14 | extra_data field. 15 | 16 | The user name is used by default to build the user instance ``username``, 17 | sometimes this contains non-ASCII characters which might not be desirable for 18 | the website. To avoid this issue it's possible to use the Weibo ``domain`` 19 | which will be inside the ASCII range by defining this setting:: 20 | 21 | SOCIAL_AUTH_WEIBO_DOMAIN_AS_USERNAME = True 22 | 23 | .. _Weibo: http://open.weibo.com 24 | -------------------------------------------------------------------------------- /docs/backends/discord.rst: -------------------------------------------------------------------------------- 1 | Discord 2 | ======= 3 | 4 | Discord uses OAuth2 for authentication. 5 | 6 | - Register a new application at the `Discord Developer Portal`_, set the 7 | callback URL to ``http://example.com/complete/discord/`` replacing 8 | ``example.com`` with your domain. 9 | 10 | - Fill ``Client ID`` and ``Client Secret`` values in the settings:: 11 | 12 | SOCIAL_AUTH_DISCORD_KEY = '' 13 | SOCIAL_AUTH_DISCORD_SECRET = '' 14 | 15 | - Also it's possible to define extra permissions with:: 16 | 17 | SOCIAL_AUTH_DISCORD_SCOPE = [...] 18 | 19 | See available scopes at `Discord OAuth2 Scopes`_. 20 | 21 | .. _Discord Developer Portal: https://discord.com/developers/applications 22 | .. _Discord OAuth2 Scopes: https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes 23 | -------------------------------------------------------------------------------- /docs/backends/mailru.rst: -------------------------------------------------------------------------------- 1 | Mail.ru OAuth 2 | ============= 3 | 4 | Mail.ru uses OAuth2 workflow. `Register new application`_ to use it and fill in settings:: 5 | 6 | SOCIAL_AUTH_MAILRU_KEY = '' 7 | SOCIAL_AUTH_MAILRU_SECRET = '' 8 | 9 | 10 | Add ``social_core.backends.mailru.MRGOAuth2`` to ``AUTHENTICATION_BACKENDS`` to activate Mail.ru authorization. 11 | 12 | Legacy OAuth2 authorization 13 | --------------------------- 14 | 15 | Also available ``social_core.backends.mailru.MailruOAuth2`` for authorization with ``connect.mail.ru`` server. 16 | 17 | `Create an app`_ and set following settings:: 18 | 19 | SOCIAL_AUTH_MAILRU_OAUTH2_KEY = '' 20 | SOCIAL_AUTH_MAILRU_OAUTH2_SECRET = '' 21 | 22 | .. _Register new application: https://oauth.mail.ru/app/ 23 | .. _Create an app: https://api.mail.ru/sites/my/add 24 | -------------------------------------------------------------------------------- /docs/backends/gitea.rst: -------------------------------------------------------------------------------- 1 | Gitea 2 | ====== 3 | 4 | Gitea supports OAuth2 protocol. 5 | 6 | - Register a new application at `Gitea Applications`_. 7 | 8 | - Set the callback URL to ``http://example.com/complete/gitea/`` 9 | replacing ``example.com`` with your domain. Drop the trailing slash 10 | if the project doesn't use it, the URL **must** match the value sent. 11 | 12 | - Fill the ``Client ID`` and ``Client Secret`` values from Gitea in the settings:: 13 | 14 | SOCIAL_AUTH_GITEA_KEY = '' 15 | SOCIAL_AUTH_GITEA_SECRET = '' 16 | 17 | 18 | If your Gitea setup resides in another domain, then add the following setting:: 19 | 20 | SOCIAL_AUTH_GITEA_API_URL = 'https://example.com' 21 | 22 | it must be the **full url** to your Gitea setup. 23 | 24 | .. _Gitea Applications: https://gitea.com/user/settings/applications 25 | -------------------------------------------------------------------------------- /docs/backends/trello.rst: -------------------------------------------------------------------------------- 1 | Trello 2 | ====== 3 | 4 | Trello provides OAuth1 support for their authentication process. 5 | 6 | In order to enable it, follow: 7 | 8 | - Generate an Application Key pair at `Trello Developers API Keys`_ 9 | 10 | - Fill **Consumer Key** and **Consumer Secret** settings:: 11 | 12 | SOCIAL_AUTH_TRELLO_KEY = '...' 13 | SOCIAL_AUTH_TRELLO_SECRET = '...' 14 | 15 | There are also two optional settings: 16 | 17 | - your app name, otherwise the authorization page will say "Let An unknown application use your account?":: 18 | 19 | SOCIAL_AUTH_TRELLO_APP_NAME = 'My App' 20 | 21 | - the expiration period, social auth defaults to 'never', but you can change it:: 22 | 23 | SOCIAL_AUTH_TRELLO_EXPIRATION = '30days' 24 | 25 | 26 | .. _Trello Developers API Keys: https://trello.com/1/appKey/generate 27 | -------------------------------------------------------------------------------- /docs/backends/yammer.rst: -------------------------------------------------------------------------------- 1 | Yammer 2 | ====== 3 | 4 | Yammer users OAuth2 for their auth mechanism, this application supports Yammer 5 | OAuth2 in production and staging modes. 6 | 7 | Production Mode 8 | --------------- 9 | 10 | In order to enable the backend, follow: 11 | 12 | 13 | - Register an application at `Client Applications`_, 14 | set the ``Redirect URI`` to ``http:///complete/yammer/`` 15 | 16 | - Fill **Client Key** and **Client Secret** settings:: 17 | 18 | SOCIAL_AUTH_YAMMER_KEY = '...' 19 | SOCIAL_AUTH_YAMMER_SECRET = '...' 20 | 21 | 22 | Staging Mode 23 | ------------ 24 | 25 | Staging mode is configured the same as ``Production Mode``, but settings are 26 | prefixed with:: 27 | 28 | SOCIAL_AUTH_YAMMER_STAGING_* 29 | 30 | .. _Client Applications: https://www.yammer.com/client_applications 31 | -------------------------------------------------------------------------------- /docs/backends/eveonline.rst: -------------------------------------------------------------------------------- 1 | EVE Online Single Sign-On (SSO) 2 | =============================== 3 | 4 | The EVE Single Sign-On (SSO) works similar to GitHub (OAuth2). 5 | 6 | - Register a new application at `EVE Developers`_, set the callback URL to 7 | ``http://example.com/complete/eveonline/`` replacing ``example.com`` with your 8 | domain. 9 | 10 | - Fill the ``Client ID`` and ``Secret Key`` values from EVE Developers in the settings:: 11 | 12 | SOCIAL_AUTH_EVEONLINE_KEY = '' 13 | SOCIAL_AUTH_EVEONLINE_SECRET = '' 14 | 15 | - If you want to use EVE Character names as user names, use this setting:: 16 | 17 | SOCIAL_AUTH_CLEAN_USERNAMES = False 18 | 19 | - If you want to access EVE Online's CREST API, use:: 20 | 21 | SOCIAL_AUTH_EVEONLINE_SCOPE = ['publicData'] 22 | 23 | .. _EVE Developers: https://developers.eveonline.com/ 24 | -------------------------------------------------------------------------------- /docs/backends/mailchimp.rst: -------------------------------------------------------------------------------- 1 | MailChimp 2 | ========= 3 | 4 | MailChimp uses OAuth v2 for Authentication, check the `official docs`_. 5 | 6 | - Create an app by filling out the form here: `Add App`_ 7 | 8 | - Fill ``Client ID`` and ``Client Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_MAILCHIMP_KEY = '' 11 | SOCIAL_AUTH_MAILCHIMP_SECRET = '' 12 | 13 | - Add the backend to the ``AUTHENTICATION_BACKENDS`` setting:: 14 | 15 | AUTHENTICATION_BACKENDS = ( 16 | ... 17 | 'social_core.backends.mailchimp.MailChimpOAuth2', 18 | ... 19 | ) 20 | 21 | - Then you can start using ``{% url social_core:begin 'mailchimp' %}`` in 22 | your templates 23 | 24 | .. _official docs: https://apidocs.mailchimp.com/oauth2/ 25 | .. _Add App: https://admin.mailchimp.com/account/oauth2/ 26 | -------------------------------------------------------------------------------- /docs/backends/vimeo.rst: -------------------------------------------------------------------------------- 1 | Vimeo 2 | ===== 3 | 4 | Vimeo uses OAuth1 to grant access to their API. In order to get the backend 5 | running follow: 6 | 7 | - Register an application at `Vimeo Developer Portal`_ filling the required 8 | settings. Ensure to fill ``App Callback URL`` field with 9 | ``http:///complete/vimeo/`` 10 | 11 | - Fill in the **Client Id** and **Client Secret** values in your settings:: 12 | 13 | SOCIAL_AUTH_VIMEO_KEY = '' 14 | SOCIAL_AUTH_VIMEO_SECRET = '' 15 | 16 | - Specify scopes with:: 17 | 18 | SOCIAL_AUTH_VIMEO_SCOPE = [...] 19 | 20 | - Add the backend to ``AUTHENTICATION_BACKENDS``:: 21 | 22 | AUTHENTICATION_BACKENDS = ( 23 | ... 24 | 'social_core.backends.vimeo.VimeoOAuth1', 25 | ... 26 | ) 27 | 28 | .. _Vimeo Developer Portal: https://developer.vimeo.com/apps/new 29 | -------------------------------------------------------------------------------- /docs/backends/dailymotion.rst: -------------------------------------------------------------------------------- 1 | DailyMotion 2 | =========== 3 | 4 | DailyMotion uses OAuth2. In order to enable the backend follow: 5 | 6 | - Register an application at `DailyMotion Developer Portal`_ 7 | 8 | - Fill in the **Client Id** and **Client Secret** values in your settings:: 9 | 10 | SOCIAL_AUTH_DAILYMOTION_KEY = '' 11 | SOCIAL_AUTH_DAILYMOTION_SECRET = '' 12 | 13 | - Set the ``Callback URL`` to ``http:///complete/dailymotion/`` 14 | 15 | - Specify scopes with:: 16 | 17 | SOCIAL_AUTH_DAILYMOTION_SCOPE = [...] 18 | 19 | Available scopes are listed in the `Requesting Extended Permissions`_ 20 | section. 21 | 22 | .. _DailyMotion Developer Portal: http://www.dailymotion.com/profile/developer/new 23 | .. _Requesting Extended Permissions: http://www.dailymotion.com/doc/api/authentication.html#requesting-extended-permissions 24 | -------------------------------------------------------------------------------- /docs/backends/naszaklasa.rst: -------------------------------------------------------------------------------- 1 | NationBuilder 2 | ============= 3 | 4 | `NaszaKlasa supports OAuth2`_ as their authentication mechanism. Follow these 5 | steps in order to use it: 6 | 7 | - Register a new application at your `NK Developers`_ (define the `Callback 8 | URL` to ``http://example.com/complete/nk/`` where ``example.com`` 9 | is your domain). 10 | 11 | - Fill the ``Client ID`` and ``Client Secret`` values from the newly created 12 | application:: 13 | 14 | SOCIAL_AUTH_NK_KEY = '' 15 | SOCIAL_AUTH_NK_SECRET = '' 16 | 17 | - Enable the backend in ``AUTHENTICATION_BACKENDS`` setting:: 18 | 19 | AUTHENTICATION_BACKENDS = ( 20 | ... 21 | 'social_core.backends.nk.NKOAuth2', 22 | ... 23 | ) 24 | 25 | .. _NaszaKlasa supports OAuth2: https://developers.nk.pl 26 | .. _NK Developers: https://developers.nk.pl/developers/oauth2client/form 27 | -------------------------------------------------------------------------------- /docs/backends/flat.rst: -------------------------------------------------------------------------------- 1 | Flat 2 | ==== 3 | 4 | `Flat`_ uses OAuth2. In order to enable the backend follow: 5 | 6 | - On your project settings, you should add Flat on your 7 | ``AUTHENTICATION_BACKENDS``:: 8 | 9 | AUTHENTICATION_BACKENDS = ( 10 | ... 11 | 'social_core.backends.flat.FlatOAuth2', 12 | ) 13 | 14 | - Register an application at `Flat Developer Portal`_ 15 | 16 | - Fill in the **Client Id** and **Client Secret** values in your settings:: 17 | 18 | SOCIAL_AUTH_FLAT_KEY = '' 19 | SOCIAL_AUTH_FLAT_SECRET = '' 20 | 21 | - Set the ``Callback URL`` to ``http:///complete/flat/`` 22 | 23 | - Specify `scopes`_ with:: 24 | 25 | SOCIAL_AUTH_FLAT_SCOPE = [...] 26 | 27 | .. _Flat: https://flat.io 28 | .. _Flat Developer Portal: https://flat.io/developers 29 | .. _scopes: https://flat.io/developers/api/reference/#section/Authentication 30 | -------------------------------------------------------------------------------- /docs/backends/khanacademy.rst: -------------------------------------------------------------------------------- 1 | Khan Academy 2 | ============ 3 | 4 | Khan Academy uses a variant of OAuth1 authentication flow. Check the API 5 | details at `Khan Academy API Authentication`_. 6 | 7 | Follow this steps in order to use the backend: 8 | 9 | - Register a new application at `Khan Academy API Apps`_, 10 | 11 | - Fill **Consumer Key** and **Consumer Secret** values:: 12 | 13 | SOCIAL_AUTH_KHANACADEMY_OAUTH1_KEY = '' 14 | SOCIAL_AUTH_KHANACADEMY_OAUTH1_SECRET = '' 15 | 16 | - Add the backend to ``AUTHENTICATION_BACKENDS`` setting:: 17 | 18 | AUTHENTICATION_BACKENDS = ( 19 | ... 20 | 'social_core.backends.khanacademy.KhanAcademyOAuth1', 21 | ... 22 | ) 23 | 24 | .. _Khan Academy API Authentication: https://github.com/Khan/khan-api/wiki/Khan-Academy-API-Authentication 25 | .. _Khan Academy API Apps: http://www.khanacademy.org/api-apps/register 26 | -------------------------------------------------------------------------------- /docs/backends/live.rst: -------------------------------------------------------------------------------- 1 | MSN Live Connect 2 | ================ 3 | 4 | Live uses OAuth2 for its connect workflow, notice that it isn't OAuth WRAP. 5 | 6 | - Register a new application at `Live Connect Developer Center`_, set your site 7 | domain as redirect domain, 8 | 9 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 10 | 11 | SOCIAL_AUTH_LIVE_KEY = '' 12 | SOCIAL_AUTH_LIVE_SECRET = '' 13 | 14 | - Also it's possible to define extra permissions with:: 15 | 16 | SOCIAL_AUTH_LIVE_SCOPE = [...] 17 | 18 | Defaults are ``wl.basic`` and ``wl.emails``. Latter one is necessary to 19 | retrieve user email. 20 | 21 | - Ensure to have a valid ``Redirect URL`` (``http://your-domain/complete/live``) 22 | defined in the application if ``Enhanced security redirection`` is enabled. 23 | 24 | .. _Live Connect Developer Center: https://account.live.com/developers/applications/create 25 | -------------------------------------------------------------------------------- /docs/backends/auth0_openidconnect.rst: -------------------------------------------------------------------------------- 1 | Auth0 OpenID Connect 2 | ======================= 3 | 4 | Auth0 OpenID Connect (OIDC) implementation. Separate from 5 | the previous ``Auth0OAuth2`` backend, as it builds on the base 6 | OIDC backend. 7 | 8 | To configure Auth0 as an OpenID Connect (OIDC) backend, 9 | you need the following minimum configuration, 10 | using details from your Auth0 tenant and an application 11 | you have configured in it:: 12 | 13 | SOCIAL_AUTH_AUTH0_OPENIDCONNECT_DOMAIN = 'mytenant.auth0.com' 14 | SOCIAL_AUTH_AUTH0_OPENIDCONNECT_KEY = '' 15 | SOCIAL_AUTH_AUTH0_OPENIDCONNECT_SECRET = '' 16 | 17 | Scopes 18 | ------- 19 | 20 | The default scope is ``["openid", "profile", "email"]``. In order to support 21 | refresh tokens/long-lived logins, you may want to add the ``offline_access`` scope:: 22 | 23 | SOCIAL_AUTH_AUTH0_OPENIDCONNECT_SCOPE = 'openid profile email offline_access' 24 | -------------------------------------------------------------------------------- /docs/backends/pinterest.rst: -------------------------------------------------------------------------------- 1 | Pinterest 2 | ========= 3 | 4 | Pinterest implemented OAuth2 protocol for their authentication mechanism. 5 | To enable ``python-social-auth`` support follow this steps: 6 | 7 | 1. Go to `Pinterest developers zone`_ and create an application. 8 | 9 | 2. Fill App Id and Secret in your project settings:: 10 | 11 | SOCIAL_AUTH_PINTEREST_KEY = '...' 12 | SOCIAL_AUTH_PINTEREST_SECRET = '...' 13 | SOCIAL_AUTH_PINTEREST_SCOPE = [ 14 | 'read_public', 15 | 'write_public', 16 | 'read_relationships', 17 | 'write_relationships' 18 | ] 19 | 20 | 3. Enable the backend:: 21 | 22 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 23 | ... 24 | 'social_core.backends.pinterest.PinterestOAuth2', 25 | ... 26 | ) 27 | 28 | .. _Pinterest developers zone: https://developers.pinterest.com/apps/ 29 | .. _Pinterest Documentation: https://developers.pinterest.com/docs/ 30 | -------------------------------------------------------------------------------- /docs/backends/fedora.rst: -------------------------------------------------------------------------------- 1 | Fedora 2 | ====== 3 | 4 | Fedora's OpenID Connect (OIDC) backend requires the following minimum 5 | configuration:: 6 | 7 | SOCIAL_AUTH_FEDORA_OIDC_KEY = '' 8 | SOCIAL_AUTH_FEDORA_OIDC_SECRET = '' 9 | 10 | Scopes 11 | ------ 12 | 13 | The default scopes will include the user's group and agreements. 14 | You can request additional claims, for example:: 15 | 16 | SOCIAL_AUTH_FEDORA_OIDC_SCOPE = ['groups'] 17 | 18 | and you can prevent the inclusion of the default scopes using:: 19 | 20 | SOCIAL_AUTH_FEDORA_OIDC_IGNORE_DEFAULT_SCOPE = True 21 | 22 | 23 | Environment 24 | ----------- 25 | 26 | You can override the location of the OIDC provider with the 27 | ``SOCIAL_AUTH_FEDORA_OIDC_OIDC_ENDPOINT`` setting. For example, to authenticate with 28 | Fedora's staging environment, use this setting:: 29 | 30 | SOCIAL_AUTH_FEDORA_OIDC_OIDC_ENDPOINT = 'https://id.stg.fedoraproject.org' 31 | -------------------------------------------------------------------------------- /docs/backends/openstreetmap.rst: -------------------------------------------------------------------------------- 1 | OpenStreetMap (Legacy OAuth 1.0a) 2 | ================================= 3 | 4 | **Note: OAuth 1.0(a) support will be sunset in Summer 2024. Please use OAuth 2.0 instead.** 5 | 6 | OpenStreetMap supports OAuth 1.0 and 1.0a but 1.0a should be used for the new 7 | applications, as 1.0 is for support of legacy clients only. 8 | 9 | Access tokens currently do not expire automatically. 10 | 11 | More documentation at `OpenStreetMap Wiki`_: 12 | 13 | - Login to your account 14 | 15 | - Register your application as OAuth consumer on your `OpenStreetMap user settings page`_, and 16 | 17 | - Set ``App Key`` and ``App Secret`` values in the settings:: 18 | 19 | SOCIAL_AUTH_OPENSTREETMAP_KEY = '' 20 | SOCIAL_AUTH_OPENSTREETMAP_SECRET = '' 21 | 22 | .. _OpenStreetMap Wiki: http://wiki.openstreetmap.org/wiki/OAuth 23 | .. _OpenStreetMap user settings page: http://www.openstreetmap.org/user/username/oauth_clients/new 24 | -------------------------------------------------------------------------------- /docs/backends/qiita.rst: -------------------------------------------------------------------------------- 1 | Qiita 2 | ===== 3 | 4 | Qiita 5 | 6 | - Register a new application at Qiita_, set the callback URL to 7 | ``http://example.com/complete/qiita/`` replacing ``example.com`` with your 8 | domain. 9 | 10 | - Fill ``Client ID`` and ``Client Secret`` values in the settings:: 11 | 12 | SOCIAL_AUTH_QIITA_KEY = '' 13 | SOCIAL_AUTH_QIITA_SECRET = '' 14 | 15 | - Also it's possible to define extra permissions with:: 16 | 17 | SOCIAL_AUTH_QIITA_SCOPE = [...] 18 | 19 | See auth scopes at `Qiita Scopes docs`_. 20 | 21 | - Default behavior is to identify users by their `id`. However, this can be changed by renaming accounts, etc. 22 | 23 | If you want to identify each user with a unique `permanent_id`, set the following:: 24 | 25 | SOCIAL_AUTH_QIITA_IDENTIFIED_BY_PERMANENT_ID = True 26 | 27 | .. _Qiita: https://qiita.com/settings/applications 28 | .. _Qiita Scopes docs: https://qiita.com/api/v2/docs#スコープ 29 | -------------------------------------------------------------------------------- /docs/backends/yahoo.rst: -------------------------------------------------------------------------------- 1 | Yahoo 2 | ===== 3 | 4 | Yahoo supports OpenID and OAuth2 for their auth flow. 5 | 6 | 7 | Yahoo OpenID 8 | ------------ 9 | 10 | OpenID doesn't require any particular configuration beside enabling the backend 11 | in the ``AUTHENTICATION_BACKENDS`` setting:: 12 | 13 | AUTHENTICATION_BACKENDS = ( 14 | ... 15 | 'social_core.backends.yahoo.YahooOAuth2', 16 | ... 17 | ) 18 | 19 | 20 | Yahoo OAuth2 21 | ------------ 22 | OAuth 2.0 workflow, useful if you are planning to use Yahoo's API. 23 | 24 | - Register a new application at `Yahoo Developer Center`_, set your app domain 25 | and configure scopes (they can't be overridden by application). 26 | 27 | - Fill ``Consumer Key`` and ``Consumer Secret`` values in the settings:: 28 | 29 | SOCIAL_AUTH_YAHOO_OAUTH2_KEY = '' 30 | SOCIAL_AUTH_YAHOO_OAUTH2_SECRET = '' 31 | 32 | 33 | .. _Yahoo Developer Center: https://developer.yahoo.com/ 34 | -------------------------------------------------------------------------------- /docs/backends/soundcloud.rst: -------------------------------------------------------------------------------- 1 | SoundCloud 2 | ========== 3 | 4 | SoundCloud uses OAuth2 for its auth mechanism. 5 | 6 | - Register a new application at `SoundCloud App Registration`_, set your 7 | application name, website and redirect URI. 8 | 9 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 10 | 11 | SOCIAL_AUTH_SOUNDCLOUD_KEY = '' 12 | SOCIAL_AUTH_SOUNDCLOUD_SECRET = '' 13 | 14 | - Also it's possible to define extra permissions with:: 15 | 16 | SOCIAL_AUTH_SOUNDCLOUD_SCOPE = [...] 17 | 18 | Possible scope values are `*` or `non-expiring` according to their `/connect 19 | documentation`_. 20 | 21 | Check the rest of their doc at `SoundCloud Developer Documentation`_. 22 | 23 | .. _SoundCloud App Registration: http://soundcloud.com/you/apps/new 24 | .. _SoundCloud Developer Documentation: http://developers.soundcloud.com/docs 25 | .. _/connect documentation: http://developers.soundcloud.com/docs/api/reference#connect 26 | -------------------------------------------------------------------------------- /docs/backends/coursera.rst: -------------------------------------------------------------------------------- 1 | Coursera 2 | ============ 3 | 4 | Coursera uses a variant of OAuth2 authentication. The details of the API 5 | can be found at `OAuth2-based APIs - Coursera Technology`_. 6 | 7 | Take the following steps in order to use the backend: 8 | 9 | 1. Create an account at `Coursera`_. 10 | 11 | 2. Open `Developer Console`_, create an organisation and application. 12 | 13 | 3. Set **Client ID** as a ``SOCIAL_AUTH_COURSERA_KEY`` and 14 | **Secret Key** as a ``SOCIAL_AUTH_COURSERA_SECRET`` in your local settings. 15 | 16 | 4. Add the backend to ``AUTHENTICATION_BACKENDS`` setting:: 17 | 18 | AUTHENTICATION_BACKENDS = ( 19 | ... 20 | 'social_core.backends.coursera.CourseraOAuth2', 21 | ... 22 | ) 23 | 24 | .. _OAuth2-based APIs - Coursera Technology: https://tech.coursera.org/app-platform/oauth2/ 25 | .. _Coursera: https://accounts.coursera.org/console 26 | .. _Developer Console: https://accounts.coursera.org/console 27 | -------------------------------------------------------------------------------- /docs/backends/gitlab.rst: -------------------------------------------------------------------------------- 1 | GitLab 2 | ====== 3 | 4 | GitLab supports OAuth2 protocol. 5 | 6 | - Register a new application at `GitLab Applications`_. 7 | 8 | - Set the callback URL to ``http://example.com/complete/gitlab/`` 9 | replacing ``example.com`` with your domain. Drop the trailing slash 10 | if the project doesn't use it, the URL **must** match the value sent. 11 | 12 | - Ensure to mark the ``read_user`` scope. If marking ``api`` scope too, define:: 13 | 14 | SOCIAL_AUTH_GITLAB_SCOPE = ['api'] 15 | 16 | - Fill the ``Client ID`` and ``Client Secret`` values from GitLab in the settings:: 17 | 18 | SOCIAL_AUTH_GITLAB_KEY = '' 19 | SOCIAL_AUTH_GITLAB_SECRET = '' 20 | 21 | 22 | If your GitLab setup resides in another domain, then add the following setting:: 23 | 24 | SOCIAL_AUTH_GITLAB_API_URL = 'https://example.com' 25 | 26 | it must be the **full url** to your GitLab setup. 27 | 28 | .. _GitLab Applications: https://gitlab.com/-/profile/applications 29 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | extensions = [ 2 | "sphinx.ext.autodoc", 3 | "sphinx.ext.intersphinx", 4 | "sphinx.ext.todo", 5 | "sphinx.ext.viewcode", 6 | ] 7 | templates_path = ["_templates"] 8 | master_doc = "index" 9 | project = "Python Social Auth" 10 | project_copyright = "Python Social Auth team" 11 | exclude_patterns = ["build"] 12 | pygments_style = "sphinx" 13 | html_theme = "furo" 14 | html_logo = "images/logo.svg" 15 | html_title = project 16 | htmlhelp_basename = "PythonSocialAuthdoc" 17 | latex_documents = [ 18 | ( 19 | "index", 20 | "PythonSocialAuth.tex", 21 | "Python Social Auth Documentation", 22 | "Matías Aguirre", 23 | "manual", 24 | ) 25 | ] 26 | man_pages = [ 27 | ( 28 | "index", 29 | "pythonsocialauth", 30 | "Python Social Auth Documentation", 31 | ["Matías Aguirre"], 32 | 1, 33 | ) 34 | ] 35 | intersphinx_mapping = { 36 | "python": ("http://docs.python.org/", None), 37 | } 38 | -------------------------------------------------------------------------------- /docs/backends/lyft.rst: -------------------------------------------------------------------------------- 1 | Lyft 2 | ==== 3 | 4 | Lyft implements OAuth2 as its authorization service. To setup a Lyft backend: 5 | 6 | 1. Register a new application via the `Lyft Developer Portal`_. 7 | 8 | 2. Add the Lyft OAuth2 backend as an option in your settings:: 9 | 10 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 11 | ... 12 | 'social_core.backends.lyft.LyftOAuth2', 13 | ... 14 | ) 15 | 16 | 3. Use the ``Client Id`` and ``Client Secret`` from the Developer Portal into your settings:: 17 | 18 | SOCIAL_AUTH_LYFT_KEY = '' 19 | SOCIAL_AUTH_LYFT_SECRET = '' 20 | 21 | 4. Specify the scope that your app should have access to:: 22 | 23 | SOCIAL_AUTH_LYFT_SCOPE = ['public', 'profile', 'rides.read', 'rides.request'] 24 | 25 | To learn more about the API and the calls that are available, read the `Lyft API Documentation`_. 26 | 27 | .. _Lyft Developer Portal: https://developer.lyft.com/ 28 | .. _Lyft API Documentation: https://developer.lyft.com/docs 29 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [project] 2 | name = "python-social-auth-docs" 3 | requires-python = ">=3.11" 4 | version = "2025.0" 5 | 6 | [tool.ruff.lint] 7 | ignore = [ 8 | "ANN", # TODO: missing type annotations 9 | "COM", # CONFIG: No trailing commas 10 | "D", # TODO: missing documentation 11 | "D203", # CONFIG: incompatible with D211 12 | "D212", # CONFIG: incompatible with D213 13 | "E501", # WONTFIX: we accept long strings (rest is formatted by ruff) 14 | "N", # TODO: wrong naming conventions 15 | "PTH", # TODO: not using pathlib 16 | "S603", # CONFIG: subprocess is being used 17 | "S607", # CONFIG: subprocess executes system tools 18 | "T201", # CONFIG: print is used 19 | 'ISC001' # CONFIG: formatter 20 | ] 21 | select = ["ALL"] 22 | 23 | [tool.ruff.lint.per-file-ignores] 24 | "docs/conf.py" = ["INP001"] 25 | 26 | [tool.tomlsort] 27 | ignore_case = true 28 | sort_inline_arrays = true 29 | sort_inline_tables = true 30 | sort_table_keys = true 31 | spaces_before_inline_comment = 2 32 | -------------------------------------------------------------------------------- /docs/backends/qq.rst: -------------------------------------------------------------------------------- 1 | QQ 2 | == 3 | 4 | QQ implemented OAuth2 protocol for their authentication mechanism. To enable 5 | ``python-social-auth`` support follow this steps: 6 | 7 | 1. Go to `QQ`_ and create an application. 8 | 9 | 2. Fill App Id and Secret in your project settings:: 10 | 11 | SOCIAL_AUTH_QQ_KEY = '...' 12 | SOCIAL_AUTH_QQ_SECRET = '...' 13 | 14 | 3. Enable the backend:: 15 | 16 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 17 | ... 18 | 'social_core.backends.qq.QQOauth2', 19 | ... 20 | ) 21 | 22 | 23 | The values for ``nickname``, ``figureurl_qq_1`` and ``gender`` will be stored 24 | in the ``extra_data`` field. The ``nickname`` will be used as the account 25 | username. ``figureurl_qq_1`` can be used as the profile image. 26 | 27 | Sometimes nickname will duplicate with another ``qq`` account, to avoid this 28 | issue it's possible to use ``openid`` as ``username`` by define this setting:: 29 | 30 | SOCIAL_AUTH_QQ_USE_OPENID_AS_USERNAME = True 31 | 32 | .. _QQ: http://connect.qq.com/ 33 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Python Social Auth - Documentation 2 | 3 | Python Social Auth is an easy to setup social authentication/registration 4 | mechanism with support for several frameworks and auth providers. 5 | 6 | ## Description 7 | 8 | This is the documentation repository for the 9 | [social-auth ecosystem](https://github.com/python-social-auth/social-core). 10 | 11 | ## Documentation 12 | 13 | Project documentation is available at https://python-social-auth.readthedocs.io/. 14 | 15 | ## Contributing 16 | 17 | Contributions are welcome! 18 | 19 | Only the core and Django modules are currently in development. All others are in maintenance only mode, and maintainers are especially welcome there. 20 | 21 | See the [CONTRIBUTING.md](https://github.com/python-social-auth/.github/blob/main/CONTRIBUTING.md) document for details. 22 | 23 | ## Versioning 24 | 25 | This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). 26 | 27 | ## License 28 | 29 | This project follows the BSD license. See the [LICENSE](LICENSE) for details. 30 | -------------------------------------------------------------------------------- /docs/backends/moves.rst: -------------------------------------------------------------------------------- 1 | Moves 2 | ===== 3 | 4 | Moves_ provides an OAuth2 authentication flow. In order to enable it: 5 | 6 | - Register an application at `Manage Your Apps`_, remember to fill the 7 | ``Redirect URI`` once the application was created. 8 | 9 | - Fill **Client ID** and **Client secret** in the settings:: 10 | 11 | SOCIAL_AUTH_MOVES_KEY = '' 12 | SOCIAL_AUTH_MOVES_SECRET = '' 13 | 14 | - Define the mandatory scope for your application:: 15 | 16 | SOCIAL_AUTH_MOVES_SCOPE = ['activity', 'location'] 17 | 18 | The scope parameter is required by Moves_ but the backend doesn't set 19 | a default one to minimize the application permissions request, so it's 20 | mandatory for the developer to define this setting. 21 | 22 | - Add the backend to the ``AUTHENTICATION_BACKENDS`` setting:: 23 | 24 | AUTHENTICATION_BACKENDS = ( 25 | ... 26 | 'social_core.backends.moves.MovesOAuth2', 27 | ... 28 | ) 29 | 30 | .. _Moves: http://moves-app.com/ 31 | .. _Manage Your Apps: https://dev.moves-app.com/apps 32 | -------------------------------------------------------------------------------- /docs/backends/amazon.rst: -------------------------------------------------------------------------------- 1 | Amazon 2 | ====== 3 | 4 | Amazon implemented OAuth2 protocol for their authentication mechanism. To 5 | enable ``python-social-auth`` support follow this steps: 6 | 7 | 1. Go to `Amazon App Console`_ and create an application. 8 | 9 | 2. Fill App Id and Secret in your project settings:: 10 | 11 | SOCIAL_AUTH_AMAZON_KEY = '...' 12 | SOCIAL_AUTH_AMAZON_SECRET = '...' 13 | 14 | 3. Enable the backend:: 15 | 16 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 17 | ... 18 | 'social_core.backends.amazon.AmazonOAuth2', 19 | ... 20 | ) 21 | 22 | Further documentation at `Website Developer Guide`_ and `Getting Started for Web`_. 23 | 24 | **Note:** This backend supports TLSv1 protocol since SSL will be deprecated 25 | from May 25, 2015 26 | 27 | .. _Amazon App Console: http://login.amazon.com/manageApps 28 | .. _Website Developer Guide: https://images-na.ssl-images-amazon.com/images/G/01/lwa/dev/docs/website-developer-guide._TTH_.pdf 29 | .. _Getting Started for Web: http://login.amazon.com/website 30 | -------------------------------------------------------------------------------- /docs/backends/grafana.rst: -------------------------------------------------------------------------------- 1 | Grafana 2 | ======= 3 | 4 | Grafana works similar to Facebook (OAuth). 5 | 6 | - On your project settings, you should add Grafana on your ``AUTHENTICATION_BACKENDS``:: 7 | 8 | AUTHENTICATION_BACKENDS = ( 9 | ... 10 | 'social_core.backends.grafana.GrafanaOAuth2', 11 | ) 12 | 13 | - Register a new application at `Grafana Cloud Portal` in grafana.com by doing 14 | `My Account → SECURITY → OAuth Clients → Add OAuth Client Application`. 15 | Set any name and in URL just the domain, without any path. 16 | 17 | - Copy `client_id` and `client_secret` and add these values in your project settings file. 18 | 19 | The ``client_id`` should be added on ``SOCIAL_AUTH_GRAFANA_KEY`` and the ``client_secret`` should be 20 | added on ``SOCIAL_AUTH_GRAFANA_SECRET``:: 21 | 22 | SOCIAL_AUTH_GRAFANA_KEY = 'a1b2c3d4' 23 | SOCIAL_AUTH_GRAFANA_SECRET = 'e5f6g7h8i9' 24 | 25 | - The default scope is ```['profile', 'email']``` but it's possible to define it in settings with:: 26 | 27 | SOCIAL_AUTH_GRAFANA_SCOPE = [...] 28 | -------------------------------------------------------------------------------- /docs/backends/nationbuilder.rst: -------------------------------------------------------------------------------- 1 | NationBuilder 2 | ============= 3 | 4 | `NationBuilder supports OAuth2`_ as their authentication mechanism. Follow these 5 | steps in order to use it: 6 | 7 | - Register a new application at your `Nation Admin panel`_ (define the `Callback 8 | URL` to ``http://example.com/complete/nationbuilder/`` where ``example.com`` 9 | is your domain). 10 | 11 | - Fill the ``Client ID`` and ``Client Secret`` values from the newly created 12 | application:: 13 | 14 | SOCIAL_AUTH_NATIONBUILDER_KEY = '' 15 | SOCIAL_AUTH_NATIONBUILDER_SECRET = '' 16 | 17 | - Also define your NationBuilder slug:: 18 | 19 | SOCIAL_AUTH_NATIONBUILDER_SLUG = 'your-nationbuilder-slug' 20 | 21 | - Enable the backend in ``AUTHENTICATION_BACKENDS`` setting:: 22 | 23 | AUTHENTICATION_BACKENDS = ( 24 | ... 25 | 'social_core.backends.nationbuilder.NationBuilderOAuth2' 26 | ... 27 | ) 28 | 29 | .. _Nation Admin panel: https://psa.nationbuilder.com/admin/apps 30 | .. _NationBuilder supports OAuth2: http://nationbuilder.com/api_quickstart 31 | -------------------------------------------------------------------------------- /docs/backends/digitalocean.rst: -------------------------------------------------------------------------------- 1 | DigitalOcean 2 | ============ 3 | 4 | DigitalOcean uses OAuth2 for its auth process. See the full `DigitalOcean 5 | developer's documentation`_ for more information. 6 | 7 | - Register a new application in the `Apps & API page`_ in the DigitalOcean 8 | control panel, setting the callback URL to ``http://example.com/complete/digitalocean/`` 9 | replacing ``example.com`` with your domain. 10 | 11 | - Fill the ``Client ID`` and ``Client Secret`` values from GitHub in the settings:: 12 | 13 | SOCIAL_AUTH_DIGITALOCEAN_KEY = '' 14 | SOCIAL_AUTH_DIGITALOCEAN_SECRET = '' 15 | 16 | - By default, only ``read`` permissions are granted. In order to create, 17 | destroy, and take other actions on the user's resources, you must request 18 | ``read write`` permissions like so:: 19 | 20 | SOCIAL_AUTH_DIGITALOCEAN_AUTH_EXTRA_ARGUMENTS = {'scope': 'read write'} 21 | 22 | 23 | .. _DigitalOcean developer's documentation: https://developers.digitalocean.com/documentation/ 24 | .. _Apps & API page: https://cloud.digitalocean.com/settings/applications 25 | -------------------------------------------------------------------------------- /docs/backends/stripe.rst: -------------------------------------------------------------------------------- 1 | Stripe 2 | ====== 3 | 4 | Stripe uses OAuth2 for its authorization service. To setup Stripe backend: 5 | 6 | - Register a new application at `Stripe App Creation`_, and 7 | 8 | - Grab the ``client_id`` value in ``Applications`` tab and fill the ``App Id`` 9 | setting:: 10 | 11 | SOCIAL_AUTH_STRIPE_KEY = 'ca_...' 12 | 13 | - Grab the ``Test Secret Key`` in the ``API Keys`` tab and fill the ``App 14 | Secret`` setting:: 15 | 16 | SOCIAL_AUTH_STRIPE_SECRET = '...' 17 | 18 | - Define ``SOCIAL_AUTH_STRIPE_SCOPE`` with the desired scope (options are 19 | ``read_only`` and ``read_write``):: 20 | 21 | SOCIAL_AUTH_STRIPE_SCOPE = ['read_only'] 22 | 23 | - Add the needed backend to ``AUTHENTICATION_BACKENDS``:: 24 | 25 | AUTHENTICATION_BACKENDS = ( 26 | ... 27 | 'social_core.backends.stripe.StripeOAuth2', 28 | ... 29 | ) 30 | 31 | More info on Stripe OAuth2 at `Integrating OAuth`_. 32 | 33 | .. _Stripe App Creation: https://manage.stripe.com/#account/applications/settings 34 | .. _Integrating OAuth: https://stripe.com/docs/connect/oauth 35 | -------------------------------------------------------------------------------- /docs/backends/simplelogin.rst: -------------------------------------------------------------------------------- 1 | SimpleLogin 2 | =========== 3 | 4 | SimpleLogin uses OAuth 2.0 for Authentication. 5 | 6 | - On your project settings, you should add SimpleLogin on your 7 | ``AUTHENTICATION_BACKENDS``:: 8 | 9 | AUTHENTICATION_BACKENDS = ( 10 | ... 11 | 'social_core.backends.simplelogin.SimpleLoginOAuth2', 12 | ) 13 | 14 | - Register a new app at `SimpleLogin App`_. By default, SimpleLogin whitelists 15 | ``localhost`` so your app should work locally. 16 | Please set the callback URL to ``http://example.com/complete/simplelogin/`` 17 | replacing ``example.com`` with your domain when you deploy your web app to 18 | production. 19 | 20 | - Add these values of ``Client ID`` and ``Client Secret`` from SimpleLogin in 21 | your project settings file. 22 | 23 | The ``Client ID`` should be added on ``SOCIAL_AUTH_SIMPLELOGIN_KEY`` and the 24 | ``Client Secret`` should be added on ``SOCIAL_AUTH_SIMPLELOGIN_SECRET``:: 25 | 26 | SOCIAL_AUTH_SIMPLELOGIN_KEY = 'client-id' 27 | SOCIAL_AUTH_SIMPLELOGIN_SECRET = 'very-secret' 28 | 29 | .. _SimpleLogin App: https://app.simplelogin.io 30 | -------------------------------------------------------------------------------- /docs/backends/rdio.rst: -------------------------------------------------------------------------------- 1 | Rdio 2 | ==== 3 | 4 | Rdio provides OAuth 1 and 2 support for their authentication process. 5 | 6 | OAuth 1.0a 7 | ---------- 8 | 9 | To setup Rdio OAuth 1.0a, add the following to your settings page:: 10 | 11 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 12 | ... 13 | 'social_core.backends.rdio.RdioOAuth1', 14 | ... 15 | ) 16 | 17 | SOCIAL_AUTH_RDIO_OAUTH1_KEY = '' 18 | SOCIAL_AUTH_RDIO_OAUTH1_SECRET = '' 19 | 20 | 21 | OAuth 2.0 22 | --------- 23 | 24 | To setup Rdio OAuth 2.0, add the following to your settings page:: 25 | 26 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 27 | ... 28 | 'social_core.backends.rdio.RdioOAuth2', 29 | ... 30 | ) 31 | 32 | SOCIAL_AUTH_RDIO_OAUTH2_KEY = os.environ['RDIO_OAUTH2_KEY'] 33 | SOCIAL_AUTH_RDIO_OAUTH2_SECRET = os.environ['RDIO_OAUTH2_SECRET'] 34 | SOCIAL_AUTH_RDIO_OAUTH2_SCOPE = [] 35 | 36 | 37 | Extra Fields 38 | ------------ 39 | 40 | The following extra fields are automatically requested: 41 | 42 | - rdio_id 43 | - rdio_icon_url 44 | - rdio_profile_url 45 | - rdio_username 46 | - rdio_stream_region 47 | -------------------------------------------------------------------------------- /docs/backends/okta.rst: -------------------------------------------------------------------------------- 1 | Okta 2 | ==== 3 | 4 | This section describes how to setup the different services provided by Okta. 5 | 6 | Okta OAuth2 7 | ----------- 8 | 9 | To enable OAuth2 support: 10 | 11 | - Fill ``Client ID``, ``Client Secret`` and `API URL (e.g. 12 | https://dev-000000.oktapreview.com/oauth2)` settings, these values can be 13 | obtained easily from Okta after creating a Web application. Please note, do 14 | not use the ``/oauth2/default`` endpoint for Okta authentication:: 15 | 16 | SOCIAL_AUTH_OKTA_OAUTH2_KEY = '' 17 | SOCIAL_AUTH_OKTA_OAUTH2_SECRET = '' 18 | SOCIAL_AUTH_OKTA_OAUTH2_API_URL = '' 19 | 20 | Okta OpenId Connect 21 | ------------------- 22 | 23 | - Fill ``Client ID``, ``Client Secret`` and `API URL (e.g. 24 | https://dev-000000.oktapreview.com/oauth2)` settings, these values can be 25 | obtained easily from Okta after creating a Web application. Please note, do 26 | not use the ``/oauth2/default`` endpoint for Okta authentication:: 27 | 28 | SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY = '' 29 | SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET = '' 30 | SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL = '' 31 | -------------------------------------------------------------------------------- /docs/backends/untappd.rst: -------------------------------------------------------------------------------- 1 | Untappd 2 | ======= 3 | 4 | Untappd uses OAuth v2 for Authentication, check the `official docs`_. 5 | 6 | - Create an app by filling out the form here: `Add App`_ 7 | 8 | - Apps are approved on a one-by-one basis, so you'll need to wait a 9 | few days to get your client ID and secret. 10 | 11 | - Fill ``Client ID`` and ``Client Secret`` values in the settings:: 12 | 13 | SOCIAL_AUTH_UNTAPPD_KEY = '' 14 | SOCIAL_AUTH_UNTAPPD_SECRET = '' 15 | 16 | - Optionally include a ``User Agent`` to identify your calls to Untappd (this 17 | may become required in the future):: 18 | 19 | SOCIAL_AUTH_UNTAPPD_USER_AGENT = 'My Custom User Agent or App Name' 20 | 21 | - Add the backend to the ``AUTHENTICATION_BACKENDS`` setting:: 22 | 23 | AUTHENTICATION_BACKENDS = ( 24 | ... 25 | 'social_core.backends.untappd.UntappdOAuth2', 26 | ... 27 | ) 28 | 29 | - Then you can start using ``{% url social:begin 'untappd' %}`` in 30 | your templates 31 | 32 | .. _official docs: https://untappd.com/api/docs 33 | .. _Add App: https://untappd.com/api/register?register=new 34 | -------------------------------------------------------------------------------- /docs/backends/mixcloud.rst: -------------------------------------------------------------------------------- 1 | Mixcloud OAuth2 2 | =============== 3 | 4 | The `Mixcloud API`_ offers support for authorization. To this backend support: 5 | 6 | - Register a new application at `Mixcloud Developers`_ 7 | 8 | - Add Mixcloud backend to ``AUTHENTICATION_BACKENDS`` in settings:: 9 | 10 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 11 | ... 12 | 'social_core.backends.mixcloud.MixcloudOAuth2', 13 | ) 14 | 15 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 16 | 17 | SOCIAL_AUTH_MIXCLOUD_KEY = '' 18 | SOCIAL_AUTH_MIXCLOUD_SECRET = '' 19 | 20 | - Similar to the other OAuth backends you can define:: 21 | 22 | SOCIAL_AUTH_MIXCLOUD_EXTRA_DATA = [('username', 'username'), 23 | ('name', 'name'), 24 | ('pictures', 'pictures'), 25 | ('url', 'url')] 26 | 27 | as a list of tuples ``(response name, alias)`` to store user profile data on 28 | the ``UserSocialAuth.extra_data``. 29 | 30 | .. _Mixcloud API: http://www.mixcloud.com/developers/documentation 31 | .. _Mixcloud Developers: http://www.mixcloud.com/developers 32 | -------------------------------------------------------------------------------- /docs/backends/cognito.rst: -------------------------------------------------------------------------------- 1 | Cognito 2 | ======= 3 | 4 | Cognito implemented OAuth2 protocol for their authentication mechanism. To 5 | enable ``python-social-auth`` support follow this steps: 6 | 7 | 1. Go to `AWS Cognito Console`_ and select ``Manage User Pools``. 8 | 9 | 2. Choose an existing pool or create a new one following the `Cognito Pool 10 | Tutorial`_. 11 | 12 | 3. Create an app (make sure to generate a client secret) and configure a pool 13 | domain (`Cognito App Configuration`_):: 14 | 15 | SOCIAL_AUTH_COGNITO_KEY = '...' 16 | SOCIAL_AUTH_COGNITO_SECRET = '...' 17 | SOCIAL_AUTH_COGNITO_POOL_DOMAIN = '...' 18 | 19 | 4. Enable the backend:: 20 | 21 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 22 | ... 23 | 'social_core.backends.cognito.CognitoOAuth2', 24 | ... 25 | ) 26 | 27 | .. _AWS Cognito Console: https://console.aws.amazon.com/cognito/home 28 | .. _Cognito Pool Tutorial: https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html 29 | .. _Cognito App Configuration: Getting Started for Web: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html 30 | -------------------------------------------------------------------------------- /docs/backends/behance.rst: -------------------------------------------------------------------------------- 1 | Behance 2 | ======= 3 | 4 | DEPRECATED NOTICE 5 | ----------------- 6 | 7 | **NOTE:** IT SEEMS THAT BEHANCE HAS DROPPED THEIR OAUTH2 SUPPORT WITHOUT MUCH 8 | NOTICE BESIDE A `BLOG POST`_ ON SEPTEMBER 2014 MENTIONING THAT IT WILL BE 9 | INTRODUCED "SOON". THIS BACKEND IS IN DEPRECATED STATE FOR NOW. 10 | 11 | Behance uses OAuth2 for its auth mechanism. 12 | 13 | - Register a new application at `Behance App Registration`_, set your 14 | application name, website and redirect URI. 15 | 16 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 17 | 18 | SOCIAL_AUTH_BEHANCE_KEY = '' 19 | SOCIAL_AUTH_BEHANCE_SECRET = '' 20 | 21 | - Also it's possible to define extra permissions with:: 22 | 23 | SOCIAL_AUTH_BEHANCE_SCOPE = [...] 24 | 25 | Check available permissions at `Possible Scopes`_. Also check the rest of their 26 | doc at `Behance Developer Documentation`_. 27 | 28 | .. _Behance App Registration: http://www.behance.net/dev/register 29 | .. _Possible Scopes: http://www.behance.net/dev/authentication#scopes 30 | .. _Behance Developer Documentation: http://www.behance.net/dev 31 | .. _BLOG POST: http://blog.behance.net/dev/introducing-the-behance-api 32 | -------------------------------------------------------------------------------- /docs/backends/mediawiki.rst: -------------------------------------------------------------------------------- 1 | MediaWiki OAuth1 backend 2 | ======================== 3 | 4 | Usage 5 | ----- 6 | 7 | In addition to the general setup you need to define the 8 | following settings:: 9 | 10 | SOCIAL_AUTH_MEDIAWIKI_KEY = 11 | SOCIAL_AUTH_MEDIAWIKI_SECRET = 12 | SOCIAL_AUTH_MEDIAWIKI_URL = 'https://meta.wikimedia.org/w/index.php' 13 | 14 | In the OAuth consumer registration you can choose the option to: 15 | 16 | Allow consumer to specify a callback in requests 17 | and use "callback" URL above as a required prefix 18 | 19 | This is preferable. If your URL is `https://myurl.org/` use 20 | the following option:: 21 | 22 | SOCIAL_AUTH_MEDIAWIKI_CALLBACK = \ 23 | 'https://myurl.org/oauth/complete/mediawiki' 24 | 25 | But it is also possible to use:: 26 | 27 | SOCIAL_AUTH_MEDIAWIKI_CALLBACK = 'oob' 28 | 29 | General documentation 30 | --------------------- 31 | 32 | https://www.mediawiki.org/wiki/Extension:OAuth 33 | 34 | Developer documentation 35 | ----------------------- 36 | 37 | https://www.mediawiki.org/wiki/OAuth/For_Developers 38 | 39 | Code based on 40 | ------------- 41 | 42 | https://github.com/mediawiki-utilities/python-mwoauth 43 | -------------------------------------------------------------------------------- /docs/backends/fitbit.rst: -------------------------------------------------------------------------------- 1 | Fitbit 2 | ====== 3 | 4 | Fitbit supports both OAuth 2.0 and OAuth 1.0a logins. OAuth 2 is 5 | preferred for new integrations, as OAuth 1.0a does not support getting 6 | heartrate or location and will be deprecated in the future. 7 | 8 | 1. Register a new OAuth Consumer `here`_ 9 | 10 | 2. Configure the appropriate settings for OAuth 2.0 or OAuth 1.0a (see 11 | below). 12 | 13 | OAuth 2.0 or OAuth 1.0a 14 | ----------------------- 15 | 16 | - Fill ``Consumer Key`` and ``Consumer Secret`` values in the 17 | settings:: 18 | 19 | SOCIAL_AUTH_FITBIT_KEY = '' 20 | SOCIAL_AUTH_FITBIT_SECRET = '' 21 | 22 | OAuth 2.0 specific settings 23 | --------------------------- 24 | 25 | By default, only the ``profile`` scope is requested. To request more 26 | scopes, set SOCIAL_AUTH_FITBIT_SCOPE:: 27 | 28 | SOCIAL_AUTH_FITBIT_SCOPE = [ 29 | 'activity', 30 | 'heartrate', 31 | 'location', 32 | 'nutrition', 33 | 'profile', 34 | 'settings', 35 | 'sleep', 36 | 'social', 37 | 'weight' 38 | ] 39 | 40 | The above will request all permissions from the user. 41 | 42 | .. _here: https://dev.fitbit.com/apps/new 43 | -------------------------------------------------------------------------------- /docs/backends/oauth.rst: -------------------------------------------------------------------------------- 1 | OAuth 2 | ===== 3 | 4 | OAuth_ communication demands a set of keys exchange to validate the client 5 | authenticity prior to user approbation. Twitter, and Facebook facilitates 6 | these keys by application registration, Google works the same, 7 | but provides the option for unregistered applications. 8 | 9 | Check next sections for details. 10 | 11 | OAuth_ backends also can store extra data in ``UserSocialAuth.extra_data`` 12 | field by defining a set of values names to retrieve from service response. 13 | 14 | Settings is per backend and its name is dynamically checked using uppercase 15 | backend name as prefix:: 16 | 17 | SOCIAL_AUTH__EXTRA_DATA 18 | 19 | Example:: 20 | 21 | SOCIAL_AUTH_FACEBOOK_EXTRA_DATA = [(..., ...)] 22 | 23 | Settings must be a list of tuples mapping value name in response and value 24 | alias used to store. A third value (boolean) is supported, its purpose is 25 | to signal if the value should be discarded if it evaluates to ``False``, this 26 | is to avoid replacing old (needed) values when they don't form part of current 27 | response. If not present, then this check is avoided and the value will replace 28 | any data. 29 | 30 | 31 | .. _OAuth: http://oauth.net/ 32 | -------------------------------------------------------------------------------- /docs/backends/pixelpin.rst: -------------------------------------------------------------------------------- 1 | PixelPin 2 | ======== 3 | 4 | PixelPin only supports OAuth2. 5 | 6 | PixelPin OAuth2 7 | --------------- 8 | 9 | Developer documentation for PixelPin can be found at 10 | http://developer.pixelpin.co.uk/. To setup OAuth2 do the following: 11 | 12 | - Register a new developer account at `PixelPin Developers`_. 13 | 14 | You require a PixelPin account to create developer accounts. Sign up at 15 | `PixelPin Account Page`_ For the value of redirect uri, use whatever path you 16 | need to return to on your web application. The example code provided with the 17 | plugin uses ``http:///complete/pixelpin-oauth2/``. 18 | 19 | Once verified by email, record the values of client id and secret for the 20 | next step. 21 | 22 | - Fill **Consumer Key** and **Consumer Secret** values in your settings.py 23 | file:: 24 | 25 | SOCIAL_AUTH_PIXELPIN_OAUTH2_KEY = '' 26 | SOCIAL_AUTH_PIXELPIN_OAUTH2_SECRET = '' 27 | 28 | - Add ``'social_core.backends.pixelpin.PixelPinOAuth2'`` into your 29 | ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS``. 30 | 31 | .. _PixelPin homepage: http://pixelpin.co.uk/ 32 | .. _PixelPin Account Page: https://login.pixelpin.co.uk/ 33 | .. _PixelPin Developers: http://developer.pixelpin.co.uk/ 34 | -------------------------------------------------------------------------------- /docs/backends/twitter_oauth2.rst: -------------------------------------------------------------------------------- 1 | Twitter API v2 2 | ============== 3 | 4 | Twitter offers per application keys named ``Client ID`` and ``Client Secret``. 5 | To enable Twitter these two keys are needed. Further documentation at 6 | `Twitter development resources`_: 7 | 8 | - Register a new application at `Twitter App Creation`_, 9 | 10 | - Fill **Client ID** and **Client Secret** values:: 11 | 12 | SOCIAL_AUTH_TWITTER_OAUTH2_KEY = '' 13 | SOCIAL_AUTH_TWITTER_OAUTH2_SECRET = '' 14 | 15 | - You can specify PKCE challenge method following:: 16 | 17 | SOCIAL_AUTH_TWITTER_OAUTH2_PKCE_CODE_CHALLENGE_METHOD = '' 18 | 19 | The possible values for configuration are ``s256`` and ``plain``. 20 | By default, ``s256`` is set. 21 | 22 | You can see more information about PKCE at `RFC7636`_. 23 | 24 | - You need to specify an URL callback or the OAuth will raise a "403 Client Error". 25 | The callback URL should be something like "https://example.com/complete/twitter-oauth2" 26 | 27 | 28 | .. _Twitter development resources: https://developer.twitter.com/en/docs/authentication/oauth-2-0/authorization-code 29 | .. _Twitter App Creation: https://developer.twitter.com/en/portal/dashboard 30 | .. _RFC7636: https://datatracker.ietf.org/doc/html/rfc7636 31 | -------------------------------------------------------------------------------- /docs/backends/mendeley.rst: -------------------------------------------------------------------------------- 1 | Mendeley 2 | ======== 3 | 4 | Mendeley supports OAuth1 and OAuth2, they are in the process of deprecating 5 | OAuth1 API (which should be fully deprecated on April 2014, check their 6 | announcement_). 7 | 8 | 9 | OAuth1 10 | ------ 11 | 12 | In order to support OAuth1 (not recommended, use OAuth2 instead): 13 | 14 | - Register a new application at `Mendeley Application Registration`_ 15 | 16 | - Fill **Consumer Key** and **Consumer Secret** values:: 17 | 18 | SOCIAL_AUTH_MENDELEY_KEY = '' 19 | SOCIAL_AUTH_MENDELEY_SECRET = '' 20 | 21 | 22 | OAuth2 23 | ------ 24 | 25 | In order to support OAuth2: 26 | 27 | - Register a new application at `Mendeley Application Registration`_, or 28 | migrate your OAuth1 application, check their `migration steps here`_. 29 | 30 | - Fill **Application ID** and **Application Secret** values:: 31 | 32 | SOCIAL_AUTH_MENDELEY_OAUTH2_KEY = '' 33 | SOCIAL_AUTH_MENDELEY_OAUTH2_SECRET = '' 34 | 35 | 36 | .. _Mendeley Application Registration: http://dev.mendeley.com/applications/register/ 37 | .. _announcement: https://sites.google.com/site/mendeleyapi/home/authentication 38 | .. _migration steps here: https://groups.google.com/forum/#!topic/mendeley-open-api-developers/KmUQW9I0ST0 39 | -------------------------------------------------------------------------------- /docs/backends/ngpvan_actionid.rst: -------------------------------------------------------------------------------- 1 | NGP VAN ActionID 2 | ================ 3 | 4 | `NGP VAN`_'s ActionID_ service provides an OpenID 1.1 endpoint, which provides 5 | first name, last name, email address, and phone number. 6 | 7 | ActionID doesn't require major settings beside being defined on 8 | ``AUTHENTICATION_BACKENDS`` 9 | 10 | .. code-block:: python 11 | 12 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 13 | ... 14 | 'social_core.backends.ngpvan.ActionIDOpenID', 15 | ... 16 | ) 17 | 18 | 19 | If you want to be able to access the "phone" attribute offered by NGP VAN 20 | within ``extra_data`` you can add the following to your settings: 21 | 22 | .. code-block:: python 23 | 24 | SOCIAL_AUTH_ACTIONID_OPENID_AX_EXTRA_DATA = [ 25 | ('http://openid.net/schema/contact/phone/business', 'phone') 26 | ] 27 | 28 | 29 | NGP VAN offers the ability to have your domain whitelisted, which will disable 30 | the "{domain} is requesting a link to your ActionID" warning when your app 31 | attempts to login using an ActionID account. Contact 32 | `NGP VAN Developer Support`_ for more information 33 | 34 | .. _NGP VAN: http://www.ngpvan.com/ 35 | .. _ActionID: http://developers.ngpvan.com/action-id 36 | .. _NGP VAN Developer Support: http://developers.ngpvan.com/support/contact 37 | -------------------------------------------------------------------------------- /.github/renovate.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://docs.renovatebot.com/renovate-schema.json", 3 | "extends": [ 4 | "config:best-practices", 5 | ":dependencyDashboard", 6 | "helpers:pinGitHubActionDigests" 7 | ], 8 | "automerge": true, 9 | "automergeType": "pr", 10 | "automergeStrategy": "rebase", 11 | "platformAutomerge": true, 12 | "pre-commit": { 13 | "enabled": true 14 | }, 15 | "poetry": { 16 | "enabled": false 17 | }, 18 | "packageRules": [ 19 | { 20 | "matchDatasources": [ 21 | "pypi" 22 | ], 23 | "rangeStrategy": "widen" 24 | } 25 | ], 26 | "customManagers": [ 27 | { 28 | "customType": "regex", 29 | "managerFilePatterns": [ 30 | "/\\.pre-commit-config\\.yaml/" 31 | ], 32 | "matchStrings": [ 33 | "(?[^'\" ]+)==(?[^'\" ,\\s]+)" 34 | ], 35 | "datasourceTemplate": "pypi", 36 | "versioningTemplate": "pep440" 37 | }, 38 | { 39 | "customType": "regex", 40 | "managerFilePatterns": [ 41 | "/\\.pre-commit-config\\.yaml/" 42 | ], 43 | "matchStrings": [ 44 | "(?[^'\" ]+)@(?[^'\" ,\\s]+)" 45 | ], 46 | "datasourceTemplate": "npm", 47 | "versioningTemplate": "npm" 48 | } 49 | ] 50 | } 51 | -------------------------------------------------------------------------------- /docs/backends/auth0.rst: -------------------------------------------------------------------------------- 1 | Auth0 2 | ===== 3 | 4 | Auth0 OAuth2 5 | ------------ 6 | 7 | Auth0 provides OAuth2 authentication. This is the original ``Auth0OAuth2`` backend. 8 | 9 | For a newer OpenID Connect implementation, see :doc:`auth0_openidconnect`. 10 | 11 | Setup 12 | ***** 13 | 14 | To enable Auth0 OAuth2 support: 15 | 16 | 1. Register your application at `Auth0 Dashboard`_ to get your Auth0 domain, 17 | Client ID, and Client Secret. 18 | 19 | 2. Fill in the settings with your Auth0 domain, Client ID, and Client Secret:: 20 | 21 | SOCIAL_AUTH_AUTH0_KEY = '' 22 | SOCIAL_AUTH_AUTH0_SECRET = '' 23 | SOCIAL_AUTH_AUTH0_DOMAIN = 'yourdomain.auth0.com' 24 | 25 | Replace ``yourdomain`` with your Auth0 tenant domain. 26 | 27 | 3. Add the backend to your authentication backends:: 28 | 29 | AUTHENTICATION_BACKENDS = ( 30 | ... 31 | 'social_core.backends.auth0.Auth0OAuth2', 32 | ... 33 | ) 34 | 35 | Scopes 36 | ****** 37 | 38 | You can define custom scopes using the ``SOCIAL_AUTH_AUTH0_SCOPE`` setting:: 39 | 40 | SOCIAL_AUTH_AUTH0_SCOPE = ['openid', 'profile', 'email'] 41 | 42 | The backend will handle JWT token validation and extract user details including 43 | username, email, full name, and profile picture. 44 | 45 | .. _Auth0 Dashboard: https://manage.auth0.com/ 46 | -------------------------------------------------------------------------------- /docs/backends/reddit.rst: -------------------------------------------------------------------------------- 1 | Reddit 2 | ====== 3 | 4 | Reddit implements `OAuth2 authentication workflow`_. To enable it, just follow: 5 | 6 | - Register an application at `Reddit Preferences Apps`_ 7 | 8 | - Fill the **Consumer Key** and **Consumer Secret** values in your settings:: 9 | 10 | SOCIAL_AUTH_REDDIT_KEY = '' 11 | SOCIAL_AUTH_REDDIT_SECRET = '' 12 | 13 | - By default the token is not permanent, it will last an hour. To get 14 | a refresh token just define:: 15 | 16 | SOCIAL_AUTH_REDDIT_AUTH_EXTRA_ARGUMENTS = {'duration': 'permanent'} 17 | 18 | This will store the ``refresh_token`` in ``UserSocialAuth.extra_data`` 19 | attribute, to refresh the access token just do:: 20 | 21 | from social_django.utils import load_strategy 22 | 23 | strategy = load_strategy(backend='reddit') 24 | user = User.objects.get(pk=foo) 25 | social = user.social_auth.filter(provider='reddit')[0] 26 | social.refresh_token(strategy=strategy, 27 | redirect_uri='http://localhost:8000/complete/reddit/') 28 | 29 | Reddit requires ``redirect_uri`` when refreshing the token and it must be the 30 | same value used during the auth process. 31 | 32 | .. _Reddit Preferences Apps: https://ssl.reddit.com/prefs/apps/ 33 | .. _OAuth2 authentication workflow: https://github.com/reddit/reddit/wiki/OAuth2 34 | -------------------------------------------------------------------------------- /docs/backends/appsfuel.rst: -------------------------------------------------------------------------------- 1 | Appsfuel 2 | ======== 3 | 4 | Appsfuel uses OAuth v2 for Authentication check the `official docs`_ too. 5 | 6 | - Sign up at the `Appsfuel Developer Program`_ 7 | 8 | - Create and verify a new app 9 | 10 | - On the dashboard click on **Show API keys** 11 | 12 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 13 | 14 | SOCIAL_AUTH_APPSFUEL_KEY = '' 15 | SOCIAL_AUTH_APPSFUEL_SECRET = '' 16 | 17 | Appsfuel gives you the chance to integrate with **Live** or **Sandbox** env. 18 | 19 | 20 | Appsfuel Live 21 | ------------- 22 | 23 | - Add 'social_core.backends.contrib.appsfuel.AppsfuelBackend' into your 24 | ``AUTHENTICATION_BACKENDS``. 25 | 26 | - Then you can start using ``{% url social:begin 'appsfuel' %}`` in your 27 | templates 28 | 29 | 30 | Appsfuel Sandbox 31 | ---------------- 32 | 33 | - Add ``'social_core.backends.appsfuel.AppsfuelOAuth2Sandbox'`` into your 34 | ``AUTHENTICATION_BACKENDS``. 35 | 36 | - Then you can start using ``{% url social:begin 'appsfuel-sandbox' %}`` in 37 | your templates 38 | 39 | - Define the settings:: 40 | 41 | SOCIAL_AUTH_APPSFUEL_SANDBOX_KEY = '' 42 | SOCIAL_AUTH_APPSFUEL_SANDBOX_SECRET = '' 43 | 44 | 45 | .. _official docs: http://docs.appsfuel.com/api_reference#api_integration 46 | .. _Appsfuel Developer Program: https://developer.appsfuel.com 47 | -------------------------------------------------------------------------------- /docs/backends/battlenet.rst: -------------------------------------------------------------------------------- 1 | Battle.net 2 | ========== 3 | 4 | Blizzard implemented OAuth2 protocol for their authentication mechanism. To 5 | enable ``python-social-auth`` support follow this steps: 6 | 7 | 1. Go to `Battlenet Developer Portal`_ and create an application. 8 | 9 | 2. Fill App Id and Secret in your project settings:: 10 | 11 | SOCIAL_AUTH_BATTLENET_OAUTH2_KEY = '...' 12 | SOCIAL_AUTH_BATTLENET_OAUTH2_SECRET = '...' 13 | 14 | 3. Enable the backend:: 15 | 16 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 17 | ... 18 | 'social_core.backends.battlenet.BattleNetOAuth2', 19 | ... 20 | ) 21 | 22 | Note: If you want to allow the user to choose a username from their own 23 | characters, some further steps are required, see the use cases part of the 24 | documentation. To get the account id and battletag use the user_data function, as 25 | `account id is no longer passed inherently`_. 26 | 27 | Another note: If you get a 500 response "Internal Server Error" the API now requires `https on callback endpoints`_. 28 | 29 | Further documentation at `Developer Guide`_. 30 | 31 | .. _Battlenet Developer Portal: https://dev.battle.net/ 32 | .. _Developer Guide: https://dev.battle.net/docs/read/oauth 33 | .. _https on callback endpoints: http://us.battle.net/en/forum/topic/17085510584 34 | .. _account id is no longer passed inherently: http://us.battle.net/en/forum/topic/18300183303 35 | -------------------------------------------------------------------------------- /docs/backends/discourse.rst: -------------------------------------------------------------------------------- 1 | Discourse 2 | ========= 3 | 4 | Discourse can serve as a Single Sign On provider for Authentication. 5 | 6 | - Deploy a Discourse application and `configure 7 | ` the 8 | application to enable Discourse as an SSO provider. 9 | 10 | - Fill in the shared secret and url of the Discourse server in the settings:: 11 | 12 | SOCIAL_AUTH_DISCOURSE_SECRET = "myDiscourseSecret" 13 | SOCIAL_AUTH_DISCOURSE_SERVER_URL = "https://my-discourse-site.com" 14 | 15 | 16 | Using multiple Discourse instances 17 | ---------------------------------- 18 | 19 | Since Discourse is a distributed application, multiple Discourse instances can 20 | be used as SSO providers. If this is the case, the DiscourseAuth class can be 21 | extended and configured as follows:: 22 | 23 | from social_core.backends.discourse import DiscourseAuth 24 | 25 | class DiscourseAuthFoo(DiscourseAuth): 26 | name = 'discourse-foo' 27 | 28 | class DiscourseAuthBar(DiscourseAuth): 29 | name = 'discourse-bar' 30 | 31 | Fill in the settings like so:: 32 | 33 | SOCIAL_AUTH_DISCOURSE_FOO_SECRET = "myDiscourseFooSecret" 34 | SOCIAL_AUTH_DISCOURSE_FOO_SERVER_URL = "https://my-discourse-foo-site.com" 35 | SOCIAL_AUTH_DISCOURSE_BAR_SECRET = "myDiscourseBarSecret" 36 | SOCIAL_AUTH_DISCOURSE_BAR_SERVER_URL = "https://my-discourse-bar-site.com" 37 | -------------------------------------------------------------------------------- /docs/backends/facebook_limited_login.rst: -------------------------------------------------------------------------------- 1 | Facebook Limited Login 2 | ====================== 3 | 4 | `Facebook Limited Login`_ is required by the Facebook iOS SDK. 5 | 6 | App creation 7 | ------------ 8 | 9 | Register a new application at `Facebook App Creation`_, don't use 10 | ``localhost`` in the ``App Domains`` and ``Site URL`` fields as 11 | Facebook does not allow this. 12 | 13 | Instead, use a placeholder like ``myapp.com`` and define that 14 | domain in your ``/etc/hosts`` or similar file for your OS. For 15 | more information see the `hosts file`_ article on Wikipedia. 16 | 17 | Configuration 18 | ------------- 19 | 20 | Set the ``SOCIAL_AUTH_FACEBOOK_LIMITED_LOGIN_KEY`` to the value 21 | of the ``App Id``. This field is required for verifying the 22 | Facebook access token received from the iOS SDK. 23 | 24 | 25 | Django Configuration 26 | -------------------- 27 | 28 | Set the Facebook Limited Login Key in ``settings.py``: 29 | 30 | .. code-block:: python 31 | 32 | SOCIAL_AUTH_FACEBOOK_LIMITED_LOGIN_KEY = "{app_id}" 33 | 34 | 35 | Enable the auth backend: 36 | 37 | .. code-block:: python 38 | 39 | AUTHENTICATION_BACKENDS = ( 40 | ... 41 | "social_core.backends.facebook_limited.FacebookLimitedLogin", 42 | ... 43 | ) 44 | 45 | .. _Facebook App Creation: https://developers.facebook.com/apps/creation/ 46 | .. _Facebook Limited Login: https://developers.facebook.com/docs/facebook-login/limited-login/ 47 | .. _hosts file: https://en.wikipedia.org/wiki/Hosts_(file) 48 | -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | Welcome to Python Social Auth's documentation! 2 | ============================================== 3 | 4 | Python Social Auth aims to be an easy-to-setup social authentication and 5 | authorization mechanism for Python projects supporting protocols like OAuth (1 6 | and 2), OpenID and others. 7 | 8 | The initial codebase is derived from django-social-auth_ with the idea of 9 | generalizing the process to suit the different frameworks around, providing 10 | the needed tools to bring support to new frameworks. 11 | 12 | django-social-auth_ itself was a product of modified code from 13 | django-twitter-oauth_ and django-openid-auth_ projects. 14 | 15 | The project is now split into smaller modules to isolate and reduce 16 | responsibilities and improve reusability. 17 | 18 | Code and other contributions are welcome. The code is hosted on GitHub_. 19 | 20 | .. toctree:: 21 | :maxdepth: 2 22 | :hidden: 23 | 24 | intro 25 | maintainers 26 | installing 27 | configuration/index 28 | pipeline 29 | strategies 30 | storage 31 | exceptions 32 | backends/index 33 | developer_intro 34 | logging_out 35 | tests 36 | use_cases 37 | thanks 38 | copyright 39 | genindex 40 | modindex 41 | 42 | 43 | .. _django-social-auth: http://github.com/omab/django-social-auth 44 | .. _django-twitter-oauth: https://github.com/henriklied/django-twitter-oauth 45 | .. _django-openid-auth: https://launchpad.net/django-openid-auth 46 | .. _GitHub: https://github.com/python-social-auth/ 47 | -------------------------------------------------------------------------------- /docs/backends/orcid.rst: -------------------------------------------------------------------------------- 1 | ORCID 2 | ===== 3 | 4 | ORCID_ uses OAuth 2 for authentication. 5 | 6 | - Register an ORCID account, go to `Developer tools`_, enable the public API, 7 | create a new application, set the redirect URI to 8 | ``http://example.com/complete/orcid/`` replacing ``example.com`` with your 9 | domain. 10 | 11 | - Fill the ``Client ID`` and ``Client secret`` values from the app details in 12 | `Developer tools` (you might need to press "Show details") in the settings:: 13 | 14 | SOCIAL_AUTH_ORCID_KEY = '' 15 | SOCIAL_AUTH_ORCID_SECRET = '' 16 | 17 | 18 | Member API 19 | ---------- 20 | 21 | You can subscribe to gain access to an `API with extended capabilities`_. 22 | Use ``'social_core.backends.orcid.ORCIDMemberOAuth2'`` class in your 23 | ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS``. 24 | 25 | 26 | Sandbox 27 | ------- 28 | 29 | ORCID supports a sandbox mode for testing, there's a custom backend for it 30 | which name is ``orcid-sandbox`` instead of ``orcid``. Same settings apply 31 | but use these instead:: 32 | 33 | SOCIAL_AUTH_ORCID_SANDBOX_KEY = '' 34 | SOCIAL_AUTH_ORCID_SANDBOX_SECRET = '' 35 | 36 | Sandbox is also available for Member API. You will have to register for with 37 | ORCID it `separately`_. 38 | 39 | .. _ORCID: https://orcid.org/ 40 | .. _Developer tools: https://orcid.org/developer-tools 41 | .. _API with extended capabilities: https://orcid.org/organizations/integrators/API 42 | .. _separately: https://orcid.org/content/register-client-application-sandbox 43 | -------------------------------------------------------------------------------- /docs/logging_out.rst: -------------------------------------------------------------------------------- 1 | Disconnect and Logging Out 2 | ========================== 3 | 4 | It's a common misconception that the ``disconnect`` action is the same as 5 | logging the user out, but this is not the case. 6 | 7 | ``Disconnect`` is the way that your users can ask your project to "forget about 8 | my account". This implies removing the ``UserSocialAuth`` instance that was 9 | created, this also implies that the user won't be able to login back into your 10 | site with the social account. Instead the action will be a signup, a new user 11 | instance will be created, not related to the previous one. 12 | 13 | Logging out is just a way to say "forget my current session", and usually 14 | implies removing cookies, invalidating a session hash, etc. The many frameworks 15 | have their own ways to logout an account (Django has ``django.contrib.auth.logout``), 16 | ``flask-login`` has it's own way too with `logout_user()`_. 17 | 18 | Since disconnecting a social account means that the user won't be able to log 19 | back in with that social provider into the same user, python-social-auth will 20 | check that the user account is in a valid state for disconnection (it has at 21 | least one more social account associated, or a password, etc). This behavior 22 | can be overridden by changing the `Disconnection Pipeline`_. 23 | 24 | .. _logout_user(): https://github.com/maxcountryman/flask-login/blob/a96de342eae560deec008a02179f593c3799b3ba/flask_login.py#L718-L739 25 | .. _Disconnection Pipeline: pipeline.html#disconnection-pipeline 26 | -------------------------------------------------------------------------------- /docs/images/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 12 | 14 | 33 | 37 | 38 | -------------------------------------------------------------------------------- /docs/backends/salesforce.rst: -------------------------------------------------------------------------------- 1 | Salesforce 2 | ========== 3 | 4 | Salesforce uses OAuth v2 for Authentication, check the `official docs`_. 5 | 6 | - Create an app following the steps in the `Defining Connected Apps`_ docs. 7 | 8 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 9 | 10 | SOCIAL_AUTH_SALESFORCE_OAUTH2_KEY = '' 11 | SOCIAL_AUTH_SALESFORCE_OAUTH2_SECRET = '' 12 | 13 | - Add the backend to the ``AUTHENTICATION_BACKENDS`` setting:: 14 | 15 | AUTHENTICATION_BACKENDS = ( 16 | ... 17 | 'social_core.backends.salesforce.SalesforceOAuth2', 18 | ... 19 | ) 20 | 21 | - Then you can start using ``{% url social:begin 'salesforce-oauth2' %}`` in 22 | your templates 23 | 24 | 25 | If using the sandbox mode: 26 | 27 | - Fill these settings instead:: 28 | 29 | SOCIAL_AUTH_SALESFORCE_OAUTH2_SANDBOX_KEY = '' 30 | SOCIAL_AUTH_SALESFORCE_OAUTH2_SANDBOX_SECRET = '' 31 | 32 | - And this backend:: 33 | 34 | AUTHENTICATION_BACKENDS = ( 35 | ... 36 | 'social_core.backends.salesforce.SalesforceOAuth2Sandbox', 37 | ... 38 | ) 39 | 40 | - Then you can start using ``{% url social:begin 'salesforce-oauth2-sandbox' %}`` 41 | in your templates 42 | 43 | .. _official docs: https://www.salesforce.com/us/developer/docs/api_rest/Content/intro_understanding_web_server_oauth_flow.htm 44 | .. _Defining Connected Apps: https://www.salesforce.com/us/developer/docs/api_rest/Content/intro_defining_remote_access_applications.htm 45 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2012-2016, Matías Aguirre 2 | All rights reserved. 3 | 4 | Redistribution and use in source and binary forms, with or without modification, 5 | are permitted provided that the following conditions are met: 6 | 7 | 1. Redistributions of source code must retain the above copyright notice, 8 | this list of conditions and the following disclaimer. 9 | 10 | 2. Redistributions in binary form must reproduce the above copyright 11 | notice, this list of conditions and the following disclaimer in the 12 | documentation and/or other materials provided with the distribution. 13 | 14 | 3. Neither the name of this project nor the names of its contributors may be 15 | used to endorse or promote products derived from this software without 16 | specific prior written permission. 17 | 18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 19 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 20 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 21 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR 22 | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 23 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 25 | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 27 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 | -------------------------------------------------------------------------------- /docs/backends/douban.rst: -------------------------------------------------------------------------------- 1 | Douban 2 | ====== 3 | 4 | Douban supports OAuth 1 and 2. 5 | 6 | Douban OAuth1 7 | ------------- 8 | 9 | Douban OAuth 1 works similar to Twitter OAuth. 10 | 11 | Douban offers per application keys named ``Consumer Key`` and ``Consumer 12 | Secret``. To enable Douban OAuth these two keys are needed. Further 13 | documentation at `Douban Services & API`_: 14 | 15 | - Register a new application at `Douban API Key`_, make sure to mark the **web 16 | application** checkbox. 17 | 18 | - Fill **Consumer Key** and **Consumer Secret** values in settings:: 19 | 20 | SOCIAL_AUTH_DOUBAN_KEY = '' 21 | SOCIAL_AUTH_DOUBAN_SECRET = '' 22 | 23 | - Add ``'social_core.backends.douban.DoubanOAuth'`` into your 24 | ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS``. 25 | 26 | 27 | Douban OAuth2 28 | ------------- 29 | 30 | Recently Douban launched their OAuth2 support and the new developer site, you 31 | can find documentation at `Douban Developers`_. To setup OAuth2 follow: 32 | 33 | - Register a new application at `Create A Douban App`_, make sure to mark the 34 | **web application** checkbox. 35 | 36 | - Fill **Consumer Key** and **Consumer Secret** values in settings:: 37 | 38 | SOCIAL_AUTH_DOUBAN_OAUTH2_KEY = '' 39 | SOCIAL_AUTH_DOUBAN_OAUTH2_SECRET = '' 40 | 41 | - Add ``'social_core.backends.douban.DoubanOAuth2'`` into your 42 | ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS``. 43 | 44 | .. _Douban Services & API: http://www.douban.com/service/ 45 | .. _Douban API Key: http://www.douban.com/service/apikey/apply 46 | .. _Douban Developers: http://developers.douban.com/ 47 | .. _Create A Douban App : http://developers.douban.com/apikey/apply 48 | -------------------------------------------------------------------------------- /docs/backends/etsy.rst: -------------------------------------------------------------------------------- 1 | Etsy OAuth2 2 | ============================= 3 | 4 | Etsy supports the `OAuth 2.0`_ protocol using Authorization code with `Proof Key for Code Exchange (PKCE)`_ flow. 5 | 6 | Configuration 7 | -------------- 8 | 9 | 1. Register a new `Application Link`_ in your Etsy Account. 10 | 11 | 2. Fill *Client ID* in ``SOCIAL_AUTH_ETSY_OAUTH2_KEY`` in your project settings:: 12 | 13 | SOCIAL_AUTH_ETSY_OAUTH2_KEY = "..." 14 | 15 | Note: *Client Secret* isn't required via this flow. 16 | 17 | 3. Enable the backend:: 18 | 19 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 20 | ... 21 | "social_core.backends.etsy.EtsyOAuth2", 22 | ... 23 | ) 24 | 25 | Extra Configuration 26 | -------------------- 27 | 28 | - You can specify the scope that your application requires:: 29 | 30 | SOCIAL_AUTH_ETSY_OAUTH2_SCOPE = ["shops_r", "shops_w", ...] 31 | 32 | You can see all possible values at `Etsy OAuth 2.0 provider API Scopes`_. 33 | 34 | - You can specify PKCE challenge method:: 35 | 36 | SOCIAL_AUTH_ETSY_OAUTH2_PKCE_CODE_CHALLENGE_METHOD = '...' 37 | 38 | The possible value for this is only ``S256`` which is set by default. 39 | 40 | You can see more information about PKCE at `RFC7636`_. 41 | 42 | .. _OAuth 2.0: https://developer.etsy.com/documentation/essentials/authentication 43 | .. _Application Link: https://developer.etsy.com/documentation/#developing-a-new-open-api-app 44 | .. _Proof Key for Code Exchange (PKCE): https://datatracker.ietf.org/doc/html/rfc7636 45 | .. _RFC7636: https://datatracker.ietf.org/doc/html/rfc7636 46 | .. _Etsy OAuth 2.0 provider API Scopes: https://developer.etsy.com/documentation/essentials/authentication/#scopes 47 | -------------------------------------------------------------------------------- /docs/backends/telegram.rst: -------------------------------------------------------------------------------- 1 | Telegram 2 | ======== 3 | 4 | Telegram uses a widget-based authentication method for login. 5 | 6 | - Create a bot using `BotFather`_ on Telegram to get a bot token. 7 | 8 | - Add the Telegram backend to ``AUTHENTICATION_BACKENDS``:: 9 | 10 | AUTHENTICATION_BACKENDS = ( 11 | ... 12 | 'social_core.backends.telegram.TelegramAuth', 13 | ... 14 | ) 15 | 16 | - Fill the ``Bot Token`` value in the settings:: 17 | 18 | SOCIAL_AUTH_TELEGRAM_BOT_TOKEN = '' 19 | 20 | - Add the Telegram Login Widget to your login page. The widget should be configured 21 | to send authentication data to your callback URL, which should be something like 22 | ``http://example.com/complete/telegram/`` replacing ``example.com`` with your domain. 23 | 24 | - The Telegram Login Widget can be added using the following HTML:: 25 | 26 | 31 | 32 | Replace ``YOUR_BOT_USERNAME`` with your bot's username (without the @ symbol) 33 | and update the ``data-auth-url`` to match your domain. 34 | 35 | - The authentication process verifies the data integrity using HMAC-SHA256 with 36 | the bot token. Authentication data is considered valid for 24 hours from the 37 | ``auth_date`` timestamp. 38 | 39 | - The backend extracts the following user information: 40 | - User ID (required) 41 | - Username 42 | - First name 43 | - Last name 44 | - Photo URL (if available) 45 | 46 | .. _BotFather: https://t.me/botfather 47 | -------------------------------------------------------------------------------- /docs/tests.rst: -------------------------------------------------------------------------------- 1 | Testing python-social-auth 2 | ========================== 3 | 4 | Testing the application is fairly simple, just met the dependencies and run the 5 | testing suite. 6 | 7 | The testing suite uses HTTPretty_ to mock server responses, it's not a live 8 | test against the providers API, to do it that way, a browser and a tool like 9 | Selenium are needed, that's slow, prone to errors on some cases, and some of 10 | the application examples must be running to perform the testing. Plus real Key 11 | and Secret pairs, in the end it's a mess to test functionality which is the 12 | real point. 13 | 14 | By mocking the server responses, we can test the backends functionality (and 15 | other areas too) easily and quick. 16 | 17 | 18 | Installing dependencies 19 | ----------------------- 20 | 21 | Go to the tests_ directory and install the dependencies listed in the 22 | requirements.txt_. Then run with ``nosetests`` command, or with the 23 | ``run_tests.sh`` script. 24 | 25 | Tox 26 | --- 27 | 28 | You can use tox_ to test compatibility against all supported Python versions: 29 | 30 | .. code-block:: bash 31 | 32 | $ pip install tox # if not present 33 | $ tox 34 | 35 | 36 | Pending 37 | ------- 38 | 39 | At the moment only OAuth1, OAuth2 and OpenID backends are being tested, and 40 | just login and partial pipeline features are covered by the test. There's still 41 | a lot to work on, like: 42 | 43 | * Frameworks support 44 | 45 | .. _HTTPretty: https://github.com/gabrielfalcao/HTTPretty 46 | .. _tests: https://github.com/python-social-auth/social-core/tree/master/social_core/tests 47 | .. _requirements.txt: https://github.com/python-social-auth/social-core/blob/master/social_core/tests/requirements.txt 48 | .. _tox: http://tox.readthedocs.org/ 49 | -------------------------------------------------------------------------------- /docs/backends/persona.rst: -------------------------------------------------------------------------------- 1 | Mozilla Persona 2 | =============== 3 | 4 | Support for `Mozilla Persona`_ is possible by posting the ``assertion`` code to 5 | ``/complete/persona/`` URL. 6 | 7 | The setup doesn't need any setting, just the usual `Mozilla Persona`_ 8 | javascript include in your document and the needed mechanism to trigger the 9 | POST to `python-social-auth`_:: 10 | 11 | 12 | 13 | 14 | 15 |
16 | 17 | Mozilla Persona 18 |
19 | 20 | 21 | 41 | 42 | .. _python-social-auth: https://github.com/python-social-auth 43 | .. _Mozilla Persona: http://www.mozilla.org/persona/ 44 | -------------------------------------------------------------------------------- /docs/backends/dropbox.rst: -------------------------------------------------------------------------------- 1 | Dropbox 2 | ======= 3 | 4 | Dropbox supports both OAuth 1 and 2. 5 | 6 | - Register a new application at `Dropbox Developers`_, and follow the 7 | instructions below for the version of OAuth for which you are adding 8 | support. 9 | 10 | 11 | OAuth2 Api V2 12 | ------------- 13 | 14 | Add the Dropbox OAuth2 backend to your settings page:: 15 | 16 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 17 | ... 18 | 'social.backends.dropbox.DropboxOAuth2V2', 19 | ... 20 | ) 21 | 22 | - Fill ``App Key`` and ``App Secret`` values in the settings:: 23 | 24 | SOCIAL_AUTH_DROPBOX_OAUTH2_KEY = '' 25 | SOCIAL_AUTH_DROPBOX_OAUTH2_SECRET = '' 26 | 27 | OAuth1 28 | ------ 29 | 30 | .. deprecated:: V1 api is deprecated. https://blogs.dropbox.com/developers/2016/06/api-v1-deprecated/ 31 | 32 | Add the Dropbox OAuth backend to your settings page:: 33 | 34 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 35 | ... 36 | 'social_core.backends.dropbox.DropboxOAuth', 37 | ... 38 | ) 39 | 40 | - Fill ``App Key`` and ``App Secret`` values in the settings:: 41 | 42 | SOCIAL_AUTH_DROPBOX_KEY = '' 43 | SOCIAL_AUTH_DROPBOX_SECRET = '' 44 | 45 | OAuth2 46 | ------ 47 | 48 | .. deprecated:: V1 api is deprecated. https://blogs.dropbox.com/developers/2016/06/api-v1-deprecated/ 49 | 50 | Add the Dropbox OAuth2 backend to your settings page:: 51 | 52 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 53 | ... 54 | 'social_core.backends.dropbox.DropboxOAuth2', 55 | ... 56 | ) 57 | 58 | - Fill ``App Key`` and ``App Secret`` values in the settings:: 59 | 60 | SOCIAL_AUTH_DROPBOX_OAUTH2_KEY = '' 61 | SOCIAL_AUTH_DROPBOX_OAUTH2_SECRET = '' 62 | 63 | .. _Dropbox Developers: https://www.dropbox.com/developers/apps 64 | -------------------------------------------------------------------------------- /docs/backends/cas.rst: -------------------------------------------------------------------------------- 1 | CAS (OpenID Connect via Apereo CAS) 2 | =================================== 3 | 4 | The CAS_ backend allows authentication against an Apereo CAS OIDC provider. 5 | The backend class is `CASOpenIdConnectAuth` with name `cas`. A minimum 6 | configuration is:: 7 | 8 | SOCIAL_AUTH_CAS_OIDC_ENDPOINT = 'https://.....' 9 | SOCIAL_AUTH_CAS_KEY = '' 10 | SOCIAL_AUTH_CAS_SECRET = '' 11 | 12 | The remaining configuration will be auto-detected, by fetching:: 13 | 14 | /.well-known/openid-configuration 15 | 16 | This class functions identically to the generic OIDC backend, but hides 17 | the differences in implementation details of the OIDC implementation in 18 | Apereo CAS. 19 | 20 | Note that despite the naming of the backend, this is NOT an implementation 21 | of the CAS protocol, also supported by Apereo CAS. The CAS backend is only 22 | intended as a way to use the Apereo CAS identity provider as an 23 | authentication service, but via OIDC. 24 | 25 | Username 26 | -------- 27 | 28 | The CAS_ backend will check for a ``preferred_username`` key in the values 29 | returned by the server. If the username is under a different key, this can 30 | be overridden:: 31 | 32 | SOCIAL_AUTH_CAS_USERNAME_KEY = 'nickname' 33 | 34 | This setting indicates that the username should be populated by the 35 | ``nickname`` claim instead. 36 | 37 | Scopes 38 | ------ 39 | 40 | The default set of scopes requested are "openid", "profile" and "email". 41 | You can request additional claims, for example:: 42 | 43 | SOCIAL_AUTH_CAS_SCOPE = ['groups'] 44 | 45 | and you can prevent the inclusion of the default scopes using:: 46 | 47 | SOCIAL_AUTH_CAS_IGNORE_DEFAULT_SCOPE = True 48 | 49 | .. _CAS: https://apereo.github.io/cas/6.6.x/authentication/OIDC-Authentication.html 50 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | # See https://pre-commit.com for more information 2 | # See https://pre-commit.com/hooks.html for more hooks 3 | repos: 4 | - repo: https://github.com/pre-commit/pre-commit-hooks 5 | rev: v6.0.0 6 | hooks: 7 | - id: trailing-whitespace 8 | - id: end-of-file-fixer 9 | - id: check-merge-conflict 10 | - id: check-yaml 11 | - id: check-json 12 | - id: check-toml 13 | - id: check-merge-conflict 14 | - id: debug-statements 15 | - id: mixed-line-ending 16 | args: [--fix=lf] 17 | - id: pretty-format-json 18 | args: [--no-sort-keys, --autofix, --no-ensure-ascii] 19 | - repo: https://github.com/astral-sh/ruff-pre-commit 20 | rev: v0.14.10 21 | hooks: 22 | - id: ruff-check 23 | args: [--fix, --exit-non-zero-on-fix] 24 | - id: ruff-format 25 | - repo: meta 26 | hooks: 27 | - id: check-hooks-apply 28 | - id: check-useless-excludes 29 | - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks 30 | rev: v2.15.0 31 | hooks: 32 | - id: pretty-format-yaml 33 | args: [--autofix, --indent, '2'] 34 | - repo: https://github.com/pappasam/toml-sort 35 | rev: v0.24.3 36 | hooks: 37 | - id: toml-sort-fix 38 | - repo: https://github.com/abravalheri/validate-pyproject 39 | rev: v0.24.1 40 | hooks: 41 | - id: validate-pyproject 42 | - repo: https://github.com/executablebooks/mdformat 43 | rev: 1.0.0 44 | hooks: 45 | - id: mdformat 46 | additional_dependencies: 47 | - mdformat-gfm==1.0.0 48 | - repo: https://github.com/codespell-project/codespell 49 | rev: v2.4.1 50 | hooks: 51 | - id: codespell 52 | additional_dependencies: 53 | - tomli 54 | - repo: https://github.com/rhysd/actionlint 55 | rev: v1.7.9 56 | hooks: 57 | - id: actionlint 58 | - repo: https://github.com/zizmorcore/zizmor-pre-commit 59 | rev: v1.19.0 60 | hooks: 61 | - id: zizmor 62 | -------------------------------------------------------------------------------- /docs/backends/twitter.rst: -------------------------------------------------------------------------------- 1 | Twitter 2 | ======= 3 | 4 | Twitter offers per application keys named ``Consumer Key`` and ``Consumer Secret``. 5 | To enable Twitter these two keys are needed. Further documentation at 6 | `Twitter development resources`_: 7 | 8 | - Register a new application at `Twitter App Creation`_, 9 | 10 | - Check the **Allow this application to be used to Sign in with Twitter** 11 | checkbox. If you don't check this box, Twitter will force your user to login 12 | every time. 13 | 14 | - Fill **Consumer Key** and **Consumer Secret** values:: 15 | 16 | SOCIAL_AUTH_TWITTER_KEY = '' 17 | SOCIAL_AUTH_TWITTER_SECRET = '' 18 | 19 | - You need to specify an URL callback or the OAuth will raise a "403 Client Error". 20 | The callback URL should be something like "https://example.com/complete/twitter" 21 | 22 | - You can request user's Email address (consult `Twitter verify 23 | credentials`_), the parameter is sent automatically, but the 24 | application needs to be whitelisted in order to get a valid value. 25 | 26 | - You’ll need to apply for Elevated access via the Developer Portal, see `Twitter access levels`_ for more info. 27 | 28 | Twitter usually fails with a 401 error when trying to call the request-token 29 | URL, this is usually caused by server datetime errors (check miscellaneous 30 | section). Installing ``ntp`` and syncing the server date with some pool does 31 | the trick. 32 | 33 | 34 | .. _Twitter development resources: https://dev.twitter.com/oauth 35 | .. _Twitter App Creation: https://apps.twitter.com/apps/new 36 | .. _Twitter verify credentials: https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-verify_credentials 37 | .. _Twitter access levels: https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api#v2-access-level 38 | -------------------------------------------------------------------------------- /docs/exceptions.rst: -------------------------------------------------------------------------------- 1 | Exceptions 2 | ========== 3 | 4 | This set of exceptions were introduced to describe the situations a bit more 5 | than just the ``ValueError`` usually raised. 6 | 7 | ``SocialAuthBaseException`` 8 | Base class for all social auth exceptions. 9 | 10 | ``AuthException`` 11 | Base exception class for authentication process errors. 12 | 13 | ``AuthFailed`` 14 | Authentication failed for some reason. 15 | 16 | ``AuthCanceled`` 17 | Authentication was canceled by the user. 18 | 19 | ``AuthUnknownError`` 20 | An unknown error stopped the authentication process. 21 | 22 | ``AuthTokenError`` 23 | Unauthorized or access token error, it was invalid, impossible to 24 | authenticate or user removed permissions to it. 25 | 26 | ``AuthMissingParameter`` 27 | A needed parameter to continue the process was missing, usually raised by 28 | the services that need some POST data like myOpenID. 29 | 30 | ``AuthAlreadyAssociated`` 31 | A different user has already associated the social account that the current 32 | user is trying to associate. 33 | 34 | ``WrongBackend`` 35 | Raised when the backend given in the URLs is invalid (not enabled or 36 | registered). 37 | 38 | ``NotAllowedToDisconnect`` 39 | Raised on disconnect action when it's not safe for the user to disconnect 40 | the social account, probably because the user lacks a password or another 41 | social account. 42 | 43 | ``AuthStateMissing`` 44 | The state parameter is missing from the server response. 45 | 46 | ``AuthStateForbidden`` 47 | The state parameter returned by the server is not the one sent. 48 | 49 | ``AuthTokenRevoked`` 50 | Raised when the user revoked the access_token in the provider. 51 | 52 | ``AuthUnreachableProvider`` 53 | Raised when server couldn't communicate with backend. 54 | 55 | These are a subclass of ``ValueError`` to keep backward compatibility. 56 | -------------------------------------------------------------------------------- /docs/backends/oidc.rst: -------------------------------------------------------------------------------- 1 | OIDC (OpenID Connect) 2 | ===================== 3 | 4 | The OIDC_ backend allows authentication against a generic OIDC provider. 5 | The backend class is `OpenIdConnectAuth` with name `oidc`. A minimum 6 | configuration is:: 7 | 8 | SOCIAL_AUTH_OIDC_OIDC_ENDPOINT = 'https://.....' 9 | SOCIAL_AUTH_OIDC_KEY = '' 10 | SOCIAL_AUTH_OIDC_SECRET = '' 11 | 12 | The remaining configuration will be auto-detected, by fetching:: 13 | 14 | /.well-known/openid-configuration 15 | 16 | This class can be used standalone, but is also the base class for some other 17 | backends. 18 | 19 | Authentication Request Parameters 20 | --------------------------------- 21 | 22 | All this parameters are optional and they might not be supported by the OIDC provider. 23 | 24 | Prompt 25 | ^^^^^^ 26 | 27 | This informs the OIDC provider whether the OIDC provider prompts the user for reauthentication and consent. :: 28 | 29 | SOCIAL_AUTH_OIDC_PROMPT = ' ...' 30 | 31 | Defined values are 32 | 33 | - ``none`` 34 | - ``login`` 35 | - ``consent`` 36 | - ``select_account`` 37 | 38 | Username 39 | -------- 40 | 41 | The OIDC_ backend will check for a ``preferred_username`` key in the values 42 | returned by the server. If the username is under a different key, this can 43 | be overridden:: 44 | 45 | SOCIAL_AUTH_OIDC_USERNAME_KEY = 'nickname' 46 | 47 | This setting indicates that the username should be populated by the 48 | ``nickname`` claim instead. 49 | 50 | Scopes 51 | ------ 52 | 53 | The default set of scopes requested are "openid", "profile" and "email". 54 | You can request additional claims, for example:: 55 | 56 | SOCIAL_AUTH_OIDC_SCOPE = ['groups'] 57 | 58 | and you can prevent the inclusion of the default scopes using:: 59 | 60 | SOCIAL_AUTH_OIDC_IGNORE_DEFAULT_SCOPE = True 61 | 62 | .. _OIDC: https://openid.net/connect/ 63 | -------------------------------------------------------------------------------- /docs/backends/openstreetmap_oauth2.rst: -------------------------------------------------------------------------------- 1 | OpenStreetMap OAuth 2 2 | ===================== 3 | 4 | OpenStreetMap supports the OAuth 2.0 protocol. It supports two types of OAuth 2.0 flows: 5 | 6 | 1. Authorization code with `Proof Key for Code Exchange (PKCE)`_ 7 | 2. Authorization code 8 | 9 | Configuration 10 | ------------- 11 | 12 | - Login to your account 13 | 14 | - Register your application as OAuth 2 application on the `My Client Applications page`_ 15 | 16 | * Set the redirect URIs to https://example.com/complete/openstreetmap-oauth2/ 17 | * PKCE can be enabled/disabled using the "Confidential application?" flag. 18 | * Select all required Permissions. 19 | * Scopes names are shown next to each permission after saving. 20 | 21 | - Fill *Client ID* in ``SOCIAL_AUTH_OPENSTREETMAP_OAUTH2_KEY`` and 22 | *Client Secret* in ``SOCIAL_AUTH_OPENSTREETMAP_OAUTH2_SECRET`` 23 | 24 | SOCIAL_AUTH_OPENSTREETMAP_OAUTH2_KEY = '...' 25 | SOCIAL_AUTH_OPENSTREETMAP_OAUTH2_SECRET = '...' 26 | 27 | Note: *Client Secret* isn't required for PKCE. 28 | 29 | - Enable the backend:: 30 | 31 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 32 | ... 33 | 'social_core.backends.openstreetmap_oauth2.OpenStreetMapOAuth2', 34 | ... 35 | ) 36 | 37 | Access tokens currently do not expire automatically. 38 | 39 | More documentation at `OpenStreetMap Wiki`_: 40 | 41 | Extra Configuration 42 | -------------------- 43 | 44 | - You can specify the scopes that your application requires:: 45 | 46 | SOCIAL_AUTH_OPENSTREETMAP_OAUTH2_SCOPE = [ 'read_prefs' ] 47 | 48 | - You can choose to disable PKCE:: 49 | 50 | SOCIAL_AUTH_OPENSTREETMAP_OAUTH2_USE_PKCE = False 51 | 52 | By default, `True` is set. 53 | 54 | 55 | .. _OpenStreetMap Wiki: http://wiki.openstreetmap.org/wiki/OAuth 56 | .. _My Client Applications page: https://www.openstreetmap.org/oauth2/applications 57 | .. _Proof Key for Code Exchange (PKCE): https://datatracker.ietf.org/doc/html/rfc7636 58 | -------------------------------------------------------------------------------- /docs/backends/openid.rst: -------------------------------------------------------------------------------- 1 | OpenID 2 | ====== 3 | 4 | OpenID_ support is simpler to implement than OAuth_. Google and Yahoo 5 | providers are supported by default, others are supported by POST method 6 | providing endpoint URL. 7 | 8 | OpenID_ backends can store extra data in ``UserSocialAuth.extra_data`` field 9 | by defining a set of values names to retrieve from any of the used schemas, 10 | AttributeExchange and SimpleRegistration. As their keywords differ we need 11 | two settings. 12 | 13 | Settings is per backend, so we have two possible values for each one. Name 14 | is dynamically checked using uppercase backend name as prefix:: 15 | 16 | SOCIAL_AUTH__SREG_EXTRA_DATA 17 | SOCIAL_AUTH__AX_EXTRA_DATA 18 | 19 | Example:: 20 | 21 | SOCIAL_AUTH_GOOGLE_SREG_EXTRA_DATA = [(..., ...)] 22 | SOCIAL_AUTH_GOOGLE_AX_EXTRA_DATA = [(..., ...)] 23 | 24 | Settings must be a list of tuples mapping value name in response and value 25 | alias used to store. A third value (boolean) is supported to, it's purpose is 26 | to signal if the value should be discarded if it evaluates to ``False``, this 27 | is to avoid replacing old (needed) values when they don't form part of current 28 | response. If not present, then this check is avoided and the value will replace 29 | any data. 30 | 31 | Username 32 | -------- 33 | 34 | The OpenID_ backend will check for a ``username`` key in the values returned by 35 | the server, but default to ``first-name`` + ``last-name`` if that key is 36 | missing. It's possible to indicate the username key in the values If the 37 | username is under a different key with a setting, but backends should have 38 | defined a default value. For example:: 39 | 40 | SOCIAL_AUTH_FEDORA_USERNAME_KEY = 'nickname' 41 | 42 | This setting indicates that the username should be populated by the 43 | ``nickname`` value in the Fedora OpenID_ provider. 44 | 45 | .. _OpenID: http://openid.net/ 46 | .. _OAuth: http://oauth.net/ 47 | -------------------------------------------------------------------------------- /docs/backends/shopify.rst: -------------------------------------------------------------------------------- 1 | Shopify 2 | ======= 3 | 4 | Shopify uses OAuth 2 for authentication. 5 | 6 | To use this backend, you must: 7 | 8 | - Install the `Shopify python library`_:: 9 | 10 | pip install --upgrade ShopifyAPI 11 | 12 | - Register a new application at `Shopify Partners`_ 13 | - Configure your Shopify app to use the application URL of `https://[your domain]/login/shopify/` 14 | - Configure your Shopify app to use the callback URL of `https://[your domain]/complete/shopify/` 15 | - If you're using Django, add the backend to your AUTHENTICATION_BACKENDS configuration:: 16 | 17 | AUTHENTICATION_BACKENDS = ( 18 | ..., 19 | 'social_core.backends.shopify.ShopifyOAuth2', 20 | ..., 21 | ) 22 | 23 | - fill ``API Key`` and ``Shared Secret`` values in your django settings:: 24 | 25 | SOCIAL_AUTH_SHOPIFY_KEY = '' 26 | SOCIAL_AUTH_SHOPIFY_SECRET = '' 27 | 28 | - fill the scope permissions that you require into the settings `Shopify API`_:: 29 | 30 | SOCIAL_AUTH_SHOPIFY_SCOPE = ['write_script_tags', 31 | 'read_orders', 32 | 'write_customers', 33 | 'read_products'] 34 | 35 | - If you'd like to, you can set your desired Shopify API version in your settings:: 36 | 37 | SOCIAL_AUTH_SHOPIFY_API_VERSION = '2020-10' 38 | 39 | `ShopifyAPI 5.0.0`_ introduced a non backward compatible change in order to 40 | support Shopify API versioning. The backend will default to value `2019-04` but 41 | it's possible to override the default with the following setting:: 42 | 43 | SOCIAL_AUTH_SHOPIFY_API_VERSION = 'unstable' 44 | 45 | .. _Shopify Partners: http://www.shopify.com/partners 46 | .. _Shopify API: http://api.shopify.com/authentication.html#scopes 47 | .. _Shopify python library: https://github.com/Shopify/shopify_python_api 48 | .. _ShopifyAPI 5.0.0: https://github.com/Shopify/shopify_python_api#-breaking-change-notice-for-version-500- 49 | -------------------------------------------------------------------------------- /docs/backends/odnoklassnikiru.rst: -------------------------------------------------------------------------------- 1 | Odnoklassniki.ru 2 | ================ 3 | 4 | There are two options with Odnoklassniki: either you use OAuth2 workflow to 5 | authenticate odnoklassniki users at external site, or you authenticate users 6 | within your IFrame application. 7 | 8 | OAuth2 9 | ------ 10 | 11 | If you use OAuth2 workflow, you need to: 12 | 13 | - register a new application with `OAuth registration form`_ 14 | 15 | - fill out some settings:: 16 | 17 | SOCIAL_AUTH_ODNOKLASSNIKI_OAUTH2_KEY = '' 18 | SOCIAL_AUTH_ODNOKLASSNIKI_OAUTH2_SECRET = '' 19 | SOCIAL_AUTH_ODNOKLASSNIKI_OAUTH2_PUBLIC_NAME = '' 20 | 21 | - add ``'social_core.backends.odnoklassniki.OdnoklassnikiOAuth2'`` into your 22 | ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS``. 23 | 24 | 25 | IFrame applications 26 | ------------------- 27 | 28 | If you want to authenticate users in your IFrame application, 29 | 30 | - read `Rules for application developers`_ 31 | 32 | - fill out `Developers registration form`_ 33 | 34 | - get your personal sandbox 35 | 36 | - fill out some settings:: 37 | 38 | SOCIAL_AUTH_ODNOKLASSNIKI_APP_KEY = '' 39 | SOCIAL_AUTH_ODNOKLASSNIKI_APP_SECRET = '' 40 | SOCIAL_AUTH_ODNOKLASSNIKI_APP_PUBLIC_NAME = '' 41 | 42 | - add ``'social_core.backends.odnoklassniki.OdnoklassnikiApp'`` into your 43 | ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS`` 44 | 45 | - sign a public offer and do some bureaucracy 46 | 47 | You may also use:: 48 | 49 | SOCIAL_AUTH_ODNOKLASSNIKI_APP_EXTRA_USER_DATA_LIST 50 | 51 | Defaults to empty tuple, for the list of available fields see `Documentation on user.getInfo`_ 52 | 53 | .. _OAuth registration form: https://apiok.ru/wiki/pages/viewpage.action?pageId=42476652 54 | .. _Rules for application developers: https://apiok.ru/wiki/display/ok/Odnoklassniki.ru+Third+Party+Platform 55 | .. _Developers registration form: https://apiok.ru/wiki/pages/viewpage.action?pageId=5668937 56 | .. _Documentation on user.getInfo: https://apiok.ru/wiki/display/ok/REST+API+-+users.getInfo 57 | -------------------------------------------------------------------------------- /docs/backends/nfdi.rst: -------------------------------------------------------------------------------- 1 | NFDI (OpenID Connect) 2 | ===================== 3 | 4 | The NFDI_ backend allows authentication against all OIDC providers of `NFDI` 5 | (German National Research Data Infrastructure) and also for the Helmholtz 6 | AAI. These backends provides their endpoints, as well as the 7 | default scopes. 8 | 9 | The provided backends are: 10 | 11 | ``` 12 | XcsOpenIdConnect 13 | TextplusOpenIdConnect 14 | MardiOpenIdConnect 15 | ObjectsOpenIdConnect 16 | CultureOpenIdConnect 17 | CatOpenIdConnect 18 | ChemOpenIdConnect 19 | DatascienceOpenIdConnect 20 | EnergyOpenIdConnect 21 | IngOpenIdConnect 22 | MatWerkOpenIdConnect 23 | DaphneOpenIdConnect 24 | FairmatOpenIdConnect 25 | ImmunoOpenIdConnect 26 | PunchOpenIdConnect 27 | HelmholtzOpenIdConnect 28 | InfraproxyStagingOpenIdConnect 29 | InfraproxyOpenIdConnect 30 | EduidOpenIdConnect 31 | EduidStagingOpenIdConnect 32 | ``` 33 | 34 | A minimum configuration is:: 35 | 36 | SOCIAL_AUTH_OIDC_KEY = '' 37 | SOCIAL_AUTH_OIDC_SECRET = '' 38 | 39 | The remaining configuration will be auto-detected, by fetching:: 40 | 41 | /.well-known/openid-configuration 42 | 43 | This class can be used standalone, but may also be used as the base class for some other 44 | backends. Find more information at the NFDI_AAI_WEBSITE_ 45 | 46 | Username 47 | -------- 48 | 49 | The NFDI_ backend will check for a ``preferred_username`` key in the values 50 | returned by the server. If the username is under a different key, this can 51 | be overridden:: 52 | 53 | SOCIAL_AUTH_OIDC_USERNAME_KEY = 'nickname' 54 | 55 | This setting indicates that the username should be populated by the 56 | ``nickname`` claim instead. 57 | 58 | Scopes 59 | ------ 60 | 61 | The default set of scopes requested are those configured by default in the 62 | cleass. You can request additional claims, for example:: 63 | 64 | SOCIAL_AUTH_OIDC_SCOPE = ['groups'] 65 | 66 | 67 | .. _NFDI: https://nfdi.de 68 | .. _NFDI_AAI_WEBSITE: https://doc.nfdi-aai.de 69 | -------------------------------------------------------------------------------- /docs/backends/apple.rst: -------------------------------------------------------------------------------- 1 | AppleID 2 | ======= 3 | 4 | Apple ID implemented OAuth2 and OpenID Connect protocols for their authentication mechanism. To 5 | enable ``python-social-auth`` support follow this steps: 6 | 7 | 1. Go to `Apple Developer Portal`_ and 8 | 9 | 1. `Create or select an existing App ID`_ 10 | 2. `Create a Sign Certificate`_ 11 | 3. `Create a Services ID`_, activate "Sign In with Apple" and grant your "return URLs" 12 | 13 | 2. Fill App Id and Secret in your project settings:: 14 | 15 | SOCIAL_AUTH_APPLE_ID_CLIENT = '...' # Your client_id com.application.your, aka "Service ID" 16 | SOCIAL_AUTH_APPLE_ID_TEAM = '...' # Your Team ID, ie K2232113 17 | SOCIAL_AUTH_APPLE_ID_KEY = '...' # Your Key ID, ie Y2P99J3N81K 18 | SOCIAL_AUTH_APPLE_ID_SECRET = """ 19 | -----BEGIN PRIVATE KEY----- 20 | MIGTAgE..... 21 | -----END PRIVATE KEY-----""" 22 | SOCIAL_AUTH_APPLE_ID_SCOPE = ['email', 'name'] 23 | SOCIAL_AUTH_APPLE_ID_EMAIL_AS_USERNAME = True # If you want to use email as username 24 | 25 | 3. Enable the backend:: 26 | 27 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 28 | ... 29 | 'social_core.backends.apple.AppleIdAuth', 30 | ... 31 | ) 32 | 33 | Further documentation at `Website Developer Guide`_ and `Getting Started`_. 34 | 35 | .. _Apple Developer Portal: https://developer.apple.com/ 36 | .. _Website Developer Guide: https://developer.apple.com/documentation/signinwithapplerestapi/authenticating_users_with_sign_in_with_apple 37 | .. _Getting Started: https://developer.apple.com/sign-in-with-apple/get-started/ 38 | .. _Authenticating users: https://developer.apple.com/documentation/signinwithapplerestapi/authenticating_users_with_sign_in_with_apple 39 | .. _Create a Sign Certificate: https://help.apple.com/developer-account/?lang=en#/dev77c875b7e 40 | .. _Create or select an existing App ID: https://help.apple.com/developer-account/?lang=en#/devde676e696 41 | .. _Create a Services ID: https://help.apple.com/developer-account/?lang=en#/dev1c0e25352 42 | -------------------------------------------------------------------------------- /docs/backends/loginradius.rst: -------------------------------------------------------------------------------- 1 | LoginRadius 2 | =========== 3 | 4 | LoginRadius uses OAuth2 for Authentication with other providers with an HTML 5 | widget used to trigger the auth process. 6 | 7 | - Register a new application at the `LoginRadius Website`_, and 8 | 9 | - Fill ``Client Id`` and ``Client Secret`` values in the settings:: 10 | 11 | SOCIAL_AUTH_LOGINRADIUS_KEY = '' 12 | SOCIAL_AUTH_LOGINRADIUS_SECRET = '' 13 | 14 | - Since the auth process is triggered by LoginRadius JS script, you need to 15 | sever such content to the user, all you need to do that is a template with 16 | the following content:: 17 | 18 |
19 | 20 | 32 | 33 | Put that content in a template named ``loginradius.html`` (accessible to your 34 | framework), or define a name with ``SOCIAL_AUTH_LOGINRADIUS_TEMPLATE`` setting, 35 | like:: 36 | 37 | SOCIAL_AUTH_LOGINRADIUS_LOCAL_HTML = 'loginradius.html' 38 | 39 | The template context will have the current backend instance under the 40 | ``backend`` name, also the application key (``LOGINRADIUS_KEY``) and the 41 | redirect URL (``LOGINRADIUS_REDIRECT_URL``). 42 | 43 | - Further documentation can be found at `LoginRadius API Documentation`_ and 44 | `LoginRadius Datapoints`_ 45 | 46 | .. _LoginRadius Website: https://loginradius.com/ 47 | .. _LoginRadius API Documentation: http://api.loginradius.com/help/ 48 | .. _LoginRadius Datapoints: http://www.loginradius.com/datapoints/ 49 | -------------------------------------------------------------------------------- /docs/backends/seznam.rst: -------------------------------------------------------------------------------- 1 | Seznam 2 | ========= 3 | 4 | Seznam supports OAuth2 for developers to authenticate users for their apps. 5 | The documentation for the API can be found at `Seznam OAuth documentation`_. 6 | This backend also provides additional configuration options to support 7 | slightly different enterprise versions. 8 | 9 | 1. Register a new application at `Application management`_, set the 10 | ``redirect_uri`` to ``http://example.com/complete/seznam-oauth2/``, 11 | replacing ``example.com`` with your domain. 12 | 13 | 2. Fill ``client_id`` and ``client_secret`` values in the settings:: 14 | 15 | SOCIAL_AUTH_SEZNAM_OAUTH2_KEY = '' 16 | SOCIAL_AUTH_SEZNAM_OAUTH2_SECRET = '' 17 | 18 | - If you would like to access some additional information from the user, 19 | you can set the ``SOCIAL_AUTH_SEZNAM_OAUTH2_SCOPE`` setting to a list of 20 | extra scopes that are supported according to the `scope documentation`_. For 21 | example, to request access to the user's phone number and avatar: 22 | 23 | .. code-block:: python 24 | 25 | SOCIAL_AUTH_SEZNAM_OAUTH2_SCOPE = ['contact-phone', 'avatar'] 26 | 27 | User ID 28 | ------- 29 | 30 | Seznam recommends the use of ``oauth_user_id`` as the user identifier instead 31 | of mutable data such as ``username`` or ``email`` because using mutable identifiers 32 | can pose security risks if the user changes them. 33 | 34 | For that reason ``oauth_user_id`` is used by default, but for compatibility 35 | with enterprise backend versions or other use cases, you can override this behavior 36 | by configuring the ID key via settings: 37 | 38 | .. code-block:: python 39 | 40 | SOCIAL_AUTH_SEZNAM_OAUTH2_ID_KEY = 'id' 41 | 42 | See the `Configurable User ID Key`_ documentation for more information about this feature. 43 | 44 | .. _Configurable User ID Key: ../configuration/settings.html#configurable-user-id-key 45 | 46 | .. _Seznam OAuth documentation: https://vyvojari.seznam.cz/oauth/doc?lang=en 47 | .. _Application management: https://vyvojari.seznam.cz/oauth/admin 48 | .. _scope documentation: https://vyvojari.seznam.cz/oauth/scopes?lang=en 49 | -------------------------------------------------------------------------------- /docs/backends/bitbucket.rst: -------------------------------------------------------------------------------- 1 | Bitbucket 2 | ========= 3 | 4 | Bitbucket supports both OAuth2 and OAuth1 logins. 5 | 6 | 1. Register a new OAuth Consumer by following the instructions in the 7 | Bitbucket documentation: `OAuth on Bitbucket`_ 8 | 9 | Note: For OAuth2, your consumer MUST have the "account" scope otherwise 10 | the user profile information (username, name, etc.) won't be accessible. 11 | 12 | 2. Configure the appropriate settings for OAuth2 or OAuth1 (see below). 13 | 14 | 15 | OAuth2 16 | ------ 17 | 18 | - Fill ``Consumer Key`` and ``Consumer Secret`` values in the settings:: 19 | 20 | SOCIAL_AUTH_BITBUCKET_OAUTH2_KEY = '' 21 | SOCIAL_AUTH_BITBUCKET_OAUTH2_SECRET = '' 22 | 23 | - If you would like to restrict access to only users with verified e-mail 24 | addresses, set ``SOCIAL_AUTH_BITBUCKET_OAUTH2_VERIFIED_EMAILS_ONLY = True`` 25 | By default the setting is set to ``False`` since it's possible for a 26 | project to gather this information by other methods. 27 | 28 | 29 | OAuth1 30 | ------ 31 | 32 | - OAuth1 works similarly to OAuth2, but you must fill in the following settings 33 | instead:: 34 | 35 | SOCIAL_AUTH_BITBUCKET_KEY = '' 36 | SOCIAL_AUTH_BITBUCKET_SECRET = '' 37 | 38 | - If you would like to restrict access to only users with verified e-mail 39 | addresses, set ``SOCIAL_AUTH_BITBUCKET_VERIFIED_EMAILS_ONLY = True``. 40 | By default the setting is set to ``False`` since it's possible for a 41 | project to gather this information by other methods. 42 | 43 | 44 | User ID 45 | ------- 46 | 47 | Bitbucket recommends the use of UUID_ as the user identifier instead 48 | of ``username`` since they can change and impose a security risk. For 49 | that reason ``UUID`` is used by default, but for backward 50 | compatibility reasons, it's possible to get the old behavior again by 51 | defining this setting:: 52 | 53 | SOCIAL_AUTH_BITBUCKET_USERNAME_AS_ID = True 54 | 55 | .. _UUID: https://confluence.atlassian.com/display/BITBUCKET/Use+the+Bitbucket+REST+APIs 56 | .. _OAuth on Bitbucket: https://confluence.atlassian.com/display/BITBUCKET/OAuth+on+Bitbucket 57 | -------------------------------------------------------------------------------- /docs/backends/osso.rst: -------------------------------------------------------------------------------- 1 | Osso - Open Source SAML SSO 2 | ================================ 3 | 4 | Osso is an open source service that handles SAML tenant onboarding, documentation and authentication. 5 | 6 | Your application can then consume normalized user profile resources as part of an OAuth 2.0 authorization code grant flow. 7 | 8 | Learn more about Osso at https://ossoapp.com or continue below to start consuming your Osso instance from your application via Python Social Auth. 9 | 10 | To enable Osso as a backend: 11 | 12 | - On your project settings, add Osso on your ``AUTHENTICATION_BACKENDS``:: 13 | 14 | AUTHENTICATION_BACKENDS = ( 15 | ... 16 | 'social_core.backends.osso.OssoOAuth2', 17 | ) 18 | 19 | - Create or update an OAuth Client in your Osso instance, adding a redirect URI to your allow 20 | ``http://example.com/complete/osso/`` replacing ``http://example.com`` with your application's domain. 21 | Grab the ``Client ID`` and ``Client Secret`` to use in your application. 22 | 23 | - Add these values of ``Client ID`` and ``Client Secret`` from Osso in your project settings file. 24 | 25 | The ``Client ID`` should be added on ``SOCIAL_AUTH_OSSO_KEY`` and the ``Client Secret`` should be 26 | added on ``SOCIAL_AUTH_OSSO_SECRET``. You also need to add your Osso instance base URL as ``SOCIAL_AUTH_OSSO_BASE_URL``:: 27 | 28 | SOCIAL_AUTH_OSSO_KEY = os.getenv('SOCIAL_AUTH_OSSO_KEY') 29 | SOCIAL_AUTH_OSSO_SECRET = os.getenv('SOCIAL_AUTH_OSSO_SECRET') 30 | SOCIAL_AUTH_OSSO_BASE_URL = 'https://demo.ossoapp.com' 31 | 32 | When constructing your sign in flow, Osso supports passing an ``email`` or ``domain`` parameter in order to route 33 | the user to the correct IDP. If you don't include one of these parameters, and instead implement a button, Osso 34 | will display a hosted login page. Here's an example login form with ``email``: 35 | 36 | 37 | .. code-block:: html+django 38 | 39 | 45 | -------------------------------------------------------------------------------- /docs/backends/username.rst: -------------------------------------------------------------------------------- 1 | Username Auth 2 | ============= 3 | 4 | python-social-auth_ comes with an UsernameAuth_ backend which comes handy when 5 | your site uses requires the plain old username and password authentication 6 | mechanism. 7 | 8 | Actually that's a lie since the backend doesn't handle password at all, that's 9 | up to the developer to validate the password in and the proper place to do it 10 | is the pipeline, right after the user instance was retrieved or created. 11 | 12 | The reason to leave password handling to the developer is because too many 13 | things are really tied to the project, like the field where the password is 14 | stored, salt handling, password hashing algorithm and validation. So just add 15 | the pipeline functions that will do that following the needs of your project. 16 | 17 | 18 | Backend settings 19 | ---------------- 20 | 21 | ``SOCIAL_AUTH_USERNAME_FORM_URL = '/login-form/'`` 22 | Used to redirect the user to the login/signup form, it must have at least 23 | one field named ``username``. Form submit should go to ``/complete/username``, 24 | or if it goes to your view, then your view should complete the process 25 | calling ``social_core.actions.do_complete``. 26 | 27 | ``SOCIAL_AUTH_USERNAME_FORM_HTML = 'login_form.html'`` 28 | The template will be used to render the login/signup form to the user, it 29 | must have at least one field named ``username``. Form submit should go to 30 | ``/complete/username``, or if it goes to your view, then your view should 31 | complete the process calling ``social_core.actions.do_complete``. 32 | 33 | 34 | Password handling 35 | ----------------- 36 | 37 | Here's an example of password handling to add to the pipeline:: 38 | 39 | def user_password(strategy, user, is_new=False, *args, **kwargs): 40 | if strategy.backend.name != 'username': 41 | return 42 | 43 | password = strategy.request_data()['password'] 44 | if is_new: 45 | user.set_password(password) 46 | user.save() 47 | elif not user.validate_password(password): 48 | # return {'user': None, 'social': None} 49 | raise AuthException(strategy.backend) 50 | 51 | .. _python-social-auth: https://github.com/python-social-auth 52 | .. _UsernameAuth: https://github.com/python-social-auth/social-core/blob/master/social_core/backends/username.py 53 | -------------------------------------------------------------------------------- /docs/backends/github_enterprise.rst: -------------------------------------------------------------------------------- 1 | .. _github-enterprise: 2 | 3 | GitHub Enterprise 4 | ================= 5 | 6 | GitHub Enterprise works similar to regular GitHub, which is in turn based on Facebook (OAuth). 7 | 8 | - Register a new application on your instance of `GitHub Enterprise Developers`_, 9 | set the callback URL to ``http://example.com/complete/github-enterprise/`` replacing ``example.com`` 10 | with your domain. 11 | 12 | - Set the URL for your GitHub Enterprise appliance: 13 | 14 | SOCIAL_AUTH_GITHUB_ENTERPRISE_URL = 'https://git.example.com/' 15 | 16 | - Set the API URL for your GitHub Enterprise appliance: 17 | 18 | SOCIAL_AUTH_GITHUB_ENTERPRISE_API_URL = 'https://git.example.com/api/v3/' 19 | 20 | - Fill the ``Client ID`` and ``Client Secret`` values from GitHub in the settings: 21 | 22 | SOCIAL_AUTH_GITHUB_ENTERPRISE_KEY = 'Client_ID' 23 | SOCIAL_AUTH_GITHUB_ENTERPRISE_SECRET = 'Client_Secret' 24 | 25 | - Also it's possible to define extra permissions with:: 26 | 27 | SOCIAL_AUTH_GITHUB_ENTERPRISE_SCOPE = [...] 28 | 29 | 30 | GitHub Enterprise for Organizations 31 | ----------------------------------- 32 | 33 | When defining authentication for organizations, use the 34 | ``GithubEnterpriseOrganizationOAuth2`` backend instead. The settings are the same as 35 | the non-organization backend, but the names must be:: 36 | 37 | SOCIAL_AUTH_GITHUB_ENTERPRISE_ORG_* 38 | 39 | Be sure to define the organization name using the setting:: 40 | 41 | SOCIAL_AUTH_GITHUB_ENTERPRISE_ORG_NAME = '' 42 | 43 | This name will be used to check that the user really belongs to the given 44 | organization and discard it if they're not part of it. 45 | 46 | 47 | GitHub Enterprise for Teams 48 | --------------------------- 49 | 50 | Similar to ``GitHub Enterprise for Organizations``, there's a GitHub for Teams backend, 51 | use the backend ``GithubEnterpriseTeamOAuth2``. The settings are the same as 52 | the basic backend, but the names must be:: 53 | 54 | SOCIAL_AUTH_GITHUB_ENTERPRISE_TEAM_* 55 | 56 | Be sure to define the ``Team ID`` using the setting:: 57 | 58 | SOCIAL_AUTH_GITHUB_ENTERPRISE_TEAM_ID = '' 59 | 60 | This ``id`` will be used to check that the user really belongs to the given 61 | team and discard it if they're not part of it. 62 | 63 | .. _GitHub Enterprise Developers: https:///settings/applications/new 64 | -------------------------------------------------------------------------------- /docs/configuration/webpy.rst: -------------------------------------------------------------------------------- 1 | Webpy Framework 2 | =============== 3 | 4 | Webpy_ framework is easy to setup, once that python-social-auth_ is installed 5 | or accessible in the ``PYTHONPATH``, just add the needed configurations to make 6 | it run. 7 | 8 | 9 | Dependencies 10 | ------------ 11 | 12 | The `Webpy app` depends on sqlalchemy_, there's no support for others 13 | ORMs yet but pull-requests are welcome. 14 | 15 | 16 | Installing 17 | ---------- 18 | 19 | From pypi_:: 20 | 21 | $ pip install social-auth-app-webpy 22 | 23 | 24 | Configuration 25 | ------------- 26 | 27 | Add the needed settings into ``web.config`` store. Settings are prefixed with 28 | ``SOCIAL_AUTH_`` but there's a helper for it:: 29 | 30 | from social_core.utils import setting_name 31 | 32 | web.config[setting_name('USER_MODEL')] = 'models.User' 33 | web.config[setting_name('LOGIN_REDIRECT_URL')] = '/done/' 34 | web.config[setting_name('AUTHENTICATION_BACKENDS')] = ( 35 | 'social_core.backends.google.GoogleOAuth2', 36 | ... 37 | ) 38 | 39 | Add all the settings needed for the app (check Configuration_ section for 40 | details). 41 | 42 | 43 | URLs 44 | ---- 45 | 46 | Add the social application into URLs:: 47 | 48 | from social_webpy import app as social_app 49 | 50 | urls = ( 51 | ... 52 | '', social_app.app_social 53 | ... 54 | ) 55 | 56 | 57 | Session 58 | ------- 59 | 60 | python-social-auth_ depends on sessions storage to keep some essential values, 61 | usually redirects and ``state`` parameters used to validate authentication 62 | process on OAuth providers. 63 | 64 | The `Webpy built-in app` expects the session reference to be available under 65 | ``web.web_session`` so ensure it's available there. 66 | 67 | 68 | User model 69 | ---------- 70 | 71 | Like the other apps, the User model must be defined on settings since 72 | a reference to it is kept on ``UserSocialAuth`` instance. Define like this:: 73 | 74 | web.config[setting_name('USER_MODEL')] = 'models.User' 75 | 76 | Where the value is the import path to the User model used on your project. 77 | 78 | 79 | .. _python-social-auth: https://github.com/python-social-auth 80 | .. _Webpy: http://webpy.org/ 81 | .. _Webpy built-in app: https://github.com/python-social-auth/social-app-webpy 82 | .. _sqlalchemy: http://www.sqlalchemy.org/ 83 | .. _pypi: http://pypi.python.org/pypi/social-auth-app-webpy/ 84 | -------------------------------------------------------------------------------- /docs/strategies.rst: -------------------------------------------------------------------------------- 1 | Strategies 2 | ========== 3 | 4 | Different strategies are defined to encapsulate the different frameworks 5 | capabilities under a common API to reuse as much code as possible. 6 | 7 | 8 | Description 9 | ----------- 10 | 11 | A strategy's responsibility is to provide access to: 12 | 13 | * Request data and host information and URI building 14 | * Session access 15 | * Project settings 16 | * Response types (HTML and redirects) 17 | * HTML rendering 18 | 19 | Different frameworks implement these features on different ways, thus the need 20 | for these interfaces. 21 | 22 | 23 | Implementing a new Strategy 24 | --------------------------- 25 | 26 | The following methods must be defined on strategies sub-classes. 27 | 28 | Request:: 29 | 30 | def request_data(self): 31 | """Return current request data (POST or GET)""" 32 | raise NotImplementedError('Implement in subclass') 33 | 34 | def request_host(self): 35 | """Return current host value""" 36 | raise NotImplementedError('Implement in subclass') 37 | 38 | def build_absolute_uri(self, path=None): 39 | """Build absolute URI with given (optional) path""" 40 | raise NotImplementedError('Implement in subclass') 41 | 42 | 43 | Session:: 44 | 45 | def session_get(self, name): 46 | """Return session value for given key""" 47 | raise NotImplementedError('Implement in subclass') 48 | 49 | def session_set(self, name, value): 50 | """Set session value for given key""" 51 | raise NotImplementedError('Implement in subclass') 52 | 53 | def session_pop(self, name): 54 | """Pop session value for given key""" 55 | raise NotImplementedError('Implement in subclass') 56 | 57 | 58 | Settings:: 59 | 60 | def get_setting(self, name): 61 | """Return value for given setting name""" 62 | raise NotImplementedError('Implement in subclass') 63 | 64 | 65 | Responses:: 66 | 67 | def html(self, content): 68 | """Return HTTP response with given content""" 69 | raise NotImplementedError('Implement in subclass') 70 | 71 | def redirect(self, url): 72 | """Return a response redirect to the given URL""" 73 | raise NotImplementedError('Implement in subclass') 74 | 75 | def render_html(self, tpl=None, html=None, context=None): 76 | """Render given template or raw html with given context""" 77 | raise NotImplementedError('Implement in subclass') 78 | -------------------------------------------------------------------------------- /docs/backends/email.rst: -------------------------------------------------------------------------------- 1 | Email Auth 2 | ========== 3 | 4 | python-social-auth_ comes with an EmailAuth_ backend which comes handy when 5 | your site uses requires the plain old email and password authentication 6 | mechanism. 7 | 8 | Actually that's a lie since the backend doesn't handle password at all, that's 9 | up to the developer to validate the password in and the proper place to do it 10 | is the pipeline, right after the user instance was retrieved or created. 11 | 12 | The reason to leave password handling to the developer is because too many 13 | things are really tied to the project, like the field where the password is 14 | stored, salt handling, password hashing algorithm and validation. So just add 15 | the pipeline functions that will do that following the needs of your project. 16 | 17 | 18 | Backend settings 19 | ---------------- 20 | 21 | ``SOCIAL_AUTH_EMAIL_FORM_URL = '/login-form/'`` 22 | Used to redirect the user to the login/signup form, it must have at least 23 | one field named ``email``. Form submit should go to ``/complete/email``, 24 | or if it goes to your view, then your view should complete the process 25 | calling ``social_core.actions.do_complete``. 26 | 27 | ``SOCIAL_AUTH_EMAIL_FORM_HTML = 'login_form.html'`` 28 | The template will be used to render the login/signup form to the user, it 29 | must have at least one field named ``email``. Form submit should go to 30 | ``/complete/email``, or if it goes to your view, then your view should 31 | complete the process calling ``social_core.actions.do_complete``. 32 | 33 | 34 | Email validation 35 | ---------------- 36 | 37 | Check *Email validation* pipeline in the `pipeline docs`_. 38 | 39 | Password handling 40 | ----------------- 41 | 42 | Here's an example of password handling to add to the pipeline:: 43 | 44 | def user_password(strategy, backend, user, is_new=False, *args, **kwargs): 45 | if backend.name != 'email': 46 | return 47 | 48 | password = strategy.request_data()['password'] 49 | if is_new: 50 | user.set_password(password) 51 | user.save() 52 | elif not user.validate_password(password): 53 | # return {'user': None, 'social': None} 54 | raise AuthForbidden(backend) 55 | 56 | .. _python-social-auth: https://github.com/python-social-auth 57 | .. _EmailAuth: https://github.com/python-social-auth/social-core/blob/master/social_core/backends/email.py 58 | .. _pipeline docs: ../pipeline.html#email-validation 59 | -------------------------------------------------------------------------------- /docs/backends/bitbucket_datacenter_oauth2.rst: -------------------------------------------------------------------------------- 1 | Bitbucket Data Center OAuth2 2 | ============================= 3 | 4 | Bitbucket Data Center (previously Bitbucket Server) supports the `OAuth 2.0`_ protocol. It supports two types of OAuth 2.0 flows: 5 | 6 | 1. Authorization code with `Proof Key for Code Exchange (PKCE)`_ 7 | 2. Authorization code 8 | 9 | Configuration 10 | -------------- 11 | 12 | 1. Register a new `Application Link`_ in your Bitbucket Data Center instance. 13 | 14 | 2. Provide the host URL of your Bitbucket Data Center instance:: 15 | 16 | SOCIAL_AUTH_BITBUCKET_DATACENTER_OAUTH2_URL = "https://my-bitbucket-server.acme.com" 17 | 18 | 3. Fill *Client ID* in ``SOCIAL_AUTH_BITBUCKET_DATACENTER_OAUTH2_KEY`` and *Client Secret* in ``SOCIAL_AUTH_BITBUCKET_DATACENTER_OAUTH2_SECRET`` in your project settings:: 19 | 20 | SOCIAL_AUTH_BITBUCKET_DATACENTER_OAUTH2_KEY = "..." 21 | SOCIAL_AUTH_BITBUCKET_DATACENTER_OAUTH2_SECRET = "..." 22 | 23 | 4. Enable the backend:: 24 | 25 | SOCIAL_AUTH_AUTHENTICATION_BACKENDS = ( 26 | ... 27 | "social_core.backends.bitbucket_datacenter.BitbucketDataCenterOAuth2", 28 | ... 29 | ) 30 | 31 | Extra Configuration 32 | -------------------- 33 | 34 | - You can specify the scope that your application requires:: 35 | 36 | SOCIAL_AUTH_BITBUCKET_DATACENTER_OAUTH2_SCOPE = ["PUBLIC_REPOS"] 37 | 38 | You can see all possible values at `Bitbucket Data Center OAuth 2.0 provider API`_. By default, ``PUBLIC_REPOS`` is set. 39 | 40 | - You can choose to disable PKCE:: 41 | 42 | SOCIAL_AUTH_BITBUCKET_DATACENTER_OAUTH2_USE_PKCE = False 43 | 44 | By default, `True` is set. 45 | 46 | - You can specify PKCE challenge method:: 47 | 48 | SOCIAL_AUTH_BITBUCKET_DATACENTER_OAUTH2_PKCE_CODE_CHALLENGE_METHOD = '...' 49 | 50 | The possible values for this are ``s256`` and ``plain``. 51 | By default, ``s256`` is set. 52 | 53 | You can see more information about PKCE at `RFC7636`_. 54 | 55 | - You can specify the user's avatar size:: 56 | 57 | SOCIAL_AUTH_BITBUCKET_DATACENTER_OAUTH2_USER_AVATAR_SIZE = 48 58 | 59 | This is the size of the user's avatar requested from the API which is stored in ``EXTRA_DATA["avatar_url"]``. By default, ``48`` is set. 60 | 61 | .. _OAuth 2.0: https://confluence.atlassian.com/bitbucketserver/bitbucket-oauth-2-0-provider-api-1108483661.html 62 | .. _Application Link: https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html 63 | .. _Proof Key for Code Exchange (PKCE): https://datatracker.ietf.org/doc/html/rfc7636 64 | .. _RFC7636: https://datatracker.ietf.org/doc/html/rfc7636 65 | .. _Bitbucket Data Center OAuth 2.0 provider API: https://confluence.atlassian.com/bitbucketserver/bitbucket-oauth-2-0-provider-api-1108483661.html#BitbucketOAuth2.0providerAPI-scopes 66 | -------------------------------------------------------------------------------- /docs/configuration/cherrypy.rst: -------------------------------------------------------------------------------- 1 | CherryPy Framework 2 | ================== 3 | 4 | CherryPy framework is supported, it works but I'm sure there's room for 5 | improvements. The implementation uses SQLAlchemy as ORM and expects some values 6 | accessible on ``cherrypy.request`` for it to work. 7 | 8 | At the moment the configuration is expected on ``cherrypy.config`` but ideally 9 | it should be an application configuration instead. 10 | 11 | Expected values are: 12 | 13 | ``cherrypy.request.user`` 14 | Current logged in user, load it in your application on a ``before_handler`` 15 | handler. 16 | 17 | ``cherrypy.request.db`` 18 | Current database session, again, load it in your application on 19 | a ``before_handler``. 20 | 21 | 22 | Dependencies 23 | ------------ 24 | 25 | The `CherryPy application` depends on sqlalchemy_, there's no support for 26 | others ORMs yet. 27 | 28 | 29 | Installing 30 | ---------- 31 | 32 | From pypi_:: 33 | 34 | $ pip install social-auth-app-cherrypy 35 | 36 | 37 | Enabling the application 38 | ------------------------ 39 | 40 | The application is defined on ``social_cherrypy.views.CherryPyPSAViews``, 41 | register it in the preferred way for your project. 42 | 43 | Check the rest of the docs for the other settings like enabling authentication 44 | backends and backends keys. 45 | 46 | 47 | Models Setup 48 | ------------ 49 | 50 | The models are located in ``social_cherrypy.models``. A reference to 51 | your ``User`` model is required to be defined in the project settings, it 52 | should be an import path, for example:: 53 | 54 | cherrypy.config.update({ 55 | 'SOCIAL_AUTH_USER_MODEL': 'models.User' 56 | }) 57 | 58 | 59 | Login mechanism 60 | --------------- 61 | 62 | By default the application sets the session value ``user_id``, this is a simple 63 | solution and it should be improved, if you want to provider your own login 64 | mechanism you can do it by defining the ``SOCIAL_AUTH_LOGIN_METHOD`` setting, 65 | it should be an import path to a callable, like this:: 66 | 67 | SOCIAL_AUTH_USER_MODEL = 'app.login_user' 68 | 69 | And an example of this function:: 70 | 71 | def login_user(strategy, user): 72 | strategy.session_set('user_id', user.id) 73 | 74 | Then, ensure to load the user in your application at ``cherrypy.request.user``, 75 | for example:: 76 | 77 | def load_user(): 78 | user_id = cherrypy.session.get('user_id') 79 | if user_id: 80 | cherrypy.request.user = cherrypy.request.db.query(User).get(user_id) 81 | else: 82 | cherrypy.request.user = None 83 | 84 | 85 | cherrypy.tools.authenticate = cherrypy.Tool('before_handler', load_user) 86 | 87 | 88 | .. _CherryPy built-in app: https://github.com/python-social-auth/social-app-cherrypy 89 | .. _sqlalchemy: http://www.sqlalchemy.org/ 90 | .. _pypi: http://pypi.python.org/pypi/social-auth-app-cherrypy/ 91 | -------------------------------------------------------------------------------- /docs/backends/keycloak.rst: -------------------------------------------------------------------------------- 1 | Keycloak - Open Source Red Hat SSO 2 | ================================== 3 | 4 | Keycloak is an open source IAM and SSO system. 5 | 6 | To enable Keycloak as a backend: 7 | 8 | - On your project settings, add Keycloak on your ``AUTHENTICATION_BACKENDS``:: 9 | 10 | AUTHENTICATION_BACKENDS = ( 11 | ... 12 | 'social_core.backends.keycloak.KeycloakOAuth2', 13 | 'django.contrib.auth.backends.ModelBackend', 14 | ) 15 | 16 | - Create a Client in your Keycloak realm 17 | 18 | - On your client under ``Fine Grain OpenID Connect Configuration`` ensure that ``User Info Signed Response Algorithm`` and ``Request Object Signature Algorithm`` is set to ``RS256``. Save. Then go to: Realm Settings -> Keys -> RS256 and copy your Public key to ``SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY`` in your django settings 19 | 20 | - Add these values of ``Client ID`` and ``Client Secret`` from client in your project settings file. 21 | 22 | The ``Client ID`` should be added on ``SOCIAL_AUTH_KEYCLOAK_KEY`` and the ``Client Secret`` should be 23 | added on ``SOCIAL_AUTH_KEYCLOAK_SECRET``. You also need to add your keycloak instance auth and token URL's found in the Realm OpenID Endpoint Configuration:: 24 | 25 | SOCIAL_AUTH_KEYCLOAK_KEY = 'test-django-oidc' 26 | SOCIAL_AUTH_KEYCLOAK_SECRET = 'a7a41-245e-...' 27 | SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY = \ 28 | 'MIIBIjANBxxxdSD' 29 | SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL = \ 30 | 'https://iam.example.com/auth/realms/voxcloud-staff/protocol/openid-connect/auth' 31 | SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL = \ 32 | 'https://iam.example.com/auth/realms/voxcloud-staff/protocol/openid-connect/token' 33 | 34 | Lastly you need to ensure the ``client_id`` is in your JWT's ``aud`` key. On your client go to Mappers -> Create. Create an ``Audience Mapper`` and ensure the ``Included Client Audience`` is your ``client_id``. 35 | 36 | Thereafter go to: ``/login/keycloak`` and the authorization code flow should commence. 37 | 38 | User ID Configuration 39 | --------------------- 40 | 41 | The default behavior is to associate users via the ``sub`` (subject) field from the 42 | JWT token. However, you can configure which field to use as the unique user identifier 43 | by setting:: 44 | 45 | SOCIAL_AUTH_KEYCLOAK_ID_KEY = 'email' 46 | 47 | This can be useful if you want to use email, username, or another field as the unique 48 | identifier instead of the ``sub`` field. 49 | 50 | .. warning:: 51 | Changing the ID key after users have already authenticated will prevent them from 52 | logging in, as their stored ``uid`` will not match the new identifier. Configure 53 | this setting before users start authenticating, or perform a data migration. 54 | 55 | See the `Configurable User ID Key`_ documentation for more information about this feature. 56 | 57 | .. _Configurable User ID Key: ../configuration/settings.html#configurable-user-id-key 58 | -------------------------------------------------------------------------------- /docs/backends/vault.rst: -------------------------------------------------------------------------------- 1 | Hashicorp Vault 2 | =============== 3 | 4 | The Vault_ backend allows authentication against the OIDC provider_ in 5 | Hashicorp Vault_ version 1.9 and later. 6 | 7 | The backend class is `VaultOpenIdConnect` with name `vault`. A minimum 8 | configuration is:: 9 | 10 | SOCIAL_AUTH_VAULT_OIDC_ENDPOINT = 'https://vault.example.net:8200/v1/identity/oidc/provider/default' 11 | SOCIAL_AUTH_VAULT_KEY = '' 12 | SOCIAL_AUTH_VAULT_SECRET = '' 13 | 14 | The remaining configuration will be auto-detected, by fetching:: 15 | 16 | /.well-known/openid-configuration 17 | 18 | You may need to set ``SOCIAL_AUTH_VAULT_VERIFY_SSL = False`` if your Vault 19 | server does not have its certificate signed by a trusted CA (e.g. with 20 | LetsEncrypt), although this should only be used for testing and not in 21 | production. 22 | 23 | Vault OIDC configuration 24 | ------------------------ 25 | 26 | Vault 1.10 onwards includes a pre-defined provider "default", key "default" 27 | and assignment "allow_all". With Vault 1.9 you will need to create these 28 | objects explicitly. 29 | 30 | You can then create an OIDC client, and read it back to get the auto-generated 31 | client ID and secret:: 32 | 33 | vault write identity/oidc/client/my-app \ 34 | redirect_uris="https://www.example.com/callback" \ 35 | assignments="allow_all" \ 36 | key="default" \ 37 | id_token_ttl="30m" \ 38 | access_token_ttl="1h" 39 | 40 | vault read identity/oidc/client/my-app 41 | 42 | Scopes 43 | ------ 44 | 45 | Vault is very flexible with regard to configuring claims and scopes, 46 | so it's up to you how you map entity and/or alias metadata to OIDC claims. 47 | Here is a suggestion, which exposes the entity name as "preferred_username" 48 | and takes the other claims from entity metadata:: 49 | 50 | vault write identity/oidc/scope/profile \ 51 | description="Provides user info" \ 52 | template='{ 53 | "preferred_username": {{identity.entity.name}}, 54 | "name": {{identity.entity.metadata.name}}, 55 | "given_name": {{identity.entity.metadata.given_name}}, 56 | "family_name": {{identity.entity.metadata.family_name}} 57 | }' 58 | 59 | vault write identity/oidc/scope/email \ 60 | description="Provides email address" \ 61 | template='{ 62 | "email": {{identity.entity.metadata.email}} 63 | }' 64 | 65 | vault write identity/oidc/scope/groups \ 66 | description="Provides a list of group names" \ 67 | template='{ 68 | "groups": {{identity.entity.groups.names}} 69 | }' 70 | 71 | The Vault backend inherits defaults from ``open_id_connect.py``. In 72 | particular, it looks for the username in the ``preferred_username`` claim. 73 | If you need to choose a different claim then you can do so:: 74 | 75 | SOCIAL_AUTH_VAULT_USERNAME_KEY = 'nickname' 76 | 77 | The default set of scopes requested are "openid", "profile" and "email". 78 | You can request additional claims like this:: 79 | 80 | SOCIAL_AUTH_VAULT_SCOPE = ['groups'] 81 | 82 | and you can remove the default scopes using:: 83 | 84 | SOCIAL_AUTH_VAULT_IGNORE_DEFAULT_SCOPE = True 85 | 86 | .. _Vault: https://www.vaultproject.io/ 87 | .. _provider: https://www.vaultproject.io/docs/secrets/identity/oidc-provider 88 | -------------------------------------------------------------------------------- /docs/backends/index.rst: -------------------------------------------------------------------------------- 1 | Backends 2 | ======== 3 | 4 | Here's a list and detailed instructions on how to set up the support for each 5 | backend. 6 | 7 | Adding new backend support 8 | -------------------------- 9 | 10 | Add new backends is quite easy, usually adding just a ``class`` with a couple 11 | methods overrides to retrieve user data from services API. Follow the details 12 | in the *Implementation* docs. 13 | 14 | .. toctree:: 15 | :maxdepth: 2 16 | 17 | implementation 18 | 19 | 20 | Supported backends 21 | ------------------ 22 | 23 | Here's the list of currently supported backends. 24 | 25 | Non-social backends 26 | ******************* 27 | 28 | .. toctree:: 29 | :maxdepth: 2 30 | 31 | email 32 | username 33 | 34 | Base OAuth and OpenID classes 35 | ***************************** 36 | 37 | .. toctree:: 38 | :maxdepth: 2 39 | 40 | oauth 41 | openid 42 | saml 43 | 44 | Social backends 45 | *************** 46 | 47 | .. toctree:: 48 | :maxdepth: 2 49 | 50 | amazon 51 | angel 52 | aol 53 | apple 54 | appsfuel 55 | arcgis 56 | auth0 57 | auth0_openidconnect 58 | azuread 59 | battlenet 60 | beats 61 | behance 62 | belgium_eid 63 | bitbucket 64 | bitbucket_datacenter_oauth2 65 | box 66 | bungie 67 | cas 68 | changetip 69 | clef 70 | coinbase 71 | cognito 72 | coursera 73 | dailymotion 74 | digitalocean 75 | discogs 76 | discord 77 | discourse 78 | disqus 79 | docker 80 | douban 81 | dribbble 82 | drip 83 | dropbox 84 | edmodo 85 | etsy 86 | eventbrite 87 | eveonline 88 | evernote 89 | facebook 90 | facebook_limited_login 91 | fedora 92 | fitbit 93 | flat 94 | flickr 95 | foursquare 96 | github 97 | github_enterprise 98 | gitlab 99 | gitea 100 | google 101 | grafana 102 | instagram 103 | jawbone 104 | justgiving 105 | kakao 106 | keycloak 107 | khanacademy 108 | kick 109 | lastfm 110 | launchpad 111 | lifescience 112 | line 113 | linkedin 114 | livejournal 115 | live 116 | loginradius 117 | lyft 118 | mailchimp 119 | mailru 120 | mapmyfitness 121 | mediawiki 122 | meetup 123 | mendeley 124 | microsoftgraph 125 | mineid 126 | mixcloud 127 | moves 128 | naszaklasa 129 | nationbuilder 130 | naver 131 | nfdi 132 | ngpvan_actionid 133 | odnoklassnikiru 134 | okta 135 | openstreetmap 136 | openstreetmap_oauth2 137 | oidc 138 | orbi 139 | orcid 140 | osso 141 | patreon 142 | persona 143 | pinterest 144 | pixelpin 145 | pocket 146 | podio 147 | qiita 148 | qq 149 | quizlet 150 | rdio 151 | readability 152 | reddit 153 | runkeeper 154 | salesforce 155 | seznam 156 | shimmering 157 | shopify 158 | simplelogin 159 | sketchfab 160 | skyrock 161 | slack 162 | soundcloud 163 | spotify 164 | suse 165 | stackoverflow 166 | steam 167 | stocktwits 168 | strava 169 | stripe 170 | taobao 171 | telegram 172 | thisismyjam 173 | trello 174 | tripit 175 | tumblr 176 | twilio 177 | twitch 178 | twitter 179 | twitter_oauth2 180 | udata 181 | uber 182 | untappd 183 | upwork 184 | vault 185 | vend 186 | vimeo 187 | vk 188 | weibo 189 | withings 190 | wunderlist 191 | xing 192 | yahoo 193 | yammer 194 | zotero 195 | -------------------------------------------------------------------------------- /docs/backends/linkedin.rst: -------------------------------------------------------------------------------- 1 | LinkedIn 2 | ======== 3 | 4 | Sign In with LinkedIn only support OpenID Connect since August 1, 2023. The previous 5 | OAuth2 has been deprecated. See `LinkedIn OpenID Connect`_ for more details. 6 | 7 | LinkedIn previously supported OAuth2. Migration between each type is fairly 8 | simple since the same Key / Secret pair is used for both authentication types. 9 | 10 | LinkedIn OAuth2 setup is similar to any other OAuth2 service. The auth flow is 11 | explained on `LinkedIn Developers`_ docs. First you will need to register an 12 | app att `LinkedIn Developer Network`_. 13 | 14 | OpenID Connect 15 | -------------- 16 | 17 | - Fill the application key and secret in your settings:: 18 | 19 | SOCIAL_AUTH_LINKEDIN_OPENIDCONNECT_KEY = '' 20 | SOCIAL_AUTH_LINKEDIN_OPENIDCONNECT_SECRET = '' 21 | 22 | OAuth2 23 | ------ 24 | 25 | - Fill the application key and secret in your settings:: 26 | 27 | SOCIAL_AUTH_LINKEDIN_OAUTH2_KEY = '' 28 | SOCIAL_AUTH_LINKEDIN_OAUTH2_SECRET = '' 29 | 30 | - Application scopes can be specified by:: 31 | 32 | SOCIAL_AUTH_LINKEDIN_OAUTH2_SCOPE = [...] 33 | 34 | Check the available options at `LinkedIn Scopes`_ (also called as permissions 35 | by LinkedIn). If you want to request a user's email address, you'll need 36 | specify that your application needs access to the email address use the 37 | ``r_emailaddress`` scope. 38 | 39 | - To request extra fields using `LinkedIn fields selectors`_ just define this 40 | setting:: 41 | 42 | SOCIAL_AUTH_LINKEDIN_OAUTH2_FIELD_SELECTORS = [...] 43 | 44 | with the needed fields selectors, also define 45 | ``SOCIAL_AUTH_LINKEDIN_OAUTH2_EXTRA_DATA`` properly, that way the values will 46 | be stored in ``UserSocialAuth.extra_data`` field. By default ``id``, 47 | ``firstName`` and ``lastName`` are requested and stored. 48 | 49 | For example, to request a user's email from the Linkedin API and store the 50 | information in ``UserSocialAuth.extra_data``, you would add these settings:: 51 | 52 | # Add email to requested authorizations. 53 | SOCIAL_AUTH_LINKEDIN_OAUTH2_SCOPE = ['r_liteprofile', 'r_emailaddress'] 54 | # Add the fields so they will be requested from linkedin. 55 | SOCIAL_AUTH_LINKEDIN_OAUTH2_FIELD_SELECTORS = ['emailAddress'] 56 | # Arrange to add the fields to UserSocialAuth.extra_data 57 | SOCIAL_AUTH_LINKEDIN_OAUTH2_EXTRA_DATA = [('id', 'id'), 58 | ('firstName', 'first_name'), 59 | ('lastName', 'last_name'), 60 | ('emailAddress', 'email_address')] 61 | 62 | 63 | Looks like LinkedIn is forcing the definition of the callback URL in the 64 | application when OAuth2 is used. Follow the setup 1 carefully as per `Linkedin 65 | App Setup`_ to add a redirect url/callback url. Be sure to set the proper 66 | values, otherwise a ``(400) Client Error: Bad Request`` might be returned by 67 | their service. 68 | 69 | .. _Linkedin OpenID Connect: https://learn.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin-v2 70 | .. _LinkedIn fields selectors: https://docs.microsoft.com/en-us/linkedin/shared/references/v2/profile/lite-profile 71 | .. _LinkedIn Scopes: https://docs.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin 72 | .. _LinkedIn Developer Network: https://www.linkedin.com/secure/developer 73 | .. _LinkedIn Developers: https://docs.microsoft.com/en-us/linkedin/shared/authentication/authentication 74 | .. _Linkedin App Setup: https://docs.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow 75 | -------------------------------------------------------------------------------- /docs/backends/github.rst: -------------------------------------------------------------------------------- 1 | GitHub 2 | ====== 3 | 4 | GitHub works similar to Facebook (OAuth). 5 | 6 | - On your project settings, you should add Github on your ``AUTHENTICATION_BACKENDS``:: 7 | 8 | AUTHENTICATION_BACKENDS = ( 9 | ... 10 | 'social_core.backends.github.GithubOAuth2', 11 | ) 12 | 13 | - Register a new application at `GitHub Developers`_, set the callback URL to 14 | ``http://example.com/complete/github/`` replacing ``example.com`` with your 15 | domain. This will generate a Client Key and a Client Secret. 16 | 17 | - Add these values of ``Client ID`` and ``Client Secret`` from GitHub in your project settings file. 18 | 19 | The ``Client ID`` should be added on ``SOCIAL_AUTH_GITHUB_KEY`` and the ``Client Secret`` should be 20 | added on ``SOCIAL_AUTH_GITHUB_SECRET``:: 21 | 22 | SOCIAL_AUTH_GITHUB_KEY = 'a1b2c3d4' 23 | SOCIAL_AUTH_GITHUB_SECRET = 'e5f6g7h8i9' 24 | 25 | - Also it's possible to define extra permissions with:: 26 | 27 | SOCIAL_AUTH_GITHUB_SCOPE = [...] 28 | 29 | GitHub for Organizations 30 | ------------------------ 31 | 32 | When defining authentication for organizations, use the 33 | ``GithubOrganizationOAuth2`` backend instead. The settings are the same as 34 | the non-organization backend, but the names must be:: 35 | 36 | SOCIAL_AUTH_GITHUB_ORG_* 37 | 38 | Be sure to define the organization name using the setting:: 39 | 40 | SOCIAL_AUTH_GITHUB_ORG_NAME = '' 41 | 42 | This name will be used to check that the user really belongs to the given 43 | organization and discard it if they're not part of it. 44 | 45 | 46 | GitHub for Teams 47 | ---------------- 48 | 49 | Similar to ``GitHub for Organizations``, there's a GitHub for Teams backend, 50 | use the backend ``GithubTeamOAuth2``. The settings are the same as 51 | the basic backend, but the names must be:: 52 | 53 | SOCIAL_AUTH_GITHUB_TEAM_* 54 | 55 | Be sure to define the ``Team ID`` using the setting:: 56 | 57 | SOCIAL_AUTH_GITHUB_TEAM_ID = '' 58 | 59 | This ``id`` will be used to check that the user really belongs to the given 60 | team and discard it if they're not part of it. 61 | 62 | 63 | GitHub for Enterprises 64 | ---------------------- 65 | 66 | Check the docs :ref:`github-enterprise` if planning to use GitHub 67 | Enterprises. 68 | 69 | 70 | GitHub Apps 71 | ----------- 72 | 73 | Similar to the ``GithubOAuth2`` backend but primarily intended for use 74 | with GitHub applications (non-oauth application type). For GitHub App 75 | applications there are two primary workflows: 76 | 77 | 1) A person clicks on an icon/button on your website and initiates the 78 | OAuth login procedure. They will be redirected to GitHub to complete 79 | the process and then back to your website. The person should be logged-in 80 | automatically. This is the same workflow as with standard OAuth GitHub apps. 81 | 82 | 2) A person visits your GitHub App public URL, e.g. ``https://github.com/apps/my-app``. 83 | They click the **Install** button, select onto which account/organization and 84 | repositori(es) to install your application and finish the process. GitHub 85 | will start sending webhooks to the URL you have configured! It will also 86 | redirect the person to ``Setup URL (optional)``. 87 | 88 | - Create a new GitHub App application owned by your organization. e.g. 89 | ``https://github.com/organizations/python-social-auth/settings/apps/new`` 90 | 91 | - Set ``User authorization callback URL`` to 92 | ``http://example.com/complete/github/`` replacing ``example.com`` with your 93 | domain. 94 | 95 | - Turn on ``Request user authorization (OAuth) during installation`` if 96 | you wish to make ``Setup URL`` equal to ``User authorization callback URL``. 97 | The side-effect of this is that after installing your GitHub app the person 98 | will be redirected back to your website and logged in automatically. When 99 | this is turned on steps 2) and 1) above are executed in sequence. 100 | 101 | - Add the values of ``Client ID`` and ``Client Secret`` from GitHub in your 102 | project settings file as shown above. 103 | 104 | 105 | 106 | .. _GitHub Developers: https://github.com/settings/applications/new 107 | -------------------------------------------------------------------------------- /docs/backends/bungie.rst: -------------------------------------------------------------------------------- 1 | Bungie 2 | ====== 3 | 4 | Bungie uses OAuth 2.0 for authentication. 5 | 6 | - Bungie does not return username, email or name information. They 7 | return a short form membership id (bungie site account) that is then 8 | stored as the uid for social auth. To get the username, 9 | _GetBungieNetUser_ is called which returns the bungie.net profile, 10 | including user name as the _displayName_ field. You may super the 11 | ``get_user_details`` function to change behavior or redirect your 12 | users to a partial pipeline flow that gathers missing user data such 13 | as email, password (local to your site), first name, last name 14 | etc. The pipeline flow is best interrupted at the 6th step in the 15 | sample pipeline below:: 16 | 17 | SOCIAL_AUTH_PIPELINE = ( 18 | # Get the information we can about the user and return it in a simple 19 | # format to create the user instance later. On some cases the details are 20 | # already part of the auth response from the provider, but sometimes this 21 | # could hit a provider API. 22 | 'social_core.pipeline.social_auth.social_details', 23 | # Get the social uid from whichever service we're authing thru. The uid is 24 | # the unique identifier of the given user in the provider. 25 | 'social_core.pipeline.social_auth.social_uid', 26 | # Verifies that the current auth process is valid within the current 27 | # project, this is where emails and domains whitelists are applied (if 28 | # defined). 29 | # Super'ed in bungie.py 30 | 'social_core.pipeline.social_auth.auth_allowed', 31 | # Checks if the current social-account is already associated in the site. 32 | 'social_core.pipeline.social_auth.social_user', 33 | # Make up a username for this person, appends a random string at the end if 34 | # there's any collision. 35 | 'social_core.pipeline.user.get_username', 36 | # Redirect to an @partial view to get missing user information here. 37 | # If you wish to validate or associate by email, this is required. 38 | # '.pipeline.required_user_information', 39 | # Send a validation email to the user to verify its email address. 40 | # Disabled by default. 41 | # 'social_core.pipeline.mail.mail_validation', 42 | # Associates the current social details with another user account with 43 | # a similar email address. Disabled by default. 44 | # 'social_core.pipeline.social_auth.associate_by_email', 45 | # Create a user account if we haven't found one yet. 46 | 'social_core.pipeline.user.create_user', 47 | # Create the record that associates the social account with the user. 48 | 'social_core.pipeline.social_auth.associate_user', 49 | # Populate the extra_data field in the social record with the values 50 | # specified by settings (and the default ones like access_token, etc). 51 | 'social_core.pipeline.social_auth.load_extra_data', 52 | # Update the user record with any changed info from the auth service. 53 | 'social_core.pipeline.user.user_details', 54 | ) 55 | 56 | - Register a new application at https://www.bungie.net/en/Application/ 57 | 58 | - Set the ``Callback URL`` in the Bungie.net Application Registration 59 | page to ``https:///complete/bungie`` This **must** be 60 | ``https``. During development you can use stunnel to proxy the request 61 | or you can install sslserver from pip. 62 | 63 | - Set the ``Authentication Backend``, ``Client ID (aka OAuth Key)``, 64 | ``OAuth Secret``, and ``X-API-KEY`` values in your Django settings:: 65 | 66 | AUTHENTICATION_BACKENDS = ( 67 | ... 68 | 'social_core.backends.bungie.BungieBaseAuth', 69 | ... 70 | ) 71 | 72 | SOCIAL_AUTH_BUNGIE_API_KEY = '...' 73 | SOCIAL_AUTH_BUNGIE_KEY = '' 74 | SOCIAL_AUTH_BUNGIE_SECRET = '...' 75 | SOCIAL_AUTH_BUNGIE_ORIGIN = '...' 76 | 77 | - Bungie allows whitespace in usernames, modify these if needed:: 78 | 79 | SOCIAL_AUTH_SLUGIFY_USERNAMES = False 80 | SOCIAL_AUTH_CLEAN_USERNAMES = False 81 | SOCIAL_AUTH_USER_MODEL = 'auth.User' 82 | 83 | .. _Bungie API Forum: https://www.bungie.net/en/Clan/Forum/39966 84 | .. _Bungie API Guide (unofficial): https://destinydevs.github.io/BungieNetPlatform/ 85 | -------------------------------------------------------------------------------- /docs/installing.rst: -------------------------------------------------------------------------------- 1 | Installation 2 | ============ 3 | 4 | python-social-auth_ is a very modular library looking to provide the 5 | basic tools to implement social authentication / authorization in 6 | Python projects. For that reason, the project is split in smaller 7 | components that focus on providing a simpler functionality. Some 8 | components are: 9 | 10 | * social-auth-core_ 11 | Core library that the rest depends on, this contains the basic 12 | functionality to establish an authentication/authorization flow with 13 | the different supported providers. 14 | 15 | * social-auth-storage-sqlalchemy_, social-auth-storage-peewee_, social-auth-storage-mongoengine_ 16 | Different storage solutions that can be reused across the supported 17 | frameworks or newer implementations. 18 | 19 | * social-auth-app-django_, social-auth-app-django-mongoengine_ 20 | Django framework integration 21 | 22 | * social-auth-app-flask_, social-auth-app-flask-sqlalchemy_, social-auth-app-flask-mongoengine_, social-auth-app-flask-peewee_ 23 | Flask framework integration 24 | 25 | * social-auth-app-pyramid_ 26 | Pyramid framework integration 27 | 28 | * social-auth-app-cherrypy_ 29 | Cherrypy framework integration 30 | 31 | * social-auth-app-tornado_ 32 | Tornado framework integration 33 | 34 | * social-auth-app-webpy_ 35 | Webpy framework integration 36 | 37 | 38 | Dependencies 39 | ------------ 40 | 41 | Dependencies are properly defined in the requirements files. 42 | There are some ``extras`` defined to install the corresponding 43 | dependencies since they are required to build extensions that, unless 44 | used, are undesired. 45 | 46 | * :doc:`backends/saml` support requires the use of the ``saml`` extra. 47 | * :doc:`backends/shopify` support requires the use of the ``shopify`` extra. 48 | * :doc:`backends/google` One Tap support requires the use of the ``google-onetap`` extra. 49 | * :doc:`backends/azuread` support requires the use of the ``azuread`` extra. 50 | 51 | There's also the ``all`` extra that will install all the extra options. 52 | 53 | Several backends demand application registration on their 54 | corresponding sites and other dependencies like SQLAlchemy_ on Flask 55 | and Webpy. 56 | 57 | 58 | Get a copy 59 | ---------- 60 | 61 | From PyPI_:: 62 | 63 | $ pip install social-auth- 64 | 65 | Or, grab the relevant repository from GitHub_, then:: 66 | 67 | $ cd social-auth- 68 | $ sudo python setup.py install 69 | 70 | 71 | Using the ``extras`` options 72 | ---------------------------- 73 | 74 | To enable any of the ``extras`` options to bring the dependencies for 75 | SAML_, or all:: 76 | 77 | $ pip install "social-auth-core[saml]" 78 | $ pip install "social-auth-core[all]" 79 | 80 | 81 | .. _OpenID: http://openid.net/ 82 | .. _OpenIDConnect: http://openid.net/connect/ 83 | .. _OAuth: http://oauth.net/ 84 | .. _SAML: https://www.onelogin.com/saml 85 | .. _PyPI: https://pypi.org/project/social-auth-core/ 86 | .. _GitHub: https://github.com/python-social-auth/ 87 | .. _python-openid: http://pypi.org/project/python-openid/ 88 | .. _requests-oauthlib: https://requests-oauthlib.readthedocs.org/ 89 | .. _SQLAlchemy: http://www.sqlalchemy.org/ 90 | .. _python-social-auth: https://github.com/python-social-auth 91 | .. _social-auth-core: https://github.com/python-social-auth/social-core 92 | .. _social-auth-storage-sqlalchemy: https://github.com/python-social-auth/social-storage-sqlalchemy 93 | .. _social-auth-storage-peewee: https://github.com/python-social-auth/social-storage-peewee 94 | .. _social-auth-storage-mongoengine: https://github.com/python-social-auth/social-storage-mongoengine 95 | .. _social-auth-app-django: https://github.com/python-social-auth/social-app-django 96 | .. _social-auth-app-django-mongoengine: https://github.com/python-social-auth/social-app-django-mongoengine 97 | .. _social-auth-app-flask: https://github.com/python-social-auth/social-app-flask 98 | .. _social-auth-app-flask-mongoengine: https://github.com/python-social-auth/social-app-flask-mongoengine 99 | .. _social-auth-app-flask-peewee: https://github.com/python-social-auth/social-app-flask-peewee 100 | .. _social-auth-app-flask-sqlalchemy: https://github.com/python-social-auth/social-app-flask-sqlalchemy 101 | .. _social-auth-app-pyramid: https://github.com/python-social-auth/social-app-pyramid 102 | .. _social-auth-app-cherrypy: https://github.com/python-social-auth/social-app-cherrypy 103 | .. _social-auth-app-tornado: https://github.com/python-social-auth/social-app-tornado 104 | .. _social-auth-app-webpy: https://github.com/python-social-auth/social-app-webpy 105 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = _build 9 | 10 | # Internal variables. 11 | PAPEROPT_a4 = -D latex_paper_size=a4 12 | PAPEROPT_letter = -D latex_paper_size=letter 13 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 14 | 15 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest 16 | 17 | help: 18 | @echo "Please use \`make ' where is one of" 19 | @echo " html to make standalone HTML files" 20 | @echo " dirhtml to make HTML files named index.html in directories" 21 | @echo " singlehtml to make a single large HTML file" 22 | @echo " pickle to make pickle files" 23 | @echo " json to make JSON files" 24 | @echo " htmlhelp to make HTML files and a HTML help project" 25 | @echo " qthelp to make HTML files and a qthelp project" 26 | @echo " devhelp to make HTML files and a Devhelp project" 27 | @echo " epub to make an epub" 28 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 29 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 30 | @echo " text to make text files" 31 | @echo " man to make manual pages" 32 | @echo " changes to make an overview of all changed/added/deprecated items" 33 | @echo " linkcheck to check all external links for integrity" 34 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 35 | 36 | clean: 37 | -rm -rf $(BUILDDIR)/* 38 | 39 | html: 40 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 41 | @echo 42 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 43 | 44 | dirhtml: 45 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 46 | @echo 47 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 48 | 49 | singlehtml: 50 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 51 | @echo 52 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 53 | 54 | pickle: 55 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 56 | @echo 57 | @echo "Build finished; now you can process the pickle files." 58 | 59 | json: 60 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 61 | @echo 62 | @echo "Build finished; now you can process the JSON files." 63 | 64 | htmlhelp: 65 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 66 | @echo 67 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 68 | ".hhp project file in $(BUILDDIR)/htmlhelp." 69 | 70 | qthelp: 71 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 72 | @echo 73 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 74 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 75 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/DjangoSocialAuth.qhcp" 76 | @echo "To view the help file:" 77 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/DjangoSocialAuth.qhc" 78 | 79 | devhelp: 80 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 81 | @echo 82 | @echo "Build finished." 83 | @echo "To view the help file:" 84 | @echo "# mkdir -p $$HOME/.local/share/devhelp/DjangoSocialAuth" 85 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/DjangoSocialAuth" 86 | @echo "# devhelp" 87 | 88 | epub: 89 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 90 | @echo 91 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 92 | 93 | latex: 94 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 95 | @echo 96 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 97 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 98 | "(use \`make latexpdf' here to do that automatically)." 99 | 100 | latexpdf: 101 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 102 | @echo "Running LaTeX files through pdflatex..." 103 | make -C $(BUILDDIR)/latex all-pdf 104 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 105 | 106 | text: 107 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 108 | @echo 109 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 110 | 111 | man: 112 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 113 | @echo 114 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 115 | 116 | changes: 117 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 118 | @echo 119 | @echo "The overview file is in $(BUILDDIR)/changes." 120 | 121 | linkcheck: 122 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 123 | @echo 124 | @echo "Link check complete; look for any errors in the above output " \ 125 | "or in $(BUILDDIR)/linkcheck/output.txt." 126 | 127 | doctest: 128 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 129 | @echo "Testing of doctests in the sources finished, look at the " \ 130 | "results in $(BUILDDIR)/doctest/output.txt." 131 | -------------------------------------------------------------------------------- /docs/backends/facebook.rst: -------------------------------------------------------------------------------- 1 | Facebook 2 | ======== 3 | 4 | Python Social Auth provides multiple backends for Facebook authentication: 5 | 6 | - **FacebookOAuth2** (``social_core.backends.facebook.FacebookOAuth2``) - Standard Facebook OAuth2 authentication 7 | - **FacebookAppOAuth2** (``social_core.backends.facebook.FacebookAppOAuth2``) - For Facebook Canvas Applications 8 | - **FacebookLimitedLogin** (``social_core.backends.facebook_limited.FacebookLimitedLogin``) - For Facebook Limited Login (iOS SDK) 9 | 10 | OAuth2 11 | ------ 12 | 13 | Facebook uses OAuth2 for its auth process. Further documentation at `Facebook 14 | development resources`_: 15 | 16 | - Register a new application at `Facebook App Creation`_, don't use 17 | ``localhost`` as ``App Domains`` and ``Site URL`` since Facebook won't allow 18 | them. Use a placeholder like ``myapp.com`` and define that domain in your 19 | ``/etc/hosts`` or similar file. 20 | 21 | - Add the Facebook OAuth2 backend to your ``AUTHENTICATION_BACKENDS`` setting:: 22 | 23 | AUTHENTICATION_BACKENDS = ( 24 | ... 25 | 'social_core.backends.facebook.FacebookOAuth2', 26 | ... 27 | ) 28 | 29 | - fill ``App Id`` and ``App Secret`` values in values:: 30 | 31 | SOCIAL_AUTH_FACEBOOK_KEY = '' 32 | SOCIAL_AUTH_FACEBOOK_SECRET = '' 33 | 34 | - Define ``SOCIAL_AUTH_FACEBOOK_SCOPE`` to get extra permissions 35 | from facebook. Email is not sent by default, to get it, you must request the 36 | ``email`` permission:: 37 | 38 | SOCIAL_AUTH_FACEBOOK_SCOPE = ['email'] 39 | 40 | - Define ``SOCIAL_AUTH_FACEBOOK_PROFILE_EXTRA_PARAMS`` to pass extra parameters 41 | to https://graph.facebook.com/me when gathering the user profile data (you need 42 | to explicitly ask for fields like ``email`` using ``fields`` key):: 43 | 44 | SOCIAL_AUTH_FACEBOOK_PROFILE_EXTRA_PARAMS = { 45 | 'locale': 'ru_RU', 46 | 'fields': 'id, name, email, age_range' 47 | } 48 | 49 | If you define a redirect URL in Facebook setup page, be sure to not define 50 | http://127.0.0.1:8000 or http://localhost:8000 because it won't work when 51 | testing. Instead I define http://myapp.com and setup a mapping on ``/etc/hosts``. 52 | 53 | Currently the backend uses Facebook API version `18.0` by default, but this can 54 | be overridden by the following setting:: 55 | 56 | SOCIAL_AUTH_FACEBOOK_API_VERSION = '19.0' 57 | 58 | .. note:: 59 | If you're using Facebook Graph API v3.0 or later, be aware that several 60 | parameters have been deprecated: 61 | 62 | - The ``display`` parameter (e.g., ``{'display': 'touch'}``) is no longer 63 | supported. Facebook now automatically detects mobile devices based on 64 | the user agent. 65 | - Make sure to check Facebook's `Graph API Changelog`_ for other deprecated 66 | features when upgrading to newer API versions. 67 | 68 | .. _Graph API Changelog: https://developers.facebook.com/docs/graph-api/changelog 69 | 70 | 71 | Canvas Application 72 | ------------------ 73 | 74 | If you need to perform authentication from Facebook Canvas application: 75 | 76 | - Create your canvas application at http://developers.facebook.com/apps 77 | 78 | - In Facebook application settings specify your canvas URL ``mysite.com/fb`` 79 | (current default) 80 | 81 | - Add the Facebook Canvas Application backend to your ``AUTHENTICATION_BACKENDS`` setting:: 82 | 83 | AUTHENTICATION_BACKENDS = ( 84 | ... 85 | 'social_core.backends.facebook.FacebookAppOAuth2', 86 | ... 87 | ) 88 | 89 | - Setup your Python Social Auth settings and your application namespace:: 90 | 91 | SOCIAL_AUTH_FACEBOOK_APP_KEY = '' 92 | SOCIAL_AUTH_FACEBOOK_APP_SECRET = '' 93 | SOCIAL_AUTH_FACEBOOK_APP_NAMESPACE = '' 94 | 95 | - Launch your testing server on port 80 (use sudo or nginx or apache) for 96 | browser to be able to load it when Facebook calls canvas URL 97 | 98 | - Open your Facebook page via http://apps.facebook.com/app_namespace or 99 | better via http://www.facebook.com/pages/user-name/user-id?sk=app_app-id 100 | 101 | - After that you will see this page in a right way and will able to connect 102 | to application and login automatically after connection 103 | 104 | - Provide a template to be rendered, it must have this JavaScript snippet (or 105 | similar) in it:: 106 | 107 | 116 | 117 | 118 | More info on the topic at `Facebook Canvas Application Authentication`_. 119 | 120 | .. _Facebook development resources: http://developers.facebook.com/docs/authentication/ 121 | .. _Facebook App Creation: https://developers.facebook.com/apps/ 122 | .. _Facebook Canvas Application Authentication: http://www.ikrvss.ru/2011/09/22/django-social-auth-and-facebook-canvas-applications/ 123 | -------------------------------------------------------------------------------- /docs/configuration/pyramid.rst: -------------------------------------------------------------------------------- 1 | Pyramid Framework 2 | ================= 3 | 4 | Pyramid_ reusable applications are tricky (or I'm not capable enough). Here are 5 | details on how to enable this application on Pyramid. 6 | 7 | 8 | Dependencies 9 | ------------ 10 | 11 | The `Pyramid app`_ depends on sqlalchemy_, there's no support for others 12 | ORMs yet but pull-requests are welcome. 13 | 14 | 15 | Installing 16 | ---------- 17 | 18 | From pypi_:: 19 | 20 | $ pip install social-auth-app-pyramid 21 | 22 | 23 | Enabling the application 24 | ------------------------ 25 | 26 | The application can be scanned by ``Configurator.scan()``, also it defines an 27 | ``includeme()`` in the ``__init__.py`` file which will add the needed routes to 28 | your application configuration. To scan it just add:: 29 | 30 | config.include('social_pyramid') 31 | config.scan('social_pyramid') 32 | 33 | 34 | Models Setup 35 | ------------ 36 | 37 | At the moment the models for python-social-auth_ are defined inside a function 38 | because they need the reference to the current DB instance and the User model 39 | used on your project (check *User model reference* below). Once the Pyramid 40 | application configuration and database are defined, call ``init_social`` to 41 | register the models:: 42 | 43 | from social_pyramid.models import init_social 44 | 45 | init_social(config, Base, DBSession) 46 | 47 | So far I wasn't able to find another way to define the models on another way 48 | rather than making it as a side-effect of calling this function since the 49 | database is not available and ``current_app`` cannot be used on initialization 50 | time, just run time. 51 | 52 | 53 | User model reference 54 | -------------------- 55 | 56 | The application keeps a reference to the User model used by your project, 57 | define it by using this setting:: 58 | 59 | SOCIAL_AUTH_USER_MODEL = 'foobar.models.User' 60 | 61 | The value must be the import path to the User model. 62 | 63 | 64 | Global user 65 | ----------- 66 | 67 | The application expects the current logged in user accessible at ``request.user``, 68 | the example application ensures that with this handler:: 69 | 70 | def get_user(request): 71 | user_id = request.session.get('user_id') 72 | if user_id: 73 | user = DBSession.query(User)\ 74 | .filter(User.id == user_id)\ 75 | .first() 76 | else: 77 | user = None 78 | return user 79 | 80 | The handler is added to the configuration doing:: 81 | 82 | config.add_request_method('example.auth.get_user', 'user', reify=True) 83 | 84 | This is just a simple example, probably your project does it in a better way. 85 | 86 | 87 | User login 88 | ---------- 89 | 90 | Since the application doesn't make any assumption on how you are going to login 91 | the users, you need to specify it. In order to do that, define these settings:: 92 | 93 | SOCIAL_AUTH_LOGIN_FUNCTION = 'example.auth.login_user' 94 | SOCIAL_AUTH_LOGGEDIN_FUNCTION = 'example.auth.login_required' 95 | 96 | The first one must accept the strategy used and the user instance that was 97 | created or retrieved from the database, there you can set the user id in the 98 | session or cookies or whatever place used later to retrieve the id again and 99 | load the user from the database (check the snippet above in *Global User*). 100 | 101 | The second one is used to ensure that there's a user logged in when calling the 102 | disconnect view. It must accept a ``User`` instance and return ``True`` or 103 | ``False``. 104 | 105 | Check the auth.py_ in the example application for details on how it's done 106 | there. 107 | 108 | 109 | Social auth in templates context 110 | -------------------------------- 111 | 112 | To access the social instances related to a user in the template context, you 113 | can do so by accessing the ``social_auth`` attribute in the user instance:: 114 | 115 |
  • ${social.provider}
    • 116 | 117 | Also you can add the backends (associated and not associated to a user) by 118 | enabling this context function in your project:: 119 | 120 | from pyramid.events import subscriber, BeforeRender 121 | from social_pyramid.utils import backends 122 | 123 | @subscriber(BeforeRender) 124 | def add_social(event): 125 | request = event['request'] 126 | event.update(backends(request, request.user)) 127 | 128 | That will load a dict with entries:: 129 | 130 | { 131 | 'associated': [...], 132 | 'not_associated': [...], 133 | 'backends': [...] 134 | } 135 | 136 | The ``associated`` key will have all the associated ``UserSocialAuth`` 137 | instances related to the given user. ``not_associated`` will have the backends 138 | names not associated and backends will have all the enabled backends names. 139 | 140 | 141 | .. _Pyramid: http://www.pylonsproject.org/projects/pyramid/about 142 | .. _python-social-auth: https://github.com/python-social-auth 143 | .. _Pyramid app: https://github.com/python-social-auth/social-app-pyramid 144 | .. _sqlalchemy: http://www.sqlalchemy.org/ 145 | .. _auth.py: https://github.com/python-social-auth/social-examples/blob/master/example-pyramid/example/auth.py 146 | .. _pypi: http://pypi.python.org/pypi/social-auth-app-pyramid/ 147 | --------------------------------------------------------------------------------