PKCE を使用した Auth0 シングルページアプリケーション SDK の認可コードグラントフロー。

PKCE を使用した認可コードグラントフロー向けのシングルページアプリケーション用 Auth0 SDK。

Auth0 Single Page App SDK は、Auth0 を使用してシングルページアプリ (SPA) に認証および認可を実装するための新しい JavaScript ライブラリです。高水準の API を提供し、さまざまな詳細を処理してくれるため、コード量を抑えながらベストプラクティスに沿って SPA を保護できます。

Auth0 SPA SDK は、グラントやプロトコルの詳細、token の有効期限と更新、さらに token の保存とキャッシュを処理します。内部的には、Universal Login と Authorization Code Grant Flow with PKCE を実装しています。

このライブラリと API documentation は 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">Click to Login</button>

作成したボタンのクリックイベントを待ち受けます。イベントが発生したら、使用するログイン方法でユーザーを認証します (この例では loginWithRedirect() を使用します) 。ユーザーの認証後、getUser() メソッドでユーザープロファイルを取得できます。

async/await を使う

document.getElementById('login').addEventListener('click', async () => {
  await auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  });
  //ログインしました。次のようにユーザープロファイルを取得できます:
  const user = await auth0.getUser();
  console.log(user);
});

Promise を使う

document.getElementById('login').addEventListener('click', () => {
  auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  }).then(token => {
    //ログインしました。次のようにユーザープロファイルを取得できます:
    auth0.getUser().then(user => {
      console.log(user);
    });
  });
});

API を呼び出す

API を呼び出すには、まずユーザーの アクセストークン を取得します。次に、そのアクセストークンをリクエストで使用します。この例では、アクセストークンの取得に getTokenSilently メソッドを使用しています。

<button id="callApi">Call an 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">Logout</button>

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

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

Auth0 SPA SDK は、デフォルトでトークンをメモリに保存します。ただし、この方法ではページを再読み込みしたり、ブラウザーの別タブを開いたりすると保持されません。代わりに、SDK の初期化時に cacheLocation プロパティを localstorage に設定することで、トークンをローカルストレージに保存するよう明示的に有効化できます。これにより、アクセストークンをより長く保持できるため、Auth0 の セッションクッキー へのアクセスを制限するブラウザーのプライバシー保護機能による影響を、一部軽減できます。

ブラウザーのローカルストレージにトークンを保存すると、ページの再読み込み後やブラウザーの別タブでも保持されます。ただし、攻撃者がクロスサイトスクリプティング (XSS) 攻撃によって SPA 上で JavaScript を実行できた場合、ローカルストレージに保存されたトークンを取得されるおそれがあります。XSS 攻撃の成功につながる脆弱性は、SPA のソースコード内にある場合もあれば、SPA に組み込まれているサードパーティの JavaScript コード (bootstrap、jQuery、Google Analytics など) 内にある場合もあります。

詳しくは、トークンの保存をご覧ください。

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

Auth0 SPA SDK は、ローテーションするリフレッシュトークンを使用して、新しいアクセストークンをサイレントに取得するよう設定できます。これにより、サイレント認証時に Auth0 セッションクッキー へのアクセスを妨げるブラウザーのプライバシー保護機能を回避できるほか、組み込みの再利用検知も利用できます。

これを行うには、初期化時に useRefreshTokens を true に設定します:

リフレッシュトークンを SPA で使用するには、事前にテナントで設定しておく必要があります。

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

使い方

以下に、SDK の各種メソッドの使用例を示します。なお、これらの例では jQuery を使用しています。

リダイレクトでログイン

Auth0 の /authorize エンドポイントへリダイレクトして、Universal Login フローを開始します。

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

ポップアップでログイン

ポップアップウィンドウを使用して、Universal Login ページからログインします：

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

ユーザーが認証フローの完了に既定のタイムアウトである 60 秒以上かかると、認証は中断されます。そのため、コードでエラーを捕捉し、次のいずれかに対応する必要があります。

ユーザーに再試行を促し、error.popup.close を使ってポップアップを手動で閉じるよう案内します。

$('#loginPopup').click(async () => {
  try {
    await auth0.loginWithPopup();
  } catch {error}
  if (error instanceof auth0.PopupTimeoutError) {
    // ユーザーに再試行を促すカスタムロジック
    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) {
    // ユーザーに再試行を促すカスタムロジック
    error.popup.close();
  }
});

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

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

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

操作なしでアクセストークンを取得する

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

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

インメモリストレージ (デフォルト) とリフレッシュトークンを使用している場合、サポート対象のブラウザーでは Web Worker を使って新しいトークンが取得されます：

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

getTokenSilently() メソッドを使用するには、Auth0 Dashboard の API 設定で Allow Skipping User Consent を有効にしておく必要があります。さらに、‘localhost’ ではユーザーの同意を省略できません。

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

アクセストークンは、ポップアップを使って取得することもできます。getTokenSilently とは異なり、この方法であれば、サードパーティ Cookie がデフォルトでブロックされているブラウザーでもアクセストークンを取得できます。

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

別の audience 向けのアクセストークンを取得する

getTokenSilently にオプションを渡すと、ユーザーの認証時にリクエストしたものとは異なる audience と scope を持つアクセストークンを取得できます。

これは、リフレッシュトークンを使用していない場合 (useRefreshTokens: false) にのみ機能します。リフレッシュトークンは、ユーザーの認証時にリクエストした特定の audience と scope に紐づいているためです。

$('#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 トークンのクレームを取得する

getIdTokenClaims メソッドを呼び出すと、認証済みユーザーのID トークンのクレームを取得できます。

$('#getIdTokenClaims').click(async () => {
  const claims = await auth0.getIdTokenClaims();
  // 生のid_tokenが必要な場合は、__rawプロパティを使用して
  // アクセスできます
  const id_token = claims.__raw;
});

ログアウト (デフォルト)

logout メソッドを呼び出すことで、ログアウトを開始できます。

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

Client ID を指定しないログアウト

logout メソッドを呼び出して clientId: null を指定すると、Client ID を指定せずにログアウトアクションを開始できます。

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

詳細はこちら

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