あなたの Python ウェブアプリケーションに認証 (Authentication) を追加する

このガイドでは、あなたの Python ウェブアプリケーションに Logto を統合する方法を紹介します。

ヒント:

• この例では Flask を使用していますが、概念は他のフレームワークでも同じです。
• Python のサンプルプロジェクトは、私たちの Python SDK リポジトリ で利用可能です。
• Logto SDK はコルーチンを活用しているため、非同期関数を呼び出す際には await を使用することを忘れないでください。

前提条件

• Logto Cloud アカウントまたは セルフホスト Logto。
• 作成された Logto の従来のウェブアプリケーション。

インストール

プロジェクトのルートディレクトリで実行します：

pip install logto # または `poetry add logto` などを使用

統合

LogtoClient の初期化

まず、Logto の設定を作成します：

client.py

from logto import LogtoClient, LogtoConfig

client = LogtoClient(
    LogtoConfig(
        endpoint="https://you-logto-endpoint.app",  # あなたの Logto エンドポイントに置き換えてください
        appId="replace-with-your-app-id",
        appSecret="replace-with-your-app-secret",
    ),
)

ヒント:

「App Secret」は管理コンソールのアプリケーション詳細ページから見つけてコピーできます：

また、デフォルトのメモリストレージを永続的なストレージに置き換えます。例えば：

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(),
)

詳細については、Storage を参照してください。

リダイレクト URI の設定

詳細に入る前に、エンドユーザーの体験について簡単に説明します。サインインプロセスは次のように簡略化できます：

1. あなたのアプリがサインインメソッドを呼び出します。
2. ユーザーは Logto のサインインページにリダイレクトされます。ネイティブアプリの場合、システムブラウザが開かれます。
3. ユーザーがサインインし、あなたのアプリにリダイレクトされます（リダイレクト URI として設定されています）。

リダイレクトベースのサインインについて

1. この認証 (Authentication) プロセスは OpenID Connect (OIDC) プロトコルに従い、Logto はユーザーのサインインを保護するために厳格なセキュリティ対策を講じています。
2. 複数のアプリがある場合、同じアイデンティティプロバイダー (Logto) を使用できます。ユーザーがあるアプリにサインインすると、Logto は別のアプリにアクセスした際に自動的にサインインプロセスを完了します。

リダイレクトベースのサインインの理論と利点について詳しく知るには、Logto サインイン体験の説明を参照してください。

---

注記:

以下のコードスニペットでは、あなたのアプリが http://localhost:3000/ で実行されていると仮定しています。

リダイレクト URI を設定する

Logto Console のアプリケーション詳細ページに移動します。リダイレクト URI http://localhost:3000/callback を追加します。

サインインと同様に、ユーザーは共有セッションからサインアウトするために Logto にリダイレクトされるべきです。完了したら、ユーザーをあなたのウェブサイトに戻すと良いでしょう。例えば、http://localhost:3000/ をサインアウト後のリダイレクト URI セクションとして追加します。

その後、「保存」をクリックして変更を保存します。

サインインおよびサインアウトルートの実装

あなたの Web アプリケーションで、ユーザーからのサインインリクエストを適切に処理するためのルートを追加します。例として /sign-in を使用します：

flask.py

@app.route("/sign-in")
async def sign_in():
  # サインイン URL を取得し、ユーザーをその URL にリダイレクトします
  return redirect(await client.signIn(
      redirectUri="http://localhost:3000/callback",
  ))

このアプリケーションの Logto コンソールで設定したコールバック URL に http://localhost:3000/callback を置き換えてください。

最初の画面にサインアップページを表示したい場合は、interactionMode を signUp に設定できます：

flask.py

@app.route("/sign-in")
async def sign_in():
  return redirect(await client.signIn(
      redirectUri="http://localhost:3000/callback",
      interactionMode="signUp", # 最初の画面にサインアップページを表示
  ))

これで、ユーザーが http://localhost:3000/sign-in を訪れるたびに、新しいサインイン試行が開始され、ユーザーは Logto のサインインページにリダイレクトされます。

注意 サインインルートを作成することは、サインイン試行を開始する唯一の方法ではありません。signIn メソッドを使用してサインイン URL を取得し、ユーザーをその URL にリダイレクトすることも常に可能です。

ユーザーがサインアウトリクエストを行った後、Logto はセッション内のすべてのユーザー認証情報をクリアします。

Python セッションと Logto セッションをクリーンアップするために、次のようにサインアウトルートを実装できます：

flask.py

@app.route("/sign-out")
async def sign_out():
  return redirect(
      # サインアウトが成功した後、ユーザーをホームページにリダイレクト
      await client.signOut(postLogoutRedirectUri="http://localhost:3000/")
  )

認証 (Authentication) ステータスの処理

Logto SDK では、client.isAuthenticated() を使用して認証 (Authentication) 状態を確認できます。ユーザーがサインインしている場合、この値は true になり、そうでない場合は false になります。

ここでは、デモ用にシンプルなホームページを実装します：

• ユーザーがサインインしていない場合、サインインボタンを表示します。
• ユーザーがサインインしている場合、サインアウトボタンを表示します。

@app.route("/")
async def home():
    if client.isAuthenticated() is False:
        return "認証されていません <a href='/sign-in'>サインイン</a>"
    return "認証されています <a href='/sign-out'>サインアウト</a>"

チェックポイント: アプリケーションをテストする

これで、アプリケーションをテストできます：

1. アプリケーションを実行すると、サインインボタンが表示されます。
2. サインインボタンをクリックすると、SDK がサインインプロセスを初期化し、Logto のサインインページにリダイレクトされます。
3. サインインすると、アプリケーションに戻り、サインアウトボタンが表示されます。
4. サインアウトボタンをクリックして、トークンストレージをクリアし、サインアウトします。

ユーザー情報の取得

ユーザー情報の表示

ユーザーの情報を表示するには、getIdTokenClaims メソッドまたは fetchUserInfo メソッドを使用してユーザー情報を取得できます。getIdTokenClaims は ID トークンに含まれるユーザー情報を返し、fetchUserInfo は userinfo エンドポイントからユーザー情報を取得します。

ご覧のとおり、@authenticated デコレーターを使用して、Flask アプリケーション API にユーザー情報のコンテキストを提供しています。

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
          # Flask アプリケーションコンテキストにユーザー情報を保存
          g.user = (
              await client.fetchUserInfo()
              if fetchUserInfo
              else client.getIdTokenClaims()
          )
          return await func(*args, **kwargs)
      return wrapper
  return decorator

例えば、API でユーザー情報を表示するには、次のコードを使用できます：

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

私たちのデータモデルは pydantic に基づいているため、model_dump_json を使用してデータモデルを JSON にダンプできます。

exclude_unset=True を追加すると、未設定のフィールドが JSON 出力から除外され、出力がより正確になります。

例えば、サインイン時に email スコープを要求しなかった場合、email フィールドは JSON 出力から除外されます。しかし、email スコープを要求したが、ユーザーにメールアドレスがない場合、email フィールドは null 値で JSON 出力に含まれます。

スコープとクレームについて詳しくは、ユーザー情報の取得 を参照してください。

追加のクレームを要求する

client.getIdTokenClaims() から返されるオブジェクトに一部のユーザー情報が欠けていることがあります。これは、OAuth 2.0 と OpenID Connect (OIDC) が最小特権の原則 (PoLP) に従うように設計されており、Logto はこれらの標準に基づいて構築されているためです。

デフォルトでは、限られたクレーム (Claims) が返されます。より多くの情報が必要な場合は、追加のスコープ (Scopes) をリクエストして、より多くのクレーム (Claims) にアクセスできます。

備考:

「クレーム (Claim)」はサブジェクトについての主張であり、「スコープ (Scope)」はクレーム (Claims) のグループです。現在のケースでは、クレーム (Claim) はユーザーに関する情報の一部です。

スコープ (Scope) とクレーム (Claim) の関係の非規範的な例を示します：

ヒント:

「sub」クレーム (Claim) は「サブジェクト (Subject)」を意味し、ユーザーの一意の識別子（つまり、ユーザー ID）です。

Logto SDK は常に 3 つのスコープ (Scopes) をリクエストします：openid、profile、および offline_access。

追加のスコープを要求するには、スコープを LogtoConfig オブジェクトに渡すことができます。例えば：

client.py

from logto import UserInfoScope

client = LogtoClient(
    LogtoConfig(
        # ...他の設定
        scopes = [
            UserInfoScope.email,
            UserInfoScope.phone,
        ],
    ),
    storage=SessionStorage(),
)

その後、client.getIdTokenClaims() の戻り値で追加のクレームにアクセスできます：

idTokenClaims = await client.getIdTokenClaims();

ネットワークリクエストが必要なクレーム (Claims)

ID トークンの肥大化を防ぐために、一部のクレーム (Claims) は取得するためにネットワークリクエストが必要です。例えば、custom_data クレームはスコープで要求されてもユーザーオブジェクトに含まれません。これらのクレームにアクセスするには、 client.fetchUserInfo() メソッドを使用できます：

flask.py

(await client.fetchUserInfo()).custom_data

このメソッドは、userinfo エンドポイントにリクエストを送信してユーザー情報を取得します。利用可能なスコープとクレームについて詳しくは、スコープとクレームのセクションを参照してください。

スコープとクレーム

Logto は OIDC の スコープとクレームの規約 を使用して、ID トークンおよび OIDC userinfo エンドポイント からユーザー情報を取得するためのスコープとクレームを定義します。「スコープ」と「クレーム」は、OAuth 2.0 および OpenID Connect (OIDC) 仕様からの用語です。

サポートされているスコープと対応するクレームのリストはこちらです：

openid

クレーム名	タイプ	説明	ユーザー情報が必要か？
sub	string	ユーザーの一意の識別子	いいえ

profile

クレーム名	タイプ	説明	ユーザー情報が必要か？
name	string	ユーザーのフルネーム	いいえ
username	string	ユーザーのユーザー名	いいえ
picture	string	エンドユーザーのプロフィール画像の URL。この URL は画像ファイル（例：PNG、JPEG、または GIF 画像ファイル）を参照する必要があります。画像を含む Web ページを参照してはいけません。この URL は、エンドユーザーを説明する際に表示するのに適したプロフィール写真を特に参照するべきであり、エンドユーザーが撮影した任意の写真を参照するべきではありません。	いいえ
created_at	number	エンドユーザーが作成された時間。時間は Unix エポック（1970-01-01T00:00:00Z）からのミリ秒数で表されます。	いいえ
updated_at	number	エンドユーザーの情報が最後に更新された時間。時間は Unix エポック（1970-01-01T00:00:00Z）からのミリ秒数で表されます。	いいえ

その他の 標準クレーム には、family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo、および locale が含まれ、ユーザー情報エンドポイントを要求することなく profile スコープに含まれます。上記のクレームと比較しての違いは、これらのクレームは値が空でない場合にのみ返されることであり、上記のクレームは値が空の場合に null を返します。

注記:

標準クレームとは異なり、created_at と updated_at クレームは秒ではなくミリ秒を使用しています。

email

クレーム名	タイプ	説明	ユーザー情報が必要か？
email	string	ユーザーのメールアドレス	いいえ
email_verified	boolean	メールアドレスが確認済みかどうか	いいえ

phone

クレーム名	タイプ	説明	ユーザー情報が必要か？
phone_number	string	ユーザーの電話番号	いいえ
phone_number_verified	boolean	電話番号が確認済みかどうか	いいえ

address

住所クレームの詳細については、OpenID Connect Core 1.0 を参照してください。

custom_data

クレーム名	タイプ	説明	ユーザー情報が必要か？
custom_data	object	ユーザーのカスタムデータ	はい

identities

クレーム名	タイプ	説明	ユーザー情報が必要か？
identities	object	ユーザーのリンクされたアイデンティティ	はい
sso_identities	array	ユーザーのリンクされた SSO アイデンティティ	はい

roles

クレーム名	タイプ	説明	ユーザー情報が必要か？
roles	string[]	ユーザーのロール	いいえ

urn:logto:scope:organizations

クレーム名	タイプ	説明	ユーザー情報が必要か？
organizations	string[]	ユーザーが所属する組織の ID	いいえ
organization_data	object[]	ユーザーが所属する組織のデータ	はい

urn:logto:scope:organization_roles

クレーム名	タイプ	説明	ユーザー情報が必要か？
organization_roles	string[]	ユーザーが所属する組織のロール（<organization_id>:<role_name> の形式）	いいえ

---

パフォーマンスとデータサイズを考慮して、「ユーザー情報が必要か？」が「はい」の場合、クレームは ID トークンには表示されず、ユーザー情報エンドポイント のレスポンスで返されます。

API リソースと組織

まず 🔐 ロールベースのアクセス制御 (RBAC) を読むことをお勧めします。これにより、Logto の RBAC の基本概念と API リソースを適切に設定する方法を理解できます。

Logto クライアントの設定

API リソースを設定したら、アプリで Logto を設定する際にそれらを追加できます：

client.py

client = LogtoClient(
    LogtoConfig(
        # ...other configs
        resources=["https://shopping.your-app.com/api", "https://store.your-app.com/api"], # API リソースを追加
    ),
)

各 API リソースには独自の権限 (スコープ) があります。

例えば、https://shopping.your-app.com/api リソースには shopping:read と shopping:write の権限があり、https://store.your-app.com/api リソースには store:read と store:write の権限があります。

これらの権限を要求するには、アプリで Logto を設定する際にそれらを追加できます：

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"],
    ),
)

スコープが API リソースとは別に定義されていることに気付くかもしれません。これは、OAuth 2.0 のリソースインジケーター が、リクエストの最終的なスコープはすべてのターゲットサービスでのすべてのスコープの直積になると指定しているためです。

したがって、上記のケースでは、Logto での定義からスコープを簡略化できます。両方の API リソースは、プレフィックスなしで read と write スコープを持つことができます。その後、Logto の設定では：

client.py

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

各 API リソースは、read と write の両方のスコープを要求します。

注記:

API リソースで定義されていないスコープを要求しても問題ありません。例えば、API リソースに email スコープが利用できなくても、email スコープを要求できます。利用できないスコープは安全に無視されます。

サインインが成功すると、Logto はユーザーのロールに応じて適切なスコープを API リソースに発行します。

API リソースのアクセス トークンの取得

特定の API リソースのアクセス トークンを取得するには、GetAccessToken メソッドを使用できます：

flask.py

accessToken = await client.getAccessToken("https://shopping.your-app.com/api")
# または
claims = await client.getAccessTokenClaims("https://shopping.your-app.com/api")

このメソッドは、ユーザーが関連する権限を持っている場合に API リソースにアクセスするために使用できる JWT アクセス トークンを返します。現在キャッシュされているアクセス トークンが期限切れの場合、このメソッドは自動的にリフレッシュ トークンを使用して新しいアクセス トークンを取得しようとします。

組織トークンの取得

組織 (Organization) が初めての場合は、🏢 組織 (マルチテナンシー) を読んで始めてください。

Logto クライアントを設定する際に、core.UserScopeOrganizations スコープを追加する必要があります：

client.py

from logto import LogtoClient, LogtoConfig, UserInfoScope

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

ユーザーがサインインしたら、ユーザーのための組織トークンを取得できます：

flask.py

# パラメーターを有効な組織 ID に置き換えます。
# ユーザーの有効な組織 ID は、ID トークンのクレーム `organizations` にあります。
organizationToken = await client.getOrganizationToken(organization_id)
# または
organizationTokenClaims = await client.getOrganizationTokenClaims(organization_id)

さらなる読み物

エンドユーザーフロー：認証 (Authentication) フロー、アカウントフロー、組織フロー コネクターを設定する あなたの API を保護する