Útmutató: opcionális jogcímek megadása az alkalmazás számáraHow to: Provide optional claims to your app

Az alkalmazások fejlesztői használhatják az Azure AD-alkalmazásokban választható jogcímeket annak meghatározására, hogy mely jogcímeket szeretnék elküldeni az alkalmazásnak.Application developers can use optional claims in their Azure AD applications to specify which claims they want in tokens sent to their application.

A következő választható jogcímeket használhatja:You can use optional claims to:

  • Válassza ki az alkalmazáshoz tartozó jogkivonatokban szerepeltetni kívánt további jogcímeket.Select additional claims to include in tokens for your application.
  • Módosítsa a Microsoft Identity platform által a jogkivonatokban visszaadott jogcímek viselkedését.Change the behavior of certain claims that Microsoft identity platform returns in tokens.
  • Egyéni jogcímek hozzáadása és elérése az alkalmazáshoz.Add and access custom claims for your application.

A standard jogcímek listájáért tekintse meg a hozzáférési jogkivonat és a id_token jogcím dokumentációját.For the lists of standard claims, see the access token and id_token claims documentation.

Míg a választható jogcímek a v 1.0 és a v 2.0 formátumú jogkivonatokban, valamint az SAML-jogkivonatokban is támogatottak, az értékük nagy részét az 1.0 és a v 2.0 közötti váltáskor adja meg.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. A 2.0-s Microsoft Identity platform végpontjának egyik célja kisebb token-méret az ügyfelek optimális teljesítményének biztosítása érdekében.One of the goals of the v2.0 Microsoft identity platform endpoint is smaller token sizes to ensure optimal performance by clients. Ennek eredményeképpen számos, korábban a hozzáférési és azonosító jogkivonatban szereplő jogcím már nem található meg a v 2.0-s jogkivonatokban, és a kérést külön alkalmazási alapon kell megadnia.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. táblázat: alkalmazhatóságTable 1: Applicability

Fiók típusaAccount Type 1.0-s verziós tokenekv1.0 tokens v 2.0-tokenekv2.0 tokens
Személyes Microsoft-fiókPersonal Microsoft account N/AN/A TámogatottSupported
Azure AD-fiókAzure AD account TámogatottSupported TámogatottSupported

v 1.0 és v 2.0 választható jogcímek készletev1.0 and v2.0 optional claims set

Az alábbi listában a használni kívánt alkalmazások alapértelmezett választható jogcímei érhetők el.The set of optional claims available by default for applications to use are listed below. Ha egyéni opcionális jogcímeket szeretne hozzáadni az alkalmazáshoz, tekintse meg az alábbi címtárszolgáltatás-bővítményeket.To add custom optional claims for your application, see Directory Extensions, below. Ha jogcímeket ad hozzá a hozzáférési jogkivonathoz, a jogcímek az alkalmazáshoz (webes API-hoz ) kért hozzáférési jogkivonatokra vonatkoznak, az alkalmazás által kért jogcímekre nem.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. Függetlenül attól, hogy az ügyfél hogyan fér hozzá az API-hoz, a megfelelő információ szerepel az API-val való hitelesítéshez használt hozzáférési jogkivonatban.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.

Megjegyzés

Ezeknek a jogcímeknek a többsége megadható a JWTs for 1.0 és v 2.0 tokenekhez, de nem SAML-tokenekhez, kivéve, ha a jogkivonat típusa oszlopban szerepel.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. A fogyasztói fiókok a "felhasználói típus" oszlopban megjelölt jogcímek egy részhalmazát támogatják.Consumer accounts support a subset of these claims, marked in the "User Type" column. A felsorolt jogcímek többsége nem vonatkozik a felhasználói felhasználókra (nem rendelkezik Bérlővel, ezért tenant_ctry nem rendelkezik értékkel).Many of the claims listed do not apply to consumer users (they have no tenant, so tenant_ctry has no value).

2. táblázat: v 1.0 és v 2.0 opcionális jogcím-készletTable 2: v1.0 and v2.0 optional claim set

NévName LeírásDescription Jogkivonat típusaToken Type Felhasználó típusaUser Type MegjegyzésekNotes
auth_time A felhasználó utolsó hitelesítésének időpontja.Time when the user last authenticated. Lásd: OpenID Connect spec.See OpenID Connect spec. JWTJWT
tenant_region_scope Az erőforrás-bérlő régiójaRegion of the resource tenant JWTJWT
sid Munkamenet-azonosító, amely a felhasználónkénti felhasználói kijelentkezéshez használatos.Session ID, used for per-session user sign-out. JWTJWT Személyes és Azure AD-fiókok.Personal and Azure AD accounts.
verified_primary_email A felhasználó PrimaryAuthoritativeEmail származikSourced from the user's PrimaryAuthoritativeEmail JWTJWT
verified_secondary_email A felhasználó SecondaryAuthoritativeEmail származikSourced from the user's SecondaryAuthoritativeEmail JWTJWT
vnet A VNET megadására vonatkozó információk.VNET specifier information. JWTJWT
fwd IP-cím.IP address. JWTJWT Hozzáadja a kérelmező ügyfél eredeti IPv4-címe (egy VNET belül)Adds the original IPv4 address of the requesting client (when inside a VNET)
ctry Felhasználó országa/régiójaUser's country/region JWT, SAMLJWT, SAML Az Azure AD visszaadja a ctry választható jogcímet, ha a jelen van, és a mező értéke standard kétbetűs ország-vagy régiókód, például fr, JP, sz stb.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 Erőforrás-bérlő országaResource tenant's country JWTJWT Ugyanaz, mint ctry a rendszergazda által a bérlői szinten beállítottak kivételével. Standard kétbetűs értéknek is kell lennie.Same as ctry except set at a tenant level by an admin. Must also be a standard two-letter value.
xms_pdl Elsődleges adatelérési helyPreferred data location JWTJWT A többszörös földrajzi bérlők esetében az előnyben részesített adatterület a felhasználó földrajzi régióját megjelenítő hárombetűs kód.For Multi-Geo tenants, the preferred data location is the three-letter code showing the geographic region the user is in. További információ: Azure ad Connect dokumentáció az előnyben részesített adatok helyéről.For more info, see the Azure AD Connect documentation about preferred data location.
Például: APC Ázsia és a csendes-óceáni térség.For example: APC for Asia Pacific.
xms_pl Felhasználó által előnyben részesített nyelvUser preferred language JWTJWT A felhasználó által választott nyelv, ha be van állítva.The user's preferred language, if set. A saját bérlőtől származik, a vendég hozzáférési forgatókönyvekben.Sourced from their home tenant, in guest access scenarios. Formázott LL-CC ("en-us").Formatted LL-CC ("en-us").
xms_tpl Bérlő által előnyben részesített nyelvTenant preferred language JWTJWT Az erőforrás-bérlő előnyben részesített nyelve, ha be van állítva.The resource tenant's preferred language, if set. Formázott LL ("en").Formatted LL ("en").
ztdid Nulla érintéses telepítési azonosítóZero-touch Deployment ID JWTJWT A Windows Autopilot szolgáltatáshoz használt eszköz identitásaThe device identity used for Windows AutoPilot
email A felhasználó címezhető e-mail-címe, ha a felhasználó rendelkezik ilyennel.The addressable email for this user, if the user has one. JWT, SAMLJWT, SAML MSA, Azure ADMSA, Azure AD Alapértelmezés szerint ez az érték szerepel, ha a felhasználó vendég a bérlőben.This value is included by default if the user is a guest in the tenant. A felügyelt felhasználók (a bérlőn belüli felhasználók) esetében ezt a választható jogcímen keresztül kell kérni, vagy csak a 2.0-s verzióban az OpenID hatókörrel.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. A felügyelt felhasználók esetében az e-mail-címet be kell állítani az Office felügyeleti portálon.For managed users, the email address must be set in the Office admin portal.
acct Felhasználói fiók állapota a bérlőbenUsers account status in tenant JWT, SAMLJWT, SAML Ha a felhasználó tagja a bérlőnek, az érték a 0 .If the user is a member of the tenant, the value is 0. Ha vendég, az érték a 1 .If they are a guest, the value is 1.
groups Csoportos jogcímek opcionális formázásaOptional formatting for group claims JWT, SAMLJWT, SAML Az GroupMembershipClaims beállítással együtt használatos az alkalmazás jegyzékfájljában, amelyet is be kell állítani.Used in conjunction with the GroupMembershipClaims setting in the application manifest, which must be set as well. Részletekért lásd az alábbi csoportos jogcímeket .For details see Group claims below. A csoportok jogcímeivel kapcsolatos további információkért lásd: csoportos jogcímek konfigurálásaFor more information about group claims, see How to configure group claims
upn UserPrincipalNameUserPrincipalName JWT, SAMLJWT, SAML A username_hint paraméterrel használható felhasználó termékazonosító.An identifer for the user that can be used with the username_hint parameter. Nem tartós azonosító a felhasználó számára, és nem használható a felhasználói adatok egyedi azonosítására (például adatbázis-kulcsként).Not a durable identifier for the user and should not be used to uniquely identity user information (for example, as a database key). Ehelyett használja a felhasználói objektum AZONOSÍTÓját ( oid ) az adatbázis kulcsaként.Instead, use the user object ID (oid) as a database key. Az alternatív bejelentkezési azonosítóval bejelentkezett felhasználók nem láthatják az egyszerű felhasználónevet (UPN).Users signing in with an alternate login ID should not be shown their User Principal Name (UPN). Ehelyett használja a következő azonosító jogkivonat-jogcímeket a bejelentkezési állapot felhasználónak való megjelenítéséhez: preferred_username vagy unique_name v1-tokenekhez és preferred_username v2-tokenekhez.Instead, use the following ID token claims for displaying sign-in state to the user: preferred_username or unique_name for v1 tokens and preferred_username for v2 tokens. Bár ez a jogcím automatikusan szerepel, megadhatja opcionális jogcímként is, ha további tulajdonságokat szeretne csatolni a vendég felhasználói eset működésének módosításához.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 Jogkivonat típusaToken type JWT hozzáférési jogkivonatokJWT access tokens Speciális: csak az alkalmazáshoz tartozó hozzáférési jogkivonatokbanSpecial: only in app-only access tokens Az érték az, app Ha a jogkivonat csak alkalmazási token.Value is app when the token is an app-only token. Ez a legpontosabb módszer egy API számára annak megállapítására, hogy a token alkalmazás-jogkivonat vagy alkalmazás + felhasználói jogkivonat-e.This is the most accurate way for an API to determine if a token is an app token or an app+user token.

a 2.0-s verzióra vonatkozó nem kötelező jogcímek beállításav2.0-specific optional claims set

Ezeket a jogcímeket mindig tartalmazza a v 1.0 Azure AD-jogkivonatok, de a nem tartalmazza a v 2.0-tokeneket, kivéve, ha erre kérték.These claims are always included in v1.0 Azure AD tokens, but not included in v2.0 tokens unless requested. Ezek a jogcímek csak a JWTs (azonosító jogkivonatok és hozzáférési tokenek) esetén érvényesek.These claims are only applicable for JWTs (ID tokens and Access Tokens).

3. táblázat: v 2.0 – csak opcionális jogcímekTable 3: v2.0-only optional claims

JWT jogcímJWT Claim NévName LeírásDescription JegyzetekNotes
ipaddr IP-címIP Address Az ügyféltől bejelentkezett IP-cím.The IP address the client logged in from.
onprem_sid Helyszíni biztonsági azonosítóOn-Premises Security Identifier
pwd_exp Jelszó lejárati idejePassword Expiration Time Az a dátum és idő, amikor a jelszó lejár.The datetime at which the password expires.
pwd_url Jelszó URL-címének módosításaChange Password URL URL-cím, amelyet a felhasználó megkereshet a jelszavuk módosításához.A URL that the user can visit to change their password.
in_corp Vállalati hálózaton belülInside Corporate Network Azt jelzi, hogy az ügyfél bejelentkezik-e a vállalati hálózatról.Signals if the client is logging in from the corporate network. Ha nem, a rendszer nem tartalmazza a jogcímet.If they're not, the claim isn't included. Az MFA megbízható IP -címeinek beállításai alapján.Based off of the trusted IPs settings in MFA.
family_name VezetéknévLast Name A felhasználó vezetéknevét, vezetéknevét vagy családjának nevét adja meg a felhasználói objektumban definiált módon.Provides the last name, surname, or family name of the user as defined in the user object.
"family_name": "Miller""family_name":"Miller"
Támogatott a MSA és az Azure AD-ben.Supported in MSA and Azure AD. A profile hatókört igényli.Requires the profile scope.
given_name UtónévFirst name A felhasználó első vagy "megadott" nevét adja meg a felhasználói objektumra vonatkozóan.Provides the first or "given" name of the user, as set on the user object.
"given_name": "Frank""given_name": "Frank"
Támogatott a MSA és az Azure AD-ben.Supported in MSA and Azure AD . A profile hatókört igényli.Requires the profile scope.
upn Felhasználó egyszerű neveUser Principal Name A username_hint paraméterrel használható felhasználó termékazonosító.An identifer for the user that can be used with the username_hint parameter. Nem tartós azonosító a felhasználó számára, és nem használható a felhasználói adatok egyedi azonosítására (például adatbázis-kulcsként).Not a durable identifier for the user and should not be used to uniquely identity user information (for example, as a database key). Ehelyett használja a felhasználói objektum AZONOSÍTÓját ( oid ) az adatbázis kulcsaként.Instead, use the user object ID (oid) as a database key. Az alternatív bejelentkezési azonosítóval bejelentkezett felhasználók nem láthatják az egyszerű felhasználónevet (UPN).Users signing in with an alternate login ID should not be shown their User Principal Name (UPN). Ehelyett használja a következő azonosító jogkivonat-jogcímeket a bejelentkezési állapot felhasználónak való megjelenítéséhez: preferred_username vagy unique_name v1-tokenekhez és preferred_username v2-tokenekhez.Instead, use the following ID token claims for displaying sign-in state to the user: preferred_username or unique_name for v1 tokens and preferred_username for v2 tokens. A jogcím konfigurálásához tekintse meg az alábbi további tulajdonságokat .See additional properties below for configuration of the claim. A profile hatókört igényli.Requires the profile scope.

A választható jogcímek további tulajdonságaiAdditional properties of optional claims

Egyes választható jogcímek úgy konfigurálhatók, hogy megváltoztassák a jogcím visszaadásának módját.Some optional claims can be configured to change the way the claim is returned. Ezeket a további tulajdonságokat többnyire a helyszíni alkalmazások áttelepítésére használják a különböző adatelérési elvárásokkal.These additional properties are mostly used to help migration of on-premises applications with different data expectations. Például include_externally_authenticated_upn_without_hash segít olyan ügyfelek számára, akik nem kezelhetik a kivonatoló jeleket ( # ) az UPN-ben.For example, include_externally_authenticated_upn_without_hash helps with clients that cannot handle hash marks (#) in the UPN.

4. táblázat: választható jogcímek konfigurálásának értékeiTable 4: Values for configuring optional claims

Tulajdonság neveProperty name További tulajdonságnévAdditional Property name LeírásDescription
upn Az SAML-és JWT-válaszokhoz, valamint a 1.0-s és a v 2.0-tokenekhez is használható.Can be used for both SAML and JWT responses, and for v1.0 and v2.0 tokens.
include_externally_authenticated_upn Az erőforrás-bérlőben tárolt vendég UPN-t tartalmazza.Includes the guest UPN as stored in the resource tenant. Például: foo_hometenant.com#EXT#@resourcetenant.comFor example, foo_hometenant.com#EXT#@resourcetenant.com
include_externally_authenticated_upn_without_hash Ugyanaz, mint a fenti, azzal a különbséggel, hogy a kivonatoló jeleket () a # rendszer aláhúzással () váltja le _ , például: 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

További tulajdonságok – példaAdditional properties example

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

Ez a OptionalClaims objektum azt eredményezi, hogy a rendszer visszaadja az azonosító jogkivonatot az ügyfélnek, hogy tartalmazza a upn további otthoni Bérlővel és erőforrás-bérlői információkkal rendelkező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. A upn jogcímek csak abban az esetben módosulnak a jogkivonatban, ha a felhasználó a bérlő egyik vendége (amely más identitásszolgáltató használ a hitelesítéshez).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).

Választható jogcímek konfigurálásaConfiguring optional claims

Fontos

A hozzáférési jogkivonatok mindig az erőforrás jegyzékfájljának használatával jönnek létre, nem az ügyfél.Access tokens are always generated using the manifest of the resource, not the client. Tehát a kérelemben ...scope=https://graph.microsoft.com/user.read... az erőforrás a Microsoft Graph API.So in the request ...scope=https://graph.microsoft.com/user.read... the resource is the Microsoft Graph API. Így a hozzáférési jogkivonat a Microsoft Graph API-jegyzékfájl használatával jön létre, nem az ügyfél jegyzékfájlja.Thus, the access token is created using the Microsoft Graph API manifest, not the client's manifest. Az alkalmazás jegyzékfájljának módosítása soha nem okoz jogkivonatot a Microsoft Graph API-nak a különböző megjelenéséhez.Changing the manifest for your application will never cause tokens for the Microsoft Graph API to look different. Annak ellenőrzéséhez, hogy a accessToken módosítások érvényben vannak-e, igényeljen egy jogkivonatot az alkalmazáshoz, nem pedig egy másik alkalmazást.In order to validate that your accessToken changes are in effect, request a token for your application, not another app.

Az alkalmazásra vonatkozó opcionális jogcímeket a felhasználói felület vagy az alkalmazás jegyzékfájlja segítségével konfigurálhatja.You can configure optional claims for your application through the UI or application manifest.

  1. Nyissa meg az Azure Portalt.Go to the Azure portal. Keresse meg és válassza ki az Azure Active Directoryt.Search for and select Azure Active Directory.
  2. A kezelés szakaszban válassza a Alkalmazásregisztrációk lehetőséget.From the Manage section, select App registrations.
  3. Válassza ki azt az alkalmazást, amelyhez választható jogcímeket szeretne konfigurálni a listában.Select the application you want to configure optional claims for in the list.

Választható jogcímek konfigurálása a felhasználói felületen keresztül:Configuring optional claims through the UI:

Választható jogcímek konfigurálása a felhasználói felületenConfigure optional claims in the UI

  1. A kezelés szakaszban válassza a jogkivonat-konfiguráció elemet.From the Manage section, select Token configuration.
  2. Válassza a választható jogcím hozzáadása lehetőséget.Select Add optional claim.
  3. Válassza ki a konfigurálni kívánt jogkivonat-típust.Select the token type you want to configure.
  4. Válassza ki a hozzáadandó választható jogcímeket.Select the optional claims to add.
  5. Válassza a Hozzáadás elemet.Select Add.

Megjegyzés

A felhasználói felületi beállítás jogkivonat-konfigurációja panel jelenleg nem érhető el Azure ad B2C bérlőben regisztrált alkalmazásokhoz.The UI option Token configuration blade is not available for apps registered in an Azure AD B2C tenant currently . A B2C-bérlőben regisztrált alkalmazások esetében a választható jogcímeket az alkalmazás jegyzékfájljának módosításával lehet konfigurálni.For applications registered in a B2C tenant , the optional claims can be configured by modifying the application manifest . További információ: jogcímek hozzáadása és felhasználói bevitel testreszabása Egyéni szabályzatok használatával Azure Active Directory B2CFor more information see Add claims and customize user input using custom policies in Azure Active Directory B2C

Választható jogcímek konfigurálása az alkalmazás jegyzékfájlján keresztül:Configuring optional claims through the application manifest:

Bemutatja, hogyan konfigurálhat választható jogcímeket az alkalmazás jegyzékfájljának használatávalShows how to configure optional claims using the app manifest

  1. A kezelés szakaszban válassza a jegyzékfájl lehetőséget.From the Manage section, select Manifest. Megnyílik egy web-alapú jegyzékfájl-szerkesztő, amely lehetővé teszi a jegyzékfájl szerkesztését.A web-based manifest editor opens, allowing you to edit the manifest. Másik lehetőségként a Letöltés lehetőséget választva a helyi gépen is szerkesztheti az alkalmazásjegyzéket, majd a Feltöltés gombra kattintva alkalmazhatja a módosításokat az alkalmazásra.Optionally, you can select Download and edit the manifest locally, and then use Upload to reapply it to your application. Az alkalmazás jegyzékfájljának megismeréséhez tekintse meg az Azure ad Application manifest ismertetése című cikket.For more information on the application manifest, see the Understanding the Azure AD application manifest article.

    A következő Application manifest bejegyzés hozzáadja a auth_time, a IPADDR és az UPN opcionális jogcímeit az AZONOSÍTÓhoz, a hozzáféréshez és az SAML-jogkivonatokhoz.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. Ha elkészült, válassza a Mentés lehetőséget.When finished, select Save. Most a megadott választható jogcímek szerepelni fognak az alkalmazás jogkivonatában.Now the specified optional claims will be included in the tokens for your application.

OptionalClaims típusaOptionalClaims type

Deklarálja az alkalmazás által kért választható jogcímeket.Declares the optional claims requested by an application. Egy alkalmazás olyan választható jogcímeket is beállíthat, amelyek a biztonsági jogkivonat szolgáltatástól kapott három jogkivonat (azonosító token, hozzáférési jogkivonat, SAML 2 token) mindhárom típusában visszatérhetnek.An application can configure optional claims to be returned in each of three types of tokens (ID token, access token, SAML 2 token) that it can receive from the security token service. Az alkalmazás különböző választható jogcímeket konfigurálhat az egyes token-típusokban való visszatéréshez.The application can configure a different set of optional claims to be returned in each token type. Az alkalmazás entitás OptionalClaims tulajdonsága egy OptionalClaims objektum.The OptionalClaims property of the Application entity is an OptionalClaims object.

5. táblázat: OptionalClaims típusának tulajdonságaiTable 5: OptionalClaims type properties

NévName TípusType LeírásDescription
idToken Gyűjtemény (OptionalClaim)Collection (OptionalClaim) A JWT azonosító jogkivonatában visszaadott választható jogcímek.The optional claims returned in the JWT ID token.
accessToken Gyűjtemény (OptionalClaim)Collection (OptionalClaim) Az JWT hozzáférési jogkivonatban visszaadott választható jogcímek.The optional claims returned in the JWT access token.
saml2Token Gyűjtemény (OptionalClaim)Collection (OptionalClaim) Az SAML-jogkivonatban visszaadott választható jogcímek.The optional claims returned in the SAML token.

OptionalClaim típusaOptionalClaim type

Egy alkalmazáshoz vagy egy egyszerű szolgáltatáshoz társított opcionális jogcímet tartalmaz.Contains an optional claim associated with an application or a service principal. A OptionalClaims típus IdToken, AccessToken és saml2Token tulajdonsága a OptionalClaim gyűjteménye.The idToken, accessToken, and saml2Token properties of the OptionalClaims type is a collection of OptionalClaim. Ha egy adott jogcím támogatja, a OptionalClaim viselkedését a AdditionalProperties mező használatával is módosíthatja.If supported by a specific claim, you can also modify the behavior of the OptionalClaim using the AdditionalProperties field.

6. táblázat: OptionalClaim típusának tulajdonságaiTable 6: OptionalClaim type properties

NévName TípusType LeírásDescription
name Edm.StringEdm.String A választható jogcím neve.The name of the optional claim.
source Edm.StringEdm.String A jogcím forrása (Directory-objektum).The source (directory object) of the claim. A bővítmény tulajdonságaiban előre definiált jogcímek és felhasználó által definiált jogcímek találhatók.There are predefined claims and user-defined claims from extension properties. Ha a forrás értéke null, a jogcím egy előre meghatározott opcionális jogcím.If the source value is null, the claim is a predefined optional claim. Ha a forrás értéke felhasználó, a Name (név) tulajdonság értéke a felhasználói objektum kiterjesztés tulajdonsága.If the source value is user, the value in the name property is the extension property from the user object.
essential Edm.BooleanEdm.Boolean Ha az érték TRUE (igaz), akkor az ügyfél által megadott jogcím szükséges a végfelhasználó által kért feladat zökkenőmentes engedélyezési élményének biztosításához.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. Az alapértelmezett érték a hamis.The default value is false.
additionalProperties Gyűjtemény (EDM. String)Collection (Edm.String) A jogcím további tulajdonságai.Additional properties of the claim. Ha egy tulajdonság létezik ebben a gyűjteményben, a módosítja a Name (név) tulajdonságban megadott választható jogcím viselkedését.If a property exists in this collection, it modifies the behavior of the optional claim specified in the name property.

A címtár-bővítmény választható jogcímeinek konfigurálásaConfiguring directory extension optional claims

A standard opcionális jogcímek készleten kívül a jogkivonatokat is konfigurálhatja a bővítmények belefoglalásához.In addition to the standard optional claims set, you can also configure tokens to include extensions. További információ: Microsoft Graph extensionProperty dokumentációja.For more info, see the Microsoft Graph extensionProperty documentation.

A sémák és a nyitott bővítmények nem támogatottak a választható jogcímek esetében, csak a AAD-Graph Style Directory-bővítmények.Schema and open extensions are not supported by optional claims, only the AAD-Graph style directory extensions. Ez a funkció hasznos lehet az alkalmazás által használható további felhasználói adatok csatolásához – például egy további azonosító vagy fontos konfigurációs beállítás, amelyet a felhasználó beállított.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. Példaként tekintse meg az oldal alját.See the bottom of this page for an example.

Megjegyzés

A címtár-séma bővítményei egy Azure AD-only szolgáltatás.Directory schema extensions are an Azure AD-only feature. Ha az alkalmazás jegyzékfájlja egyéni kiterjesztést kér, és egy MSA-felhasználó bejelentkezik az alkalmazásba, ezek a bővítmények nem lesznek visszaadva.If your application manifest requests a custom extension and an MSA user logs in to your app, these extensions will not be returned.

Címtárszolgáltatás-bővítmény formázásaDirectory extension formatting

Ha az alkalmazás jegyzékfájljának használatával konfigurálhatja a címtár-bővítmény választható jogcímeit, használja a bővítmény teljes nevét (a következő formátumban: 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>). Az értéknek <appid> meg kell egyeznie a jogcímet kérő alkalmazás azonosítójával.The <appid> must match the ID of the application requesting the claim.

A JWT belül ezeket a jogcímeket a következő formátumnév fogja kiadni: extn.<attributename> .Within the JWT, these claims will be emitted with the following name format: extn.<attributename>.

Az SAML-tokeneken belül ezek a jogcímek a következő URI-formátummal lesznek kibocsátva: http://schemas.microsoft.com/identity/claims/extn.<attributename>Within the SAML tokens, these claims will be emitted with the following URI format: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Csoportok konfigurálása választható jogcímekConfiguring groups optional claims

Megjegyzés

A helyi verzióról szinkronizált felhasználók és csoportok számára a csoportok nevének kiadásának lehetősége nyilvános előzetes verzió.The ability to emit group names for users and groups synced from on-premises is Public Preview.

Ez a szakasz azokat a konfigurációs beállításokat ismerteti, amelyek a választható jogcímek területen az alapértelmezett csoport objectID a helyi Windows Active Directoryról szinkronizált attribútumokra vonatkozóan használt csoportok attribútumainak módosítására használhatók.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. A felhasználói felület vagy az alkalmazás jegyzékfájlja segítségével az alkalmazáshoz választható jogcímeket is konfigurálhat.You can configure groups optional claims for your application through the UI or application manifest.

Fontos

További részletek: az Azure AD-ben az alkalmazások csoportos jogcímei jogcímeinek konfigurálásacímű témakörben olvashat bővebben.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.

Csoportok konfigurálása választható jogcímek a felhasználói felületen keresztül:Configuring groups optional claims through the UI:

  1. Jelentkezzen be az Azure Portalra.Sign in to the Azure portal.
  2. A hitelesítés után válassza ki az Azure AD-bérlőt az oldal jobb felső sarkában.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.
  3. A bal oldali menüben válassza a Azure Active Directory lehetőséget.Select Azure Active Directory from the left-hand menu.
  4. A kezelés szakaszban válassza a Alkalmazásregisztrációk lehetőséget.Under the Manage section, select App registrations.
  5. Válassza ki azt az alkalmazást, amelyhez választható jogcímeket szeretne konfigurálni a listában.Select the application you want to configure optional claims for in the list.
  6. A kezelés szakaszban válassza a jogkivonat-konfiguráció elemet.Under the Manage section, select Token configuration.
  7. Válassza a Csoport hozzáadása jogcímet.Select Add groups claim.
  8. Válassza ki a visszaadni kívánt csoportok típusát (biztonsági csoportok, címtárbeli szerepkörök, az alkalmazáshoz rendelt összes csoport és/vagy csoport).Select the group types to return (Security groups, or Directory roles, All groups, and/or Groups assigned to the application). Az alkalmazás-beállításhoz rendelt csoportok csak az alkalmazáshoz rendelt csoportokat tartalmazzák.The Groups assigned to the application option includes only groups assigned to the application. A minden csoport beállítás magában foglalja az SecurityGroup, a DirectoryRole és a DistributionList, de az alkalmazáshoz nem rendelt csoportokat.The All Groups option includes SecurityGroup, DirectoryRole, and DistributionList, but not Groups assigned to the application.
  9. Nem kötelező: válassza ki az adott jogkivonat-típus tulajdonságait, hogy módosítsa a csoportok jogcím értékét, amely a helyszíni csoport attribútumait tartalmazza, vagy ha módosítani szeretné a jogcím típusát a szerepkörre.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. Kattintson a Mentés gombra.Select Save.

Csoportok konfigurálása választható jogcímek az alkalmazás jegyzékfájlján keresztül:Configuring groups optional claims through the application manifest:

  1. Jelentkezzen be az Azure Portalra.Sign in to the Azure portal.

  2. A hitelesítés után válassza ki az Azure AD-bérlőt az oldal jobb felső sarkában.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. A bal oldali menüben válassza a Azure Active Directory lehetőséget.Select Azure Active Directory from the left-hand menu.

  4. Válassza ki azt az alkalmazást, amelyhez választható jogcímeket szeretne konfigurálni a listában.Select the application you want to configure optional claims for in the list.

  5. A kezelés szakaszban válassza a jegyzékfájl lehetőséget.Under the Manage section, select Manifest.

  6. Adja hozzá a következő bejegyzést a jegyzékfájl-szerkesztő használatával:Add the following entry using the manifest editor:

    Az érvényes értékek a következők:The valid values are:

    • "All" (ez a beállítás magában foglalja az SecurityGroup, a DirectoryRole és a DistributionList)"All" (this option includes SecurityGroup, DirectoryRole, and DistributionList)
    • "SecurityGroup""SecurityGroup"
    • "DirectoryRole""DirectoryRole"
    • "Alkalmazáscsoport" (ez a beállítás csak az alkalmazáshoz rendelt csoportokat tartalmazza)"ApplicationGroup" (this option includes only groups that are assigned to the application)

    Például:For example:

    "groupMembershipClaims": "SecurityGroup"
    

    Alapértelmezés szerint a csoport ObjectIDs a rendszer a csoportos jogcím értékét fogja kiállítani.By default Group ObjectIDs will be emitted in the group claim value. Ha módosítani szeretné a jogcím értékét, hogy a tartalmazza a helyszíni csoport attribútumait, vagy módosítani szeretné a jogcím típusát a szerepkörre, használja a OptionalClaims-konfigurációt az alábbiak szerint: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. Adja meg a csoport neve konfigurációjának választható jogcímeit.Set group name configuration optional claims.

    Ha azt szeretné, hogy a tokenben lévő csoportok tartalmazzák a helyszíni AD-csoport attribútumait a választható jogcímek szakaszban, adja meg, hogy melyik jogkivonat-típust kívánja alkalmazni, a kérelmezett választható jogcím és a szükséges további tulajdonságok nevét.If you want 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. Több jogkivonat-típus is szerepelhet:Multiple token types can be listed:

    • a OIDC azonosító token idTokenidToken for the OIDC ID token
    • a OAuth hozzáférési token accessTokenaccessToken for the OAuth access token
    • SAML-tokenek Saml2Token.Saml2Token for SAML tokens.

    Megjegyzés

    A Saml2Token típusa SAML 1.1 és SAML 2.0 formátumú jogkivonatokra is vonatkozik.The Saml2Token type applies to both SAML1.1 and SAML2.0 format tokens.

    Minden releváns jogkivonat-típus esetében módosítsa a csoportok jogcímet a jegyzékfájl OptionalClaims szakaszának használatára.For each relevant token type, modify the groups claim to use the OptionalClaims section in the manifest. A OptionalClaims séma a következő:The OptionalClaims schema is as follows:

    {
        "name": "groups",
        "source": null,
        "essential": false,
        "additionalProperties": []
    }
    
    Választható jogcímek sémájaOptional claims schema ÉrtékValue
    név:name: "Groups" értéknek kell lennieMust be "groups"
    forrássource: Nincs használatban.Not used. Kihagyás vagy a Null érték meghatározásaOmit or specify null
    alapvetőessential: Nincs használatban.Not used. Kihagyás vagy a hamis meghatározásaOmit or specify false
    additionalProperties:additionalProperties: További tulajdonságok listája.List of additional properties. Az érvényes beállítások: "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"

    A additionalProperties-ben a "sam_account_name", a "dns_domain_and_sam_account_name", a "netbios_domain_and_sam_account_name" értéknek csak az egyike szükséges.In additionalProperties only one of "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name" are required. Ha egynél több van jelen, az első használatban van, és minden más figyelmen kívül lesz hagyva.If more than one is present, the first is used and any others ignored.

    Egyes alkalmazások a szerepkör-jogcímben szereplő felhasználóra vonatkozó csoportos adatokat igényelnek.Some applications require group information about the user in the role claim. Ha módosítani szeretné a jogcím típusát egy csoport jogcímen egy szerepkör-jogcímre, adja hozzá a "emit_as_roles" értéket a további tulajdonságokhoz.To change the claim type from a group claim to a role claim, add "emit_as_roles" to additional properties. A csoport értékeit a rendszer a szerepkör-jogcímben fogja kiállítani.The group values will be emitted in the role claim.

    Megjegyzés

    Ha "emit_as_roles" van használatban, a felhasználó által hozzárendelt összes alkalmazás-szerepkör nem jelenik meg a szerepkör-jogcímben.If "emit_as_roles" is used, any application roles configured that the user is assigned will not appear in the role claim.

Példák:Examples:

  1. Csoportok kibocsátása csoport neveként a OAuth hozzáférési jogkivonatokban dnsDomainName\sAMAccountName formátumbanEmit groups as group names in OAuth access tokens in dnsDomainName\sAMAccountName format

    Felhasználói felület konfigurációja:UI configuration:

    Nem kötelező jogcímek konfigurálásaConfigure optional claims

    Alkalmazás jegyzékfájljának bejegyzése:Application manifest entry:

    "optionalClaims": {
        "accessToken": [
            {
                "name": "groups",
                "additionalProperties": [
                    "dns_domain_and_sam_account_name"
                ]
            }
        ]
    }
    
  2. A netbiosDomain\sAMAccountName formátumban visszaadott csoportok nevének kibocsátása az SAML-és OIDC-azonosító jogkivonatokban lévő szerepkörök jogcímkéntEmit group names to be returned in netbiosDomain\sAMAccountName format as the roles claim in SAML and OIDC ID Tokens

    Felhasználói felület konfigurációja:UI configuration:

    Nem kötelező jogcímek a jegyzékfájlbanOptional claims in manifest

    Alkalmazás jegyzékfájljának bejegyzése: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"
                ]
            }
        ]
    }
    

Választható jogcímek – példaOptional claims example

Ebben a szakaszban áttekintheti a forgatókönyvet, amelyből megtudhatja, hogyan használhatja a választható jogcímek funkciót az alkalmazásához.In this section, you can walk through a scenario to see how you can use the optional claims feature for your application. Több lehetőség is rendelkezésre áll az alkalmazás identitás-konfigurációjának tulajdonságainak frissítésére az opcionális jogcímek engedélyezéséhez és konfigurálásához:There are multiple options available for updating the properties on an application's identity configuration to enable and configure optional claims:

  • Használhatja a jogkivonat- konfigurációs felhasználói felületet (lásd az alábbi példát)You can use the Token configuration UI (see example below)
  • Használhatja a jegyzékfájlt (lásd az alábbi példát).You can use the Manifest (see example below). Olvassa el az Azure ad Application manifest-dokumentum megismerése című dokumentumot a jegyzékfájl bevezetésének első lépéseit ismertető dokumentumban.Read the Understanding the Azure AD application manifest document first for an introduction to the manifest.
  • Olyan alkalmazást is írhat, amely a Microsoft Graph API -t használja az alkalmazás frissítéséhez.It's also possible to write an application that uses the Microsoft Graph API to update your application. A Microsoft Graph API-referenciák útmutatójának OptionalClaims -típusa segíthet a választható jogcímek konfigurálásában.The OptionalClaims type in the Microsoft Graph API reference guide can help you with configuring the optional claims.

PéldaExample:

Az alábbi példában a jogkivonat-konfigurációs felhasználói felület és a jegyzékfájl használatával adhat hozzá opcionális jogcímeket az alkalmazáshoz szánt hozzáféréshez, azonosítóhoz és SAML-jogkivonatokhoz.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. Különböző választható jogcímek lesznek hozzáadva az egyes tokenekhez, amelyeket az alkalmazás fogadni tud:Different optional claims will be added to each type of token that the application can receive:

  • Az azonosító tokenek mostantól a teljes űrlapon () is tartalmazzák az összevont felhasználók egyszerű felhasználónevét <upn>_<homedomain>#EXT#@<resourcedomain> .The ID tokens will now contain the UPN for federated users in the full form (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • Az alkalmazáshoz tartozó más ügyfelek által igényelt hozzáférési jogkivonatok mostantól tartalmazzák a auth_time jogcímet.The access tokens that other clients request for this application will now include the auth_time claim.
  • Az SAML-tokenek mostantól tartalmazzák a skypeId Directory sémakezelő bővítményt (ebben a példában az alkalmazáshoz tartozó ab603c56068041afb2f6832e2a17e237).The SAML tokens will now contain the skypeId directory schema extension (in this example, the app ID for this app is ab603c56068041afb2f6832e2a17e237). Az SAML-tokenek a Skype ID-t teszik elérhetővé extension_skypeId .The SAML tokens will expose the Skype ID as extension_skypeId.

Felhasználói felület konfigurációja:UI configuration:

  1. Jelentkezzen be az Azure Portalra.Sign in to the Azure portal.

  2. A hitelesítés után válassza ki az Azure AD-bérlőt az oldal jobb felső sarkában.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. A bal oldali menüben válassza a Azure Active Directory lehetőséget.Select Azure Active Directory from the left-hand menu.

  4. A kezelés szakaszban válassza a Alkalmazásregisztrációk lehetőséget.Under the Manage section, select App registrations.

  5. Keresse meg azt az alkalmazást, amelyhez választható jogcímeket szeretne konfigurálni a listában, majd válassza ki azt.Find the application you want to configure optional claims for in the list and select it.

  6. A kezelés szakaszban válassza a jogkivonat-konfiguráció elemet.Under the Manage section, select Token configuration.

  7. Válassza a választható jogcím hozzáadása lehetőséget, válassza ki az azonosító token típusát, válassza az egyszerű felhasználónév lehetőséget a jogcímek listájából, majd válassza a Hozzáadás lehetőséget.Select Add optional claim, select the ID token type, select upn from the list of claims, and then select Add.

  8. Válassza a választható jogcím hozzáadása lehetőséget, válassza ki a hozzáférési token típusát, válassza a auth_time elemet a jogcímek listájából, majd válassza a Hozzáadás lehetőséget.Select Add optional claim, select the Access token type, select auth_time from the list of claims, then select Add.

  9. A jogkivonat-konfiguráció áttekintése képernyőn válassza az egyszerű felhasználónév melletti ceruza ikont, válassza a külsőleg hitelesített váltógomb elemet, majd kattintson a Mentés gombra.From the Token Configuration overview screen, select the pencil icon next to upn, select the Externally authenticated toggle, and then select Save.

  10. Válassza az opcionális jogcím hozzáadása lehetőséget, válassza ki az SAML -token típusát, válassza a extn. skypeID elemet a jogcímek listájából (csak akkor érvényes, ha létrehozott egy skypeID nevű Azure ad felhasználói objektumot), majd válassza a Hozzáadás lehetőséget.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-tokenhez választható jogcímekOptional claims for SAML token

Jegyzékfájl konfigurációja:Manifest configuration:

  1. Jelentkezzen be az Azure Portalra.Sign in to the Azure portal.

  2. A hitelesítés után válassza ki az Azure AD-bérlőt az oldal jobb felső sarkában.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. A bal oldali menüben válassza a Azure Active Directory lehetőséget.Select Azure Active Directory from the left-hand menu.

  4. Keresse meg azt az alkalmazást, amelyhez választható jogcímeket szeretne konfigurálni a listában, majd válassza ki azt.Find the application you want to configure optional claims for in the list and select it.

  5. A kezelés szakaszban válassza a jegyzékfájl lehetőséget a beágyazott jegyzékfájl-szerkesztő megnyitásához.Under the Manage section, select Manifest to open the inline manifest editor.

  6. A jegyzékfájlt közvetlenül szerkesztheti a szerkesztő használatával.You can directly edit the manifest using this editor. A jegyzékfájl az alkalmazás entitásánaksémáját követi, és a mentés után automatikusan formázza a jegyzékfájlt.The manifest follows the schema for the Application entity, and automatically formats the manifest once saved. Új elemek lesznek hozzáadva a OptionalClaims tulajdonsághoz.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. Amikor befejezte a jegyzékfájl frissítését , a Mentés gombra kattintva mentheti a jegyzékfájlt.When you're finished updating the manifest, select Save to save the manifest.

Következő lépésekNext steps

További információ az Azure AD által biztosított standard jogcímekről.Learn more about the standard claims provided by Azure AD.