ネイティブ認証を使用して Android アプリにサインインを追加する - Microsoft Entra External ID

[アーティクル]
08/08/2024

このチュートリアルでは、Android モバイルアプリでネイティブ認証を使用し、メールのワンタイムパスコードまたはユーザー名とパスワードを使ってユーザーのサインインとサインアウトを行う方法でについて説明します。

このチュートリアルでは、次の作業を行う方法について説明します。

メールのワンタイムパスコードまたはユーザー名 (メールアドレス) とパスワードを使ってユーザーのサインインを行います。
ユーザーのサインアウト。
サインインエラーを処理する

前提条件

チュートリアル: ネイティブ認証用に Android アプリを準備するに関する記事の手順を完了します。このチュートリアルでは、ネイティブ認証用に Android プロジェクトまたはアプリを準備する方法について説明します。

ワンタイムパスコードを使用してユーザーのサインインを行うには、メールアドレスを収集し、ユーザーが自身のメールアドレスを検証できるようにワンタイムパスコードを含むメールを送信します。有効なワンタイムパスコードを入力すると、アプリはユーザーをサインインさせます。

ユーザー名 (メールアドレス) とパスワードを使用してユーザーのサインインを行うには、ユーザーからメールアドレスとパスワードを収集します。ユーザー名とパスワードが有効な場合、アプリによってユーザーのサインインが行われます。

ユーザーのサインインを行うには、次の操作を行う必要があります。

以下にユーザーインターフェイス (UI) を作成します。
- ユーザーからメールアドレスを収集します。入力に検証を追加して、ユーザーが有効なメールアドレスを入力していることを確認します。
- ユーザー名 (メールアドレス) とパスワードを使ってサインインを行う場合は、パスワードを収集します。
- 電子メールワンタイムパスコードでサインインする場合は、ユーザーから電子メールのワンタイムパスコードを収集します。
- 電子メールのワンタイムパスコードでサインインする場合は、ワンタイムパスコードを再送信します (推奨)。
UI で、次のコードスニペットに示すように select イベントによってサインインを開始するボタンを追加します。
```
 CoroutineScope(Dispatchers.Main).launch {
     val actionResult = authClient.signIn(
         username = emailAddress
         //password = password, Pass 'password' param if you sign in with username (email) and password
     )
     if (actionResult is SignInResult.CodeRequired) {
         val nextState = actionResult.nextState
         val submitCodeActionResult = nextState.submitCode(
             code = code
         )
         if (submitCodeActionResult is SignInResult.Complete){
             // Handle sign in success
             val accountState = submitCodeActionResult.resultValue
             val accessTokenResult = accountState.getAccessToken()
             if (accessTokenResult is GetAccessTokenResult.Complete) {
                 val accessToken = accessTokenResult.resultValue.accessToken
                 val idToken = accountState.getIdToken()
             }
         }
     }
 }
```
例えば、ユーザーが電子メールとパスワードでサインインするなど、ユーザーがパスコードを送信する必要がない場合は以下のコードスニペットを使用します。
```
    CoroutineScope(Dispatchers.Main).launch {
        val actionResult = authClient.signIn(
            username = emailAddress,
            password = password
        )
        if (actionResult is SignInResult.Complete) -> {
            // Handle sign in success
            val accountState = actionResult.resultValue
            val accessTokenResult = accountState.getAccessToken()
            if (accessTokenResult is GetAccessTokenResult.Complete) {
                    val accessToken = accessTokenResult.resultValue.accessToken
                    val idToken = accountState.getIdToken()
                }
        }
    }
```
- サインインフローを開始するには、SDK の signIn(username) または signIn(username, password) メソッドを使用します。
- メソッドのパラメータである username は、ユーザーから収集したメールアドレスです。
- サインイン方法がユーザー名 (メールアドレス) とパスワードである場合、メソッドのパラメーター password はユーザーから収集したパスワードです。
- 最も一般的なシナリオでは、signIn(username) または signIn(username, password) によって結果 SignInResult.CodeRequired が返されます。これは、ユーザーのメールアドレスに送信されたメールのワンタイムパスコードをアプリから送信することを SDK で想定していることを示します。
- SignInResult.CodeRequired オブジェクトには新しい状態参照が含まれており、actionResult.nextState を通じて取得できます。
- 新しい状態により、次の 2 つの新しいメソッドにアクセスできるようになります。
  - submitCode() では、アプリによってユーザーから収集するメールのワンタイムパスコードを送信します。
  - resendCode() では、ユーザーがコードを受信しなかった場合にメールのワンタイムパスコードを再送信します。

サインイン中、すべてのアクションが成功するわけではありません。たとえば、ユーザーが存在しないメールアドレスでサインインしようとしたり、無効なコードを送信したりすることがあります。

signIn(username) または signIn(username, password) メソッドでエラーを処理するには、次のコードスニペットを使用します。

val actionResult = authClient.sign(
    username = emailAddress
    //password = password, Pass 'password' param if you sign in with username (email) and password
)
if (actionResult is SignInResult.CodeRequired) {
    // Next step: submit code
} else if (actionResult is SignInError) {
    // Handle sign in errors
    when {
         actionResult.isUserNotFound() -> {
             // Handle "user not found" error
         }
         actionResult.isAuthNotSupported() -> {
         // Handle "authentication type not support" error
         }
         actionResult.isInvalidCredentials() -> {
             // Handle specific errors
         }
         else -> {
             // Handle other errors
         }
     }
}

SignInError は、signIn() によって返された失敗したアクション結果を示します。そのため、アクション結果には新しい状態への参照が含まれません。
actionResult is SignUpError の場合、Android SDK には、特定のエラーをさらに分析できるようにするユーティリティメソッドが用意されています。
- メソッド isUserNotFound() では、存在しないユーザー名 (メールアドレス) を使用してユーザーがサインインしているかどうかを確認します。
- メソッド isBrowserRequired() では、認証フローを完了するためにブラウザー (Web フォールバック) が必要であるかどうかを確認します。このシナリオは、認証フローを完了するのにネイティブ認証だけでは十分ではない場合に発生します。たとえば、管理者は認証方法としてメールアドレスとパスワードを構成しても、アプリが password をチャレンジ型として送信できないか、単にそれをサポートしていない場合などです。これが発生するシナリオを処理するには、Android アプリでの Web フォールバックのサポートに関する記事の手順を使用します。
- メソッド isAuthNotSupported() は、Microsoft Entra でサポートされていないチャレンジ型 (oob および password 以外のチャレンジ型の値) をアプリで送信しているかどうかを確認します。チャレンジ型の詳細を参照してください。
- ユーザー名 (メールアドレス) とパスワードのサインインの場合、メソッド isInvalidCredentials() を使ってユーザー名とパスワードの組み合わせが間違っているかどうかを確認します。

送信コードエラーを処理する

submitCode() メソッドでエラーを処理するには、次のコードスニペットを使用します:

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignInResult.Complete) {
    // Sign in flow complete, handle success state.
} else if (submitCodeActionResult is SubmitCodeError && submitCodeActionResult.isInvalidCode()) {
    // Handle "invalid code" error
}

SubmitCodeError エラーは、submitCode() によって返されたアクションが失敗した結果を示します。そのため、アクションの結果には新しい状態への参照は含まれません。
isInvalidCode() では特定のエラーがチェックされます。この場合、アクションを再実行するには、前の状態参照を使用する必要があります。

新しいメールのワンタイムパスコードを取得するには、以下のコードスニペットを使用します。

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignInError && submitCodeActionResult.isInvalidCode) {
    // Inform the user that the submitted code was incorrect or invalid, then ask them to input a new email one-time passcode
    val newCode = retrieveNewCode()
    nextState.submitCode(
        code = newCode
    )
}

アプリでユーザーを正常にサインアップさせるために必要なすべての手順を完了しました。アプリケーションをビルドして実行します。問題がなければ、メールアドレスを指定し、コードをメールで受け取り、それを使用してユーザーのサインインを完了することができます。

ID トークン要求を読み取る

アプリが ID トークンを獲得したら、現在のアカウントに関連付けられている要求を取得できます。これを行うには、次のコードスニペットを使用します。

val preferredUsername = accountState.getClaims()?.get("preferred_username")
val city = accountState.getClaims()?.get("City")
val givenName = accountState.getClaims()?.get("given_name")
//custom attribute
val loyaltyNumber = accountState.getClaims()?.get("loyaltyNumber")

要求値へのアクセスに使用するキーは、ユーザー属性をトークン要求として追加するときに指定する名前です。

組み込みおよびカスタム属性をトークン要求として追加する方法については、「トークン要求にユーザー属性を追加する」記事を参照してください。

ユーザーのサインアウト

ユーザーをサインアウトさせるには、キャッシュに現在保存されているアカウントを削除する必要があります。

以下を含むカスタムユーザーインターフェイス (UI) を作成します。
- サインアウト要求を送信するためにユーザーが選択するサインアウトボタン。

ユーザーをサインアウトさせるには、次のコードを使用します。

private fun performSignOut(accountState: AccountState) {
     CoroutineScope(Dispatchers.Main).launch {
        val accountResult = authClient.getCurrentAccount()
         if (accountResult is GetAccountResult.AccountFound) {
             val signOutResult = accountResult.resultValue.signOut()
             if (signOutResult is SignOutResult.Complete) {
                 // Show sign out successful UI
             }
         }
     }
 }

サインアウトエラーを処理する

サインアウトでエラーが発生しないようにする必要があります。エラーが発生した場合は、次のコードスニペットを使用してエラー結果を検査します。

val actionResult = accountResult.signOut()
if (actionResult is SignOutResult.Complete) {
    // Show sign out successful UI
} else {
    // Handle errors
}

必ず import ステートメントを含めます。 Android Studio では、自動的に import ステートメントが含められます。

アプリでユーザーを正常にサインアウトさせるために必要なすべての手順を完了しました。アプリケーションをビルドして実行します。問題がなければ、サインアウトボタンを選択して正常にサインアウトできます。

カスタムクレームプロバイダーの構成

外部システムからのクレームをアプリに発行されるトークンに追加する場合は、カスタムクレームプロバイダーを使用します。カスタムクレームプロバイダーは、外部システムからクレームを取り込むために、外部 REST API を呼び出すカスタム認証拡張機能で構成されています。

カスタムクレームプロバイダーの構成の手順に従って、外部システムからのクレームをセキュリティトークンに追加します。

次の方法で共有

前提条件

送信コードエラーを処理する

ID トークン要求を読み取る

ユーザーのサインアウト

サインアウトエラーを処理する

カスタムクレームプロバイダーの構成

フィードバック

その他のリソース

次の方法で共有

チュートリアル: ネイティブ認証を使用して Android アプリにサインインを追加する

前提条件

ユーザーのサインイン

サインイン エラーを処理する

サインインの開始エラーを処理する

送信コード エラーを処理する

ID トークン要求を読み取る

ユーザーのサインアウト

サインアウト エラーを処理する

カスタム クレーム プロバイダーの構成

関連するコンテンツ

フィードバック

その他のリソース

サインインエラーを処理する

送信コードエラーを処理する

サインアウトエラーを処理する

カスタムクレームプロバイダーの構成