Auth0 Single-Page App SDK

このシングルページアプリケーション用のAuth0 SDKは、PKCEを用いた認可コード付与フローを使用しています。

Auth0 Single-Page App SDKは新しいJavaScriptライブラリーで、シングルページアプリ（SPA）でAuth0を使って認証と認可を実装します。高水準のAPIを提供して、大量の詳細情報を処理しているため、作成するコードの量を低減しながら、SPAにベストプラクティスを実装することができます。

Auth0 SPA SDKは、付与とプロトコルの詳細、トークンの失効と更新、そして、トークンの保管とキャッシュをも処理します。内部では、ユニバーサルログインとPKCEを用いた認可コード付与フローを実装しています。

ライブラリとAPIドキュメントはGitHubでホストされます。

新しいJavaScript SDKを使用中に問題やエラーが発生した場合は、FAQ（よくある質問）をお読みになられて、問題が提示されているか確認してください。

インストール

プロジェクトでAuth0 SPA SDKを使用するには、いくつかのオプションがあります。

• CDNから：<script src="https://cdn.auth0.com/js/auth0-spa-js/2.0/auth0-spa-js.production.js"></script>。詳細については、「FAQ」をお読みください。
• npmを使用する場合：npm install @auth0/auth0-spa-js
• yarnを使用する場合：yarn add @auth0/auth0-spa-js

はじめに

クライアントを作成する

まず、Auth0Clientクライアントプロジェクトの新しいインスタンスを作成する必要があります。Auth0Clientインスタンスを作成してから、アプリケーションのレンダリングまたは初期化を行います。これを行うには、async/awaitメソッドまたはpromiseを使用します。クライアントには必ずインスタンスを1つだけ作成します。

createAuth0Clientを使用すると、いくつかの処理が自動的に行われます。

• Auth0Clientのインスタンスを作成する。
• getTokenSilentlyを呼び出し、ユーザーセッションを更新する。
• getTokenSilentlyからのエラーをすべて抑止する（login_requiredを除く）。

async/awaitを使用する

promiseを使用する

Auth0Clientコンストラクターを使って、クライアントを直接作成することもできます。これは、以下の場合に便利です。

• 初期化時にgetTokenSilentlyへの呼び出しをバイパスする
• カスタムエラー処理を行う
• SDKを同期的に初期化する

ログインしてユーザー情報を取得する

次に、ユーザーがクリックしてログインを始めるボタンを作成します。

<button id="login">クリックしてログイン</button>

作成したボタンのクリックイベントを待ち合わせます。イベントが発生した際には、適切なログインメソッドを実行してユーザーを認証します（この例ではloginWithRedirect()）。ユーザーが認証されたら、getUser()メソッドでユーザープロファイルを取得できます。

async/awaitを使用する

document.getElementById('login').addEventListener('click', async () => {
  await auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  });
  //logged in. you can get the user profile like this:
  const user = await auth0.getUser();
  console.log(user);
});

promiseを使用する

document.getElementById('login').addEventListener('click', () => {
  auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  }).then(token => {
    //logged in. you can get the user profile like this:
    auth0.getUser().then(user => {
      console.log(user);
    });
  });
});

APIを呼び出す

APIを呼び出すには、ユーザーのアクセストークンを取得することから始めます。それから、要求にアクセストークンを使用します。この例では、getTokenSilentlyメソッドを使ってアクセストークンを取得します。

<button id="callApi">APIを呼び出す</button>

async/awaitを使用する

document.getElementById('callApi').addEventListener('click', async () => {
  const accessToken = await auth0.getTokenSilently();
  const result = await fetch('https://exampleco.com/api', {
    method: 'GET',
    headers: {
      Authorization: 'Bearer ' + accessToken
    }
  });
  const data = await result.json();
  console.log(data);
});

promiseを使用する

document.getElementById('callApi').addEventListener('click', () => {
  auth0
    .getTokenSilently()
    .then(accessToken =>
      fetch('https://exampleco.com/api', {
        method: 'GET',
        headers: {
          Authorization: 'Bearer ' + accessToken
        }
      })
    )
    .then(result => result.json())
    .then(data => {
      console.log(data);
    });
});

ログアウト

ユーザーがログアウトするのにクリックするボタンを追加します。

<button id="logout">ログアウト</button>

$('#logout').click(async () => {
  auth0.logout({
    logoutParams: {
      returnTo: 'http://localhost:3000/'
    }
  });
});

ストレージオプションを変更する

Auth0 SPA SDKはデフォルトでトークンをメモリーに保管します。ところが、ページの更新やブラウザーのタブでは永続性が途絶えてしまします。代わりに、SDKの初期化時にcacheLocationプロパティをlocalstorageに設定することで、トークンをローカルストレージに保存するよう選択できます。これは、Auth0のセッションCookieがアクセストークンを長期保管するのに対して、ブラウザーのプライバシー保護技術がそのアクセスを妨げる弊害を低減するのに役立ちます。

トークンをブラウザーのローカルストレージに保管すると、ページが更新されても、ブラウザータブが切り替わっても、持続性を確保できるというメリットがあります。しかし、攻撃者がクロスサイトスクリプティング（XSS）によってSPAでJavaScriptを実行できるようになると、ローカルストレージに保管されているトークンを取得されてしまいます。XSS攻撃の成功につながる脆弱性は、SPAソースコード、またはSPAに含まれるサードパーティのJavaScriptコード（ブートストラップ・jQuery・Google Analyticsなど）に存在する可能性があります。

トークンストレージについての詳細をお読みください。

リフレッシュトークンのローテーションを使用する

リフレッシュトークンをローテーションさせて、サイレントモードで新しいアクセストークンを取得するように、Auth0 SPA SDKを構成できます。これによって、サイレント認証時にAuth0のセッションCookieへのアクセスを妨げるブラウザーのプライバシー保護技術を迂回するだけでなく、再利用の検出を組み込むこともできます。

このためには、初期化時にuseRefreshTokensをtrueに設定してSDKを構成します。

リフレッシュトークンは、SPAで使用する前にテナント用に構成される必要もあります。

構成を終えると、SDKは認可ステップ中にoffline_accessスコープを要求します。さらに、getTokenSilentlyは/oauth/tokenエンドポイントを呼び出し、フレッシュトークンをアクセストークンに直接交換します。SDKはリフレッシュトークンの保管について、ストレージ設定に従います。SDKがデフォルトのメモリー内ストレージに構成されている場合、リフレッシュトークンはページが更新されると失われます。

使用状況

以下は、SDKでさまざまなメソッドを使った例です。3つの例でjQueryが使用されていることに注意してください。

リダイレクトでログインする

Auth0で/authorizeエンドポイントにリダイレクトし、ユニバーサルログインフローを開始します。

$('#loginRedirect').click(async () => {
  await auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  });
});

ポップアップでログインする

ユニバーサルログインのページでポップアップ画面を使用してログインします。

$('#loginPopup').click(async () => {
  await auth0.loginWithPopup();
});

ユーザーが認証フローを完了するのに、デフォルトの60秒のタイムアウトよりも長くかかった場合には、認証が中断されます。この際には、コードでエラーをキャッチして、以下のいずれかを行う必要があります。

再試行し、error.popup.closeを使ってポップアップを手動で閉じることをユーザーに求めます。

$('#loginPopup').click(async () => {
  try {
    await auth0.loginWithPopup();
  } catch {error}
  if (error instanceof auth0.PopupTimeoutError) {
    // custom logic to inform user to retry
    error.popup.close();
  }
});

または、optionsオブジェクトでカスタムpopupオプションを作成します。

$('#loginPopup').click(async () => {
  const popup = window.open(
    '',
    'auth0:authorize:popup',
    'left=100,top=100,width=400,height=600,resizable'
  );
  try {
    await auth0.loginWithPopup({ popup });
  } catch {error}
  if (error instanceof auth0.PopupTimeoutError) {
    // custom logic to inform user to retry
    error.popup.close();
  }
});

リダイレクトのコールバックでログインする

ブラウザーがAuth0からSPAにリダイレクトされると、ログインフローを完了するためにhandleRedirectCallbackを呼び出す必要があります。

$('#loginRedirectCallback').click(async () => {
  await auth0.handleRedirectCallback();
});

ユーザーの関与なくアクセストークンを取得する

非表示のiframe とprompt=noneを使用するか、またはリフレッシュトークンをローテーションさせることで、サイレントモードで新しいアクセストークンを取得します。リフレッシュトークンは、SDKの構成時にuseRefreshTokensがtrueに設定されている場合に使用されます。

SafariやBraveなど、サードパーティクッキーをブロックするブラウザーでは、リフレッシュトークンを使用せずにサイレントでアクセストークンを取得することはできません。カスタムドメインでの回避策については、「Safariを使ったトークン更新のトラブルシューティング」をお読みください。

メモリー内ストレージ（デフォルト）の設定でリフレッシュトークンが使用されると、新しいトークンは対応しているブラウザーのウェブワーカー（Web Worker）を使って取得されます。

$('#getToken').click(async () => {
  const token = await auth0.getTokenSilently();
});

getTokenSilently()メソッドを使用する場合は、［Allow Skipping User Consent（ユーザー同意をスキップさせる）］ がDashboardのAPI設定で有効になっている必要があります。さらに、ユーザー同意を’localhost’でスキップすることはできません。

ポップアップでアクセストークンを取得する

アクセストークンはポップアップでも取得することができます。getTokenSilentlyとは違って、サードパーティのCookieがデフォルトで阻止されているブラウザーでも動作します。

$('#getTokenPopup').click(async () => {
  const token = await auth0.getTokenWithPopup({
    authorizationParams: {
      audience: 'https://mydomain/api/',
      scope: 'read:rules'
    }
  });
});

異なるオーディエンスにアクセストークンを取得する

オプションは、ユーザー認証時に要求された、異なるオーディエンスとそのスコープを持つアクセストークンを取得するgetTokenSilentlyに渡すこともできます。

これは、リフレッシュトークンを使わない場合（useRefreshTokens: false）にのみ有効です。リフレッシュトークンは、ユーザーの認証時に要求された特定のオーディエンスとスコープにバインドされているためです。

$('#getToken_audience').click(async () => {
  const differentAudienceOptions = {
    authorizationParams: {
      audience: 'https://mydomain/another-api/',
      scope: 'read:rules',
      redirect_uri: 'http://localhost:3000/callback.html'
    }
  };
  const token = await auth0.getTokenSilently(differentAudienceOptions);
});

ユーザーを取得する

認証されたユーザーのプロファイルデータを取得するには、getUserメソッドを呼び出します。

$('#getUser').click(async () => {
  const user = await auth0.getUser();
});

IDトークンのクレームを取得する

認証されたユーザーのIDトークンにあるクレームを取得するには、getIdTokenClaimsメソッドを呼び出します。

$('#getIdTokenClaims').click(async () => {
  const claims = await auth0.getIdTokenClaims();
  // if you need the raw id_token, you can access it
  // using the __raw property
  const id_token = claims.__raw;
});

ログアウト（デフォルト）

ログアウトのアクションを開始するには、logoutメソッドを呼び出します。

$('#logout').click(async () => {
  auth0.logout({
    logoutParams: {
      returnTo: 'http://localhost:3000/'
    }
  });
});

クライアントIDなしでログアウトする

クライアントIDが指定されていないログアウトのアクションを開始するには、logoutメソッドを呼び出し、clientId: nullを含めます。

$('#logoutNoClientId').click(async () => {
  auth0.logout({
    clientId: null,
    logoutParams: {
      returnTo: 'http://localhost:3000/'
    }
  });
});

もっと詳しく

• アクセストークンを検証する