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.

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.

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

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í.

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

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.

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.

Související obsah

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