メインコンテンツまでスキップ

あなたの Android (Kotlin/Java) アプリケーションに認証 (Authentication) を追加する

このガイドでは、Logto をあなたの Android アプリケーションに統合する方法を示します。

ヒント:

前提条件​

  • Logto Cloud アカウントまたは セルフホスト Logto。
  • 作成された Logto ネイティブアプリケーション。
  • Kotlin Android アプリケーションプロジェクト。

インストール​

注記:

Logto Android SDK のサポートされている最小 Android API レベルはレベル 24 です。

Logto Android SDK には 2 つのメジャーバージョンがあります：

  • v2：埋め込み WebView でサインインエクスペリエンスを開きます。ネイティブソーシャルコネクターに必要ですが、パスキーサインインをサポートしていません（WebView はパスキーの基礎となる標準である WebAuthn をサポートしていません）。
  • v3 (beta)：Chrome Custom Tabs（システムブラウザ）でサインインエクスペリエンスを開き、パスキーサインインが可能になり、ブラウザセッションを共有します。v3 は WeChat (Native) および Alipay (Native) コネクターのサポートを削除します。代わりに、ブラウザを通じて動作する WeChat (Web) および Alipay (Web) を使用できます。ネイティブコネクターに依存している場合は、v2 のままにしてください。

このガイドでは両方のバージョンを説明します。以下のタブでバージョンを選択すると、選択がこのガイド全体で同期されます。

Logto Android SDK をインストールする前に、Gradle プロジェクトのビルドファイルで mavenCentral() がリポジトリ設定に追加されていることを確認してください：

settings.gradle.kts
dependencyResolutionManagement {
  repositories {
    mavenCentral()
  }
}

Logto Android SDK を依存関係に追加します：

build.gradle.kts
dependencies {
  implementation("io.logto.sdk:android:2.0.3")
}

SDK はインターネットアクセスが必要なため、次の権限を AndroidManifest.xml ファイルに追加する必要があります：

AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:tools="http://schemas.android.com/tools">

  <!-- インターネット権限を追加 -->
  <uses-permission android:name="android.permission.INTERNET" />

  <!-- その他の設定... -->
</manifest>

統合​

LogtoClient の初期化​

LogtoViewModel.kt を作成し、このビューモデルで LogtoClient を初期化します：

LogtoViewModel.kt
//...他のインポート
import io.logto.sdk.android.LogtoClient
import io.logto.sdk.android.type.LogtoConfig

class LogtoViewModel(application: Application) : AndroidViewModel(application) {
    private val logtoConfig = LogtoConfig(
          endpoint = "<your-logto-endpoint>",
          appId = "<your-app-id>",
          scopes = null,
          resources = null,
          usingPersistStorage = true,
    )

    private val logtoClient = LogtoClient(logtoConfig, application)

    companion object {
        val Factory: ViewModelProvider.Factory = object : ViewModelProvider.Factory {
            @Suppress("UNCHECKED_CAST")
            override fun <T : ViewModel> create(
                modelClass: Class<T>,
                extras: CreationExtras
            ): T {
                // extras から Application オブジェクトを取得
                val application = checkNotNull(extras[APPLICATION_KEY])
                return LogtoViewModel(application) as T
            }
        }
    }
}

次に、MainActivity.kt のために LogtoViewModel を作成します：

MainActivity.kt
//...他のインポート
class MainActivity : AppCompatActivity() {
    private val logtoViewModel: LogtoViewModel by viewModels { LogtoViewModel.Factory }
    //...他のコード
}

リダイレクト URI の設定​

詳細に入る前に、エンドユーザー体験の概要を簡単にご紹介します。サインインプロセスは次のようにシンプルにまとめられます：

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

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

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

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


Logto コンソールのアプリケーション詳細ページに切り替えましょう。リダイレクト URI io.logto.android://io.logto.sample/callback を追加し、「変更を保存」をクリックします。

Logto コンソールのリダイレクト URI

Android では、リダイレクト URI は次のパターンに従います：$(LOGTO_REDIRECT_SCHEME)://$(YOUR_APP_PACKAGE)/callback：

  • LOGTO_REDIRECT_SCHEME は逆ドメイン形式のカスタムスキームである必要があります。
  • YOUR_APP_PACKAGE はあなたのアプリのパッケージ名です。

io.logto.android をカスタム LOGTO_REDIRECT_SCHEME とし、io.logto.sample をあなたのアプリのパッケージ名と仮定すると、リダイレクト URI は io.logto.android://io.logto.sample/callback になります。

追加の設定は不要です。サインインエクスペリエンスは埋め込み WebView で開き、SDK は WebView 内でリダイレクトをインターセプトします。

サインインとサインアウトの実装​

注記:

logtoClient.signIn を呼び出す前に、Admin Console でリダイレクト URI が正しく設定されていることを確認してください。 :::

logtoClient.signIn を使用してユーザーをサインインし、logtoClient.signOut を使用してユーザーをサインアウトできます。

例えば、Android アプリでは次のようにします：

LogtoModelView.kt
//...他のインポートと共に
class LogtoViewModel(application: Application) : AndroidViewModel(application) {
    // ...他のコード

    // 認証 (Authentication) 状態を監視するライブデータを追加
    private val _authenticated = MutableLiveData(logtoClient.isAuthenticated)
    val authenticated: LiveData<Boolean>
        get() = _authenticated

    fun signIn(context: Activity) {
        logtoClient.signIn(context, "io.logto.android://io.logto.sample/callback") { logtoException ->
            logtoException?.let { println(it) }
            // ライブデータを更新
            _authenticated.postValue(logtoClient.isAuthenticated)
        }
    }

    fun signOut() {
        logtoClient.signOut { logtoException ->
            logtoException?.let { println(it) }
            // ライブデータを更新
            _authenticated.postValue(logtoClient.isAuthenticated)
        }
    }
}

次に、アクティビティ内で signIn と signOut メソッドを呼び出します：

MainActivity.kt
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        //...他のコード

        // レイアウトに id "sign_in_button" を持つボタンがあると仮定
        val signInButton = findViewById<Button>(R.id.sign_in_button)
        signInButton.setOnClickListener {
            logtoViewModel.signIn(this)
        }

        // レイアウトに id "sign_out_button" を持つボタンがあると仮定
        val signOutButton = findViewById<Button>(R.id.sign_out_button)
        signOutButton.setOnClickListener {
            if (logtoViewModel.authenticated) { // ユーザーが認証 (Authentication) されているか確認
                logtoViewModel.signOut()
            }
        }

        // 認証 (Authentication) 状態を監視して UI を更新
        logtoViewModel.authenticated.observe(this) { authenticated ->
            if (authenticated) {
                // ユーザーは認証 (Authentication) されています
                signInButton.visibility = View.GONE
                signOutButton.visibility = View.VISIBLE
            } else {
                // ユーザーは認証 (Authentication) されていません
                signInButton.visibility = View.VISIBLE
                signOutButton.visibility = View.GONE
            }
        }

    }
}

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

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

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

ユーザー情報の取得​

ユーザー情報の表示​

ユーザーの情報を表示するには、logtoClient.getIdTokenClaims() メソッドを使用できます。例えば、ViewModel でユーザー情報を取得し、それをアクティビティで表示することができます：

LogtoModelView.kt
class LogtoViewModel(application: Application) : AndroidViewModel(application) {
    // ...他のコード

    // ID トークンクレームを監視するライブデータを追加
    private val _idTokenClaims = MutableLiveData<IdTokenClaims>()
    val idTokenClaims: LiveData<IdTokenClaims>
        get() = _idTokenClaims

    fun getIdTokenClaims() {
        logtoClient.getIdTokenClaims { logtoException, idTokenClaims ->
            logtoException?.let { _logtoException.postValue(it) } ?: _idTokenClaims.postValue(idTokenClaims)
        }
    }
}
MainActivity.kt
//...他のインポートと共に
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        //...他のコード

        // レイアウトに `user_info_text_view` という ID のテキストビューがあると仮定
        val userInfoResponseTextView: TextView = findViewById(R.id.user_info_text_view)
        logtoViewModel.userInfoResponse.observe(this) { userInfoResponse ->
            userInfoResponseTextView.text = if (userInfoResponse !== null) {
                val json = Gson().toJson(userInfoResponse, UserInfoResponse::class.java)
                JSONObject(json).toString(2)
            } else {
                ""
            }
        }
    }
}

追加のクレームをリクエストする​

logtoClient.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 オブジェクトに渡すことができます。例えば：

LogtoViewModel.kt
private val logtoConfig = LogtoConfig(
    // ...他の設定
    scopes = listOf("email", "phone"), // または `listOf(UserScope.EMAIL, UserScope.PHONE)`
)

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

logtoClient.getIdTokenClaims { logtoException, idTokenClaims ->
    println("IdTokenClaims:$idTokenClaims")
}
// これで追加のクレーム `claims.email`、`claims.phone` などにアクセスできます。

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

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

LogtoViewModel.kt
logtoClient.fetchUserInfo {_, userInfoResponse ->
  println("UserInfoResponse:$userInfoResponse")
}
// これでクレーム `userInfo.custom_data` にアクセスできます。
このメソッドは、userinfo エンドポイントにリクエストを送信してユーザー情報を取得します。利用可能なスコープとクレームについて詳しくは、スコープとクレームのセクションを参照してください。

スコープとクレーム​

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

標準の OIDC クレーム (Claim) については、ID トークンへの含有はリクエストされたスコープ (Scope) によって厳密に決定されます。拡張クレーム (Claim)（例：custom_data や organizations）は、カスタム ID トークン 設定を通じて ID トークンに追加で表示するように構成できます。

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

標準 OIDC スコープ​

openid（デフォルト）

Claim nameType説明
substringユーザーの一意の識別子

profile（デフォルト）

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

その他の 標準クレーム (Standard Claims) には、family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo、locale などがあり、これらも profile スコープに含まれます（userinfo エンドポイントをリクエストする必要はありません）。上記のクレームとの違いは、これらのクレームは値が空でない場合のみ返される点です。一方、上記のクレームは値が空の場合 null が返されます。

注記:

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

email

Claim nameType説明
emailstringユーザーのメールアドレス
email_verifiedbooleanメールアドレスが認証済みかどうか

phone

Claim nameType説明
phone_numberstringユーザーの電話番号
phone_number_verifiedboolean電話番号が認証済みかどうか

address

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

備考:

（デフォルト） と記載されたスコープは常に Logto SDK によってリクエストされます。標準 OIDC スコープ下のクレーム (Claims) は、対応するスコープがリクエストされた場合、常に ID トークン (ID token) に含まれます — 無効化できません。

拡張スコープ​

以下のスコープは Logto によって拡張されており、userinfo エンドポイント を通じてクレーム (Claims) を返します。これらのクレームは Console > Custom JWT を通じて ID トークン (ID token) に直接含めるよう設定することもできます。詳細は カスタム ID トークン を参照してください。

custom_data

Claim nameType説明デフォルトで ID トークンに含まれるか
custom_dataobjectユーザーのカスタムデータ

identities

Claim nameType説明デフォルトで ID トークンに含まれるか
identitiesobjectユーザーのリンク済みアイデンティティ
sso_identitiesarrayユーザーのリンク済み SSO アイデンティティ

roles

Claim nameType説明デフォルトで ID トークンに含まれるか
rolesstring[]ユーザーのロール✅

urn:logto:scope:organizations

Claim nameType説明デフォルトで ID トークンに含まれるか
organizationsstring[]ユーザーが所属する組織 ID✅
organization_dataobject[]ユーザーが所属する組織データ
注記:

これらの組織クレーム (Organization Claims) は、不透明トークン (Opaque token) を使用している場合でも userinfo エンドポイント経由で取得できます。ただし、不透明トークン (Opaque token) は組織トークン (Organization token) として組織固有リソースへのアクセスには使用できません。詳細は 不透明トークン (Opaque token) と組織 (Organizations) を参照してください。

urn:logto:scope:organization_roles

Claim nameType説明デフォルトで ID トークンに含まれるか
organization_rolesstring[]ユーザーが所属する組織ロール（<organization_id>:<role_name> 形式）✅

API リソースと組織​

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

Logto クライアントの設定​

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

LogtoViewModel.kt
val logtoConfig = LogtoConfig(
    //...other configs
    resources = listOf("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 を設定する際にそれらを追加できます：

LogtoViewModel.kt
val logtoConfig = LogtoConfig(
    // ..other configs
    scopes = listOf("shopping:read", "shopping:write", "store:read", "store:write"),
    resources = listOf("https://shopping.your-app.com/api", "https://store.your-app.com/api"),
)

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

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

LogtoViewModel.kt
val logtoConfig = LogtoConfig(
    // ...other configs
    scopes = listOf("read", "write"),
    resources = listOf("https://shopping.your-app.com/api", "https://store.your-app.com/api"),
)

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

注記:

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

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

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

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

LogtoViewModel.kt
logtoClient.getAccessToken("https://shopping.your-app.com/api") { logtoException, accessToken ->
    logtoException?.let { println(it) }
    accessToken?.let { println(it) }
}

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

組織トークンの取得​

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

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

LogtoViewModel.kt
val logtoConfig = LogtoConfig(
    // ...other configs
    scopes = listOf(UserScope.Organizations),
)

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

LogtoViewModel.kt
// パラメーターを有効な組織 ID に置き換えます。
// ユーザーに対する有効な組織 ID は、ID トークンのクレーム `organizations` にあります。
logtoClient.getOrganizationToken("organization-id") { logtoException, organizationToken ->
    logtoException?.let { println(it) }
    organizationToken?.let { println(it) }
}

// または
logtoClient.getOrganizationTokenClaims("organization-id") { logtoException, claims ->
    logtoException?.let { println(it) }
    claims?.let { println(it) }
}

組織 API リソース​

組織内の API リソースのアクセス トークンを取得するには、getAccessToken メソッドを使用し、API リソースと組織 ID の両方をパラメーターとして渡すことができます：

LogtoViewModel.kt
logtoClient.getAccessToken(
  'https://shopping.your-app.com/api',
  organizationId
) { logtoException, accessToken ->
    println("AccessToken:$accessToken")
}

さらなる読み物​

エンドユーザーフロー：認証 (Authentication) フロー、アカウントフロー、組織フロー コネクターの設定 認可 (Authorization)