ユーザープロファイルのメタデータを管理する方法

ユーザープロファイルのuser_metadataとapp_metadataには、ユースケースに応じてさまざまなメソッドでアクセスし、値を設定できます。

Management API
post-login アクション
ロック
ルール

Management APIのユーザー作成エンドポイント (POST /users) で新しいユーザーを作成する際は、ボディパラメーターのuser_metadataとapp_metadataを指定することで、そのユーザーのメタデータを設定できます。

例：メタデータ付きの新規ユーザーを作成

次のプロフィール情報でユーザーを作成するには：

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

の/post_usersエンドポイントに対して次のPOST呼び出しを行い、ユーザーを作成してプロパティ値を設定します：

Auth0 CLIをご利用ですか？まだの場合は、このコマンドを実行する前にCLIセッションのセットアップと認証を行ってください。

既存ユーザーのメタデータを設定または更新するには、Update a Userエンドポイント (PATCH /users/{id}) を使用し、同様にuser_metadataとapp_metadtaのボディパラメーターを指定します。

例：既存ユーザーのメタデータを更新

たとえば、次のメタデータ値を持つユーザーを作成したとします。

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

user_metadata を更新して、ユーザーの自宅住所を第2階層のプロパティとして追加するには、次のようにします。

{
    "addresses": {
        "home": "123 Main Street, Anytown, ST 12345"
    }
}

次のように PATCH 呼び出しを行います。ユーザーのプロフィールは次のように表示されるようになります。

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing",
        "addresses": {
            "home": "123 Main Street, Anytown, ST 12345"
        }
    },
    "app_metadata": {
        "plan": "full"
    }
}

既存ユーザーのメタデータを更新する場合、オブジェクトにマージされるのはルートレベルのプロパティのみです。それより下位のプロパティはすべて置き換えられます。

例：メタデータのサブプロパティを更新する

たとえば、ユーザーの勤務先住所を内部プロパティとして新たに追加するには、addresses プロパティの内容をすべて含める必要があります。addresses オブジェクトはルートレベルのプロパティなので、ユーザーを表す最終的な JSON オブジェクトにマージされますが、そのサブプロパティはマージされません。

{
  "user_metadata": {
    "addresses": {
      "home": "123 Main Street, Anytown, ST 12345",
      "work": "100 Industrial Way, Anytown, ST 12345"
    }
  }
}

したがって、これに対応する API への PATCH 呼び出しは次のようになります。

メタデータキーを削除するには、PATCH 呼び出しを実行し、対象のメタデータキーの値を null に設定します (例：{ "user_metadata": {"color": null}}) 。ユーザーまたはアプリのメタデータを完全に削除するには、PATCH 呼び出しを実行し、メタデータそのものを空のオブジェクトに設定します (例：{ "user_metadata": {} }) 。

post-loginトリガーを構成すると、ユーザーのログインフローの一部としてuser_metadataとapp_metadataを変更できます。ログイン後トリガーは、アプリケーション固有のデータをユーザープロファイルに保存する、ユーザーのオペレーションログを記録する、属性をメタデータフィールドにマッピングする、負荷の高いオペレーションの結果をユーザープロファイルにキャッシュして以降のログインで再利用する、といったタスクに便利です。post-loginのapiオブジェクトには、このトリガーで実行できる一般的なオペレーションが用意されています。ユーザーメタデータを管理するには、api.user.setAppMetadataメソッドとapi.user.setUserMetadataメソッドを使用します。たとえば、特定のユーザーに対してある動作が複数回実行されないようにするには、次のようなアクションを使用できます。

exports.onExecutePostLogin = async (event, api) => {
  if (event.user.app_metadata.didAnExpensiveTask) {
    console.log(`Skipping the expensive task because it already occurred for ${event.user.email}.`);

    return;
  }
  // 負荷の高いタスクを実行する
  api.user.setAppMetadata("didAnExpensiveTask", true);
};

ここでは、アクションの冒頭に、このユーザーに対して負荷の高い処理をすでに実行済みかどうかを確認するチェックを追加しています。メタデータフィールドが存在する場合は、関数から戻ります。アクションの最後では、api.user.setAppMetadataを呼び出して、ユーザーオブジェクトにメタデータを保存することを指示します。アクションは、各トリガーの実行終了時にユーザープロファイルを単一のオペレーションとして更新します。setUserMetadataが複数回呼び出された場合、それらが同じフロー内の別々のアクションで呼び出されたものであっても、アクションがユーザープロファイルを更新するのはトリガーの実行終了時の1回だけです。

setUserMetadataやsetAppMetadataの複数の呼び出しは、別々のアクションから行われたものであっても、トリガーの実行終了時に1回のユーザープロファイル更新としてまとめて処理されます。

api.redirect.sendUserTo()によるリダイレクトが発生した場合、保留中のユーザーメタデータやアプリメタデータの更新は、ユーザーが外部サイトにリダイレクトされる前にユーザープロファイルへ適用されます。

Lockライブラリを使用すると、user_metadata.の定義、追加、読み取り、更新を行えます。ユーザーのuser_metadataプロパティは、ほかのユーザープロファイルプロパティと同じ方法で読み取ることができます。たとえば、次のコードスニペットはuser_metadata.hobbyに関連付けられた値を取得し、ページ上の要素に割り当てます。

// 認証時に取得したaccessTokenを使ってgetUserInfoを呼び出します
lock.getUserInfo(accessToken, function(error, profile) {
  if (!error) {
    document.getElementById('hobby').textContent = profile.user_metadata.hobby;
  }
});

additionalSignUpFieldsを使用すると、ユーザーのサインアップフォームにカスタムフィールドを追加できます。ユーザーがカスタムフィールドにデータを入力すると、Auth0は入力された値をそのユーザーのuser_metadataに保存します。サインアップ時にuser_metadataを追加する方法の詳細については、「追加のサインアップフィールド」をお読みください。

ルールとHooksの提供終了 (EOL) 日は2026年11月18日です。また、2023年10月16日以降に作成された新しいテナントでは、これらの機能は利用できません。有効なHooksがある既存のテナントでは、提供終了日まで引き続きHooksを利用できます。Auth0を拡張する際は、アクションの使用を強くお勧めします。アクションでは、豊富な型情報やインラインドキュメント、公開されているnpmパッケージを利用できるほか、外部の統合機能と連携して、拡張性をさらに高めることができます。アクションで利用できる機能の詳細については、「Auth0 Actionsの仕組みを理解する」をお読みください。移行に役立つガイドとして、ルールからアクションへの移行とHooksからアクションへの移行をご用意しています。また、専用のアクションへの移行ページでは、機能の比較やアクションのデモなど、移行に役立つさまざまなリソースを紹介しています。ルールとHooksの非推奨化の詳細については、ブログ記事「Preparing for Rules and Hooks End of Life」をお読みください。

Auth0ルールを使用すると、メタデータの読み取り、更新、削除を行えます。以下のセクションでは、ユーザーとその情報を次のJSONスニペットで表した例をもとに説明します。

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

メタデータの読み取り

を使用すると、ルールでメタデータを読み取ることができます。また、user_metadataでは、次のようなプロファイル関連の情報を検索することもできます。

name
nickname
given_name
family_name

例として、メールアドレスが jane.doe@example.com のユーザーに次のメタデータが保存されているとします:

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

上記のメタデータの例を使うと、Auth0ルール内やManagement APIの呼び出しで、データセット内の特定の項目を次のように参照できます。

console.log(user.email); // "jane.doe@example.com"
console.log(user.user_metadata.hobby); // "surfing"
console.log(user.app_metadata.plan); // "full"

有効なJSONスニペットであれば、どれでもメタデータとして使用できます。user.app_metadata はデフォルトで Undefined です。

例：メタデータに基づく条件付き処理

ユーザーのロールに応じて判断できます。

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  if (user.app_metadata.roles.indexOf('writer')){
    // 実行するコード
  }
}

色の好みなど、特定の好みに基づいて判断することができます：

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  if (user.user_metadata.preferences.color === 'black'){
    // 実行するコード
  }
  ...
}

アプリケーションメタデータの読み取り (clientMetadata)

アプリケーションメタデータ (clientMetadata) は、context オブジェクトのトップレベルにある任意のプロパティです。既存のアプリケーションでは、このプロパティに値は設定されていません。

function(user, context, callback){
  context.clientMetadata = context.clientMetadata || {};
  if (context.clientMetadata.usersuppliedkey1 === 'black'){
    // このコードはユーザーに対して実行されません
  }
  ...
}

メタデータの更新

ルールを使用すると、Auth0がIdPから受け取ったSAML属性をuser_metadataまたはapp_metadataにマッピングできます。

アプリのメタデータの更新

ユーザーに管理者ロールを追加するには：

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // レスポンスに含まれる app_metadata を更新する
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('administrator');

  // app_metadata の更新を永続化する
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

その結果、ユーザープロファイルの詳細は次のような JSON で表されます：

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer", "administrator" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

ユーザーメタデータを更新する

ユーザーの fontSize 設定をユーザープロファイルに追加するには、次の手順を実行します。

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // レスポンスに含まれる user_metadata を更新する
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // user_metadata の更新内容を保存する
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

これにより、ユーザープロファイルの詳細は次のような JSON で表されます。

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}

アプリとユーザーのメタデータを同時に更新する

ルールの処理時間を短縮するには、同じルール内で app_metadata と user_metadata の両方を更新します。

function(user, context, callback){

  var q = require('q');

  user.app_metadata = user.app_metadata || {};
  user.user_metadata = user.user_metadata || {};
  // レスポンスに含まれる user_metadata を更新する
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // レスポンスに含まれる app_metadata を更新する
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('admin');

  // app_metadata の更新を永続化する
  var appMetadataPromise  = auth0.users.updateAppMetadata(user.user_id, user.app_metadata);

  // user_metadata の更新を永続化する
  var userMetadataPromise = auth0.users.updateUserMetadata(user.user_id, user.user_metadata);

  // q ライブラリを使用してすべての Promise の完了を待機する
  q.all([userMetadataPromise, appMetadataPromise])
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

これにより、ユーザープロファイルの詳細は次のような JSON で表現されます。

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer", "admin" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}

メタデータを削除

アプリメタデータのプロパティと値を削除する

プロパティを削除するには、そのプロパティの値を null に設定します。

ユーザーのロール削除の例

ユーザーのロールを削除するには、次のサンプルRuleを使用します：

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // レスポンスに含まれる app_metadata を更新する
  user.app_metadata.roles = null;

  // app_metadata の更新を永続化する
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

その結果、ユーザープロファイルの JSON 表現は次のようになります。

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": { },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

単一のプロパティ値を削除する例

プロパティの値を1つだけ削除するには、その値を指定して削除します。たとえば、ユーザープロファイルから writer ロールを削除するには、次のようにします。

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  user.app_metadata.roles = user.app_metadata.roles || [];

  var index = user.app_metadata.roles.indexOf('writer');

  if (index !== -1){
    // レスポンスに含まれるapp_metadataを更新します
    user.app_metadata.roles.splice(index, 1);
  }

  // app_metadataの更新内容を保存します
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

その結果、ユーザープロファイルは次のような JSON で表現されます：

{
  "user_id": "google-oauth2|1234",
  "email": "john.doe@gmail.com",
  "app_metadata": {
    "roles": [ ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

roles プロパティは残っていますが、値は入っていません。

ユーザーメタデータのプロパティと値を削除する

ユーザーの色設定を削除するには：

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // レスポンスに含まれる user_metadata を更新する
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  delete user.user_metadata.preferences.color;

  // user_metadata の更新を永続化する
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
  });
}

これにより、ユーザープロファイルの詳細は次のような JSON で表されます：

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": { }
  }
}

概念

操作方法

リファレンス

ユースケース

ユーザープロファイルのメタデータを管理する方法

メタデータの読み取り

アプリケーションメタデータの読み取り (clientMetadata)

メタデータの更新

アプリのメタデータの更新

ユーザーメタデータを更新する

アプリとユーザーのメタデータを同時に更新する

メタデータを削除

アプリメタデータのプロパティと値を削除する

ユーザーのロール削除の例

単一のプロパティ値を削除する例

ユーザーメタデータのプロパティと値を削除する

​メタデータの読み取り

​アプリケーションメタデータの読み取り (clientMetadata)

​メタデータの更新

​アプリのメタデータの更新

​ユーザーメタデータを更新する

​アプリとユーザーのメタデータを同時に更新する

​メタデータを削除

​アプリメタデータのプロパティと値を削除する

​ユーザーのロール削除の例

​単一のプロパティ値を削除する例

​ユーザーメタデータのプロパティと値を削除する

メタデータの読み取り

アプリケーションメタデータの読み取り (clientMetadata)

メタデータの更新

アプリのメタデータの更新

ユーザーメタデータを更新する

アプリとユーザーのメタデータを同時に更新する

メタデータを削除

アプリメタデータのプロパティと値を削除する

ユーザーのロール削除の例

単一のプロパティ値を削除する例

ユーザーメタデータのプロパティと値を削除する