Identity Documentation#

This Identity library is an authentication/authorization library that:

Suitable for apps that are targeting end users on Microsoft identity platform. (which includes Work or school accounts provisioned through Azure AD, and Personal Microsoft accounts such as Skype, Xbox, Outlook.com).
Currently designed for web apps, regardless of which Python web framework you are using.
Provides a set of high level API that is built on top of, and easier to be used than Microsoft’s MSAL Python library.
Written in Python, for Python apps.

Scenarios#

Web app that logs in users#

Firstly, create an instance of the Auth object, and assign it to a (typically global) variable:

auth = identity.web.Auth(
    session=session,  # A session object is a key-value storage with a
                      # dict-like interface. Many web frameworks provide this.
    authority="https://login.microsoftonline.com/common",
    client_id="your_app_client_id",
    client_credential="your_secret",
    )

Now, in your web app’s login controller, call the auth.log_in(scopes=["your_scope"], redirect_uri="https://your_app.example.com/redirect_uri") (see also log_in()) to obtain the auth_uri (and possibly a user_code), and then render them into your login html page.
The second leg of log-in needs to be implemented in another controller, which calls auth.complete_log_in(incoming_query_parameters) (see also complete_log_in()). If its returned dict contains an error, then render the error to end user, otherwise your end user has successfully logged in, and his/her information is available as a dict returned by get_user(). In particular, the returned dict contains a key named sub, whose value is the unique identifier which you can use to represent this end user in your app’s local database.
Don’t forget to add one more controller for log out. You do it by calling auth.log_out("https://your_app.example.com"). Please refer to log_out()’s docs for more details about its return value.

All of the content above are demonstrated in this sample (link to be provided).

Web app that logs in users and calls a web API on their behalf#

Building on top of the previous scenario, you just need to call auth.get_token_for_user(["your_scope"]) to obtain a token object. See get_token_for_user() for more details. And you can see it in action in this sample (link to be provided).

API#

The following section is the API Reference of Identity library.

Note

Only APIs and their parameters documented in this section are part of public API, with guaranteed backward compatibility for the entire 1.x series.

Other modules in the source code are all considered as internal helpers, which could change at anytime in the future, without prior notice.

class identity.web.Auth(*, session, authority, client_id, client_credential=None, http_cache=None)#

__init__(*, session, authority, client_id, client_credential=None, http_cache=None)#

Create an identity helper for a web app.

This instance is expected to be long-lived with the web app.

Parameters:

session¶ (dict) – A dict-like object to hold the session data. If you are using Flask, you should pass in session. If you are using Django, you should pass in request.session.
authority¶ (str) – The authority which your app registers with. For example, https://example.com/foo.
client_id¶ (str) – The client_id of your web app, issued by its authority.
client_credential¶ (str) – It is somtimes a string. The actual format is decided by the underlying auth library. TBD.

complete_log_in(auth_response=None)#

This is the second leg of the authentication/authorization.

It is used inside your redirect_uri controller.

Parameters:

auth_response¶ (dict) –

A dict-like object containing the parameters issued by Identity Provider. If you are using Flask, you can pass in request.args. If you are using Django, you can pass in HttpRequest.GET.

If you were using Device Code Flow, you won’t have an auth response, in that case you can leave it with its default value None.

Returns:

On failure, a dict containing “error” and optional “error_description”, for you to somehow render it to end user.
On success, a dict containing the info of current logged-in user. That dict is actually the claims from an already-validated ID token.

get_token_for_client(scopes)#

Get access token for the current app, with specified scopes.

Parameters:

scopes¶ (list) – A list of scopes that your app will need to use.

Returns:

A dict representing the json response from identity provider.

A successful response would contain “access_token” key,
An error response would contain “error” and usually “error_description”.