方法:アプリに省略可能な要求を提供するHow to: Provide optional claims to your app

アプリケーション開発者は、Azure AD アプリケーションで省略可能な要求を使用して、アプリケーションに送信されるトークンに含めたい要求を指定できます。Application developers can use optional claims in their Azure AD applications to specify which claims they want in tokens sent to their application.

次の処理に省略可能な要求を使用できます。You can use optional claims to:

  • アプリケーションのトークンに含める追加の要求を選択する。Select additional claims to include in tokens for your application.
  • Microsoft ID プラットフォームからトークンで返される特定の要求の動作を変更する。Change the behavior of certain claims that Microsoft identity platform returns in tokens.
  • アプリケーションのカスタムの要求を追加してアクセスする。Add and access custom claims for your application.

標準の要求の一覧については、アクセス トークンid_token の要求のドキュメントを参照してください。For the lists of standard claims, see the access token and id_token claims documentation.

省略可能な要求は v1.0 と v2.0 の両方の形式のトークンと、SAML トークンでサポートされていますが、v1.0 から v2.0 に移行すると、最大限の価値が得られます。While optional claims are supported in both v1.0 and v2.0 format tokens, as well as SAML tokens, they provide most of their value when moving from v1.0 to v2.0. v2.0 の Microsoft ID プラットフォーム エンドポイントの目標の 1 つは、トークン サイズを小さくしてクライアントによる最適なパフォーマンスを確保することです。One of the goals of the v2.0 Microsoft identity platform endpoint is smaller token sizes to ensure optimal performance by clients. その結果、以前のバージョンではアクセス トークンと ID トークンに含まれていた一部の要求は、v2.0 トークンでは削除されたため、アプリケーションごとに具体的に要求する必要があります。As a result, several claims formerly included in the access and ID tokens are no longer present in v2.0 tokens and must be asked for specifically on a per-application basis.

表 1:適用性Table 1: Applicability

アカウントの種類Account Type v1.0 トークンv1.0 tokens v2.0 トークンv2.0 tokens
個人用 Microsoft アカウントPersonal Microsoft account 該当なしN/A サポートされていますSupported
Azure AD アカウントAzure AD account サポートされていますSupported サポートされていますSupported

v1.0 と v2.0 の省略可能な要求セットv1.0 and v2.0 optional claims set

既定でアプリケーションが使用できる省略可能な要求セットを以下に示します。The set of optional claims available by default for applications to use are listed below. アプリケーションにカスタムの省略可能な要求を追加する方法については、後述のディレクトリ拡張に関するセクションを参照してください。To add custom optional claims for your application, see Directory Extensions, below. 要求をアクセス トークンに追加する場合、その要求は、アプリケーション (Web API) "によって" 求められた要求ではなく、アプリケーション "に対して" 要求されたアクセス トークンに適用されます。When adding claims to the access token, the claims apply to access tokens requested for the application (a web API), not claims requested by the application. クライアントがどのように API にアクセスしても、API に対する認証のために使用するアクセス トークンに、適切なデータが確実に存在します。No matter how the client accesses your API, the right data is present in the access token that is used to authenticate against your API.

注意

このような要求の大部分は v1.0 および v2.0 トークンの JWT に含めることができますが、「トークンの種類」列に記載されている場合を除き、SAML トークンに含めることはできません。The majority of these claims can be included in JWTs for v1.0 and v2.0 tokens, but not SAML tokens, except where noted in the Token Type column. コンシューマー アカウントにより、"ユーザーの種類" 列でマークされている要求のサブセットがサポートされます。Consumer accounts support a subset of these claims, marked in the "User Type" column. 表示されている要求の多くは、コンシューマー ユーザーに適用されません (テナントがなく、tenant_ctry 値がないためです)。Many of the claims listed do not apply to consumer users (they have no tenant, so tenant_ctry has no value).

表 2: v1.0 と v2.0 の省略可能な要求セットTable 2: v1.0 and v2.0 optional claim set

名前Name 説明Description トークンの種類Token Type ユーザーの種類User Type NotesNotes
auth_time ユーザーが最後に認証された時刻。Time when the user last authenticated. OpenID Connect の仕様を参照してください。See OpenID Connect spec. JWTJWT
tenant_region_scope リソースのテナントのリージョンRegion of the resource tenant JWTJWT
sid セッション ID。セッションごとのユーザーのサインアウトに使用されます。Session ID, used for per-session user sign-out. JWTJWT 個人用アカウントと Azure AD アカウント。Personal and Azure AD accounts.
verified_primary_email ユーザーの PrimaryAuthoritativeEmail が送信元ですSourced from the user's PrimaryAuthoritativeEmail JWTJWT
verified_secondary_email ユーザーの SecondaryAuthoritativeEmail が送信元ですSourced from the user's SecondaryAuthoritativeEmail JWTJWT
vnet VNET 指定子情報。VNET specifier information. JWTJWT
fwd IP アドレス。IP address. JWTJWT 要求側クライアントの元の IPv4 アドレスを追加します (VNET 内の場合)Adds the original IPv4 address of the requesting client (when inside a VNET)
ctry ユーザーの国またはリージョンUser's country/region JWT、SAMLJWT, SAML Azure AD は、存在する場合、ctry の省略可能な要求を返します。フィールドの値は、FR、JP、SZ などの標準の 2 文字の国またはリージョン番号です。Azure AD returns the ctry optional claim if it's present and the value of the field is a standard two-letter country/region code, such as FR, JP, SZ, and so on.
tenant_ctry リソース テナントの国Resource tenant's country JWTJWT 管理者がテナント レベルを設定することを除き ctry と同じです。また、標準の 2 文字値にする必要があります。Same as ctry except set at a tenant level by an admin. Must also be a standard two-letter value.
xms_pdl 優先されるデータの場所Preferred data location JWTJWT Multi-Geo テナントの場合、優先されるデータの場所は、ユーザーがどの地域にいるかを示す 3 文字のコードです。For Multi-Geo tenants, the preferred data location is the three-letter code showing the geographic region the user is in. 詳細については、優先されるデータの場所に関する Azure AD Connect のドキュメントを参照してください。For more info, see the Azure AD Connect documentation about preferred data location.
たとえば、アジア太平洋の場合は APC です。For example: APC for Asia Pacific.
xms_pl ユーザーの優先する言語User preferred language JWTJWT ユーザーの優先する言語 (設定されている場合)。The user's preferred language, if set. ゲスト アクセスのシナリオの場合、ソースはホーム テナントです。Sourced from their home tenant, in guest access scenarios. LL-CC ("en-us") という形式です。Formatted LL-CC ("en-us").
xms_tpl テナントの優先する言語Tenant preferred language JWTJWT リソース テナントの優先する言語 (設定されている場合)。The resource tenant's preferred language, if set. LL ("en") という形式です。Formatted LL ("en").
ztdid ゼロタッチ デプロイ IDZero-touch Deployment ID JWTJWT Windows AutoPilot に使用されるデバイス IDThe device identity used for Windows AutoPilot
email このユーザーのアドレス指定可能なメール アドレス (ユーザーが持っている場合)。The addressable email for this user, if the user has one. JWT、SAMLJWT, SAML MSA、Azure ADMSA, Azure AD ユーザーがテナントのゲストである場合、この値は既定で含まれます。This value is included by default if the user is a guest in the tenant. マネージド ユーザー (テナント内のユーザー) の場合は、この省略可能な要求により、または OpenID スコープで (v2.0 の場合のみ)、それを要求する必要があります。For managed users (the users inside the tenant), it must be requested through this optional claim or, on v2.0 only, with the OpenID scope. マネージド ユーザーの場合、メール アドレスは Office 管理ポータルで設定する必要があります。For managed users, the email address must be set in the Office admin portal.
acct テナント内のユーザー アカウントの状態Users account status in tenant JWT、SAMLJWT, SAML ユーザーがテナントのメンバーである場合、値は 0 です。If the user is a member of the tenant, the value is 0. ユーザーがゲストの場合、値は 1 です。If they are a guest, the value is 1.
groups グループ要求の省略可能な形式Optional formatting for group claims JWT、SAMLJWT, SAML アプリケーション マニフェスト の GroupMembershipClaims 設定と共に使用されます (こちらも設定する必要があります)。Used in conjunction with the GroupMembershipClaims setting in the application manifest, which must be set as well. 詳細については、後述のグループ要求に関する説明を参照してください。For details see Group claims below. グループ要求の詳細については、グループ要求の構成方法に関する記事を参照してくださいFor more information about group claims, see How to configure group claims
upn UserPrincipalNameUserPrincipalName JWT、SAMLJWT, SAML この要求は自動的に含まれますが、省略可能な要求として、ゲスト ユーザーの場合に動作を変更するために追加のプロパティをアタッチする要求を指定することもできます。Although this claim is automatically included, you can specify it as an optional claim to attach additional properties to modify its behavior in the guest user case.
idtyp トークンの種類Token type JWT のアクセス トークンJWT access tokens 特殊: アプリ専用アクセス トークンのみSpecial: only in app-only access tokens トークンがアプリ専用トークンの場合、値は app です。Value is app when the token is an app-only token. API を使用してトークンがアプリ トークンかアプリ + ユーザー トークンかを判断する場合、これが最も正確な方法です。This is the most accurate way for an API to determine if a token is an app token or an app+user token.

v2.0 固有の省略可能な要求セットv2.0-specific optional claims set

これらの要求は常に v1.0 Azure AD トークンに含まれますが、要求されない限り v2.0 トークンには含まれません。These claims are always included in v1.0 Azure AD tokens, but not included in v2.0 tokens unless requested. これらの要求は、JWT (ID トークンとアクセス トークン) にのみ適用されます。These claims are only applicable for JWTs (ID tokens and Access Tokens).

表 3: v2.0 のみの省略可能な要求Table 3: v2.0-only optional claims

JWT の要求JWT Claim 名前Name 説明Description NotesNotes
ipaddr IP アドレスIP Address ログインしたクライアントの IP アドレス。The IP address the client logged in from.
onprem_sid オンプレミスのセキュリティ IDOn-Premises Security Identifier
pwd_exp パスワードの有効期限Password Expiration Time パスワードの有効期限が切れる日時。The datetime at which the password expires.
pwd_url パスワードの変更 URLChange Password URL ユーザーがパスワードを変更するためにアクセスできる URL。A URL that the user can visit to change their password.
in_corp 企業ネットワーク内Inside Corporate Network クライアントが企業ネットワークからログインしている場合に通知します。Signals if the client is logging in from the corporate network. そうでない場合、この要求は含まれません。If they're not, the claim isn't included. MFA の信頼できる IP の設定に基づきます。Based off of the trusted IPs settings in MFA.
family_name Last Name ユーザー オブジェクトで定義されたユーザーの姓を示します。Provides the last name, surname, or family name of the user as defined in the user object.
"family_name":"Miller""family_name":"Miller"
MSA と Azure AD でサポートされています。Supported in MSA and Azure AD. profile スコープが必要です。Requires the profile scope.
given_name First name ユーザー オブジェクトに設定されたユーザーの名を示します。Provides the first or "given" name of the user, as set on the user object.
"given_name":"Frank""given_name": "Frank"
MSA と Azure AD でサポートされています。Supported in MSA and Azure AD . profile スコープが必要です。Requires the profile scope.
upn ユーザー プリンシパル名User Principal Name username_hint パラメーターで使用できるユーザーの識別子。An identifer for the user that can be used with the username_hint parameter. そのユーザーの持続的な識別子ではないため、重要なデータには使用しないでください。Not a durable identifier for the user and should not be used to key data. 要求の構成については、下の追加のプロパティを参照してください。See additional properties below for configuration of the claim. profile スコープが必要です。Requires the profile scope.

省略可能な要求の追加のプロパティAdditional properties of optional claims

一部の省略可能な要求は、要求が返される方法を変更するように構成することができます。Some optional claims can be configured to change the way the claim is returned. これらの追加のプロパティは、ほとんどの場合、さまざまなデータが予測されるオンプレミス アプリケーションの移行を容易にするために使用されます (たとえば、include_externally_authenticated_upn_without_hash は UPN 内のハッシュ マーク (#) を処理できないクライアントで役立ちます)。These additional properties are mostly used to help migration of on-premises applications with different data expectations (for example, include_externally_authenticated_upn_without_hash helps with clients that cannot handle hash marks (#) in the UPN)

表 4:省略可能な要求を構成するための値Table 4: Values for configuring optional claims

プロパティ名Property name 追加のプロパティ名Additional Property name 説明Description
upn SAML 応答と JWT 応答の両方や、v1.0 および v2.0 トークンに使用できます。Can be used for both SAML and JWT responses, and for v1.0 and v2.0 tokens.
include_externally_authenticated_upn リソース テナントに格納されているゲスト UPN が含まれます。Includes the guest UPN as stored in the resource tenant. たとえば、foo_hometenant.com#EXT#@resourcetenant.com のように指定します。For example, foo_hometenant.com#EXT#@resourcetenant.com
include_externally_authenticated_upn_without_hash ハッシュ マーク (#) がアンダースコア (_) に置き換えられる点を除き、上と同じです。例: foo_hometenant.com_EXT_@resourcetenant.comSame as above, except that the hash marks (#) are replaced with underscores (_), for example foo_hometenant.com_EXT_@resourcetenant.com

追加のプロパティの例Additional properties example

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

この OptionalClaims オブジェクトにより、ID トークンがクライアントに返され、追加のホーム テナントとリソース テナントの情報を持つ UPN 要求が含められます。This OptionalClaims object causes the ID token returned to the client to include a upn claim with the additional home tenant and resource tenant information. トークンの upn 要求は、ユーザーが (認証に異なる IDP を使用する) テナントのゲストである場合にのみ変更されます。The upn claim is only changed in the token if the user is a guest in the tenant (that uses a different IDP for authentication).

省略可能な要求の構成Configuring optional claims

重要

アクセス トークンは、クライアントではなく、常にリソースのマニフェストを使用して生成されます。Access tokens are always generated using the manifest of the resource, not the client. そのため、...scope=https://graph.microsoft.com/user.read... 要求では、リソースは Microsoft Graph API になります。So in the request ...scope=https://graph.microsoft.com/user.read... the resource is the Microsoft Graph API. したがって、アクセス トークンは、クライアントのマニフェストではなく、Microsoft Graph API マニフェストを使用して作成されます。Thus, the access token is created using the Microsoft Graph API manifest, not the client's manifest. アプリケーションのマニフェストを変更しても、Microsoft Graph API のトークンが変更されることはありません。Changing the manifest for your application will never cause tokens for the Microsoft Graph API to look different. accessToken の変更が有効であることを確認するには、他のアプリではなく、自分のアプリケーションのトークンを要求します。In order to validate that your accessToken changes are in effect, request a token for your application, not another app.

UI またはアプリケーション マニフェストを使用して、アプリケーションの省略可能な要求を構成できます。You can configure optional claims for your application through the UI or application manifest.

  1. Azure ポータルにアクセスします。Go to the Azure portal. Azure Active Directory を検索して選択します。Search for and select Azure Active Directory.
  2. [管理] セクションで、 [アプリの登録] を選択します。From the Manage section, select App registrations.
  3. 省略可能な要求を構成するアプリケーションを一覧から選択します。Select the application you want to configure optional claims for in the list.

UI を使用した省略可能な要求の構成:Configuring optional claims through the UI:

UI で省略可能な要求を構成するConfigure optional claims in the UI

  1. [管理] セクションで、 [トークン構成] を選択します。From the Manage section, select Token configuration.
  2. [省略可能な要求を追加] を選択します。Select Add optional claim.
  3. 構成するトークンの型を選択します。Select the token type you want to configure.
  4. 追加する省略可能な要求を選択します。Select the optional claims to add.
  5. [追加] を選択します。Select Add.

アプリケーションマニフェストを使用した省略可能な要求の構成:Configuring optional claims through the application manifest:

アプリ マニフェストを使用して省略可能な要求を構成する方法を示しますShows how to configure optional claims using the app manifest

  1. [管理] セクションで、 [マニフェスト] を選択します。From the Manage section, select Manifest. Web ベースのマニフェスト エディターが開き、マニフェストを編集できます。A web-based manifest editor opens, allowing you to edit the manifest. 必要があれば、 [ダウンロード] を選択してローカルでマニフェストを編集します。その後、 [アップロード] を使用して、アプリケーションにマニフェストを再適用します。Optionally, you can select Download and edit the manifest locally, and then use Upload to reapply it to your application. アプリケーションマニフェストの詳細については、「Azure AD アプリケーションマニフェストについて」を参照してください。For more information on the application manifest, see the Understanding the Azure AD application manifest article.

    次のアプリケーション マニフェストのエントリにより、auth_time、ipaddr、および upn の省略可能な要求が ID、アクセス、および SAML トークンに追加されます。The following application manifest entry adds the auth_time, ipaddr, and upn optional claims to ID, access, and SAML tokens.

    "optionalClaims": {
        "idToken": [
            {
                "name": "auth_time",
                "essential": false
            }
        ],
        "accessToken": [
            {
                "name": "ipaddr",
                "essential": false
            }
        ],
        "saml2Token": [
            {
                "name": "upn",
                "essential": false
            },
            {
                "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
                "source": "user",
                "essential": false
            }
        ]
    }
    
  2. 終わったら、 [保存] を選択します。When finished, select Save. これで、指定された省略可能な要求がアプリケーションのトークンに含まれるようになります。Now the specified optional claims will be included in the tokens for your application.

OptionalClaims 型OptionalClaims type

アプリケーションから要求する省略可能な要求を宣言します。Declares the optional claims requested by an application. アプリケーションは、セキュリティ トークン サービスから受信できる 3 種類の各トークン (ID トークン、アクセス トークン、SAML 2 トークン) で返される省略可能な要求を構成できます。An application can configure optional claims to be returned in each of three types of tokens (ID token, access token, SAML 2 token) it can receive from the security token service. アプリケーションは、トークンの種類ごとに返される異なる省略可能な要求セットを構成できます。The application can configure a different set of optional claims to be returned in each token type. アプリケーション エンティティの OptionalClaims プロパティは、OptionalClaims オブジェクトです。The OptionalClaims property of the Application entity is an OptionalClaims object.

表 5:OptionalClaims 型のプロパティTable 5: OptionalClaims type properties

名前Name 種類Type 説明Description
idToken コレクション (OptionalClaim)Collection (OptionalClaim) JWT ID トークンで返される省略可能な要求。The optional claims returned in the JWT ID token.
accessToken コレクション (OptionalClaim)Collection (OptionalClaim) JWT アクセス トークンで返される省略可能な要求。The optional claims returned in the JWT access token.
saml2Token コレクション (OptionalClaim)Collection (OptionalClaim) JWT SAML トークンで返される省略可能な要求。The optional claims returned in the SAML token.

OptionalClaim 型OptionalClaim type

アプリケーションまたはサービス プリンシパルに関連付けられている省略可能な要求が含まれます。Contains an optional claim associated with an application or a service principal. OptionalClaims 型の idToken、accessToken、および saml2Token プロパティは、OptionalClaim のコレクションです。The idToken, accessToken, and saml2Token properties of the OptionalClaims type is a collection of OptionalClaim. 特定の要求でサポートされている場合は、AdditionalProperties フィールドを使用して OptionalClaim の動作を変更することもできます。If supported by a specific claim, you can also modify the behavior of the OptionalClaim using the AdditionalProperties field.

表 6:OptionalClaim 型のプロパティTable 6: OptionalClaim type properties

名前Name 種類Type 説明Description
name Edm.StringEdm.String 省略可能な要求の名前。The name of the optional claim.
source Edm.StringEdm.String 要求のソース (ディレクトリ オブジェクト)。The source (directory object) of the claim. 定義済みの要求と、拡張プロパティのユーザー定義の要求があります。There are predefined claims and user-defined claims from extension properties. ソース値が null の場合、この要求は定義済みの省略可能な要求です。If the source value is null, the claim is a predefined optional claim. ソース値が user の場合、name プロパティの値はユーザー オブジェクトの拡張プロパティです。If the source value is user, the value in the name property is the extension property from the user object.
essential Edm.BooleanEdm.Boolean 値が true の場合、エンド ユーザーから要求された特定のタスクの承認エクスペリエンスを円滑にするために、クライアントに指定された要求が必要です。If the value is true, the claim specified by the client is necessary to ensure a smooth authorization experience for the specific task requested by the end user. 既定値は false です。The default value is false.
additionalProperties コレクション (Edm.String)Collection (Edm.String) 要求の追加のプロパティ。Additional properties of the claim. このコレクションにプロパティが存在する場合、name プロパティに指定された省略可能な要求の動作が変更されます。If a property exists in this collection, it modifies the behavior of the optional claim specified in the name property.

ディレクトリ拡張機能の省略可能な要求の構成Configuring directory extension optional claims

標準の省略可能な要求セットに加え、拡張機能を含むようにトークンを構成することもできます。In addition to the standard optional claims set, you can also configure tokens to include extensions. 詳細については、Microsoft Graph extensionProperty のドキュメントを参照してください。For more info, see the Microsoft Graph extensionProperty documentation.

スキーマとオープン拡張機能は、省略可能な要求ではサポートされず、AAD-Graph スタイルのディレクトリ拡張機能のみがサポートされます。Schema and open extensions are not supported by optional claims, only the AAD-Graph style directory extensions. ユーザーが設定した追加の識別子や重要な構成オプションなど、アプリで使用できる追加のユーザー情報をアタッチする場合にこの機能が便利です。This feature is useful for attaching additional user information that your app can use – for example, an additional identifier or important configuration option that the user has set. 例については、このページの最後を参照してください。See the bottom of this page for an example.

注意

ディレクトリ スキーマ拡張機能は、Azure AD のみの機能です。Directory schema extensions are an Azure AD-only feature. アプリケーション マニフェストでカスタム拡張機能が要求され、MSA ユーザーがアプリにログインした場合、これらの拡張機能は返されません。If your application manifest requests a custom extension and an MSA user logs in to your app, these extensions will not be returned.

ディレクトリ拡張の形式Directory extension formatting

アプリケーション マニフェストを使用してディレクトリ拡張機能の省略可能な要求を構成する場合は、拡張機能の完全な名前 (形式: extension_<appid>_<attributename>) を使用します。When configuring directory extension optional claims using the application manifest, use the full name of the extension (in the format: extension_<appid>_<attributename>). <appid> は、要求を必須にしているアプリケーションの ID と一致する必要があります。The <appid> must match the ID of the application requesting the claim.

JWT 内では、このような要求は extn.<attributename> という形式の名前で発行されます。Within the JWT, these claims will be emitted with the following name format: extn.<attributename>.

SAML トークン内では、このような要求は http://schemas.microsoft.com/identity/claims/extn.<attributename> という URI 形式で発行されます。Within the SAML tokens, these claims will be emitted with the following URI format: http://schemas.microsoft.com/identity/claims/extn.<attributename>

グループの省略可能な要求を構成するConfiguring groups optional claims

注意

ユーザーとグループについて、オンプレミスからの同期されたグループ名を出力する機能は、パブリック プレビュー段階です。The ability to emit group names for users and groups synced from on-premises is Public Preview.

このセクションでは、グループ要求で使用されるグループ属性を、既定のグループ objectID からオンプレミス Windows Active Directory から同期される属性へ変更するための、省略可能な要求の構成オプションについて説明します。This section covers the configuration options under optional claims for changing the group attributes used in group claims from the default group objectID to attributes synced from on-premises Windows Active Directory. UI またはアプリケーション マニフェストを使用して、アプリケーションのグループの省略可能な要求を構成できます。You can configure groups optional claims for your application through the UI or application manifest.

重要

オンプレミス属性からのグループ要求のパブリック プレビューに関する重要な注意事項などの詳細については、「Azure AD を使用してアプリケーションに対するグループ要求を構成する」を参照してください。For more details including important caveats for the public preview of group claims from on-premises attributes, see Configure group claims for applications with Azure AD.

UI を使用したグループの省略可能な要求の構成:Configuring groups optional claims through the UI:

  1. Azure ポータルSign in to the Azure portal
  2. 認証が完了したら、ページの右上隅から Azure AD テナントを選択しますAfter you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page
  3. 左側のメニューで、 [Azure Active Directory] を選択しますSelect Azure Active Directory from the left-hand menu
  4. [管理] セクションで、 [アプリの登録] を選択しますUnder the Manage section, select App registrations
  5. 省略可能な要求を構成するアプリケーションを一覧から選択しますSelect the application you want to configure optional claims for in the list
  6. [管理] セクションで、 [トークン構成] を選択します。Under the Manage section, select Token configuration
  7. [Add groups claim](グループの要求の追加) を選択しますSelect Add groups claim
  8. 返すグループの種類を選択します ( [セキュリティ グループ][ディレクトリ ロール][すべてのグループ][アプリケーションに割り当てられているグループ] )。Select the group types to return (Security groups, or Directory roles, All groups, and/or Groups assigned to the application). [アプリケーションに割り当てられているグループ] オプションには、アプリケーションに割り当てられたグループのみが含まれます。The Groups assigned to the application option includes only groups assigned to the application. [すべてのグループ] オプションには、SecurityGroupDirectoryRole、および DistributionList が含まれますが、 [アプリケーションに割り当てられているグループ] は含まれません。The All Groups option includes SecurityGroup, DirectoryRole, and DistributionList, but not Groups assigned to the application.
  9. 省略可能: 特定のトークンの種類のプロパティを選択して、オンプレミスのグループ属性を含めるようにグループの要求値を変更したり、要求の種類をロールに変更したりしますOptional: select the specific token type properties to modify the groups claim value to contain on premises group attributes or to change the claim type to a role
  10. [保存] を選びます。Select Save

アプリケーション マニフェストを使用したグループの省略可能な要求の構成:Configuring groups optional claims through the application manifest:

  1. Azure ポータルSign in to the Azure portal

  2. 認証が完了したら、ページの右上隅から Azure AD テナントを選択しますAfter you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page

  3. 左側のメニューで、 [Azure Active Directory] を選択しますSelect Azure Active Directory from the left-hand menu

  4. 省略可能な要求を構成するアプリケーションを一覧から選択しますSelect the application you want to configure optional claims for in the list

  5. [管理] セクションで、 [マニフェスト] を選択しますUnder the Manage section, select Manifest

  6. マニフェスト エディターを使用して、次のエントリを追加します。Add the following entry using the manifest editor:

    有効な値は次のとおりです。The valid values are:

    • "All" (このオプションには [SecurityGroup]、[DirectoryRole]、および [DistributionList] が含まれます)"All" (this option includes SecurityGroup, DirectoryRole, and DistributionList)
    • "SecurityGroup""SecurityGroup"
    • "DirectoryRole""DirectoryRole"
    • "ApplicationGroup " (このオプションには、アプリケーションに割り当てられているグループのみが含まれます)"ApplicationGroup" (this option includes only groups that are assigned to the application)

    次に例を示します。For example:

    "groupMembershipClaims": "SecurityGroup"
    

    既定では、グループの ObjectID は、グループ要求の値に出力されます。By default Group ObjectIDs will be emitted in the group claim value. オンプレミス グループ属性を含むように要求の値を変更するか、または要求の種類をロールに変更するには、次のように OptionalClaims 構成を使用します。To modify the claim value to contain on premises group attributes, or to change the claim type to role, use OptionalClaims configuration as follows:

  7. グループ名の構成を [optional claims](オプションの要求) に設定します。Set group name configuration optional claims.

    [optional claims](オプションの要求) セクションにあるオンプレミス AD グループ属性をトークン内のグループに含める場合は、オプション要求の適用先となるトークンの種類、要求されるオプション要求の名前、および必要な追加のプロパティを指定します。If you want to groups in the token to contain the on premises AD group attributes in the optional claims section specify which token type optional claim should be applied to, the name of optional claim requested and any additional properties desired. 次に示す複数のトークンの種類が、一覧に表示される可能性があります。Multiple token types can be listed:

    • OIDC ID トークン用の idTokenidToken for the OIDC ID token
    • OAuth アクセス トークン用の accessTokenaccessToken for the OAuth access token
    • SAML トークン用の Saml2TokenSaml2Token for SAML tokens.

    注意

    Saml2Token の種類は、SAML1.1 および SAML2.0 両方の形式のトークンに適用されます。The Saml2Token type applies to both SAML1.1 and SAML2.0 format tokens

    関連する各トークンの種類に対して、マニフェストにある OptionalClaims セクションを使用するようにグループ要求を変更します。For each relevant token type, modify the groups claim to use the OptionalClaims section in the manifest. OptionalClaims スキーマは次のようになっています。The OptionalClaims schema is as follows:

    {
        "name": "groups",
        "source": null,
        "essential": false,
        "additionalProperties": []
    }
    
    省略可能な要求のスキーマOptional claims schema Value
    name:name: 必ず "groups" になりますMust be "groups"
    source:source: 使用されていません。Not used. 省略するか、null を指定しますOmit or specify null
    essential:essential: 使用されていません。Not used. 省略するか、false を指定しますOmit or specify false
    additionalProperties:additionalProperties: その他のプロパティのリスト。List of additional properties. 有効なオプション: "sam_account_name"、"dns_domain_and_sam_account_name"、"netbios_domain_and_sam_account_name"、"emit_as_roles"Valid options are "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "emit_as_roles"

    additionalProperties では、"sam_account_name"、"dns_domain_and_sam_account_name"、"netbios_domain_and_sam_account_name" のいずれか 1 つのみが必要です。In additionalProperties only one of "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name" are required. 複数ある場合、最初の 1 つが使用され、それ以外は無視されます。If more than one is present, the first is used and any others ignored.

    アプリケーションによっては、ロール要求内にユーザーに関するグループ情報が必要になります。Some applications require group information about the user in the role claim. 要求の種類をグループ要求からロール要求に変更するには、"emit_as_roles" を追加のプロパティに付け加えます。To change the claim type to from a group claim to a role claim, add "emit_as_roles" to additional properties. グループの値が、ロール要求内に出力されます。The group values will be emitted in the role claim.

    注意

    "emit_as_roles" が使用された場合、ユーザーが割り当て済みとして構成されているアプリケーション ロールは、ロール要求には表示されませんIf "emit_as_roles" is used any Application Roles configured that the user is assigned will not appear in the role claim

例:Examples:

  1. OAuth アクセス トークンで netbiosDomain\sAMAccountName 形式でグループ名をグループとして出力するEmit groups as group names in OAuth access tokens in dnsDomainName\sAMAccountName format

    UI の構成:UI configuration:

    省略可能な要求の構成Configure optional claims

    アプリケーションマニフェストのエントリ:Application manifest entry:

    "optionalClaims": {
        "accessToken": [
            {
                "name": "groups",
                "additionalProperties": [
                    "dns_domain_and_sam_account_name"
                ]
            }
        ]
    }
    
  2. SAML および OIDC ID トークンのロール要求として、 netbiosDomain\sAMAccountName 形式で返されるグループ名を出力しますEmit group names to be returned in netbiosDomain\sAMAccountName format as the roles claim in SAML and OIDC ID Tokens

    UI の構成:UI configuration:

    マニフェストの省略可能な要求Optional claims in manifest

    アプリケーションマニフェストのエントリ:Application manifest entry:

    "optionalClaims": {
        "saml2Token": [
            {
                "name": "groups",
                "additionalProperties": [
                    "netbios_name_and_sam_account_name",
                    "emit_as_roles"
                ]
            }
        ],
        "idToken": [
            {
                "name": "groups",
                "additionalProperties": [
                    "netbios_name_and_sam_account_name",
                    "emit_as_roles"
                ]
            }
        ]
    }
    

省略可能な要求の例Optional claims example

このセクションでは、シナリオを使って、省略可能な要求機能をアプリケーションに使用する手順について説明します。In this section, you can walk through a scenario to see how you can use the optional claims feature for your application. アプリケーションの ID 構成に関するプロパティを更新し、省略可能な要求を有効にして構成するには、複数のオプションがあります。There are multiple options available for updating the properties on an application's identity configuration to enable and configure optional claims:

例:Example:

次の例では、トークン構成 UI とマニフェストを使用して、アプリケーション用のアクセス、ID、および SAML トークンに省略可能な要求を追加します。In the example below, you will use the Token configuration UI and Manifest to add optional claims to the access, ID, and SAML tokens intended for your application. アプリケーションが受け取ることができるトークンの型ごとに、さまざまな省略可能な要求が追加されます:Different optional claims will be added to each type of token that the application can receive:

  • ID トークンには、完全な形式 (<upn>_<homedomain>#EXT#@<resourcedomain>) のフェデレーション ユーザーの UPN が含まれるようになります。The ID tokens will now contain the UPN for federated users in the full form (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • 他のクライアントがこのアプリケーションに要求するアクセス トークンには、auth_time 要求が含まれるようになりますThe access tokens that other clients request for this application will now include the auth_time claim
  • SAML トークンに skypeId ディレクトリ スキーマ拡張機能が含まれるようになります (この例では、このアプリのアプリ ID は ab603c56068041afb2f6832e2a17e237 です)。The SAML tokens will now contain the skypeId directory schema extension (in this example, the app ID for this app is ab603c56068041afb2f6832e2a17e237). SAML トークンは Skype ID を extension_skypeId として公開します。The SAML tokens will expose the Skype ID as extension_skypeId.

UI の構成:UI configuration:

  1. Azure ポータルSign in to the Azure portal

  2. 認証が完了したら、ページの右上隅から Azure AD テナントを選択します。After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. 左側のメニューで、 [Azure Active Directory] を選択します。Select Azure Active Directory from the left-hand menu.

  4. [管理] セクションで、 [アプリの登録] を選択します。Under the Manage section, select App registrations.

  5. 省略可能な要求を構成するアプリケーションを一覧から探して選択します。Find the application you want to configure optional claims for in the list and select it.

  6. [管理] セクションで、 [トークン構成] を選択します。Under the Manage section, select Token configuration.

  7. [省略可能な要求の追加] を選択し、 [ID] トークンの型を選択して、要求の一覧から [upn] を選択し、 [追加] を選択します。Select Add optional claim, select the ID token type, select upn from the list of claims, and then select Add.

  8. [省略可能な要求の追加] を選択し、 [アクセス] トークンの型を選択して、要求の一覧から auth_time を選択し、 [追加] を選択します。Select Add optional claim, select the Access token type, select auth_time from the list of claims, then select Add.

  9. [トークン構成の概要] 画面で、 [upn] の横にある鉛筆アイコンを選択し、 [外部で認証された] の切り替えを選択して、 [保存] を選択します。From the Token Configuration overview screen, select the pencil icon next to upn, select the Externally authenticated toggle, and then select Save.

  10. [省略可能な要求の追加] を選択し、 [SAML] トークンの型を選択して、要求の一覧から [extn. skypeID] を選択し (skypeID という Azure AD ユーザーオブジェクトを作成した場合にのみ適用されます)、 [追加] を選択します。Select Add optional claim, select the SAML token type, select extn.skypeID from the list of claims (only applicable if you've created an Azure AD user object called skypeID), and then select Add.

    SAML トークンの省略可能な要求Optional claims for SAML token

マニフェストの構成:Manifest configuration:

  1. Azure portal にサインインします。Sign in to the Azure portal.

  2. 認証が完了したら、ページの右上隅から Azure AD テナントを選択します。After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. 左側のメニューで、 [Azure Active Directory] を選択します。Select Azure Active Directory from the left-hand menu.

  4. 省略可能な要求を構成するアプリケーションを一覧から探して選択します。Find the application you want to configure optional claims for in the list and select it.

  5. [管理] セクションで、 [マニフェスト] を選択して、インライン マニフェスト エディターを開きます。Under the Manage section, select Manifest to open the inline manifest editor.

  6. このエディターを使用して、マニフェストを直接編集できます。You can directly edit the manifest using this editor. マニフェストは、アプリケーション エンティティのスキーマに従っています。保存されると、マニフェストの書式が自動的に構成されます。The manifest follows the schema for the Application entity, and automatically formats the manifest once saved. 新しい要素が OptionalClaims プロパティに追加されます。New elements will be added to the OptionalClaims property.

    "optionalClaims": {
        "idToken": [
            {
                "name": "upn",
                "essential": false,
                "additionalProperties": [
                    "include_externally_authenticated_upn"
                ]
            }
        ],
        "accessToken": [
            {
                "name": "auth_time",
                "essential": false
            }
        ],
        "saml2Token": [
            {
                "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
                "source": "user",
                "essential": true
            }
        ]
    }
    
  7. マニフェストの更新が完了したら、 [保存] を選択してマニフェストを保存します。When you're finished updating the manifest, select Save to save the manifest.

次のステップNext steps

Azure AD に用意されている標準の要求について詳しく学びます。Learn more about the standard claims provided by Azure AD.