Skip to main content

Add authentication to your Python web application

This guide will show you how to integrate Logto into your Python web application.

tip
  • The example uses Flask, but the concepts are the same for other frameworks.
  • The Python sample project is available on our Python SDK repo.
  • Logto SDK leverages coroutines, remember to use await when calling async functions.

Prerequisites

Installation

Execute in the project root directory:

pip install logto # or `poetry add logto` or whatever you use

Integration

Init LogtoClient

First, create a Logto config:

client.py
from logto import LogtoClient, LogtoConfig

client = LogtoClient(
LogtoConfig(
endpoint="https://you-logto-endpoint.app", # Replace with your Logto endpoint
appId="replace-with-your-app-id",
appSecret="replace-with-your-app-secret",
),
)
tip

You can find and copy "App Secret" from application details page in Admin Console:

App Secret

Also replace the default memory storage with a persistent storage, for example:

client.py
from logto import LogtoClient, LogtoConfig, Storage
from flask import session
from typing import Union

class SessionStorage(Storage):
def get(self, key: str) -> Union[str, None]:
return session.get(key, None)

def set(self, key: str, value: Union[str, None]) -> None:
session[key] = value

def delete(self, key: str) -> None:
session.pop(key, None)

client = LogtoClient(
LogtoConfig(...),
storage=SessionStorage(),
)

See Storage for more details.

Configure redirect URIs

Before we dive into the details, here's a quick overview of the end-user experience. The sign-in process can be simplified as follows:

  1. Your app invokes the sign-in method.
  2. The user is redirected to the Logto sign-in page. For native apps, the system browser is opened.
  3. The user signs in and is redirected back to your app (configured as the redirect URI).
Regarding redirect-based sign-in
  1. This authentication process follows the OpenID Connect (OIDC) protocol, and Logto enforces strict security measures to protect user sign-in.
  2. If you have multiple apps, you can use the same identity provider (Logto). Once the user signs in to one app, Logto will automatically complete the sign-in process when the user accesses another app.

To learn more about the rationale and benefits of redirect-based sign-in, see Logto sign-in experience explained.


note

In the following code snippets, we assume your app is running on http://localhost:3000/.

Configure redirect URIs

Switch to the application details page of Logto Console. Add a redirect URI http://localhost:3000/callback.

Redirect URI in Logto Console

Just like signing in, users should be redirected to Logto for signing out of the shared session. Once finished, it would be great to redirect the user back to your website. For example, add http://localhost:3000/ as the post sign-out redirect URI section.

Then click "Save" to save the changes.

Implement sign-in and sign-out routes

In your web application, add a route to properly handle the sign-in request from users. Let's use /sign-in as an example:

flask.py
@app.route("/sign-in")
async def sign_in():
# Get the sign-in URL and redirect the user to it
return redirect(await client.signIn(
redirectUri="http://localhost:3000/callback",
))

Replace http://localhost:3000/callback with the callback URL you set in your Logto Console for this application.

If you want to show the sign-up page on the first screen, you can set interactionMode to signUp:

flask.py
@app.route("/sign-in")
async def sign_in():
return redirect(await client.signIn(
redirectUri="http://localhost:3000/callback",
interactionMode="signUp", # Show the sign-up page on the first screen
))

Now, whenever your users visit http://localhost:3000/sign-in, it will start a new sign-in attempt and redirect the user to the Logto sign-in page.

Note Creating a sign-in route isn't the only way to start a sign-in attempt. You can always use the signIn method to get the sign-in URL and redirect the user to it.

After the user makes a signing-out request, Logto will clear all user authentication information in the session.

To clean up the Python session and Logto session, a sign-out route can be implemented as follows:

flask.py
@app.route("/sign-out")
async def sign_out():
return redirect(
# Redirect the user to the home page after a successful sign-out
await client.signOut(postLogoutRedirectUri="http://localhost:3000/")
)

Handle authentication status

In Logto SDK, we can use client.isAuthenticated() to check the authentication status, if the user is signed in, the value will be true, otherwise, the value will be false.

Here we also implement a simple home page for demonstration:

  • If the user is not signed in, show a sign-in button;
  • If the user is signed in, show a sign-out button.
@app.route("/")
async def home():
if client.isAuthenticated() is False:
return "Not authenticated <a href='/sign-in'>Sign in</a>"
return "Authenticated <a href='/sign-out'>Sign out</a>"

Checkpoint: Test your application

Now, you can test your application:

  1. Run your application, you will see the sign-in button.
  2. Click the sign-in button, the SDK will init the sign-in process and redirect you to the Logto sign-in page.
  3. After you signed in, you will be redirected back to your application and see the sign-out button.
  4. Click the sign-out button to clear local storage and sign out.

Get user information

Display user information

To display the user's information, you can use either the getIdTokenClaims method or fetchUserInfo method to get user information. While getIdTokenClaims returns the user information contains in the ID token, fetchUserInfo fetches the user information from the userinfo endpoint.

As you can see, we use @authenticated decorator to bring user information context to the Flask application APIs.

authenticated.py
from functools import wraps
from flask import g, jsonify, redirect
from samples.client import client
def authenticated(shouldRedirect: bool = False, fetchUserInfo: bool = False):
def decorator(func):
@wraps(func)
async def wrapper(*args, **kwargs):
if client.isAuthenticated() is False:
if shouldRedirect:
return redirect("/sign-in")
return jsonify({"error": "Not authenticated"}), 401
# Store user info in Flask application context
g.user = (
await client.fetchUserInfo()
if fetchUserInfo
else client.getIdTokenClaims()
)
return await func(*args, **kwargs)
return wrapper
return decorator

For example, to display the user's information in an API, you can use the following code:

flask.py
@app.route("/protected/userinfo")
@authenticated(shouldRedirect=True, fetchUserInfo=True)
async def protectedUserinfo():
try:
return (
"<h2>User info</h2>"
+ g.user.model_dump_json(indent=2, exclude_unset=True).replace("\n", "<br>")
+ navigationHtml
)
except LogtoException as e:
return "<h2>Error</h2>" + str(e) + "<br>" + navigationHtml

Our data models are based on pydantic, so you can use model_dump_json to dump the data model to JSON.

Adding exclude_unset=True will exclude unset fields from the JSON output, which makes the output more precise.

For example, if we didn't request the email scope when signing in, and the email field will be excluded from the JSON output. However, if we requested the email scope, but the user doesn't have an email address, the email field will be included in the JSON output with a null value.

To learn more about scopes and claims, see Get user information.

Request additional claims

You may find some user information are missing in the returned object from client.getIdTokenClaims(). This is because OAuth 2.0 and OpenID Connect (OIDC) are designed to follow the principle of least privilege (PoLP), and Logto is built on top of these standards.

By default, limited claims are returned. If you need more information, you can request additional scopes to access more claims.

info

A "claim" is an assertion made about a subject; a "scope" is a group of claims. In the current case, a claim is a piece of information about the user.

Here's a non-normative example the scope - claim relationship:

tip

The "sub" claim means "subject", which is the unique identifier of the user (i.e. user ID).

Logto SDK will always request three scopes: openid, profile, and offline_access.

To request additional scopes, you can pass the scopes to the LogtoConfig object. For example:

client.py
from logto import UserInfoScope

client = LogtoClient(
LogtoConfig(
# ...other configurations
scopes = [
UserInfoScope.email,
UserInfoScope.phone,
],
),
storage=SessionStorage(),
)

Then you can access the additional claims in the return value of client.getIdTokenClaims():

idTokenClaims = await client.getIdTokenClaims();

Claims that need network requests

To prevent bloating the ID token, some claims require network requests to fetch. For example, the custom_data claim is not included in the user object even if it's requested in the scopes. To access these claims, you can use the client.fetchUserInfo() method:

flask.py
(await client.fetchUserInfo()).custom_data
This method will fetch the user information by requesting to the userinfo endpoint. To learn more about the available scopes and claims, see the Scopes and claims section.

Scopes and claims

Logto uses OIDC scopes and claims conventions to define the scopes and claims for retrieving user information from the ID token and OIDC userinfo endpoint. Both of the "scope" and the "claim" are terms from the OAuth 2.0 and OpenID Connect (OIDC) specifications.

Here's the list of supported scopes and the corresponding claims:

openid

Claim nameTypeDescriptionNeeds userinfo?
substringThe unique identifier of the userNo

profile

Claim nameTypeDescriptionNeeds userinfo?
namestringThe full name of the userNo
usernamestringThe username of the userNo
picturestringURL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User.No
created_atnumberTime the End-User was created. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).No
updated_atnumberTime the End-User's information was last updated. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).No

Other standard claims include family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo, and locale will be also included in the profile scope without the need for requesting the userinfo endpoint. A difference compared to the claims above is that these claims will only be returned when their values are not empty, while the claims above will return null if the values are empty.

note

Unlike the standard claims, the created_at and updated_at claims are using milliseconds instead of seconds.

email

Claim nameTypeDescriptionNeeds userinfo?
emailstringThe email address of the userNo
email_verifiedbooleanWhether the email address has been verifiedNo

phone

Claim nameTypeDescriptionNeeds userinfo?
phone_numberstringThe phone number of the userNo
phone_number_verifiedbooleanWhether the phone number has been verifiedNo

address

Please refer to the OpenID Connect Core 1.0 for the details of the address claim.

custom_data

Claim nameTypeDescriptionNeeds userinfo?
custom_dataobjectThe custom data of the userYes

identities

Claim nameTypeDescriptionNeeds userinfo?
identitiesobjectThe linked identities of the userYes
sso_identitiesarrayThe linked SSO identities of the userYes

urn:logto:scope:organizations

Claim nameTypeDescriptionNeeds userinfo?
organizationsstring[]The organization IDs the user belongs toNo
organization_dataobject[]The organization data the user belongs toYes

urn:logto:scope:organization_roles

Claim nameTypeDescriptionNeeds userinfo?
organization_rolesstring[]The organization roles the user belongs to with the format of <organization_id>:<role_name>No

Considering performance and the data size, if "Needs userinfo?" is "Yes", it means the claim will not show up in the ID token, but will be returned in the userinfo endpoint response.

API resources and organizations

We recommend to read 🔐 Role-Based Access Control (RBAC) first to understand the basic concepts of Logto RBAC and how to set up API resources properly.

Configure Logto client

Once you have set up the API resources, you can add them when configuring Logto in your app:

client.py
client = LogtoClient(
LogtoConfig(
# ...other configs
resources=["https://shopping.your-app.com/api", "https://store.your-app.com/api"], # Add API resources
),
)

Each API resource has its own permissions (scopes).

For example, the https://shopping.your-app.com/api resource has the shopping:read and shopping:write permissions, and the https://store.your-app.com/api resource has the store:read and store:write permissions.

To request these permissions, you can add them when configuring Logto in your app:

client.py
client = LogtoClient(
LogtoConfig(
# ...other configs
scopes=["shopping:read", "shopping:write", "store:read", "store:write"],
resources=["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
),
)

You may notice that scopes are defined separately from API resources. This is because Resource Indicators for OAuth 2.0 specifies the final scopes for the request will be the cartesian product of all the scopes at all the target services.

Thus, in the above case, scopes can be simplified from the definition in Logto, both of the API resources can have read and write scopes without the prefix. Then, in the Logto config:

client.py
client = LogtoClient(
LogtoConfig(
# ...other configs
scopes=["read", "write"],
resources=["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
),
)

For every API resource, it will request for both read and write scopes.

note

It is fine to request scopes that are not defined in the API resources. For example, you can request the email scope even if the API resources don't have the email scope available. Unavailable scopes will be safely ignored.

After the successful sign-in, Logto will issue proper scopes to API resources according to the user's roles.

Fetch access token for the API resource

To fetch the access token for a specific API resource, you can use the GetAccessToken method:

flask.py
accessToken = await client.getAccessToken("https://shopping.your-app.com/api")
# or
claims = await client.getAccessTokenClaims("https://shopping.your-app.com/api")

This method will return a JWT access token that can be used to access the API resource when the user has related permissions. If the current cached access token has expired, this method will automatically try to use a refresh token to get a new access token.

Fetch organization tokens

If organization is new to you, please read 🏢 Organizations (Multi-tenancy) to get started.

You need to add core.UserScopeOrganizations scope when configuring the Logto client:

client.py
from logto import LogtoClient, LogtoConfig, UserInfoScope

client = LogtoClient(
LogtoConfig(
# ...other configs
scopes=[UserInfoScope.organizations],
),
)

Once the user is signed in, you can fetch the organization token for the user:

flask.py
# Replace the parameter with a valid organization ID.
# Valid organization IDs for the user can be found in the ID token claim `organizations`.
organizationToken = await client.getOrganizationToken(organization_id)
# or
organizationTokenClaims = await client.getOrganizationTokenClaims(organization_id)

Further readings

End-user flows: authentication flows, account flows, and organization flows Configure connectors Protect your API