Claims aanpassen die zijn uitgegeven in het JSON-webtoken (JWT) voor bedrijfstoepassingen
Het Microsoft Identity Platform ondersteunt eenmalige aanmelding (SSO) met de meeste vooraf geïntegreerde toepassingen in de Microsoft Entra-toepassingsgalerie en aangepaste toepassingen. Wanneer een gebruiker zich verifieert bij een toepassing via het Microsoft Identity Platform met behulp van het OIDC-protocol, verzendt het Microsoft Identity Platform een token naar de toepassing. De toepassing valideert en gebruikt het token om de gebruiker te ondertekenen in plaats van om een gebruikersnaam en wachtwoord te vragen.
Deze JSON-webtokens (JWT) die worden gebruikt door OIDC- en OAuth-toepassingen bevatten stukjes informatie over de gebruiker die claims wordt genoemd. Een claim is informatie die een id-provider verstrekt over een gebruiker in het token dat deze uitgeeft voor die gebruiker. In een OIDC-antwoord zijn claimgegevens doorgaans opgenomen in het id-token dat is uitgegeven door de id-provider in de vorm van een JWT.
Claims weergeven of bewerken
Tip
Stappen in dit artikel kunnen enigszins variëren op basis van de portal waaruit u begint.
De claims die in de JWT zijn uitgegeven, weergeven of bewerken in de toepassing:
- Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een cloudtoepassing Beheer istrator.
- Blader naar Bedrijfstoepassingen voor identiteitstoepassingen>>>Alle toepassingen.
- Selecteer de toepassing, selecteer Eenmalige aanmelding in het menu aan de linkerkant en selecteer vervolgens Bewerken in de sectie Kenmerken & Claims .
Een toepassing heeft mogelijk om verschillende redenen een aanpassing van claims nodig. Als een toepassing bijvoorbeeld een andere set claim-URI's of claimwaarden vereist. Met behulp van de sectie Kenmerken en claims kunt u een claim voor uw toepassing toevoegen of verwijderen. U kunt ook een aangepaste claim maken die specifiek is voor een toepassing op basis van de use-case.
In de volgende stappen wordt beschreven hoe u een constante waarde toewijst:
- Selecteer de claim die u wilt wijzigen.
- Voer de constante waarde zonder aanhalingstekens in het kenmerk Bron in volgens uw organisatie en selecteer Opslaan.
In het overzicht kenmerken wordt de constante waarde weergegeven.
Speciale claimtransformaties
U kunt de volgende speciale claimtransformatiefuncties gebruiken.
| Functie | Beschrijving |
|---|---|
| ExtractMailPrefix() | Hiermee verwijdert u het domeinachtervoegsel uit het e-mailadres of de principal-naam van de gebruiker. Met deze functie wordt alleen het eerste deel van de gebruikersnaam geëxtraheerd. Bijvoorbeeld, joe_smith in plaats van joe_smith@contoso.com. |
| ToLower() | Converteert de tekens van het geselecteerde kenmerk naar kleine letters. |
| ToUpper() | Converteert de tekens van het geselecteerde kenmerk naar hoofdletters. |
Toepassingsspecifieke claims toevoegen
Voor toevoegen van toepassingsspecifieke claims
- Selecteer in Gebruikerskenmerken en -claims de optie Nieuwe claim toevoegen om de pagina Gebruikersclaims beheren te openen.
- Voer de naam van de claims in. De waarde hoeft niet strikt een URI-patroon te volgen. Als u een URI-patroon nodig hebt, kunt u dat in het veld Naamruimte plaatsen.
- Selecteer de bron waar de claim de waarde gaat ophalen. U kunt een gebruikerskenmerk selecteren in de vervolgkeuzelijst van het bronkenmerk of een transformatie toepassen op het gebruikerskenmerk voordat u het als claim verzendt.
Transformaties voor claims
Een transformatie toepassen op een gebruikerskenmerk:
- Selecteer in Claim beherenTransformatie als de claimbron om de pagina Transformatie beheren te openen.
- Selecteer de functie in de vervolgkeuzelijst Transformatie. Afhankelijk van de geselecteerde functie geeft u parameters en een constante waarde op die u in de transformatie wilt evalueren.
- Bron behandelen als meerdere waarden geeft aan of de transformatie wordt toegepast op alle waarden of alleen op de eerste. Standaard wordt het eerste element in een claim met meerdere waarden toegepast op de transformaties. Wanneer u dit selectievakje inschakelt, wordt dit op alle toegepast. Dit selectievakje is alleen ingeschakeld voor kenmerken met meerdere waarden. Bijvoorbeeld:
user.proxyaddresses. - Als u meerdere transformaties wilt toepassen, selecteert u Transformatie toevoegen. U kunt maximaal twee transformaties toepassen op een claim. U kunt bijvoorbeeld eerst het e-mailvoorvoegsel extraheren van de
user.mail. Maak vervolgens de tekenreeks met hoofdletters.
U kunt de volgende functies gebruiken om claims te transformeren.
| Functie | Beschrijving |
|---|---|
| ExtractMailPrefix() | Hiermee verwijdert u het domeinachtervoegsel uit het e-mailadres of de principal-naam van de gebruiker. Met deze functie wordt alleen het eerste deel van de gebruikersnaam geëxtraheerd. Bijvoorbeeld, joe_smith in plaats van joe_smith@contoso.com. |
| Samenvoegen() | Hiermee maakt u een nieuwe waarde door twee kenmerken te koppelen. U kunt eventueel een scheidingsteken tussen de twee kenmerken gebruiken. Voor nameID-claimtransformatie heeft de functie Join() specifiek gedrag wanneer de transformatie-invoer een domeinonderdeel bevat. Het domeinonderdeel wordt uit invoer verwijderd voordat het wordt toegevoegd met het scheidingsteken en de geselecteerde parameter. Als de invoer van de transformatie bijvoorbeeld is joe_smith@contoso.com en het scheidingsteken is @ en de parameter is fabrikam.com, resulteert deze invoercombinatie in joe_smith@fabrikam.com. |
| ToLowercase() | Converteert de tekens van het geselecteerde kenmerk naar kleine letters. |
| ToUppercase() | Converteert de tekens van het geselecteerde kenmerk naar hoofdletters. |
| Contains() | Voert een kenmerk of constante uit als de invoer overeenkomt met de opgegeven waarde. Anders kunt u een andere uitvoer opgeven als er geen overeenkomst is. Als u bijvoorbeeld een claim wilt verzenden waarbij de waarde het e-mailadres van de gebruiker is als deze het domein @contoso.combevat, anders wilt u de principal-naam van de gebruiker uitvoeren. Als u deze functie wilt uitvoeren, configureert u de volgende waarden:Parameter 1(invoer): user.email Waarde: "@contoso.com" Parameter 2 (uitvoer): user.email Parameter 3 (uitvoer als er geen overeenkomst is): user.userprincipalname |
| EndWith() | Voert een kenmerk of constante uit als de invoer eindigt op de opgegeven waarde. Anders kunt u een andere uitvoer opgeven als er geen overeenkomst is. Als u bijvoorbeeld een claim wilt verzenden waarbij de waarde de werknemer-id van de gebruiker is als de werknemer-id eindigt 000, anders wilt u een extensiekenmerk uitvoeren. Als u deze functie wilt uitvoeren, configureert u de volgende waarden:Parameter 1(invoer): user.employeeid Waarde: "000" Parameter 2 (uitvoer): user.employeeid Parameter 3 (uitvoer als er geen overeenkomst is): user.extensionattribute1 |
| StartWith() | Resulteert in een kenmerk of constante als de invoer begint met de opgegeven waarde. Anders kunt u een andere uitvoer opgeven als er geen overeenkomst is. Als u bijvoorbeeld een claim wilt verzenden waarbij de waarde de werknemer-id van de gebruiker is als het land of de regio begint US, anders wilt u een extensiekenmerk uitvoeren. Als u deze functie wilt uitvoeren, configureert u de volgende waarden:Parameter 1(invoer): user.country Waarde: "US" Parameter 2 (uitvoer): user.employeeid Parameter 3 (uitvoer als er geen overeenkomst is): user.extensionattribute1 |
| Extract(): na afstemmen | Retourneert de subtekenreeks nadat deze overeenkomt met de opgegeven waarde. Als de waarde van de invoer bijvoorbeeld is, is Finance_BSimonFinance_de overeenkomende waarde , dan is BSimonde uitvoer van de claim . |
| Extract(): Voordat wordt geëxtraheerd | Retourneert de subtekenreeks totdat deze overeenkomt met de opgegeven waarde. Als de waarde van de invoer bijvoorbeeld is, is BSimon_US_USde overeenkomende waarde , dan is BSimonde uitvoer van de claim . |
| Extract(): Tussen afstemmen | Retourneert de subtekenreeks totdat deze overeenkomt met de opgegeven waarde. Als de waarde van de invoer bijvoorbeeld , de eerste overeenkomende waarde is Finance_BSimon_USFinance_, is de tweede overeenkomende waarde , _USdan is BSimonde uitvoer van de claim . |
| ExtractAlpha(): voorvoegsel | Retourneert het alfabetische voorvoegsel van de tekenreeks. Als de waarde van de invoer bijvoorbeeld is BSimon_123, wordt deze geretourneerd BSimon. |
| ExtractAlpha(): achtervoegsel | Retourneert het alfabetische achtervoegsel van de tekenreeks. Als de waarde van de invoer bijvoorbeeld is 123_Simon, wordt deze geretourneerd Simon. |
| ExtractNumeric(): voorvoegsel | Retourneert het alfabetische voorvoegsel van de tekenreeks. Als de waarde van de invoer bijvoorbeeld is 123_BSimon, wordt deze geretourneerd 123. |
| ExtractNumeric(): achtervoegsel | Retourneert het numerieke achtervoegseldeel van de tekenreeks. Als de waarde van de invoer bijvoorbeeld is BSimon_123, wordt deze geretourneerd 123. |
| IfEmpty() | Voert een kenmerk of constante uit als de invoer null of leeg is. Als u bijvoorbeeld een kenmerk wilt uitvoeren dat is opgeslagen in een extensiekenmerk als de werknemer-id voor een bepaalde gebruiker leeg is. Als u deze functie wilt uitvoeren, configureert u de volgende waarden: Parameter 1(invoer): user.employeeid Parameter 2 (uitvoer): user.extensionattribute1 Parameter 3 (uitvoer als er geen overeenkomst is): user.userprincipalname |
| IfNotEmpty() | Voert een kenmerk of constante uit als de invoer niet null of leeg is. Als u bijvoorbeeld een kenmerk wilt uitvoeren dat is opgeslagen in een extensiekenmerk als de werknemer-id voor een bepaalde gebruiker niet leeg is. Als u deze functie wilt uitvoeren, configureert u de volgende waarden: Parameter 1(invoer): user.employeeid Parameter 2 (uitvoer): user.extensionattribute1 |
| Subtekenreeks() - Vaste lengte | Extraheert onderdelen van een tekenreeksclaimtype, beginnend bij het teken op de opgegeven positie en retourneert het opgegeven aantal tekens. SourceClaim: de claimbron van de transformatie die moet worden uitgevoerd. StartIndex: de op nul gebaseerde begintekenpositie van een subtekenreeks in dit exemplaar. Lengte: de lengte in tekens van de subtekenreeks. Voorbeeld: sourceClaim - PleaseExtractThisNow StartIndex - 6 Lengte - 11 Uitvoer: ExtractThis |
| Subtekenreeks() - EndOfString | Extraheert delen van een type tekenreeksclaim, beginnend bij het teken op de opgegeven positie, en retourneert de rest van de claim uit de opgegeven startindex. SourceClaim: de claimbron van de transformatie. StartIndex: de op nul gebaseerde begintekenpositie van een subtekenreeks in dit exemplaar. Voorbeeld: sourceClaim - PleaseExtractThisNow StartIndex - 6 Uitvoer: ExtractThisNow |
| RegexReplace() | RegexReplace() transformatie accepteert als invoerparameters: - Parameter 1: een gebruikerskenmerk als invoer van reguliere expressie - Een optie om de bron te vertrouwen als meerdere waarden - Patroon van reguliere expressie - Vervangingspatroon Het vervangende patroon kan een statische tekstindeling bevatten, samen met een verwijzing die verwijst naar regex-uitvoergroepen en meer invoerparameters. |
Als u andere transformaties nodig hebt, dient u uw idee in op het feedbackforum in Microsoft Entra ID onder de categorie SaaS-toepassing .
Transformatie van claims op basis van Regex
In de volgende afbeelding ziet u een voorbeeld van het eerste niveau van transformatie:
De volgende tabel bevat informatie over het eerste niveau van transformaties. De acties die in de tabel worden vermeld, komen overeen met de labels in de vorige afbeelding. Selecteer Bewerken om de blade claimtransformatie te openen.
| Actie | Veld | Beschrijving |
|---|---|---|
| 1 | Transformation |
Selecteer de optie RegexReplace() in de transformatieopties om de op regex gebaseerde claimtransformatiemethode te gebruiken voor claimtransformatie. |
| 2 | Parameter 1 |
De invoer voor de reguliere expressietransformatie. Bijvoorbeeld user.mail met een e-mailadres van een gebruiker, zoals admin@fabrikam.com. |
| 3 | Treat source as multivalued |
Sommige gebruikerskenmerken voor invoer kunnen gebruikerskenmerken met meerdere waarden zijn. Als het geselecteerde gebruikerskenmerk meerdere waarden ondersteunt en de gebruiker meerdere waarden wil gebruiken voor de transformatie, moeten ze de bron behandelen selecteren als meerdere waarden. Indien geselecteerd, worden alle waarden gebruikt voor de regex-overeenkomst, anders wordt alleen de eerste waarde gebruikt. |
| 4 | Regex pattern |
Een reguliere expressie die wordt geëvalueerd op basis van de waarde van het gebruikerskenmerk dat is geselecteerd als parameter 1. Een reguliere expressie voor het extraheren van de gebruikersalias uit het e-mailadres van de gebruiker wordt bijvoorbeeld weergegeven als (?'domain'^.*?)(?i)(\@fabrikam\.com)$. |
| 5 | Add additional parameter |
Er kunnen meer dan één gebruikerskenmerk worden gebruikt voor de transformatie. De waarden van de kenmerken worden vervolgens samengevoegd met regex-transformatie-uitvoer. Maximaal vijf parameters worden ondersteund. |
| 6 | Replacement pattern |
Het vervangende patroon is de tekstsjabloon, die tijdelijke aanduidingen voor regex-resultaat bevat. Alle groepsnamen moeten tussen de accolades staan, zoals {group-name}. Stel dat het beheer gebruikersalias wil gebruiken met een andere domeinnaam, bijvoorbeeld xyz.com en de landnaam hiermee samenvoegen. In dit geval is {country}.{domain}@xyz.comhet vervangingspatroon, waarbij {country} de waarde van de invoerparameter is en {domain} de groepsuitvoer is van de reguliere expressie-evaluatie. In dat geval is US.swmal@xyz.comhet verwachte resultaat . |
In de volgende afbeelding ziet u een voorbeeld van het tweede transformatieniveau:
De volgende tabel bevat informatie over het tweede niveau van transformaties. De acties die in de tabel worden vermeld, komen overeen met de labels in de vorige afbeelding.
| Actie | Veld | Beschrijving |
|---|---|---|
| 1 | Transformation |
Op Regex gebaseerde claimtransformaties zijn niet beperkt tot de eerste transformatie en kunnen ook worden gebruikt als de transformatie op het tweede niveau. Elke andere transformatiemethode kan als de eerste transformatie worden gebruikt. |
| 2 | Parameter 1 |
Als RegexReplace() is geselecteerd als een transformatie op het tweede niveau, wordt de uitvoer van transformatie op het eerste niveau gebruikt als invoer voor de transformatie op het tweede niveau. Als u de transformatie wilt toepassen, moet de regex-expressie op het tweede niveau overeenkomen met de uitvoer van de eerste transformatie. |
| 3 | Regex pattern |
Regex-patroon is de reguliere expressie voor de transformatie op het tweede niveau. |
| 4 | Parameter input |
Invoer van gebruikerskenmerken voor de transformaties op het tweede niveau. |
| 5 | Parameter input |
Beheer istrators kunnen de geselecteerde invoerparameter verwijderen als ze deze niet meer nodig hebben. |
| 6 | Replacement pattern |
Het vervangende patroon is de tekstsjabloon, die tijdelijke aanduidingen bevat voor de naam van de regex-resultaatgroep, de naam van de invoerparametergroep en de statische tekstwaarde. Alle groepsnamen moeten in de accolades worden verpakt, zoals {group-name}. Stel dat het beheer gebruikersalias wil gebruiken met een andere domeinnaam, bijvoorbeeld xyz.com en de landnaam hiermee samenvoegen. In dit geval is {country}.{domain}@xyz.comhet vervangingspatroon, waarbij {country} de waarde van de invoerparameter is en {domain} de groepsuitvoer is van de reguliere expressie-evaluatie. In dat geval is US.swmal@xyz.comhet verwachte resultaat . |
| 7 | Test transformation |
De regexReplace() transformatie wordt alleen geëvalueerd als de waarde van het geselecteerde gebruikerskenmerk voor parameter 1 overeenkomt met de reguliere expressie die is opgegeven in het tekstvak Regex-patroon . Als deze niet overeenkomen, wordt de standaardclaimwaarde toegevoegd aan het token. Als u een reguliere expressie wilt valideren op basis van de waarde van de invoerparameter, is er een testervaring beschikbaar op de het blad Transformaties. Deze testervaring werkt alleen bij dummy-waarden. Wanneer er meer invoerparameters worden gebruikt, wordt de naam van de parameter toegevoegd aan het testresultaat in plaats van de werkelijke waarde. Selecteer Testtransformatie om toegang te krijgen tot de testsectie. |
In de volgende afbeelding ziet u een voorbeeld van het testen van de transformaties:
De volgende tabel bevat informatie over het testen van de transformaties. De acties die in de tabel worden vermeld, komen overeen met de labels in de vorige afbeelding.
| Actie | Veld | Beschrijving |
|---|---|---|
| 1 | Test transformation |
Selecteer de knop Sluiten of (X) om de testsectie te verbergen en de knop Testtransformatie opnieuw weer te geven op de blade. |
| 2 | Test regex input |
Accepteert invoer die wordt gebruikt voor de evaluatie van de reguliere expressietest. Als op regex gebaseerde claimtransformatie is geconfigureerd als een transformatie op het tweede niveau, geeft u een waarde op die de verwachte uitvoer van de eerste transformatie is. |
| 3 | Run test |
Nadat de regex-invoer van de test is opgegeven en het Regex-patroon, het vervangingspatroon en de invoerparameters zijn geconfigureerd, kan de expressie worden geëvalueerd door De test uitvoeren te selecteren. |
| 4 | Test transformation result |
Als de evaluatie slaagt, wordt een uitvoer van de testtransformatie weergegeven op basis van het resultaatlabel Testtransformatie . |
| 5 | Remove transformation |
De transformatie op het tweede niveau kan worden verwijderd door transformatie verwijderen te selecteren. |
| 6 | Specify output if no match |
Wanneer een regex-invoerwaarde is geconfigureerd voor de parameter 1 die niet overeenkomt met de reguliere expressie, wordt de transformatie overgeslagen. In dergelijke gevallen kan het alternatieve gebruikerskenmerk worden geconfigureerd, dat wordt toegevoegd aan het token voor de claim door uitvoer opgeven te controleren als er geen overeenkomst is. |
| 7 | Parameter 3 |
Als een alternatief gebruikerskenmerk moet worden geretourneerd wanneer er geen overeenkomst is en uitvoer opgeven als er geen overeenkomst is ingeschakeld, kan een alternatief gebruikerskenmerk worden geselecteerd met behulp van de vervolgkeuzelijst. Deze vervolgkeuzelijst is beschikbaar voor parameter 3 (uitvoer als er geen overeenkomst is) . |
| 8 | Summary |
Onder aan de blade wordt een volledige samenvatting van de indeling weergegeven waarin de betekenis van de transformatie in eenvoudige tekst wordt uitgelegd. |
| 9 | Add |
Nadat de configuratie-instellingen voor de transformatie zijn geverifieerd, kan deze worden opgeslagen in een claimbeleid door Toevoegen te selecteren. Selecteer Opslaan op de blade Claim beheren om de wijzigingen op te slaan. |
RegexReplace() transformatie is ook beschikbaar voor de transformaties van groepsclaims.
Transformatievalidaties
Een bericht bevat meer informatie wanneer de volgende voorwaarden optreden na het selecteren van de test Toevoegen of Uitvoeren:
- Invoerparameters met dubbele gebruikerskenmerken zijn gebruikt.
- Ongebruikte invoerparameters gevonden. Gedefinieerde invoerparameters moeten respectievelijk gebruik hebben in de tekst van het vervangende patroon.
- De opgegeven regex-invoer voor de test komt niet overeen met de opgegeven reguliere expressie.
- Er zijn geen bronnen voor de groepen in het vervangingspatroon gevonden.
Claims verzenden op basis van voorwaarden
U kunt de bron van een claim opgeven op basis van het gebruikerstype en de groep waarvan de gebruiker deel uitmaakt.
Het gebruikerstype kan zijn:
- Alle gebruikers hebben toegang tot de toepassing.
- Leden: systeemeigen lid van de tenant
- Alle gasten: gebruiker is verplaatst van een externe organisatie met of zonder Microsoft Entra-id.
- Microsoft Entra-gasten: Gastgebruiker behoort tot een andere organisatie met behulp van Microsoft Entra-id.
- Externe gasten: Gastgebruiker behoort tot een externe organisatie die geen Microsoft Entra-id heeft.
Een scenario waarin het gebruikerstype nuttig is, is wanneer de bron van een claim verschilt voor een gast en een werknemer die toegang heeft tot een toepassing. U kunt opgeven dat als de gebruiker een werknemer is, de NameID ophalen uit user.email. Als de gebruiker een gast is, is de NameID afkomstig van user.extensionattribute1.
Een claimvoorwaarde toevoegen:
- Vouw in Claim beheren de claimvoorwaarden uit.
- Selecteer het gebruikerstype.
- Selecteer de groep(en) waartoe de gebruiker behoort. U kunt maximaal 50 unieke groepen selecteren voor alle claims voor een bepaalde toepassing.
- Selecteer de bron waar de claim de waarde gaat ophalen. U kunt een gebruikerskenmerk selecteren in de vervolgkeuzelijst van het bronkenmerk of een transformatie toepassen op het gebruikerskenmerk voordat u het als claim verzendt.
De volgorde waarin u de voorwaarden toevoegt, zijn belangrijk. Microsoft Entra evalueert eerst alle voorwaarden met bron Attribute en evalueert vervolgens alle voorwaarden met de bron Transformation om te bepalen welke waarde in de claim moet worden verzonden. Microsoft Entra ID evalueert voorwaarden met dezelfde bron van boven naar beneden. De claim verzendt de laatste waarde die overeenkomt met de expressie in de claim. Transformaties zoals IsNotEmpty en Contains fungeren als beperkingen.
Bijvoorbeeld: Britta Simon is een gastgebruiker in de Contoso-tenant. Britta behoort tot een andere organisatie die ook gebruikmaakt van Microsoft Entra ID. Gezien de volgende configuratie voor de Fabrikam-toepassing, evalueert het Microsoft Identity Platform de voorwaarden wanneer Britta zich probeert aan te melden bij Fabrikam.
Eerst controleert het Microsoft Identity Platform of het gebruikerstype van Britta Alle gasten is. Omdat het type Alle gasten is, wijst het Microsoft Identity Platform de bron voor de claim toe aanuser.extensionattribute1. Ten tweede controleert het Microsoft Identity Platform of het gebruikerstype van Britta Microsoft Entra-gasten is. Omdat het type Alle gasten is, wijst het Microsoft Identity Platform de bron voor de claim toe aanuser.mail. Ten slotte wordt de claim verzonden met een waarde voor user.mail Britta.
Overweeg bijvoorbeeld wanneer Britta Simon zich probeert aan te melden met behulp van de volgende configuratie. Microsoft Entra evalueert eerst alle voorwaarden met bron Attribute. De bron voor de claim is user.mail wanneer het gebruikerstype van Britta Microsoft Entra-gasten is. Vervolgens evalueert Microsoft Entra ID de transformaties. Omdat Britta een gast is, user.extensionattribute1 is dit de nieuwe bron voor de claim. Omdat Britta zich in Microsoft Entra-gasten bevindt, user.othermail is dit de nieuwe bron voor deze claim. Ten slotte wordt de claim verzonden met een waarde voor user.othermail Britta.
Bekijk als laatste voorbeeld wat er gebeurt als Britta geen user.othermail configuratie heeft of leeg is. De claim valt terug op user.extensionattribute1 het negeren van de voorwaardevermelding in beide gevallen.
Beveiligingsoverwegingen
Toepassingen die tokens ontvangen, zijn afhankelijk van claimwaarden waarmee niet kan worden geknoeid. Wanneer u de inhoud van het token wijzigt via het aanpassen van claims, zijn deze veronderstellingen mogelijk niet meer juist. Toepassingen moeten expliciet bevestigen dat tokens zijn gewijzigd om zichzelf te beschermen tegen aanpassingen die zijn gemaakt door kwaadwillende actoren. Beveilig op een van de volgende manieren tegen ongepaste aanpassingen:
- Een aangepaste ondertekeningssleutel configureren
- werk het toepassingsmanifest bij om toegewezen claims te accepteren.
Zonder dit retourneert Microsoft Entra-id een AADSTS50146 foutcode.
Een aangepaste ondertekeningssleutel configureren
Voor apps met meerdere tenants moet een aangepaste ondertekeningssleutel worden gebruikt. Stel deze niet acceptMappedClaims in het app-manifest in. wanneer u een app instelt in Azure Portal, krijgt u een app-registratieobject en een service-principal in uw tenant. Deze app maakt gebruik van de globale aanmeldingssleutel van Azure, die niet kan worden gebruikt voor het aanpassen van claims in tokens. Om aangepaste claims in tokens op te halen, maakt u een aangepaste aanmeldingssleutel van een certificaat en voegt u deze toe aan een service-principal. Voor testdoeleinden kunt u een zelfondertekend certificaat maken. Nadat u de aangepaste ondertekeningssleutel hebt geconfigureerd, moet uw toepassingscode de tokenondertekeningssleutel valideren.
Voeg de volgende informatie toe aan de service-principal:
- Persoonlijke sleutel (als sleutelreferentie)
- Wachtwoord (als wachtwoordreferentie)
- Openbare sleutel (als sleutelreferentie)
Neem de met Base64 gecodeerde persoonlijke en openbare sleutel uit de PFX-bestandsexport van uw certificaat. Zorg dat de keyId voor de keyCredential die wordt gebruikt voor 'Sign' overeenkomt met de keyId van de passwordCredential. U kunt de customkeyIdentifier genereren door de hash van de vingerafdruk van het certificaat op te halen.
Aanvragen
Notitie
Schakel eerst een vergrendelingsconfiguratie van de service-principal uit op de blade app-registraties van het Microsoft Entra-beheercentrum voordat u een PATCH op de service-principal probeert uit te voeren, wat resulteert in een ongeldige aanvraag van 400.
In het volgende voorbeeld ziet u de indeling van de HTTP PATCH-aanvraag om een aangepaste ondertekeningssleutel toe te voegen aan een service-principal. De waarde 'key' in de eigenschap keyCredentials is ingekort voor leesbaarheid. De waarde is gecodeerd met Base64. Voor de persoonlijke sleutel is Signhet gebruik van de eigenschap . Voor de openbare sleutel is Verifyhet gebruik van de eigenschap .
PATCH https://graph.microsoft.com/v1.0/servicePrincipals/f47a6776-bca7-4f2e-bc6c-eec59d058e3e
Content-type: servicePrincipals/json
Authorization: Bearer {token}
{
"keyCredentials":[
{
"customKeyIdentifier": "lY85bR8r6yWTW6jnciNEONwlVhDyiQjdVLgPDnkI5mA=",
"endDateTime": "2021-04-22T22:10:13Z",
"keyId": "4c266507-3e74-4b91-aeba-18a25b450f6e",
"startDateTime": "2020-04-22T21:50:13Z",
"type": "X509CertAndPassword",
"usage": "Sign",
"key":"MIIKIAIBAz.....HBgUrDgMCERE20nuTptI9MEFCh2Ih2jaaLZBZGeZBRFVNXeZmAAgIH0A==",
"displayName": "CN=contoso"
},
{
"customKeyIdentifier": "lY85bR8r6yWTW6jnciNEONwlVhDyiQjdVLgPDnkI5mA=",
"endDateTime": "2021-04-22T22:10:13Z",
"keyId": "e35a7d11-fef0-49ad-9f3e-aacbe0a42c42",
"startDateTime": "2020-04-22T21:50:13Z",
"type": "AsymmetricX509Cert",
"usage": "Verify",
"key": "MIIDJzCCAg+gAw......CTxQvJ/zN3bafeesMSueR83hlCSyg==",
"displayName": "CN=contoso"
}
],
"passwordCredentials": [
{
"customKeyIdentifier": "lY85bR8r6yWTW6jnciNEONwlVhDyiQjdVLgPDnkI5mA=",
"keyId": "4c266507-3e74-4b91-aeba-18a25b450f6e",
"endDateTime": "2022-01-27T19:40:33Z",
"startDateTime": "2020-04-20T19:40:33Z",
"secretText": "mypassword"
}
]
}
Een aangepaste ondertekeningssleutel configureren met behulp van PowerShell
Gebruik PowerShell om een openbare MSAL-clienttoepassing te instantiëren en de stroom Autorisatiecode verlenen te gebruiken om een gedelegeerd machtigingstoegangstoken voor Microsoft Graph te verkrijgen. Gebruik het toegangstoken om Microsoft Graph aan te roepen en een aangepaste ondertekeningssleutel voor de service-principal te configureren. Nadat u de aangepaste ondertekeningssleutel hebt geconfigureerd, moet uw toepassingscode de tokenondertekeningssleutel valideren.
Als u dit script wilt uitvoeren, hebt u het volgende nodig:
- De object-id van de service-principal van uw toepassing, te vinden op de blade Overzicht van de vermelding van uw toepassing in Bedrijfstoepassingen in de Azure-portal.
- Een toepassingsregistratie om een gebruiker aan te melden en een toegangstoken op te halen om Microsoft Graph aan te roepen. Haal de toepassings-id (client) van deze app op de blade Overzicht van de vermelding van de toepassing in Toepassingsregistraties in de Azure-portal. De app-registratie moet de volgende configuratie hebben:
- Een omleidings-URI van "http://localhost" vermeld in de platformconfiguratie voor mobiele toepassingen en desktoptoepassingen .
- In API-machtigingen heeft Microsoft Graph gedelegeerde machtigingen Application.ReadWrite.All en User.Read (zorg ervoor dat u Beheer toestemming verleent voor deze machtigingen).
- Een gebruiker die zich aanmeldt om het Microsoft Graph-toegangstoken op te halen. De gebruiker moet een van de volgende Microsoft Entra-beheerdersrollen zijn (vereist om de service-principal bij te werken):
- Beheerder van de cloudtoepassing
- Toepassingsbeheerder
- Globale beheerder
- Een certificaat dat moet worden geconfigureerd als een aangepaste ondertekeningssleutel voor onze toepassing. U kunt een zelfondertekend certificaat maken of een certificaat verkrijgen bij uw vertrouwde certificeringsinstantie. De volgende certificaatonderdelen worden gebruikt in het script:
- openbare sleutel (meestal een .cer-bestand)
- persoonlijke sleutel in PKCS#12-indeling (in een .pfx-bestand)
- wachtwoord voor de persoonlijke sleutel (.pfx-bestand)
Belangrijk
De persoonlijke sleutel moet de PKCS#12-indeling hebben, omdat Microsoft Entra ID geen andere indelingstypen ondersteunt. Als u de verkeerde indeling gebruikt, kan dit resulteren in de fout 'Ongeldig certificaat: sleutelwaarde is ongeldig certificaat' wanneer u Microsoft Graph gebruikt om de service-principal te patchen met een keyCredentials certificaatgegevens.
$fqdn="fourthcoffeetest.onmicrosoft.com" # this is used for the 'issued to' and 'issued by' field of the certificate
$pwd="mypassword" # password for exporting the certificate private key
$location="C:\\temp" # path to folder where both the pfx and cer file will be written to
# 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
$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
$ClientID = "<app-id>"
$loginURL = "https://login.microsoftonline.com"
$tenantdomain = "fourthcoffeetest.onmicrosoft.com"
$redirectURL = "http://localhost" # this reply URL is needed for PowerShell Core
[string[]] $Scopes = "https://graph.microsoft.com/.default"
$pfxpath = $pfxFile # path to pfx file
$cerpath = $cerFile # path to cer file
$SPOID = "<service-principal-id>"
$graphuri = "https://graph.microsoft.com/v1.0/serviceprincipals/$SPOID"
$password = $pwd # password for the pfx file
# choose the correct folder name for MSAL based on PowerShell version 5.1 (.Net) or PowerShell Core (.Net Core)
if ($PSVersionTable.PSVersion.Major -gt 5)
{
$core = $true
$foldername = "netcoreapp2.1"
}
else
{
$core = $false
$foldername = "net45"
}
# Load the MSAL/microsoft.identity/client assembly -- needed once per PowerShell session
[System.Reflection.Assembly]::LoadFrom((Get-ChildItem C:/Users/<username>/.nuget/packages/microsoft.identity.client/4.32.1/lib/$foldername/Microsoft.Identity.Client.dll).fullname) | out-null
$global:app = $null
$ClientApplicationBuilder = [Microsoft.Identity.Client.PublicClientApplicationBuilder]::Create($ClientID)
[void]$ClientApplicationBuilder.WithAuthority($("$loginURL/$tenantdomain"))
[void]$ClientApplicationBuilder.WithRedirectUri($redirectURL)
$global:app = $ClientApplicationBuilder.Build()
Function Get-GraphAccessTokenFromMSAL {
[Microsoft.Identity.Client.AuthenticationResult] $authResult = $null
$AquireTokenParameters = $global:app.AcquireTokenInteractive($Scopes)
[IntPtr] $ParentWindow = [System.Diagnostics.Process]::GetCurrentProcess().MainWindowHandle
if ($ParentWindow)
{
[void]$AquireTokenParameters.WithParentActivityOrWindow($ParentWindow)
}
try {
$authResult = $AquireTokenParameters.ExecuteAsync().GetAwaiter().GetResult()
}
catch {
$ErrorMessage = $_.Exception.Message
Write-Host $ErrorMessage
}
return $authResult
}
$myvar = Get-GraphAccessTokenFromMSAL
if ($myvar)
{
$GraphAccessToken = $myvar.AccessToken
Write-Host "Access Token: " $myvar.AccessToken
#$GraphAccessToken = "eyJ0eXAiOiJKV1QiL ... iPxstltKQ"
# 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
# Write-Host "Enter password for the pfx file..."
# calling Get-PfxCertificate in PowerShell 5.1 prompts for password
# $cert = Get-PfxCertificate -FilePath $pfxpath
$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 = "X509CertAndPassword"
usage = "Sign"
key = $base64pfx
displayName = "CN=fourthcoffeetest"
},
[ordered]@{
customKeyIdentifier = $customKeyIdentifier
endDateTime = $endDateTime
keyId = $guid2
startDateTime = $startDateTime
type = "AsymmetricX509Cert"
usage = "Verify"
key = $base64cer
displayName = "CN=fourthcoffeetest"
}
)
passwordCredentials = @(
[ordered]@{
customKeyIdentifier = $customKeyIdentifier
keyId = $guid1
endDateTime = $endDateTime
startDateTime = $startDateTime
secretText = $password
}
)
}
$json = $object | ConvertTo-Json -Depth 99
Write-Host "JSON Payload:"
Write-Output $json
# Request Header
$Header = @{}
$Header.Add("Authorization","Bearer $($GraphAccessToken)")
$Header.Add("Content-Type","application/json")
try
{
Invoke-RestMethod -Uri $graphuri -Method "PATCH" -Headers $Header -Body $json
}
catch
{
# Dig into the exception to get the Response details.
# Note that value__ is not a typo.
Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__
Write-Host "StatusDescription:" $_.Exception.Response.StatusDescription
}
Write-Host "Complete Request"
}
else
{
Write-Host "Fail to get Access Token"
}
Tokenondertekeningssleutel valideren
Toepassingen waarvoor claimtoewijzing is ingeschakeld, moeten de ondertekeningssleutels van hun token valideren door appid={client_id} toe te voegen aan hun OpenID Connect-metagegevensaanvragen. In het volgende voorbeeld ziet u de indeling van het OpenID-Verbinding maken metagegevensdocument dat u moet gebruiken:
https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}
Het toepassingsmanifest bijwerken
Voor toepassingen met één tenant kunt u de eigenschap acceptMappedClaims instellen op true in het toepassingsmanifest. Zoals beschreven in het apiApplication resourcetype. Als u de eigenschap instelt, kan een toepassing claimtoewijzing gebruiken zonder een aangepaste ondertekeningssleutel op te geven.
Waarschuwing
Stel de eigenschap acceptMappedClaims niet in op true voor apps met meerdere tenants, waardoor kwaadwillende actoren claimstoewijzingsbeleid voor uw app kunnen maken.
De aangevraagde tokendoelgroep is vereist voor het gebruik van een geverifieerde domeinnaam van uw Microsoft Entra-tenant. Dit betekent dat u de Application ID URI (vertegenwoordigd door het manifest van de identifierUris toepassing) moet https://contoso.com/my-api instellen op of (eenvoudigweg met de standaardtenantnaam). https://contoso.onmicrosoft.com/my-api
Als u geen geverifieerd domein gebruikt, retourneert Microsoft Entra-id een AADSTS501461 foutcode met het bericht '_AcceptMappedClaims wordt alleen ondersteund voor een tokendoelgroep die overeenkomt met de toepassings-GUID of een doelgroep binnen de geverifieerde domeinen van de tenant. Wijzig de resource-id of gebruik een toepassingsspecifieke ondertekeningssleutel.
Geavanceerde opties voor claims
Configureer geavanceerde claimopties voor OIDC-toepassingen om dezelfde claim weer te geven als SAML-tokens. Ook voor toepassingen die dezelfde claim willen gebruiken voor zowel SAML2.0- als OIDC-antwoordtokens.
Configureer geavanceerde claimopties door het selectievakje onder Geavanceerde claimopties in te schakelen op de blade Claims beheren.
Volgende stappen
- Meer informatie over de claims en tokens die worden gebruikt in Microsoft Entra ID.