Konfigurace volitelných deklarací identity

Tokeny, které microsoft Entra vrací, se uchovávají menší, aby zajistili optimální výkon klientů, kteří je požadují. V důsledku toho se ve výchozím nastavení v tokenu nezobrazuje několik deklarací identity a musí být požádáno konkrétně pro jednotlivé aplikace.

Volitelné deklarace identity pro vaši aplikaci můžete nakonfigurovat prostřednictvím uživatelského rozhraní nebo manifestu centra pro správu Microsoft Entra.

Požadavky

• Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
• Dokončení rychlého startu : Registrace aplikace

Konfigurace volitelných deklarací identity v aplikaci

1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce cloudových aplikací.
2. Přejděte k aplikacím> identit>Registrace aplikací.
3. Zvolte aplikaci, pro kterou chcete nakonfigurovat volitelné deklarace identity na základě vašeho scénáře a požadovaného výsledku.

Pokračovat v uživatelském rozhraní aplikace

1. V části Spravovat vyberte konfiguraci tokenu.
2. Vyberte Přidat volitelnou deklaraci identity.
3. Vyberte typ tokenu, který chcete nakonfigurovat, například Access.
4. Vyberte volitelné deklarace identity, které chcete přidat.
5. Vyberte Přidat.

Pokračovat v manifestu

1. V části Spravovat vyberte Manifest. Otevře se webový editor manifestu, který umožňuje upravit manifest. Volitelně můžete vybrat Stáhnout, upravit manifest místně a potom ho Nahrát zpět do aplikace. Pokud soubor neobsahuje optionalClaims vlastnost, můžete ji přidat.

   Následující položka manifestu aplikace přidá auth_timeid ipaddr, přístup a tokeny SAML a upn volitelné deklarace identity.

   "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. Jakmile budete hotovi, vyberte Uložit. Teď jsou zadané volitelné deklarace identity zahrnuté do tokenů pro vaši aplikaci.

Objekt optionalClaims deklaruje volitelné deklarace identity požadované aplikací. Aplikace může nakonfigurovat volitelné deklarace identity, které se vrátí v tokenech ID, přístupových tokenech a tokenech SAML 2. Aplikace může nakonfigurovat jinou sadu volitelných deklarací identity, které se mají vrátit v každém typu tokenu.

Name	Typ	Popis
idToken	Kolekce	Volitelné deklarace identity vrácené v tokenu ID JWT.
accessToken	Kolekce	Volitelné deklarace identity vrácené v přístupovém tokenu JWT.
saml2Token	Kolekce	Volitelné deklarace identity vrácené v tokenu SAML.

Pokud je určitá deklarace identity podporovaná, můžete také upravit chování volitelné deklarace identity pomocí additionalProperties pole.

Name	Typ	Popis
name	Edm.String	Název volitelné deklarace identity.
source	Edm.String	Zdroj (objekt adresáře) deklarace identity. Existují předdefinované deklarace identity a deklarace identity definované uživatelem z vlastností rozšíření. Pokud je zdrojová hodnota null, deklarace identity je předdefinovaná volitelná deklarace identity. Pokud je zdrojová hodnota uživatel, hodnota ve vlastnosti name je vlastnost rozšíření z objektu uživatele.
essential	Edm.Boolean	Pokud je hodnota pravdivá, deklarace identity zadaná klientem je nezbytná k zajištění hladkého prostředí autorizace pro konkrétní úlohu požadovanou koncovým uživatelem. Výchozí hodnota je false.
additionalProperties	Kolekce (Edm.String)	Další vlastnosti deklarace identity. Pokud v této kolekci existuje vlastnost, upraví chování volitelné deklarace identity zadané ve vlastnosti name.

---

Konfigurace volitelných deklarací identity rozšíření adresáře

Kromě standardní volitelné sady deklarací identity můžete také nakonfigurovat tokeny tak, aby zahrnovaly rozšíření Microsoft Graphu. Další informace najdete v tématu Přidání vlastních dat do prostředků pomocí rozšíření.

Důležité

Přístupové tokeny se vždy generují pomocí manifestu prostředku, nikoli klienta. V požadavku ...scope=https://graph.microsoft.com/user.read...je prostředek rozhraní Microsoft Graph API. Přístupový token se vytvoří pomocí manifestu rozhraní Microsoft Graph API, nikoli manifestu klienta. Změna manifestu pro vaši aplikaci nikdy nezpůsobí, že tokeny pro rozhraní Microsoft Graph API vypadají jinak. Pokud chcete ověřit, že se změny accessToken projeví, požádejte o token pro vaši aplikaci, ne o jinou aplikaci.

Volitelné deklarace identity podporují atributy rozšíření a rozšíření adresáře. Tato funkce je užitečná pro připojení dalších informací o uživateli, které může vaše aplikace používat. Například jiné identifikátory nebo důležité možnosti konfigurace, které uživatel nastavil. Pokud manifest aplikace požaduje vlastní rozšíření a uživatel MSA se přihlásí k vaší aplikaci, tato rozšíření se nevrátí.

Formátování rozšíření adresáře

Při konfiguraci volitelných deklarací identity rozšíření adresáře pomocí manifestu aplikace použijte úplný název rozšíření (ve formátu: extension_<appid>_<attributename>). Jedná se <appid> o prořezanou verzi appId (nebo ID klienta) aplikace, která žádost o deklaraci identity požaduje.

V JWT se tyto deklarace identity vygenerují s následujícím formátem názvu: extn.<attributename>. V tokenech SAML se tyto deklarace identity vygenerují s následujícím formátem identifikátoru URI: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Konfigurace volitelných deklarací identity skupin

Tip

Postup v tomto článku se může mírně lišit v závislosti na portálu, od který začínáte.

Tato část popisuje možnosti konfigurace v rámci volitelných deklarací identity pro změnu atributů skupiny používaných v deklarací skupiny z výchozího ID objektu skupiny na atributy synchronizované z místní služby Windows Active Directory. Volitelné deklarace identity skupin pro vaši aplikaci můžete nakonfigurovat prostřednictvím webu Azure Portal nebo manifestu aplikace. Volitelné deklarace identity skupiny se generují pouze v JWT pro objekty zabezpečení uživatele. Instanční objekty nejsou zahrnuty do volitelných deklarací identity ve skupině generované v JWT.

Důležité

Počet skupin generovaných v tokenu je omezen na 150 pro kontrolní výrazy SAML a 200 pro JWT včetně vnořených skupin. Další informace o omezeních skupin a důležitých upozorněních pro deklarace identity skupin z místních atributů najdete v tématu Konfigurace deklarací identity skupin pro aplikace.

Pokud chcete nakonfigurovat volitelné deklarace identity skupin pomocí webu Azure Portal, proveďte následující kroky:

1. Vyberte aplikaci, pro kterou chcete nakonfigurovat volitelné deklarace identity.
2. V části Spravovat vyberte konfiguraci tokenu.
3. Vyberte Přidat deklaraci identity skupin.
4. Vyberte typy skupin, které se mají vrátit (skupiny zabezpečení nebo role adresáře, všechny skupiny a/nebo skupiny přiřazené k aplikaci):
   • Skupiny přiřazené k aplikaci zahrnují pouze skupiny přiřazené k aplikaci. Skupiny přiřazené k aplikaci se doporučují pro velké organizace kvůli limitu počtu skupin v tokenu. Pokud chcete změnit skupiny přiřazené k aplikaci, vyberte aplikaci ze seznamu podnikových aplikací . Vyberte Uživatelé a skupiny a pak přidejte uživatele nebo skupinu. V části Uživatelé a skupiny vyberte skupiny, které chcete přidat do aplikace.
   • Možnost Všechny skupiny zahrnuje skupinu SecurityGroup, DirectoryRole a DistributionList, ale ne skupiny přiřazené k aplikaci.
5. Volitelné: Vyberte konkrétní vlastnosti typu tokenu a upravte hodnotu deklarace identity skupiny tak, aby obsahovala atributy místní skupiny, nebo změňte typ deklarace identity na roli.
6. Zvolte Uložit.

Pomocí následujících kroků nakonfigurujte volitelné deklarace identity skupin prostřednictvím manifestu aplikace:

1. Vyberte aplikaci, pro kterou chcete nakonfigurovat volitelné deklarace identity.

2. V části Spravovat vyberte Manifest.

3. Pomocí editoru manifestu přidejte následující položku:

   Platné hodnoty jsou:

   • "Vše" (tato možnost zahrnuje SecurityGroup, DirectoryRole a DistributionList)
   • "SecurityGroup"
   • "DirectoryRole"
   • "ApplicationGroup" (tato možnost zahrnuje pouze skupiny, které jsou přiřazeny k aplikaci)

   Příklad:

   "groupMembershipClaims": "SecurityGroup"
   

   Ve výchozím nastavení se ID objektů skupiny vygenerují v hodnotě deklarace identity skupiny. Chcete-li upravit hodnotu deklarace identity tak, aby obsahovala atributy místní skupiny nebo změnit typ deklarace identity na roli, použijte optionalClaims konfiguraci následujícím způsobem:

4. Nastavte volitelné deklarace identity pro konfiguraci názvu skupiny.

   Pokud chcete, aby skupiny v tokenu obsahovaly atributy místní skupiny v oddílu volitelných deklarací identity, určete, na který typ tokenu se má použít volitelná deklarace identity. Zadáte také název volitelné požadované deklarace identity a všechny další požadované vlastnosti.

   Můžete uvést více typů tokenů:

   • idToken pro token ID OIDC
   • accessToken pro přístupový token OAuth
   • Saml2Token pro tokeny SAML.

   Typ Saml2Token platí pro tokeny formátu SAML1.1 i SAML2.0.

   Pro každý relevantní typ tokenu upravte deklaraci identity skupin tak, aby používala optionalClaims oddíl v manifestu. Schéma optionalClaims je následující:

   {
       "name": "groups",
       "source": null,
       "essential": false,
       "additionalProperties": []
   }
   

   Volitelné schéma deklarací identity	Hodnota
   name	Musí být groups
   source	Nepoužívá se. Vynecháte nebo zadejte hodnotu null.
   essential	Nepoužívá se. Vynecháte nebo zadejte false.
   additionalProperties	Seznam dalších vlastností Platné možnosti jsou sam_account_name, dns_domain_and_sam_account_name, netbios_domain_and_sam_account_nameemit_as_roles a cloud_displayname.

   Pouze v additionalProperties jednom z sam_account_name, dns_domain_and_sam_account_namenetbios_domain_and_sam_account_name jsou požadovány. Pokud je k dispozici více než jeden, použije se první a ostatní budou ignorovány. Můžete také přidat cloud_displayname zobrazovaný název cloudové skupiny. Tato možnost funguje pouze v případě, že groupMembershipClaims je nastavena na ApplicationGrouphodnotu .

   Některé aplikace vyžadují informace o skupině o uživateli v deklaraci identity role. Chcete-li změnit typ deklarace identity ze skupiny na deklaraci identity role, přidejte emit_as_roles do additionalProperties. Hodnoty skupiny se v deklaraci identity role vygenerují.

   Pokud emit_as_roles se použije, nebudou v deklaraci identity role přiřazené žádné role aplikace nakonfigurované uživatelem (nebo aplikací prostředků).

Následující příklady ukazují konfiguraci manifestu pro deklarace identity skupin:

Vygeneruje skupiny jako názvy skupin v přístupových tokenech OAuth ve dnsDomainName\sAMAccountName formátu.

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Vygenerujte názvy skupin, které se mají vrátit ve netbiosDomain\sAMAccountName formátu jako deklarace rolí v tokenech SAML a OIDC ID.

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

Vygenerujte názvy skupin ve formátu sam_account_name pro místní synchronizované skupiny a cloud_display název pro cloudové skupiny v tokenech SAML a ID OIDC pro skupiny přiřazené k aplikaci.

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

Příklad volitelných deklarací identity

Pro povolení a konfiguraci volitelných deklarací identity aplikace je k dispozici několik možností aktualizace vlastností konfigurace identity:

• Můžete použít Azure Portal.
• Manifest můžete použít.
• Je také možné napsat aplikaci, která k aktualizaci aplikace používá rozhraní Microsoft Graph API . Typ OptionalClaims v referenční příručce k rozhraní Microsoft Graph API vám může pomoct s konfigurací volitelných deklarací identity.

V následujícím příkladu se azure Portal a manifest používají k přidání volitelných deklarací identity pro přístup, ID a tokeny SAML určené pro vaši aplikaci. Do každého typu tokenu, který může aplikace přijímat, se přidají různé volitelné deklarace identity:

• Tokeny ID obsahují hlavní název uživatele (UPN) pro federované uživatele v úplném formátu (<upn>_<homedomain>#EXT#@<resourcedomain>).
• Přístupové tokeny, které ostatní klienti požadují pro tuto aplikaci, zahrnují auth_time deklaraci identity.
• Tokeny SAML obsahují rozšíření schématu skypeId adresáře (v tomto příkladu je ab603c56068041afb2f6832e2a17e237ID aplikace pro tuto aplikaci). Token SAML zveřejňuje ID Skypu jako extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Konfigurace deklarací identity na webu Azure Portal:

1. Vyberte aplikaci, pro kterou chcete nakonfigurovat volitelné deklarace identity.
2. V části Spravovat vyberte konfiguraci tokenu.
3. Vyberte Přidat volitelnou deklaraci identity, vyberte typ tokenu ID , ze seznamu deklarací identity vyberte upn a pak vyberte Přidat.
4. Vyberte Přidat volitelnou deklaraci identity, vyberte typ přístupového tokenu, v seznamu deklarací identity vyberte auth_time a pak vyberte Přidat.
5. Na obrazovce Přehled konfigurace tokenů vyberte ikonu tužky vedle hlavního názvu uživatele( upn), vyberte přepínač Externě ověřený a pak vyberte Uložit.
6. Vyberte Přidat volitelnou deklaraci identity, vyberte typ tokenu SAML , ze seznamu deklarací identity vyberte extn.skypeID (platí jenom v případě, že jste vytvořili objekt uživatele Microsoft Entra s názvem skypeID) a pak vyberte Přidat.

Konfigurace deklarací identity v manifestu:

1. Vyberte aplikaci, pro kterou chcete nakonfigurovat volitelné deklarace identity.

2. V části Spravovat vyberte Manifest a otevřete vložený editor manifestu.

3. Manifest můžete přímo upravit pomocí tohoto editoru. Manifest se řídí schématem entity Aplikace a po uložení manifest automaticky formátuje. Do vlastnosti se přidají optionalClaims nové prvky.

   "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
           }
       ]
   }
   

4. Po dokončení aktualizace manifestu vyberte Uložit a uložte manifest.

Omezení

Aplikace může vydat maximální počet 10 atributů rozšíření jako volitelné deklarace identity.

Související obsah

• Přístupové tokeny
• Manifest aplikace
• Tokeny ID
• Volitelné referenční informace k deklaracím