user_metadataとapp_metadataには、ユースケースに応じてさまざまなメソッドでアクセスし、値を設定できます。
- Management API
post-loginアクション- ロック
- ルール
Management APIのユーザー作成エンドポイント (
既存ユーザーのメタデータを設定または更新するには、Update a Userエンドポイント (
既存ユーザーのメタデータを更新する場合、オブジェクトにマージされるのはルートレベルのプロパティのみです。それより下位のプロパティはすべて置き換えられます。
メタデータキーを削除するには、
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セッションのセットアップと認証を行ってください。
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"
}
}
例:メタデータのサブプロパティを更新する
例:メタデータのサブプロパティを更新する
たとえば、ユーザーの勤務先住所を内部プロパティとして新たに追加するには、したがって、これに対応する API への
addresses プロパティの内容をすべて含める必要があります。addresses オブジェクトはルートレベルのプロパティなので、ユーザーを表す最終的な JSON オブジェクトにマージされますが、そのサブプロパティはマージされません。{
"user_metadata": {
"addresses": {
"home": "123 Main Street, Anytown, ST 12345",
"work": "100 Industrial Way, Anytown, ST 12345"
}
}
}
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を追加する方法の詳細については、「追加のサインアップフィールド」をお読みください。Rules will reach end of life (EOL) on January 31, 2028.
- As of October 16, 2023, Rules are no longer available in newly created tenants.
- As of November 18, 2024, Rules are read-only. Active Rules still run, and you can enable or disable them and change their configuration values and secrets. You can’t edit their code in the Dashboard, the Management API, or tools that use it, such as the Auth0 CLI, Deploy CLI, Terraform, and Agent Skills.
- After January 31, 2028, Rules stop running and are removed.
Use Actions to extend Auth0:
- To learn more about Actions, read Understand How Auth0 Actions Work.
- To migrate, read Migrate from Rules to Actions.
{
"user_id": "jdoe",
"email": "john.doe@example.com",
"app_metadata": {
"roles": [ "writer" ]
},
"user_metadata": {
"preferences": {
"color": "blue"
}
}
}
メタデータの読み取り
を使用すると、ルールでメタデータを読み取ることができます。また、user_metadataでは、次のようなプロファイル関連の情報を検索することもできます。namenicknamegiven_namefamily_name
jane.doe@example.com のユーザーに次のメタデータが保存されているとします:{
"email": "jane.doe@example.com",
"user_metadata": {
"hobby": "surfing"
},
"app_metadata": {
"plan": "full"
}
}
console.log(user.email); // "jane.doe@example.com"
console.log(user.user_metadata.hobby); // "surfing"
console.log(user.app_metadata.plan); // "full"
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);
});
}
{
"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);
});
}
{
"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);
});
}
{
"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);
});
}
{
"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);
});
}
{
"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);
});
}
{
"user_id": "jdoe",
"email": "john.doe@example.com",
"app_metadata": {
"roles": [ "writer" ]
},
"user_metadata": {
"preferences": { }
}
}