Přizpůsobení deklarací identity vydaných ve webovém tokenu JSON (JWT) pro podnikové aplikace

Platforma Microsoft Identity Platform podporuje jednotné přihlašování (SSO) s většinou předem integrovaných aplikací v galerii aplikací Microsoft Entra a vlastních aplikací. Když se uživatel ověří v aplikaci prostřednictvím platformy Microsoft Identity Platform pomocí protokolu OIDC, odešle do aplikace token. Aplikace ověří a použije token k přihlášení uživatele místo výzvy k zadání uživatelského jména a hesla.

Tyto webové tokeny JSON (JWT) používané aplikacemi OIDC a OAuth obsahují informace o uživateli známém jako deklarace identity. Deklarace identity je informace, které zprostředkovatel identity uvádí o uživateli uvnitř tokenu, který pro daného uživatele vydává. V odpovědi OIDC jsou data deklarací identity obvykle obsažena v tokenu ID vydaném zprostředkovatelem identity ve formě JWT.

Zobrazení nebo úprava deklarací identity

Tip

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

Volitelné deklarace identity JWT je možné nakonfigurovat v původní registraci aplikace, ale dají se nakonfigurovat i v podnikové aplikaci. Zobrazení nebo úprava deklarací identity vydané v JWT pro aplikaci:

1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce cloudových aplikací.
2. Přejděte k podnikovým aplikacím>Identita>Aplikace>Všechny aplikace.
3. Vyberte aplikaci, v nabídce vlevo vyberte jednotné přihlašování a pak v části Atributy a deklarace identity vyberte Upravit.

Aplikace může potřebovat přizpůsobení deklarací identity z různých důvodů. Pokud například aplikace vyžaduje jinou sadu identifikátorů URI deklarací identity nebo hodnot deklarací identity. Pomocí oddílu Atributy a deklarace identity můžete přidat nebo odebrat deklaraci identity pro vaši aplikaci. Můžete také vytvořit vlastní deklaraci identity, která je specifická pro aplikaci na základě případu použití.

Následující kroky popisují, jak přiřadit konstantní hodnotu:

1. Vyberte deklaraci identity, kterou chcete upravit.
2. Zadejte konstantní hodnotu bez uvozovek v atributu Zdroj podle vaší organizace a pak vyberte Uložit.

Přehled atributů zobrazuje konstantní hodnotu.

Speciální transformace deklarací identity

Můžete použít následující speciální funkce transformací deklarací identity.

Function	Popis
ExtractMailPrefix()	Odebere příponu domény z e-mailové adresy nebo hlavního názvu uživatele. Tato funkce extrahuje pouze první část uživatelského jména. Například místo joe_smith joe_smith@contoso.com.
ToLower()	Převede znaky vybraného atributu na malá písmena.
ToUpper()	Převede znaky vybraného atributu na velká písmena.

Přidání deklarací identity specifických pro aplikaci

Přidání deklarací identity specifických pro aplikaci:

1. V části Atributy a deklarace identity uživatele vyberte Přidat novou deklaraci identity a otevřete stránku Spravovat deklarace identity uživatele.
2. Zadejte název deklarací identity. Hodnota nemusí striktně dodržovat vzor identifikátoru URI. Pokud potřebujete vzor identifikátoru URI, můžete ho umístit do pole Obor názvů .
3. Vyberte zdroj, ve kterém deklarace identity načte její hodnotu. Atribut uživatele můžete vybrat z rozevíracího seznamu zdrojového atributu nebo použít transformaci na atribut uživatele, než ho vygenerujete jako deklaraci identity.

Transformace deklarací identity

Použití transformace u atributu uživatele:

1. V části Spravovat deklaraci identity vyberte Transformovat jako zdroj deklarací, aby se otevřela stránka Spravovat transformaci .
2. V rozevíracím seznamu transformace vyberte funkci. V závislosti na vybrané funkci zadejte parametry a konstantní hodnotu, které se mají vyhodnotit v transformaci.
3. Považovat zdroj za vícehodnotový označuje, zda je transformace použita pro všechny hodnoty nebo pouze první. Ve výchozím nastavení se u transformací použije první prvek deklarace více hodnot. Když toto políčko zaškrtnete, zajistíte, že se použije u všech. Toto políčko je povoleno pouze pro atributy s více hodnotami. Například user.proxyaddresses.
4. Pokud chcete použít více transformací, vyberte Přidat transformaci. U deklarace identity můžete použít maximálně dvě transformace. Můžete například napřed extrahovat předponu user.maile-mailu . Potom nastavte velká písmena řetězce.

K transformaci deklarací identity můžete použít následující funkce.

Function	Popis
ExtractMailPrefix()	Odebere příponu domény z e-mailové adresy nebo hlavního názvu uživatele. Tato funkce extrahuje pouze první část uživatelského jména. Například místo joe_smith joe_smith@contoso.com.
Join()	Vytvoří novou hodnotu spojením dvou atributů. Volitelně můžete použít oddělovač mezi dvěma atributy. U transformace deklarace identity NameID má funkce Join() specifické chování, pokud má vstup transformace část domény. Před spojením s oddělovačem a vybraným parametrem odebere část domény ze vstupu. Pokud je například vstup transformace joe_smith@contoso.com a oddělovač je @ a parametr je fabrikam.com, výsledkem této kombinace vstupu je joe_smith@fabrikam.com.
ToLowercase()	Převede znaky vybraného atributu na malá písmena.
ToUppercase()	Převede znaky vybraného atributu na velká písmena.
Contains()	Vypíše atribut nebo konstantu, pokud vstup odpovídá zadané hodnotě. V opačném případě můžete zadat jiný výstup, pokud neexistuje žádná shoda. Pokud například chcete vygenerovat deklaraci identity, ve které je hodnota e-mailová adresa uživatele, pokud obsahuje doménu @contoso.com, jinak chcete vygenerovat hlavní název uživatele. Chcete-li provést tuto funkci, nakonfigurujete následující hodnoty: Parametr 1(input): user.email Hodnota: "@contoso.com" Parametr 2 (výstup): user.email Parametr 3 (výstup, pokud neexistuje žádná shoda): user.userprincipalname
EndWith()	Vypíše atribut nebo konstantu, pokud vstup končí zadanou hodnotou. V opačném případě můžete zadat jiný výstup, pokud neexistuje žádná shoda. Pokud například chcete vygenerovat deklaraci identity, ve které je hodnota ID zaměstnance uživatele, pokud ID zaměstnance končí 000, jinak chcete vygenerovat atribut rozšíření. Chcete-li provést tuto funkci, nakonfigurujete následující hodnoty: Parametr 1(input): user.employeeid Hodnota: "000" Parametr 2 (výstup): user.employeeid Parametr 3 (výstup, pokud neexistuje žádná shoda): user.extensionattribute1
StartWith()	Vypíše atribut nebo konstantu, pokud vstup začíná zadanou hodnotou. V opačném případě můžete zadat jiný výstup, pokud neexistuje žádná shoda. Pokud například chcete vygenerovat deklaraci identity, ve které je hodnota ID zaměstnance uživatele, pokud země nebo oblast začíná US, jinak chcete vygenerovat atribut rozšíření. Chcete-li provést tuto funkci, nakonfigurujete následující hodnoty: Parametr 1(input): user.country Hodnota: "US" Parametr 2 (výstup): user.employeeid Parametr 3 (výstup, pokud neexistuje žádná shoda): user.extensionattribute1
Extract() – Po párování	Vrátí podřetěděcí řetězec, který odpovídá zadané hodnotě. Pokud je Finance_BSimonnapříklad hodnota vstupu , odpovídající hodnota je Finance_, pak je BSimonvýstup deklarace identity .
Extract() – Před párování	Vrátí podřetěžec, dokud neodpovídá zadané hodnotě. Pokud je BSimon_USnapříklad hodnota vstupu , odpovídající hodnota je _US, pak je BSimonvýstup deklarace identity .
Extract() – Mezi párování	Vrátí podřetěžec, dokud neodpovídá zadané hodnotě. Pokud je Finance_BSimon_USnapříklad vstupní hodnota , první odpovídající hodnota je Finance_, druhá odpovídající hodnota je _US, pak je BSimonvýstup deklarace identity .
ExtractAlpha() – předpona	Vrátí předponu abecední část řetězce. Pokud je BSimon_123například hodnota vstupu , vrátí BSimonhodnotu .
ExtractAlpha() – přípona	Vrátí příponu abecední část řetězce. Pokud je 123_Simonnapříklad hodnota vstupu , vrátí Simonhodnotu .
ExtractNumeric() – předpona	Vrátí číselnou část řetězce s předponou. Pokud je 123_BSimonnapříklad hodnota vstupu , vrátí 123hodnotu .
ExtractNumeric() – přípona	Vrátí číselnou část řetězce s příponou. Pokud je BSimon_123například hodnota vstupu , vrátí 123hodnotu .
IfEmpty()	Vypíše atribut nebo konstantu, pokud je vstup null nebo prázdný. Pokud například chcete vypsat atribut uložený v atributu rozšíření, pokud je ID zaměstnance daného uživatele prázdné. Pokud chcete tuto funkci provést, nakonfigurujte následující hodnoty: Parametr 1(input): user.employeeid Parametr 2 (výstup): user.extensionattribute1 Parametr 3 (výstup, pokud neexistuje žádná shoda): user.employeeid
IfNotEmpty()	Vypíše atribut nebo konstantu, pokud vstup není null nebo prázdný. Pokud například chcete vypsat atribut uložený v atributu rozšíření, pokud ID zaměstnance daného uživatele není prázdné. Chcete-li provést tuto funkci, nakonfigurujete následující hodnoty: Parametr 1(input): user.employeeid Parametr 2 (výstup): user.extensionattribute1
Substring() – pevná délka	Extrahuje části typu deklarace identity řetězce, počínaje znakem na zadané pozici a vrátí zadaný počet znaků. SourceClaim – zdroj deklarace identity transformace, která by se měla provést. StartIndex – pozice počátečního znaku založeného na nule podřetězdce v této instanci. Délka – délka znaků podřetědce. Příklad: sourceClaim - PleaseExtractThisNow StartIndex – 6 Délka – 11 Výstup: ExtractThis
Podřetězce() – EndOfString	Extrahuje části typu deklarace identity řetězce, počínaje znakem na zadané pozici a vrátí zbytek deklarace identity ze zadaného počátečního indexu. SourceClaim – zdroj deklarace identity transformace. StartIndex – pozice počátečního znaku založeného na nule podřetězdce v této instanci. Příklad: sourceClaim - PleaseExtractThisNow StartIndex – 6 Výstup: ExtractThisNow
RegexReplace()	Transformace RegexReplace() přijímá jako vstupní parametry: - Parametr 1: atribut uživatele jako vstup regulárního výrazu – Možnost důvěřovat zdroji jako vícehodnotové - Vzor regulárních výrazů - Náhradní vzor. Náhradní vzor může obsahovat statický textový formát spolu s odkazem, který odkazuje na výstupní skupiny regulárních výrazů a další vstupní parametry.

Pokud potřebujete další transformace, odešlete svůj nápad na fóru pro zpětnou vazbu ve fóru Microsoft Entra ID v kategorii aplikace SaaS.

Transformace deklarací identit založených na regulárních výrazech

Následující obrázek ukazuje příklad první úrovně transformace:

Následující tabulka obsahuje informace o první úrovni transformací. Akce uvedené v tabulce odpovídají popiskům na předchozím obrázku. Výběrem možnosti Upravit otevřete okno transformace deklarací identity.

Akce	Pole	Popis
1	Transformation	V možnostech transformace vyberte možnost RegexReplace() a použijte metodu transformace deklarací identity založenou na regulárním výrazu pro transformaci deklarací.
2	Parameter 1	Vstup pro transformaci regulárního výrazu. Například user.mail, který má e-mailovou adresu uživatele, například admin@fabrikam.com.
3	Treat source as multivalued	Některé vstupní atributy uživatele můžou být atributy uživatele s více hodnotami. Pokud vybraný atribut uživatele podporuje více hodnot a uživatel chce pro transformaci použít více hodnot, musí vybrat Možnost Považovat zdroj za více hodnot. Pokud je tato možnost vybraná, použijí se všechny hodnoty pro shodu regulárních výrazů, jinak se použije jenom první hodnota.
4	Regex pattern	Regulární výraz, který je vyhodnocen proti hodnotě atributu uživatele vybraného jako parametr 1. Například regulární výraz pro extrahování uživatelského aliasu z e-mailové adresy uživatele je reprezentován jako (?'domain'^.*?)(?i)(\@fabrikam\.com)$.
5	Add additional parameter	Pro transformaci lze použít více než jeden atribut uživatele. Hodnoty atributů by se pak sloučily s výstupem transformace regulárních výrazů. Podporuje se až pět dalších parametrů.
6	Replacement pattern	Vzor nahrazení je textová šablona, která obsahuje zástupné symboly pro výsledek regulárního výrazu. Všechny názvy skupin musí být zabalené uvnitř složených závorek, například {group-name}. Řekněme, že správa chce použít alias uživatele s jiným názvem domény, například xyz.com sloučit název země s ním. V tomto případě by {country}.{domain}@xyz.combyl vzor nahrazení , kde {country} je hodnota vstupního parametru a {domain} je výstupem skupiny z vyhodnocení regulárního výrazu. V takovém případě je US.swmal@xyz.comočekávaný výsledek .

Následující obrázek ukazuje příklad druhé úrovně transformace:

Následující tabulka obsahuje informace o druhé úrovni transformací. Akce uvedené v tabulce odpovídají popiskům na předchozím obrázku.

Akce	Pole	Popis
1	Transformation	Transformace deklarací identity založené na regulárních výrazech nejsou omezeny na první transformaci a lze je použít také jako druhou úroveň transformace. Jako první transformaci je možné použít jakoukoli jinou metodu transformace.
2	Parameter 1	Pokud je jako transformace druhé úrovně vybraná možnost RegexReplace(), použije se výstup transformace první úrovně jako vstup pro transformaci druhé úrovně. Pokud chcete použít transformaci, měl by výraz regulárního výrazu druhé úrovně odpovídat výstupu první transformace.
3	Regex pattern	Vzor regulárního výrazu je regulární výraz pro transformaci druhé úrovně.
4	Parameter input	Vstupy atributů uživatele pro transformace druhé úrovně
5	Parameter input	Správci můžou vybraný vstupní parametr odstranit, pokud už ho nepotřebují.
6	Replacement pattern	Vzor nahrazení je textová šablona, která obsahuje zástupné symboly pro název skupiny výsledků regex, název skupiny vstupních parametrů a statickou textovou hodnotu. Všechny názvy skupin musí být zabaleny uvnitř složených závorek, například {group-name}. Řekněme, že správa chce použít alias uživatele s jiným názvem domény, například xyz.com sloučit název země s ním. V tomto případě by {country}.{domain}@xyz.combyl vzor nahrazení , kde {country} je hodnota vstupního parametru a {domain} je výstupem skupiny z vyhodnocení regulárního výrazu. V takovém případě je US.swmal@xyz.comočekávaný výsledek .
7	Test transformation	Transformace RegexReplace() je vyhodnocena pouze v případě, že hodnota vybraného atributu uživatele pro parametr 1 odpovídá regulárnímu výrazu zadanému v textovém poli vzoru Regex. Pokud se neshodují, přidá se do tokenu výchozí hodnota deklarace identity. K ověření regulárního výrazu vůči hodnotě vstupního parametru je v okně transformace k dispozici testovací prostředí. Toto testovací prostředí funguje pouze na fiktivních hodnotách. Při použití více vstupních parametrů se název parametru přidá do výsledku testu místo skutečné hodnoty. Pokud chcete získat přístup k testovací části, vyberte Test transformace.

Následující obrázek ukazuje příklad testování transformací:

Následující tabulka obsahuje informace o testování transformací. Akce uvedené v tabulce odpovídají popiskům na předchozím obrázku.

Akce	Pole	Popis
1	Test transformation	Výběrem tlačítka Zavřít nebo (X) skryjete testovací oddíl a znovu vykreslíte tlačítko Transformace testu v okně.
2	Test regex input	Přijímá vstup, který se používá pro vyhodnocení testu regulárního výrazu. V případě, že je transformace deklarací identity založená na regulárních výrazech nakonfigurovaná jako transformace druhé úrovně, zadejte hodnotu, která je očekávaným výstupem první transformace.
3	Run test	Po zadání vstupu testovacího regulárního výrazu a způsobu regulárního výrazu, vzor nahrazení a vstupní parametry lze výraz vyhodnotit výběrem příkazu Spustit test.
4	Test transformation result	Pokud je vyhodnocení úspěšné, výstup transformace testu se vykreslí s popiskem výsledku transformace testu.
5	Remove transformation	Druhou úroveň transformace lze odebrat výběrem možnosti Odebrat transformaci.
6	Specify output if no match	Pokud je vstupní hodnota regulárního výrazu nakonfigurovaná pro parametr 1, který neodpovídá regulárnímu výrazu, transformace se přeskočí. V takových případech je možné nakonfigurovat alternativní atribut uživatele, který se přidá do tokenu deklarace identity zaškrtnutím políčka Zadat výstup, pokud se neshoduje.
7	Parameter 3	Pokud je potřeba vrátit alternativní atribut uživatele, pokud není žádná shoda, a zadat výstup, pokud není zaškrtnuto žádná shoda , lze pomocí rozevíracího seznamu vybrat alternativní atribut uživatele. Tento rozevírací seznam je k dispozici pro parametr 3 (výstup, pokud se neshoduje).
8	Summary	V dolní části okna se zobrazí úplný souhrn formátu, který vysvětluje význam transformace v jednoduchém textu.
9	Add	Jakmile se ověří nastavení konfigurace transformace, můžete ho uložit do zásad deklarací tak, že vyberete Přidat. Výběrem možnosti Uložit v okně Spravovat deklaraci identity uložte změny.

Transformace RegexReplace() je také k dispozici pro transformace deklarací identity skupin.

Ověření transformace

Zpráva obsahuje další informace, když po výběru možnosti Přidat nebo spustit test dojde k následujícím podmínkám:

• Byly použity vstupní parametry s duplicitními atributy uživatele.
• Byly nalezeny nepoužité vstupní parametry. Definované vstupní parametry by měly mít odpovídající použití v textu vzoru nahrazení.
• Zadaný vstup regulárního výrazu testu neodpovídá zadanému regulárnímu výrazu.
• Nebyly nalezeny žádné zdroje pro skupiny ve vzoru nahrazení.

Generování deklarací identity na základě podmínek

Zdroj deklarace identity můžete zadat na základě typu uživatele a skupiny, do které uživatel patří.

Typ uživatele může být následující:

• Libovolná – Přístup k aplikaci mají všichni uživatelé.
• Členové: Nativní člen tenanta
• Všichni hosté: Uživatel se přesunul z externí organizace s ID Microsoft Entra nebo bez.
• Hosté Microsoft Entra: Uživatel typu host patří do jiné organizace pomocí ID Microsoft Entra.
• Externí hosté: Uživatel typu host patří do externí organizace, která nemá ID Microsoft Entra.

Jedním ze scénářů, kdy je užitečný typ uživatele, je situace, kdy se zdroj deklarace identity liší pro hosta a zaměstnance, který přistupuje k aplikaci. Můžete zadat, že pokud je uživatel zaměstnancem, získejte ID jména z user.email. Pokud je uživatel hostem, pak ID názvu pochází z user.extensionattribute1.

Přidání podmínky deklarace identity:

1. V části Spravovat deklaraci identity rozbalte podmínky deklarace identity.
2. Vyberte typ uživatele.
3. Vyberte skupiny, do kterých má uživatel patřit. Pro danou aplikaci můžete vybrat až 50 jedinečných skupin pro všechny deklarace identity.
4. Vyberte zdroj, ve kterém deklarace identity načte její hodnotu. Atribut uživatele můžete vybrat z rozevíracího seznamu zdrojového atributu nebo použít transformaci na atribut uživatele, než ho vygenerujete jako deklaraci identity.

Pořadí, ve kterém přidáte podmínky, jsou důležité. Microsoft Entra nejprve vyhodnotí všechny podmínky se zdrojem Attribute a pak vyhodnotí všechny podmínky se zdrojem Transformation a rozhodne, kterou hodnotu se má v deklaraci identity vygenerovat. ID Microsoft Entra vyhodnocuje podmínky se stejným zdrojem shora dolů. Deklarace identity generuje poslední hodnotu, která odpovídá výrazu v deklaraci identity. Transformace, jako IsNotEmpty jsou omezení a Contains chovají se jako omezení.

Britta Simon je například uživatel typu host v tenantovi Contoso. Britta patří do jiné organizace, která používá také ID Microsoft Entra. Vzhledem k následující konfiguraci pro aplikaci Fabrikam se Britta pokusí přihlásit k Fabrikam, platforma Microsoft Identity Platform vyhodnotí podmínky.

Nejprve platforma Microsoft Identity Platform ověřuje, jestli je typ uživatele Britta Všichni hosté. Vzhledem k tomu, že typ je Všichni hosté, platforma Microsoft Identity Platform přiřadí zdroj deklarace identity .user.extensionattribute1 Za druhé platforma Microsoft Identity Platform ověřuje, jestli je typ uživatele Britta hosty Microsoft Entra. Vzhledem k tomu, že typ je Všichni hosté, platforma Microsoft Identity Platform přiřadí zdroj deklarace identity .user.mail Nakonec se deklarace identity vygeneruje s hodnotou user.mail pro Britta.

Jako další příklad zvažte, když se Britta Simon pokusí přihlásit pomocí následující konfigurace. Microsoft Entra nejprve vyhodnotí všechny podmínky se zdrojem Attribute. Zdrojem deklarace identity je user.mail , že typ uživatele Britta je Microsoft Entra guests. V dalším kroku vyhodnocuje ID Microsoft Entra transformace. Protože Britta je host, user.extensionattribute1 je novým zdrojem deklarace identity. Vzhledem k tomu, že Britta je ve službě Microsoft Entra guests, user.othermail je novým zdrojem této deklarace identity. Nakonec se deklarace identity vygeneruje s hodnotou user.othermail pro Britta.

Jako poslední příklad zvažte, co se stane, když Britta nemá user.othermail nakonfigurovanou žádnou konfiguraci nebo je prázdná. Deklarace identity se vrátí k user.extensionattribute1 ignorování položky podmínky v obou případech.

Bezpečnostní aspekty

Aplikace, které přijímají tokeny, spoléhají na hodnoty deklarací identity, se kterými nelze manipulovat. Při úpravě obsahu tokenu prostřednictvím přizpůsobení deklarací identity už tyto předpoklady nemusí být správné. Aplikace musí explicitně potvrdit, že tokeny byly upraveny tak, aby se chránily před vlastními nastaveními vytvořenými aktéry se zlými úmysly. Chraňte před nevhodnými přizpůsobeními jedním z následujících způsobů:

• Konfigurace vlastního podpisového klíče
• Aktualizujte manifest aplikace tak, aby přijímal mapované deklarace identity.

Bez toho vrátí ID Microsoft Entra kód chyby AADSTS50146.

Konfigurace vlastního podpisového klíče

U víceklientských aplikací by se měl použít vlastní podpisový klíč. Nenastavujte acceptMappedClaims v manifestu aplikace. Při nastavování aplikace na webu Azure Portal získáte objekt registrace aplikace a instanční objekt ve vašem tenantovi. Tato aplikace používá globální přihlašovací klíč Azure, který se nedá použít k přizpůsobení deklarací identity v tokenech. Pokud chcete získat vlastní deklarace identity v tokenech, vytvořte z certifikátu vlastní přihlašovací klíč a přidejte ho do instančního objektu. Pro účely testování můžete použít certifikát podepsaný svým držitelem. Po nakonfigurování vlastního podpisového klíče musí kód aplikace ověřit podpisový klíč tokenu.

Do instančního objektu přidejte následující informace:

• Privátní klíč (jako přihlašovací údaje klíče)
• Heslo (jako přihlašovací údaje hesla)
• Veřejný klíč (jako přihlašovací údaje klíče)

Extrahujte privátní a veřejný klíč s kódováním Base-64 z exportu souboru PFX vašeho certifikátu. Ujistěte se, že keyId hodnota použitá keyCredential pro znak odpovídá keyId hodnotě znaménko passwordCredential. Hodnotu hash kryptografického otisku certifikátu můžete vygenerovat customkeyIdentifier .

Požádat

Poznámka:

Nejprve zakažte všechny konfigurace uzamčení instančního objektu v nově vytvořených aplikacích z okna Registrace aplikací Centra pro správu Microsoft Entra, než se pokusíte provést opravu instančního objektu, což vede k chybnému požadavku 400.

Následující příklad ukazuje formát požadavku HTTP PATCH pro přidání vlastního podpisového klíče do instančního objektu. Hodnota "klíč" ve keyCredentials vlastnosti je zkrácena pro čitelnost. Hodnota má kódování base-64. Pro privátní klíč je Signpoužití vlastnosti . Pro veřejný klíč je Verifypoužití vlastnosti .

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/aaaaaaaa-bbbb-cccc-1111-222222222222

Content-type: servicePrincipals/json
Authorization: Bearer {token}

{
    "keyCredentials":[
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=", 
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "X509CertAndPassword",
            "usage": "Sign",
            "key":"cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
            "displayName": "CN=contoso"
        },
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "bbbbbbbb-1c1c-2d2d-3e3e-444444444444",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
            "displayName": "CN=contoso"
        }

    ],
    "passwordCredentials": [
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
            "keyId": "cccccccc-2d2d-3e3e-4f4f-555555555555",
            "endDateTime": "2022-01-27T19:40:33Z",
            "startDateTime": "2020-04-20T19:40:33Z",
            "secretText": "mypassword"
        }
    ]
}

Konfigurace vlastního podpisového klíče pomocí PowerShellu

Pomocí PowerShellu vytvořte instanci veřejné klientské aplikace MSAL a použijte tok udělení autorizačního kódu k získání delegovaného přístupového tokenu oprávnění pro Microsoft Graph. Přístupový token použijte k volání Microsoft Graphu a konfiguraci vlastního podpisového klíče pro instanční objekt. Po nakonfigurování vlastního podpisového klíče musí kód aplikace ověřit podpisový klíč tokenu.

Ke spuštění tohoto skriptu potřebujete:

• ID objektu instančního objektu vaší aplikace, které najdete v okně Přehled položky aplikace v podnikových aplikacích na webu Azure Portal.
• Registrace aplikace pro přihlášení uživatele a získání přístupového tokenu pro volání Microsoft Graphu Získejte ID aplikace (klienta) této aplikace v okně Přehled položky aplikace v Registrace aplikací na webu Azure Portal. Registrace aplikace by měla mít následující konfiguraci:
  • Identifikátor URI přesměrování "http://localhost" uvedené v konfiguraci platformy Mobilní a desktopové aplikace .
  • V oprávněních rozhraní API delegovaná oprávnění Služby Microsoft Graph Application.ReadWrite.All a User.Read (ujistěte se, že jste udělili souhlas správce s těmito oprávněními).
• Uživatel, který se přihlásí, aby získal přístupový token Microsoft Graphu. Uživatel by měl být jednou z následujících rolí pro správu Microsoft Entra (nutné k aktualizaci instančního objektu):
  • Správce cloudové aplikace
  • Správce aplikace
• Certifikát pro konfiguraci jako vlastní podpisový klíč pro naši aplikaci. Můžete buď vytvořit certifikát podepsaný svým držitelem, nebo ho získat od důvěryhodné certifikační autority. Ve skriptu se používají následující součásti certifikátu:
  • veřejný klíč (obvykle soubor .cer )
  • privátní klíč ve formátu PKCS#12 (v souboru .pfx )
  • heslo pro privátní klíč (soubor .pfx )

Důležité

Privátní klíč musí být ve formátu PKCS#12, protože ID Microsoft Entra nepodporuje jiné typy formátů. Použití nesprávného formátu může mít za následek chybu Neplatný certifikát: Hodnota klíče je neplatný certifikát při použití Microsoft Graphu k opravě instančního objektu s informacemi keyCredentials o certifikátu.

##########################################################
# Replace the variables below with the appropriate values 

$fqdn="yourDomainHere" # This is used for the 'issued to' and 'issued by' field of the certificate
$pwd="password" # password for exporting the certificate private key
$tenantId   = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Replace with your Tenant ID
$appObjId = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" # Replace with the Object ID of the App Registration

##########################################################

# Create a self-signed cert

$cert = New-SelfSignedCertificate -certstorelocation cert:\currentuser\my -DnsName $fqdn
$pwdSecure = ConvertTo-SecureString -String $pwd -Force -AsPlainText
$path = 'cert:\currentuser\my\' + $cert.Thumbprint
$location="C:\\temp" # path to folder where both the pfx and cer file will be written to
$cerFile = $location + "\\" + $fqdn + ".cer"
$pfxFile = $location + "\\" + $fqdn + ".pfx"
 
# Export the public and private keys
Export-PfxCertificate -cert $path -FilePath $pfxFile -Password $pwdSecure
Export-Certificate -cert $path -FilePath $cerFile

$pfxpath = $pfxFile # path to pfx file
$cerpath = $cerFile # path to cer file
$password = $pwd  # password for the pfx file
 
# Check PowerShell version (minimum 5.1) (.Net) or PowerShell Core (.Net Core) and read the certificate file accordingly
 
if ($PSVersionTable.PSVersion.Major -gt 5)
    { 
        $core = $true
    }
else
    { 
        $core = $false
    }
 
    #  this is for PowerShell Core
    $Secure_String_Pwd = ConvertTo-SecureString $password -AsPlainText -Force
 
    # reading certificate files and creating Certificate Object
    if ($core)
    {
        $pfx_cert = get-content $pfxpath -AsByteStream -Raw
        $cer_cert = get-content $cerpath -AsByteStream -Raw
        $cert = Get-PfxCertificate -FilePath $pfxpath -Password $Secure_String_Pwd
    }
    else
    {
        $pfx_cert = get-content $pfxpath -Encoding Byte
        $cer_cert = get-content $cerpath -Encoding Byte
        # calling Get-PfxCertificate in PowerShell 5.1 prompts for password - using alternative method
        $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfxpath, $password)
    }

 
    # base 64 encode the private key and public key
    $base64pfx = [System.Convert]::ToBase64String($pfx_cert)
    $base64cer = [System.Convert]::ToBase64String($cer_cert)
 
    # getting id for the keyCredential object
    $guid1 = New-Guid
    $guid2 = New-Guid
 
    # get the custom key identifier from the certificate thumbprint:
    $hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
    $hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($cert.Thumbprint))
    $customKeyIdentifier = [System.Convert]::ToBase64String($hash)
 
    # get end date and start date for our keycredentials
    $endDateTime = ($cert.NotAfter).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
    $startDateTime = ($cert.NotBefore).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
 
    # building our json payload
    $object = [ordered]@{    
    keyCredentials = @(       
         [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid1
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Sign"
            key = $base64pfx
            displayName = "CN=$fqdn" 
        },
        [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid2
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Verify"
            key = $base64cer
            displayName = "CN=$fqdn"   
        }
        )  
    passwordCredentials = @(
        [ordered]@{
            customKeyIdentifier = $customKeyIdentifier
            displayName = "CN=$fqdn"
            keyId = $guid1           
            endDateTime = $endDateTime
            startDateTime = $startDateTime
            secretText = $password
            hint = $null
        }
    )
    }
 
Connect-MgGraph -tenantId $tenantId -Scopes Application.ReadWrite.All
$graphuri = "https://graph.microsoft.com/v1.0/applications/$appObjId"
Invoke-MgGraphRequest -Method PATCH -Uri $graphuri -Body $object

    $json = $object | ConvertTo-Json -Depth 99
    Write-Host "JSON Payload:"
    Write-Output $json

Ověření podpisového klíče tokenu

Aplikace, které mají povolené mapování deklarací identity, musí ověřit podpisové klíče tokenu připojením appid={client_id} k žádostem o metadata OpenID Connect. Následující příklad ukazuje formát dokumentu metadat OpenID Connect, který byste měli použít:

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

Aktualizace manifestu aplikace

U aplikací s jedním tenantem můžete vlastnost nastavit acceptMappedClaims v true manifestu aplikace. Jak je uvedeno v apiApplication typu prostředku. Nastavení vlastnosti umožňuje aplikaci používat mapování deklarací identity bez zadání vlastního podpisového klíče.

Upozorňující

Nenastavujte vlastnost acceptMappedClaims na true pro aplikace s více tenanty, což může umožnit škodlivým hercům vytvářet zásady mapování deklarací identity pro vaši aplikaci.

Požadovaná cílová skupina tokenů se vyžaduje k použití ověřeného názvu domény vašeho tenanta Microsoft Entra, což znamená, že byste měli nastavit Application ID URI (reprezentovanou identifierUris v manifestu aplikace) například na https://contoso.com/my-api nebo (jednoduše pomocí výchozího názvu tenanta). https://contoso.onmicrosoft.com/my-api

Pokud nepoužíváte ověřenou doménu, vrátí ID Microsoft Entra kód chyby se zprávou AADSTS501461 "_AcceptMappedClaims je podporován pouze pro cílovou skupinu tokenů odpovídající identifikátoru GUID aplikace nebo cílové skupině v rámci ověřených domén tenanta. Buď změňte identifikátor prostředku, nebo použijte podpisový klíč specifický pro aplikaci.

Rozšířené možnosti deklarací identity

Nakonfigurujte pokročilé možnosti deklarací identity pro aplikace OIDC tak, aby zpřístupnil stejnou deklaraci identity jako tokeny SAML. Také pro aplikace, které mají v úmyslu použít stejnou deklaraci identity pro tokeny odpovědi SAML2.0 i OIDC.

Konfigurace rozšířených možností deklarací identity zaškrtnutím políčka Upřesnit možnosti deklarací identity v okně Správa deklarací identity

Související obsah

• Deklarace identity a tokeny používané v MICROSOFT Entra ID.