モバイルアプリ向けネイティブパスキー

パスキーは、従来の認証手段 (ユーザー名とパスワードなど) に代わる、フィッシングに強い認証方式です。より簡単で安全なユーザー体験を提供し、FIDO® W3C Web Authentication (WebAuthn) および Client to Authenticator Protocol (CTAP) の仕様に基づいています。 Auth0 は現在、データベース接続の認証方法としてパスキーをサポートしており、次の 2 つの実装方法を提供しています。

Web ベースのアプリケーション向けのUniversal Login passkeys
Android および iOS アプリケーション向けのネイティブパスキー。
Web ベースおよびネイティブアプリケーション向けのEmbedded Login

仕組み

ネイティブパスキーでは、Auth0 Authentication API と iOS または Android のネイティブ API を組み合わせて使用し、チャレンジフローをモバイルアプリケーションに直接組み込みます。これにより、認証完了のためにユーザーをブラウザにリダイレクトしなくても、アプリケーションに統合されたサインアップおよびログイン体験を実現できます。以下の例は、新規ユーザーがパスキーのサインアップフローでどのような体験をする可能性があるかを示しています。

新規ユーザーがモバイルアプリケーションを起動し、ログイン画面を開きます。新規ユーザーのため、Sign Up ボタンを選択します。
次の画面で、ユーザーはメールアドレスを入力し、Create Account を選択します。
次に、ユーザーはアプリケーション用のパスキーを作成するかどうか確認されます。続行するには、Continue を選択します。
パスキーを生成するには、ユーザーは生体認証や PIN の入力などの認証方法を使って、デバイス上でローカル認証を行う必要があります。
ローカル認証が完了すると、新しいパスキーがユーザーのデバイスに保存され、iCloud や Google などのパスキープロバイダーと同期されます。
パスキーが保存されると、ユーザーは新規ユーザー登録プロセスを続け、アカウント作成を完了します。

このプロセスが完了すると、ユーザーは次回アプリケーションにログインするときに、保存したパスキーを使って認証できます。

始める前に

カスタムドメインを設定する

ネイティブパスキーを使用するには、が必要です。続行する前に、テナントにカスタムドメインが設定されていることを確認してください。詳細については、Custom Domainsを参照してください。

パスキーポリシーを設定する

Android または iOS アプリケーションでネイティブパスキーを実装する前に、Auth0 テナントでパスキーポリシーを設定する必要があります。テナントを準備するには、パスキーポリシーを設定するの手順に従ってください。

アプリケーションを準備する

アプリケーションでネイティブパスキーを利用できるようにするには、Device Settings を構成し、Passkey グラントを追加する必要があります。これらの設定は、またはで行えます。

Auth0 Dashboard を設定する

Applications > Applications に移動し、更新するアプリケーションを選択します。
Settings タブの下部にある Advanced Settings を選択し、次に Device Settings タブを選択します。
アプリケーションに応じて iOS と Android の各セクションを設定し、Save Changes をクリックします。
Advanced Settings セクションで、Grant Types タブを選択します。
Passkey グラントを有効にし、Save Changes を選択します。

Management API

Update a Client エンドポイントを呼び出し、次の操作を行います。

grant_types を更新し、urn:okta:params:oauth:grant-type:webauthn を含めます。
必要に応じて、mobile オブジェクトを使用して iOS および Android デバイスの設定を指定します。

パスキーフローを実装する

アプリケーションでは、次のパスキーフローを定義できます。

サインアップフロー: ユーザー登録時に、新規ユーザーがパスキーを生成して保存できるようにします。
ログインフロー: すでにパスキーを登録済みの既存ユーザーが、ログイン時に保存済みのパスキーで認証できるようにします。

ユーザーが初めてアプリケーションへのログインを試みると、パスキーのサインアップフローが開始されます。ユーザーが既存の識別子を入力した場合は、代わりにログインフローを完了するよう案内することをおすすめします。そうしないと、その操作は失敗します。

フローの手順

ユーザーがアプリケーションにアクセスし、新しいアカウントの登録を選択します。ユーザーは、メールアドレスなど、アプリケーションで求められた識別子を入力します。
次に、アプリケーションは Auth0 Authentication API の Request Signup Challenge エンドポイントを呼び出して、サインアップチャレンジを開始します。

realm を指定しない場合は、テナントのデフォルトディレクトリが使用されます。
デフォルトでは、必須の識別子はメールアドレスです。データベース接続で Flexible Identifiers を有効にしている場合は、代わりに email、phone_number、username の組み合わせを使用できます。これらのオプションは必須にも任意にも設定でき、Flexible Identifier の設定と一致している必要があります。

   POST /passkey/register
   Content-Type: application/json

   {
     "client_id": "{YOUR_CLIENT_ID}",
     "realm": "{OPTIONAL_CONNECTION}",
     "user_profile": {
   	  "email": "{VALID_EMAIL_ADDRESS}",
   	  "name": "{OPTIONAL_USER_DISPLAY_NAME}",
     }
   }

これに対して、Auth0 は PublicKeyCredentialCreationOptions を、auth_session ID および rp.id としての rpId とともに返します。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "authn_params_public_key": {
    "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
    "timeout": {MILLISECONDS},
    "rp": {
      "id": "{YOUR_CUSTOM_DOMAIN}",
      "name": "{YOUR_CUSTOM_DOMAIN}"
    },
    "pubKeyCredParams": [
      { type: 'public-key', alg: -8 },
      { type: 'public-key', alg: -7 },
      { type: 'public-key', alg: -257 }
    ],
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "preferred"
    },
    "user": {
      "id": "{GENERATED_ID}",
      "name": "{USER-ENTERED_IDENTIFIER}",
      "displayName": "{USER-ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING}"
    }
  },
  "auth_session": "{SESSION_ID}"
 }

レスポンスで返される rpId は、関連ドメインでパスキーを機能させるために Web フローで使用されるドメインと一致します。

次に、アプリケーションは適切なネイティブ API を使用して、ユーザー登録プロセスを完了します。
- Android の登録に関するドキュメントを確認してください。
- iOS の登録に関するドキュメントを確認してください。

次に、アプリケーションは登録プロセスで取得した認証情報 (authn_response の詳細を含む) を使用して、Token エンドポイントを呼び出します。

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "{YOUR_CLIENT_ID}",
  "realm": "{OPTIONAL_CONNECTION}",
  "scope": "{OPTIONAL_REQUESTED_SCOPE}",
  "audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
  "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
  "authn_response": {
    "id": "{BASE64URL_ID}",
    "rawId": "{BASE64URL_RAWID}",
    "type": "public-key",
    "authenticatorAttachment": "platform|cross-platform",
    "response": {
      "clientDataJSON": "{BASE64URL_CLIENT_DATA_JSON}",
      "attestationObject": "{BASE64URL_ATTESTATION_OBJECT}",
      {OTHER_PROPERTIES}
    },
  },
}

Auth0 は新しいユーザーアカウントを作成し、要求されたトークンを返してフローを完了します。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "{BASE64_TOKEN}",
  "refresh_token": "{BASE64_TOKEN}",
  "id_token": "{BASE64_TOKEN}",
  "token_type": "Bearer",
  "expires_in": {SECONDS}
}

既存ユーザーがアプリケーションへのログインを試みると、パスキーによるログインフローが開始されます。このフローは、初回登録時にアカウントにパスキーを保存した既存ユーザーにのみ適用されます。

フローの手順

ユーザーがアプリケーションを起動してログインを開始すると、アプリケーションは Authentication API の Request Login Challenge エンドポイントを呼び出して、ログインチャレンジを開始します。
realm を指定しない場合は、テナントのデフォルトディレクトリが使用されます。
```
POST /passkey/challenge
Content-Type: application/json

{
  "client_id": "{YOUR_CLIENT_ID}",
  "realm": "{OPTIONAL_CONNECTION}"
}
```

これに対し、Auth0 は PublicKeyCredentialRequestOptions と、アプリケーション内でフローを継続するための auth_session を返します。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "authn_params_public_key": {
    "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
    "timeout": {AUTH_TIMEOUT_IN_MILLISECONDS},
    "rpId": "{CUSTOM_DOMAIN}",
    "userVerification": "preferred"
  },
  "auth_session": "{SESSION_ID}"
}

次に、アプリケーションは適切なネイティブ API を使用してログイン処理を完了します。
- Android のログインに関するドキュメントを参照してください。
- iOS のログインに関するドキュメントを参照してください。

次に、アプリケーションはログイン処理で取得した認証情報 (authn_response の詳細を含む) を使用して、Token エンドポイントを呼び出します。

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "{YOUR_CLIENT_ID}",
  "realm": "{OPTIONAL_CONNECTION}",
  "scope": "{OPTIONAL_REQUESTED_SCOPE}",
  "audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
  "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
  "authn_response": {
    "id": "{BASE64URL_ID}",
    "rawId": "{BASE64URL_RAWID}",
    "type": "public-key",
    "authenticatorAttachment": "platform|cross-platform",
    "response": {
      "authenticatorData": "{BASE64URL_AUTHENTICATORDATA}",
      "clientDataJSON": "{BASE64URL_CLIENTDATAJSON}",
      "signature": "{BASE64URL_SIGNATURE}",
      "userHandle": "{BASE64URL_USERHANDLE}"
    },
    "clientExtensionResults": {OPTIONAL_OBJECT}
   }
}

Auth0 は認証情報を検証し、要求されたトークンを返してフローを完了します。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "{BASE64_TOKEN}",
  "refresh_token": "{BASE64_TOKEN}",
  "id_token": "{BASE64_TOKEN}",
  "token_type": "Bearer",
  "expires_in": {SECONDS}
}

参考資料

モバイルアプリケーションにネイティブパスキーを実装する際は、以下のリソースを参照してください。

Auth0 Authentication API
Android のリソース
- 登録に関するドキュメント
- ログインに関するドキュメント
iOS のリソース
- 登録に関するドキュメント
- ログインに関するドキュメント

​仕組み

​始める前に

​カスタムドメインを設定する

​パスキーポリシーを設定する

​アプリケーションを準備する

​関連ドメイン

​Auth0 Dashboard を設定する

​Management API

​パスキーフローを実装する

​サインアップフロー

​フローの手順

​ログインフロー

​フローの手順

​参考資料

仕組み

始める前に

カスタムドメインを設定する

パスキーポリシーを設定する

アプリケーションを準備する

関連ドメイン

Auth0 Dashboard を設定する

Management API

パスキーフローを実装する

サインアップフロー

フローの手順

ログインフロー

フローの手順

参考資料