Lock API リファレンス

Lock v11 API に関する詳細。

Lock には多数のメソッド、機能、設定可能なオプションがあります。このリファレンスでは、必要なものをすぐ見つけられるようにし、その使い方を説明します。探しているメソッドに直接移動するには以下をクリックするか、そのまま参照してください。Lock が発するイベントに関する情報を探している場合は、on() メソッドのセクションに一覧があります。

• new Auth0Lock - Lock をインスタンス化する
• getUserInfo() - ログイン済みユーザーのプロファイルを取得する
• show() - Lock ウィジェットを表示する
• on() - イベントを監視する
• resumeAuth() - autoParseHash が false の場合に認証フローを完了するために使用する
• checkSession() - 認証済みユーザー向けに Auth0 から新しいトークンを取得する
• logout() - ユーザーをログアウトする

Auth0Lock

new Auth0Lock(clientID, domain, options)

Auth0 の管理ダッシュボードにある、アカウントの domain とアプリケーションの clientID を使用して、新しい Auth0Lock インスタンスを初期化します。3 つ目の任意のパラメータは options オブジェクトで、アプリケーションの要件に合わせて Lock を設定するために使用します。この情報は アプリケーション設定 で確認できます。

• clientId {String}: 必須パラメータ。Auth0 におけるアプリケーションの clientId です。
• domain {String}: 必須パラメータ。Auth0 のドメインです。通常は your-account.auth0.com です。
• options {Object}: 任意のパラメータ。Lock の外観と動作を設定できます。詳しくは 設定オプションのページ を参照してください。

getUserInfo()

getUserInfo(accessToken, callback)

ユーザーがログインしてトークンを取得したら、そのトークンを使って getUserInfo からユーザーのユーザープロファイルを取得できます。このメソッドは非推奨の `getProfile()“ の代わりに使用します。

• accessToken {String}: ユーザーのトークン。
• callback {Function}: ユーザープロファイルの取得後に呼び出されます。

lock.getUserInfo(accessToken, function(error, profile) {
  if (!error) {
    alert("hello " + profile.name);
  }
});

show()

show(options)

show メソッドはウィジェットを表示します。Lock バージョン 10.2.0 以降では、show メソッドで options オブジェクトをパラメータとして受け取れるようになりました。このパラメータは、このとき表示するウィジェットに限って Lock の options を上書きするためのものです。options は Lock のインスタンス化時に設定し、必要な場合にのみ、ここで特定のユースケースに合わせて上書きしてください。

Lock のインスタンス化時に設定された値 (またはデフォルト値) から上書きできる options の一部は、次のとおりです。

• allowedConnections
• auth.params
• allowLogin
• allowSignUp
• allowForgotPassword
• initialScreen
• rememberLastLogin

show メソッドで上書きできる上記の限られた項目とは異なり、Lock のインスタンス化時に指定できる設定可能な options の一覧全体について詳しくは、ユーザーが設定可能な options のページを参照してください。

Options の上書き例:

// オプションを上書きせずにLockウィジェットを表示する
lock.show();

// 一部のオプションを上書きしてLockウィジェットを表示する
lock.show({
  allowedConnections: ["twitter", "facebook"],
  allowSignUp: false
});

オプションは、Lock を最初にインスタンス化する際に var lock = new Auth0Lock(clientId, domain, options); で設定してください。show にオプションを渡すのは、このタイミングと場所でウィジェットを表示する際に、あらかじめ設定したオプションを一時的に上書きする場合に限られます。

show メソッドでは、flashMessage という追加オプションも設定できます。

flashMessage

このオブジェクトは、Lock をインスタンス化する際の通常の options オブジェクトでは使用できず、show メソッドのオプションとしてのみ利用できます。flashMessage オブジェクトは、Lock の表示時にエラーまたは成功のフラッシュメッセージを表示します。使用できるパラメータは次のとおりです。

• type {String}: メッセージの種類。error または success のいずれかを指定します。
• text {String}: 表示するテキスト。

lock.show({
  flashMessage:{
    type: 'success',
    text: 'Amazing Success!!'
  }
});

flashMessage オプションの実践的な使い方の1つは、認可エラーへの対処です。flashMessage にはエラーの説明テキストを設定できます。

lock.on('authorization_error', function(error) {
  lock.show({
    flashMessage: {
      type: 'error',
      text: error.errorDescription
    }
  });
});

したがって、[e-mail] が今サインインを試みると、ブロックされているユーザーであるため、単にログインに失敗して Lock が閉じるのではなく、上部バーにエラーメッセージが表示された状態で、再び Lock が表示されます。

hide()

hide()

hide メソッドは、ウィジェットが現在開いている場合に閉じます。通常、ほとんどのケースではウィジェットは自動的に閉じるため、このメソッドを呼び出すのは主に特定のユースケースに限られます。たとえば、unrecoverable_error イベントを監視し、その後 Lock を hide して独自のエラーページにリダイレクトしたい場合があります。別の例として、popup mode を実装しているユーザーは、authenticated イベントの発生後にウィジェットを手動で hide する必要があるかもしれません。

popup mode で Lock ウィジェットを非表示にする (閉じる) 使用例:

// authenticatedイベントをリッスンしてLockを非表示にする
lock.on("authenticated", function() {
  lock.hide();

  // authenticatedイベントで実行したいその他の処理

});

on()

Lock はライフサイクルの中でイベントを発行します。on メソッドを使うと、特定のイベントを監視して、それに応じた処理を実行できます。

• show: Lock が表示されたときに発行されます。引数はありません。
• hide: Lock が非表示になったときに発行されます。引数はありません。
• unrecoverable_error: 回復不能なエラーが発生したときに発行されます。たとえば、利用可能な接続がない場合です。引数はエラーのみです。
• authenticated: 認証が成功した後に発行されます。引数は認証結果のみです。認証結果には、ユーザーのプロファイル取得に使用したり、以降の確認でログイン状態を維持するために保存したりできるトークンが含まれます。
• authorization_error: 認可に失敗したときに発行されます。引数はエラーのみです。
• hash_parsed: 新しい Auth0Lock オブジェクトが redirect mode (デフォルト) で初期化されるたびに、ログイン試行の結果を探すため URL のハッシュ部分の解析が試みられます。これは高度なユースケース向けの低レベルイベントであり、可能であれば authenticated と authorization_error を優先して使用してください。その後、ハッシュ内に何も見つからなかった場合、このイベントは null を引数に発行されます。ログインが成功した後は authenticated イベントと同じ引数で、問題が発生した場合は authorization_error と同じ引数で発行されます。popup mode では URL のハッシュ部分を解析する必要がないため、このイベントは発行されません。
• forgot_password ready: 「Forgot password」画面が表示されたときに発行されます。 (Version >10.18 のみ)
• forgot_password submit: ユーザーが「Forgot password」画面の送信ボタンをクリックしたときに発行されます。 (Version >10.14 のみ)
• signin ready: 「Sign in」画面が表示されたときに発行されます。
• signup ready: 「Sign up」画面が表示されたときに発行されます。
• signin submit: ユーザーが「Login」画面の送信ボタンをクリックしたときに発行されます。 (Version >10.18 のみ)
• signup submit: ユーザーが「Sign Up」画面の送信ボタンをクリックしたときに発行されます。 (Version >10.18 のみ)
• federated login: ユーザーがソーシャル接続ボタンをクリックしたときに発行されます。引数は接続名と strategy です。 (Version >10.18 のみ)
• socialOrPhoneNumber ready: Social + Phone Number の パスワードレス 画面が表示されたときに発行されます
• socialOrPhoneNumber submit: Social + Phone Number のパスワードレス画面が送信されたときに発行されます
• socialOrEmail ready: Social + Email のパスワードレス画面が表示されたときに発行されます
• socialOrEmail submit: Social + Email のパスワードレス画面が送信されたときに発行されます
• vcode ready: ワンタイムパスワード付きのパスワードレス画面が表示されたときに発行されます
• vcode submit: ワンタイムパスワード付きのパスワードレス画面が送信されたときに発行されます

authenticated イベントリスナーには、authResult オブジェクトという 1 つの引数があります。このオブジェクトには、accessToken、idToken、state、refreshToken、idTokenPayload の各プロパティが含まれます。

authenticated イベントの使用例:

resumeAuth()

このメソッドは、auth.autoParseHash オプションを false に設定した場合にのみ使用できます。認証フローを完了するには、resumeAuth を呼び出す必要があります。このメソッドは、# を使って URL を処理するクライアントサイドの router (useHash を使用する angular2、または hashHistory を使用する react-router) を使っている場合に便利です。

• hash {String}: リダイレクトで受け取ったハッシュフラグメント。
• callback {Function}: 解析の完了後に呼び出されます。第 1 引数にはエラー (ある場合) 、第 2 引数には認証結果が渡されます。使用できるハッシュがない場合は、どちらの引数も null になります。

lock.resumeAuth(hash, function(error, authResult) {
  if (error) {
    alert("Could not parse hash");
  }
  //これはあくまでも例です。本番環境ではアクセストークンをログに記録しないでください。
  console.log(authResult.accessToken);
});

checkSession()

checkSession メソッドを使うと、あなたのドメインの Auth0 ですでに認証されているユーザー向けに、Auth0 から新しいトークンを取得できます。指定できるパラメータは次のとおりです。

• options {Object}: 任意。通常 /authorize に送信する有効な OAuth 2.0 パラメータを受け付けます。省略した場合は、Auth0 の初期化時に指定したパラメータが使用されます。
• callback {Function}: トークン更新の結果を受け取って呼び出されます。第 1 引数にはエラー (ある場合) 、第 2 引数には認証結果が渡されます。

lock.checkSession({}, function(err, authResult) {
  // エラーまたは新しいトークンを処理する
});

logout()

ユーザーをログアウトします。

• options {オブジェクト}: 省略可能です。auth0.js の logout() と同じルールに従います。

lock.logout({
  returnTo: 'https://myapp.com/bye-bye'
});