1. Install Django

  2. Install and configure the Sites framework


    Make sure you update the domain in your `Site` object

    This needs to match the host (hostname + port) that you are using to access the Django site with. The easiest way to do this to go to /admin/sites/site/1/change/ if you have the admin site enabled.

    SITE_ID is only required if want to use the MicrosoftClient without a request object (all of the code provided in this package uses a request object). If you want multiple Site objects and generate authorize URL when accessing your site from multiple domains, you must not set a SITE_ID

  3. Create a Azure AD App. After you register the app, make sure you click on “Certificates & Secrets” and generate a new Client Secret.


    You will need Client ID and an Client Secret for step 5. Make sure you generate these and store them somewhere.

    When you are registering the app it will ask for a Redirect URI. This must match the absolute URL of your microsoft_auth:auth-callback view. By default this would be https://<your-domain>/microsoft/auth-callback/.

    This URL must be HTTPS unless your hostname is localhost. localhost can only be used if DEBUG is set to True. Microsoft only allows HTTP authentication if the hostname is localhost.

  4. Install package from PyPi

$ pip install django_microsoft_auth
  1. Add the following to your
    # other apps...

        # other template settings...
        'OPTIONS': {
            'context_processors': [
                # other context_processors...

    'django.contrib.auth.backends.ModelBackend' # if you also want to use Django's authentication
    # I recommend keeping this with at least one database superuser in case of unable to use others

# values you got from step 2 from your Mirosoft app

# Microsoft authentication
# include Microsoft Accounts, Office 365 Enterpirse and Azure AD accounts

# Xbox Live authentication
MICROSOFT_AUTH_LOGIN_TYPE = 'xbl'  # Xbox Live authentication
  1. Add the following to your
urlpatterns = [
    # other urlpatterns...
    path('microsoft/', include('microsoft_auth.urls', namespace='microsoft')),
  1. Run migrations
$ python migrate
  1. Start site and goto /admin to and logout if you are logged in.
  2. Login as Microsoft/Office 365/Xbox Live user. It will fail. This will automatically create your new user.
  3. Login as a Password user with access to change user accounts.
  4. Go to Admin -> Users and edit your Microsoft user to have any permissions you want as you normally.

Running behind a reverse-proxy

Make sure to pass your protocol with X-Forwarded-Proto so your callback url will be constructed properly

Test Site

As part of unit testing, there minimal functioning site that is pimarily used for running tests against and to help development. It can be used as a reference for how to do some things.

The full refrence site exists under tests/site

To setup,

  1. Make sure you have installed the project from sources.
  2. Get a Microsoft app with a Client ID and Client Secret following step 3 above.
  3. Create a tests/site/ file and add your MICROSOFT_AUTH_CLIENT_ID and MICROSOFT_AUTH_CLIENT_SECRET settings
  4. Start up the site
$ python -m migrate
$ python -m createsuperuser
$ python -m runserver
  1. Configure your Site.

Migrating from 1.0 to 2.0

django_microsoft_auth v2.0 changed the scopes that are used to retrieve user data to fall inline with OpenID Connect standards. The old scope is now deprecated and openid email profile scopes are required by default.

This means the user ID that is returned from Microsoft has changed. To prevent any possible data loss, out of the box, django_microsoft_auth will essentially make it so you cannot log in with Microsoft auth to access any users that are linked with a v1 Microsoft auth account.

You set MICROSOFT_AUTH_AUTO_REPLACE_ACCOUNTS to True to enable the behavior that will automatically replace a paired Microsoft Account on a user with the newly created one returned from Microsoft. This can potientally result is orhpaned data if you have a related object references to MicrosoftAccount instead of the user. It is recommend you stay on 1.3.x until you can manually migrate this data.

Once these account have been migrated, you can safely delete any remaining v1 Microsoft Accounts.

Sliencing Scope has changed warnings

If you stay on 1.3.x for a bit and you start getting Scope has changed from “User.Read” to “User.Read email profile openid”., you can slience this warning by setting an env variable for OAUTHLIB_RELAX_TOKEN_SCOPE before starting Django.


`bash $ export OAUTHLIB_RELAX_TOKEN_SCOPE=true $ python runserver `


`powershell > $env:OAUTHLIB_RELAX_TOKEN_SCOPE=$TRUE > python runserver `

You should however upgrade to 2.0 once you can.