カスタムクレームを作成する

アクセストークンと上のカスタムクレームを読み取るには、 (JWT) を使用し、OIDC のログインフローで (aud) を渡す必要があります。詳しくは、アクセストークンを参照してください。 JWT でカスタムクレームを設定する際は、名前の衝突を避ける必要があります。カスタムクレームが予約済みクレームや他のリソースのクレームと衝突しないよう、衝突しにくい名前を付けてください。Auth0 では、名前空間付き形式の使用を推奨しています。

Auth0 では名前空間付きクレームと名前空間なしクレームの両方を使用できますが、いくつかの制限があります (一般的な制限事項を参照) 。名前の衝突を避けるため、名前空間付きクレームの使用を推奨します。衝突が発生してもトランザクションは失敗しませんが、カスタムクレームはトークンに追加されません。

一般的な制限

Auth0 では、カスタムクレームに次の制限が適用されます。

カスタムクレームのペイロードの上限は 100KB です
OPENID 標準クレームおよび Auth0 が内部で使用するクレームは、カスタマイズまたは変更できません
/userinfo エンドポイントを除き、Auth0 API のオーディエンスを持つには、名前空間なしのプライベートなカスタムクレームを含めることはできません
指定された OIDC のユーザープロフィールクレームのみをアクセストークンに追加できます

以下のクレームは Auth0 の制限対象です。

acr
act
active
amr
at_hash
ath
attest
aud
auth_time
authorization_details
azp
c_hash
client_id
cnf
cty
dest
entitlements
events
exp
groups
gty
htm
htu
iat
internalService
iss
jcard
jku
jti
jwe
jwk
kid
may_act
mky
nbf
nonce
object_id
org_id
org_name
orig
origid
permissions
roles
rph
s_hash
sid
sip_callid
sip_cseq_num
sip_date
sip_from_tag
sip_via_branch
sub
sub_jwk
toe
txn
typ
uuid
vot
vtm
x5t#S256

制限対象ではないクレーム

機微なユーザー情報に関するクレームを作成すると、ユーザープロフィールを充実させ、ユーザー体験を向上させることができます。これらのクレームは、アプリケーションがIDトークンから利用します。制限対象ではないクレームの使用方法について詳しくは、IDトークンを参照してください。使用する場合は、トークンのベストプラクティスも考慮してください。次のクレームには、一般的な制限のみが適用されます。

address
birthdate
email
email_verified
family_name
gender
given_name
locale
middle_name
name
nickname
phone_number
phone_number_verified
picture
preferred_username
profile
updated_at
website
zoneinfo

名前空間付きガイドライン

Auth0 URN urn:auth0 は、名前空間識別子として使用できません。

名前空間識別子については、次のガイドラインに従ってください。

名前空間識別子には、Auth0 以外の任意の HTTP または HTTPS URL を使用します。Auth0 のドメインは名前空間識別子として使用できません。具体的には、次のものが該当します。
- auth0.com
- webtask.io
- webtask.run
名前空間識別子には、自身で管理している URL を使用します。これにより、他者が同じ名前空間を使用しているリスクを回避できます。名前空間 URL は、実際のリソースを指している必要はありません。これは識別子としてのみ使用され、呼び出されることはありません。
URL は http:// または https:// で始めます。
また、カスタム API を使用する場合は、URN ベースの名前空間識別子を使用することもできます。その場合、Auth0 URN urn:auth0 は予約されているため、名前空間識別子として使用できません。
必要に応じて、複数の名前空間を作成します。

名前空間を選択したら、それにクレームを追加して、トークンに追加できる名前空間付きクレームを作成します。例: http://www.example.com/favorite_color

名前空間なしのガイドライン

名前空間なしのカスタムクレームには、次のガイドラインに従ってください。

アプリケーションで絶対に必要な場合を除き、衝突しにくい公開の名前空間付きカスタムクレームを使用してください。
クレームは、意味が明確で衝突しにくい名前で作成してください。たとえば、e_id ではなく employee_id を使用します。
クレーム名と値はできるだけ軽量にし、アプリケーションに本当に必要なデータだけを渡してください。
カスタムクレームに大きなペイロードを設定するのは避けてください。

トークンに追加するカスタムクレームの例については、サンプルユースケース: スコープとクレームを参照してください。