Native to Web SSO を設定して実装する

アプリケーションで Native to Web SSO を使用するための設定方法について説明します。

​

Native to Web SSO を設定する

Native to Web シングルサインオン (SSO) を利用するには、Auth0 の Management API を使用してセッションを作成および管理するように、ネイティブアプリと Web アプリ (Single Page App または Regular Web App) を設定します。

Management API または Auth0 CLI を使用するには、アクセストークン が必要です。

Native to Web SSO を設定するには、session_transfer_tokens を作成および管理し、ネイティブアプリケーションと Web アプリケーションを設定する必要があります。

Native to Web SSO は、次の SDK をサポートしています: Auth0 Android SDK、Auth0 Swift SDK、および Auth0 React Native SDK。

Native to Web SSO は、次のツールでサポートされています: Auth0 Deploy CLI、Auth0 Terraform Provider、および Auth0 CLI。

Native to Web SSO は、Resource Owner Password Flow や Authorization Code Flow with Proof Key for Code Exchange など、リフレッシュトークンを返すすべての認証フローをサポートしています。

​

セッション転送トークン の作成と管理

最初の Management API 呼び出しでは、ネイティブアプリケーションと Web アプリケーションで次のことが可能になります。

• session_transfer_tokens の作成と管理
• Cookie または URL パラメーターを使用して Web ブラウザーでセッションを作成
• IP アドレスまたは ASN を使用して、セッションをユーザーのデバイスに関連付ける

既存のアプリケーションの場合は、Update a Client エンドポイントに対して PATCH 呼び出しを行います。新しいアプリケーションを作成するには、Create a Client エンドポイントに対して POST 呼び出しを行います。

{
  "session_transfer": {
    "can_create_session_transfer_token": false,
    "allowed_authentication_methods": ["cookie", "query"],
    "enforce_device_binding": "ip", // "none" や "asn" も指定可能,
    "allow_refresh_token": false,
    "enforce_cascade_revocation": true,
    "enforce_online_refresh_tokens": true
  }
}

​

ネイティブアプリケーションを設定する

ユーザーが認証されると、Auth0 は アクセストークン、IDトークン、および (必要に応じて) リフレッシュトークン を返します。

ネイティブアプリケーションを設定して、リフレッシュトークンをセッション転送トークンと交換できます。Web アプリケーションが Cookie の挿入をサポートしていない場合は、ネイティブアプリケーションで Web アプリケーションの Login URI も設定し、セッション転送トークン を URI パラメーターとして渡せるようにする必要があります。

• Auth0 Dashboard を使用してネイティブアプリケーションを更新します。

  1. Dashboard > Applications に移動します。
  2. アプリケーションを選択するか、アプリケーションを作成します。
  3. Settings タブを選択します。
  4. Session Transfer で Allow Native to Web SSO を有効にします。
  5. Require Cascade Revocation を選択して、Web アプリケーションのセッションと関連トークンを自動的に失効させます。
  6. Save を選択してアプリケーションを更新します。

• Management API の アクセストークン を使用して、Update a Client エンドポイントでネイティブアプリケーションを更新します。

• Auth0 CLI を使用して、ネイティブアプリケーションを更新します。

​

Webアプリケーションを設定する

セッション転送トークン を有効にする前に、追加のパラメーターを処理できるよう、Webアプリケーションの Application Login URI を設定しておいてください。URI の詳細については、Application Settings を参照してください。

• Auth0 Dashboard を使用して Webアプリケーションを更新します。

  1. Dashboard > Applications に移動します。
  2. Webアプリケーションを選択するか、新規作成します。
  3. Settings タブを選択します。
  4. Session Transfer で、Native to Web SSO Methods を有効にします。
  5. Cookie Authentication と Query Authentication を選択します。
  6. Device Binding Method を有効にし、None、ASN Binding、または IP Address Binding のいずれかを選択します。
  7. セッショントランスファー後に新しいリフレッシュトークンを発行するには、Allow Refresh Token Requests を有効にします。
  8. Use online refresh tokens を選択します。
  9. Save を選択して Webアプリケーションを更新します。

• Management API アクセストークンを使用して、Update a Client エンドポイントで Webアプリケーションを更新します。

• Auth0 CLI を使用して、Web アプリケーションを更新します。

​

Native to Web SSO を実装する

Native to Web Single SSO では、認証済みのユーザーをネイティブアプリケーションから Web アプリケーションへシームレスに移行させることができます。

これを実現するには、ネイティブアプリケーションでリフレッシュトークンをセッション転送トークン に交換し、その セッション転送トークン を URL または cookie 経由で Web アプリケーションに送信して、セッションを認可する必要があります。

• クライアントで allow_refresh_token が無効になっている状態でアプリケーションが offline_access を要求しても、Auth0 は refresh_token を発行しませんが、認証自体は引き続き機能します。

• リフレッシュトークンローテーションが有効な場合、Auth0 はトークン交換の呼び出しで新しい refresh_token を返します。リフレッシュトークンの交換は、コードで Web アプリケーションを開く直前に行う必要があります。

​

ネイティブアプリケーションで

​

ステップ 1: リフレッシュトークンをセッション転送トークンと交換する

ネイティブアプリケーションで /token エンドポイントを使用して、リフレッシュトークンをセッション転送トークンと交換します。

• Swift、Android、または React Native SDK を使用してリフレッシュトークンをセッション転送トークンと交換する:

Swift SDK

credentialsManager.ssoCredentials { result in
    switch result {
    case .success(let ssoCredentials):
        print("Obtained SSO credentials: \(ssoCredentials)")
    case .failure(let error):
        print("Failed with: \(error)")
    }
}

// または async/await を使用

do {
    let ssoCredentials = try await credentialsManager.ssoCredentials()
    print("Obtained SSO credentials: \(ssoCredentials)")
} catch {
    print("Failed with: \(error)")
}

Android SDK

secureCredentialsManager.getSsoCredentials(
    mapOf(),  // オプション パラメーター
    object : Callback<SSOCredentials, CredentialsManagerException> {
        override fun onSuccess(result: SSOCredentials) {
            // result.sessionTransferToken を使用して
            // アプリ内の Web セッションでユーザーを認証します
        }

        override fun onFailure(error: CredentialsManagerException) {
            // エラーを処理します
        }
    }
)

React Native SDK

// Hooks を使用
import { useAuth0 } from 'react-native-auth0';

function MyComponent() {
  const { getSSOCredentials } = useAuth0();

  const openWebApp = async () => {
    try {
      const ssoCredentials = await getSSOCredentials();
      // ssoCredentials.sessionTransferToken を使用して
      // アプリ内の Web セッションでユーザーを認証します
      console.log('Session Transfer Token:', ssoCredentials.sessionTransferToken);
    } catch (error) {
      console.error('Failed to get SSO credentials:', error);
    }
  };
}

// Auth0 クラスを使用
import Auth0 from 'react-native-auth0';

const auth0 = new Auth0({
  domain: '{yourDomain}',
  clientId: '{yourClientId}',
});

const ssoCredentials = await auth0.credentialsManager.getSSOCredentials();
console.log('Session Transfer Token:', ssoCredentials.sessionTransferToken);

• HTTP を使用してリフレッシュトークンをセッション転送トークンと交換する:

これらのサンプルでは、可変の値にプレースホルダーを使用しています。プレースホルダーは、Auth0 のドメイン、client_id、既存の refresh_token に置き換えてください。

Auth0 テナントは、1 回限り使用でき、有効期間が短い (1 分) session_transfer_token を返します。

{
    "access_token": "{session_transfer_token}",
    "issued_token_type": "urn:auth0:params:oauth:token-type:session_transfer_token",
    "token_type": "N_A",
    "expires_in": 60
}

リフレッシュトークンのローテーションが有効な場合、この交換ではリフレッシュトークンも返されます。

認証時にIDトークンを要求していた場合、この呼び出しでもIDトークンが返されます。

​

ステップ 2: URL または Cookie でセッション転送トークン を送信する

設定されている allowed_authentication_methods に応じて、session_transfer_token を Web アプリケーションに送信する方法は 2 つあります。

オプション 1: session_transfer_token をクッキーとして送信する

WebView またはブラウザーを使用する Web アプリケーションがクッキーの挿入をサポートしている場合は、ネイティブアプリケーションを次のように設定できます。

• session_transfer_token をクッキーに追加します。
• WebView またはブラウザーを使用して Web アプリケーションを開きます。
• Web アプリケーションで、Auth0 テナントまたは Custom Domain にログインします。session_transfer_token がクッキーに含まれているため、ユーザーに第 1 認証要素での認証は求められません。

オプション 2: session_transfer_token を URL パラメーターとして送信する

Web アプリケーションが cookie インジェクションをサポートしていない場合は、URL パラメーターを使用するようにネイティブアプリケーションを設定し、次のことを行えます。

• session_transfer_token を URL パラメーターとして追加します。
• WebView またはブラウザーで Web アプリケーションを開きます。
• /authorize エンドポイントに session_transfer_token を URL パラメーターとして付加して、Web アプリケーションにログインします。session_transfer_token は有効で信頼できるため、Auth0 テナントは第 1 認証要素を要求せずにユーザーを認証します。

​

ウェブアプリケーションで

セッション転送トークン が Cookie として送信される場合、ブラウザーが /authorize エンドポイントへのリクエストでその Cookie を送信するため、追加の設定は不要です。

URL パラメーターを使用して、ウェブアプリケーションに Native to Web Web Single SSO を実装するには、次の手順に従います。

​

オプション 1: Web アプリケーションのリクエストにセッション転送トークン を追加する

アプリケーションのログイン URL から、session_transfer_token を URL パラメーターとして送信して /authorize エンドポイントにリダイレクトします。

​

オプション 2: Auth0 SDK を使用する Web アプリケーションにセッション転送トークン を追加する

Auth0 SDK は Native to Web SSO を自動ではサポートしていないため、/authorize エンドポイントへのリクエストに session_transfer_token は含まれません。

以下は、Auth0 SDK を使用する Web アプリケーションで、/authorize エンドポイントへのリクエストに session_transfer_token を追加してリダイレクトする例です:

Node (Express.js)

Web アプリケーションで Express.js または Auth0 Express SDK を使用している場合は、以下のコードを使って session_transfer_token をサポートするミドルウェアを追加できます。

javascript

const baseConfig = {
  authRequired: false,
  auth0Logout: true
};

// session_transfer_tokenを自動検出するためにミドルウェアを拡張する
app.use((req, res, next) => {
  const { session_transfer_token } = req.query;

  // stateの漏洩を防ぐため、リクエストごとに新しい設定を作成する
  const config = { ...baseConfig };

  if (session_transfer_token) {
    config.authorizationParams = {
      session_transfer_token,
    };
  }

  auth(config)(req, res, next);
});

Auth0 SPA SDK (@auth0/auth0-spa-js)

Web アプリケーションで Auth0 SPA SDK を使用している場合は、authorizationParams 経由で session_transfer_token を loginWithRedirect() に渡せます。

typescript

import { Auth0Client } from '@auth0/auth0-spa-js';

const auth0 = new Auth0Client({
  domain: '{yourDomain}',
  clientId: '{yourClientId}',
});

// URLクエリパラメータからsession_transfer_tokenを取得（ネイティブアプリから渡される）
const urlParams = new URLSearchParams(window.location.search);
const sessionTransferToken = urlParams.get('session_transfer_token');

// session_transfer_tokenを使用してloginWithRedirectを呼び出す
if (sessionTransferToken) {
  await auth0.loginWithRedirect({
    authorizationParams: {
      session_transfer_token: sessionTransferToken,
      redirect_uri: window.location.origin,
    },
  });
}

Auth0 React SDK (@auth0/auth0-react)

Web アプリケーションで Auth0 React SDK を使用している場合は、useAuth0 フックの loginWithRedirect を使って session_transfer_token を渡せます。

typescript

import { useEffect } from 'react';
import { useAuth0 } from '@auth0/auth0-react';

function App() {
  const { loginWithRedirect, isAuthenticated, isLoading } = useAuth0();

  useEffect(() => {
    if (isLoading || isAuthenticated) return;

    const urlParams = new URLSearchParams(window.location.search);
    const sessionTransferToken = urlParams.get('session_transfer_token');

    if (sessionTransferToken) {
      loginWithRedirect({
        authorizationParams: {
          session_transfer_token: sessionTransferToken,
        },
      });
    }
  }, [loginWithRedirect, isLoading, isAuthenticated]);

  return <div>...</div>;
}

SAML と WS-Federation

Web アプリケーションで、サービスプロバイダーとして SAML または WS-Fed を使用し、Auth0 を IdP として使用している場合は、session_transfer_token を URL パラメーターとして Auth0 の /authorize エンドポイントに送信できます。redirect_uri は、SAML または WS-Fed のサインイン URL です。

​

組織を使用した Native to Web SSO

Native to Web SSO では 組織 をサポートしています。ネイティブアプリケーションでユーザーが組織を指定して認証されると、セッション転送トークンにはその組織コンテキストが含まれます。

Native to Web SSO で組織を使用する場合、Web アプリケーションの /authorize リクエスト内の organization パラメーターは、セッション転送トークンに関連付けられた組織と一致している必要があります。一致しない場合、認証は失敗し、ユーザーは再度ログインを求められます。

Native to Web SSO で組織を使用するには:

1. ネイティブアプリケーションで、組織を指定してユーザーを認証します:

javascript

// 組織を使用したネイティブアプリのログイン
await authorize({
  organization: 'org_abc123',
  scope: 'openid profile email offline_access'
});

2. Web アプリケーションにリダイレクトする際は、/authorize リクエストに同じ組織を含めてください。

bash

https://{yourDomain}/authorize?
  client_id={yourWebClientId}&
  redirect_uri={yourRedirectUri}&
  response_type=code&
  organization=org_abc123&
  session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN

/authorize リクエスト内の組織がセッション転送トークン内の組織と一致しない場合、セッション転送トークンは拒否され、ユーザーは再認証のためログインページにリダイレクトされます。イベントの説明 “Single Sign-On failed: Session Transfer Token organization mismatch detected.” を含む警告ログが、テナントログに記録されます。

​

Actions を使用するセッション転送トークン

Actions で session_transfer_token を使用すると、認証後のリスク検知と対応機能を構成し、ユーザー保護を強化できます。

これを可能にするために、post-login の Action オブジェクト event.session_transfer_token には、一意の client_id、scope、ip、asn、user_agent などの request 情報や、cityName、countryCode などの geoip 情報をはじめとする関連情報が含まれます。詳細については、Actions Triggers: post-login - Event Object を参照してください。

以下の Action コードでは、地理位置情報に基づいてトランザクションを動的に拒否できます。

javascript

/**
* PostLoginフローの実行中に呼び出されるハンドラー。
*
* @param {Event} event - ユーザーおよびログイン時のコンテキストに関する詳細情報。
* @param {PostLoginAPI} api - ログインの動作を変更するために使用できるメソッドを持つインターフェース。
*/
exports.onExecutePostLogin = async (event, api) => {
   if(
     event.session_transfer_token &&
     event.session_transfer_token.request.geoip.countryCode !== event.request.geoip.countryCode
     ) {
     api.access.deny("Network mismatch detected")
   }
};

​

親リフレッシュトークンのメタデータへのアクセス

Native to Web SSO では、SSO フローの開始に使用された親リフレッシュトークンのメタデータにアクセスできます。これにより、ネイティブアプリケーションで収集したコンテキスト情報 (デバイスの完全性、リスクシグナル、カスタムコンテキストなど) を、session_transfer_token から作成された Web セッションに引き継ぐことができます。

Auth0 は、この情報を Post Login Actions の event.session.session_transfer.parent_refresh_token.metadata オブジェクトで公開します。これにより、プラットフォーム間でメタデータを安全かつ標準化された方法で受け渡しできます。

使用例: モバイルアプリでリスクデータ (デバイススコア、位置情報など) を収集し、それをリフレッシュトークンのメタデータに保存します。ネイティブアプリが Native to Web SSO フローを開始すると、そのメタデータは対応する Web セッションで Actions を通じて自動的に利用できるようになります。

以下の Action コードを使用すると、ネイティブアプリケーションから渡されたデバイス信頼メタデータに基づいて、条件付きアクセスロジックを実行できます。

javascript

/**
* PostLoginフローの実行中に呼び出されるハンドラー。
*
* @param {Event} event - ユーザーおよびログインコンテキストの詳細。
* @param {PostLoginAPI} api - ログインの動作を変更するために使用できるメソッドのインターフェース。
*/
exports.onExecutePostLogin = async (event, api) => {
  // 親リフレッシュトークン（ネイティブアプリ）からメタデータを取得する
  const parentMetadata = event.session?.session_transfer?.parent_refresh_token?.metadata;

  if (parentMetadata) {
    const deviceTrustLevel = parentMetadata.device_trust;

    if (deviceTrustLevel !== 'high') {
      api.access.deny("Device trust level insufficient.");
    }

    // ネイティブアプリのコンテキストに基づいてclaimsを追加することも可能
    if (parentMetadata.subscription_tier) {
      api.idToken.setCustomClaim('subscription_tier', parentMetadata.subscription_tier);
    }
  }
};

​

監視

Native to Web SSO のアクティビティは、テナントのログを確認することで監視できます。

​

トークン交換ログ

• sertft : リフレッシュトークン交換の成功。このログは、audience フィールドが "audience":"urn:$auth0Domain:session_transfer" の場合、Native から Web への SSO 交換に対応するものです
• fertft: リフレッシュトークン交換の失敗。このログは、audience フィールドが "audience": "urn:$auth0Domain:session_transfer" の場合、Native から Web への SSO 交換に対応するものです

​

セッション転送検証の警告ログ

Auth0 は、/authorize リクエスト中にセッション転送トークンの検証が失敗すると、警告ログ (w) を出力します。これらのログは、Native to Web SSO の問題のトラブルシューティングに役立ちます。

イベントの説明	原因
Single Sign-On failed: Session Transfer Token not found or expired. This may indicate token reuse or expiration.	セッション転送トークンが見つからない、すでに使用されている、または有効期限が切れています (トークンは 1 回限り有効で、有効期間は 1 分です) 。
Single Sign-On failed: Session Transfer Token device binding validation failed due to IP/ASN mismatch.	Web リクエストの IP アドレスまたは ASN が、セッション転送トークンに設定されたデバイスバインディングと一致していません。
Single Sign-On failed: Session Transfer Token organization mismatch detected.	/authorize リクエストの organization パラメーターが、セッション転送トークン内の組織と一致していません。
Single Sign-On failed: Session Transfer Token user mismatch detected.	既存の Auth0 セッションが、セッション転送トークンとは別のユーザーに属しています。
Single Sign-On failed: Parent refresh token not found. Session Transfer Token won't be used for session establishment.	セッション転送トークンの作成に使用された親リフレッシュトークンが失効しているか、削除されています。