Konfigurera valfria anspråk

Artikel
06/14/2024

Token som Microsoft Entra returnerar hålls mindre för att säkerställa optimala prestanda för klienter som begär dem. Därför finns flera anspråk inte längre i token som standard och måste efterfrågas specifikt per program.

Du kan konfigurera valfria anspråk för ditt program via microsoft Entra-administrationscentrets programgränssnitt eller manifest.

Förutsättningar

Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
Slutförande av snabbstart: Registrera ett program

Konfigurera valfria anspråk i ditt program

Logga in på administrationscentret för Microsoft Entra som minst molnprogramadministratör.
Bläddra till Identitetsprogram>> Appregistreringar.
Välj det program som du vill konfigurera valfria anspråk för baserat på ditt scenario och önskat resultat.

Fortsätt med appens användargränssnitt
Fortsätt med manifestet

Under Hantera väljer du Tokenkonfiguration.
Välj Lägg till ytterligare anspråk.
Välj den tokentyp som du vill konfigurera, till exempel Åtkomst.
Välj de valfria anspråk som ska läggas till.
Markera Lägga till.

Under Hantera väljer du Manifest. En webbaserad manifestredigerare öppnas så att du kan redigera manifestet. Du kan också välja Ladda ned och redigera manifestet lokalt, och sedan använda Ladda upp för att tillämpa det på appen igen. Om filen inte innehåller optionalClaims egenskapen kan du lägga till den.

Följande programmanifestpost lägger till auth_time, ipaddroch upn valfria anspråk till ID, åtkomst och SAML-token.

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

När du är klar väljer du Spara. Nu inkluderas de angivna valfria anspråken i token för ditt program.

Objektet optionalClaims deklarerar de valfria anspråk som begärs av ett program. Ett program kan konfigurera valfria anspråk som returneras i ID-token, åtkomsttoken och SAML 2-token. Programmet kan konfigurera en annan uppsättning valfria anspråk som ska returneras i varje tokentyp.

Namn	Type	Beskrivning
`idToken`	Samling	De valfria anspråk som returneras i JWT ID-token.
`accessToken`	Samling	De valfria anspråk som returneras i JWT-åtkomsttoken.
`saml2Token`	Samling	De valfria anspråk som returneras i SAML-token.

Om det stöds av ett specifikt anspråk kan du också ändra beteendet för det valfria anspråket med hjälp av fältet additionalProperties .

Namn	Type	Beskrivning
`name`	Edm.String	Namnet på det valfria anspråket.
`source`	Edm.String	Anspråkets källa (katalogobjekt). Det finns fördefinierade anspråk och användardefinierade anspråk från tilläggsegenskaper. Om källvärdet är null är anspråket ett fördefinierat valfritt anspråk. Om källvärdet är användare är värdet i namnegenskapen tilläggsegenskapen från användarobjektet.
`essential`	Edm.Boolean	Om värdet är sant är det anspråk som anges av klienten nödvändigt för att säkerställa en smidig auktoriseringsupplevelse för den specifika uppgift som användaren begär. Standardvärdet är "false".
`additionalProperties`	Samling (Edm.String)	Andra egenskaper för anspråket. Om det finns en egenskap i den här samlingen ändras beteendet för det valfria anspråk som anges i namnegenskapen.

Konfigurera valfria anspråk för katalogtillägg

Förutom den valfria standardanspråkuppsättningen kan du även konfigurera token för att inkludera Microsoft Graph-tillägg. Mer information finns i Lägga till anpassade data till resurser med hjälp av tillägg.

Viktigt!

Åtkomsttoken genereras alltid med hjälp av resursens manifest, inte klienten. I begäran ...scope=https://graph.microsoft.com/user.read...är resursen Microsoft Graph API. Åtkomsttoken skapas med hjälp av Microsoft Graph API-manifestet, inte klientens manifest. Om du ändrar manifestet för ditt program får det aldrig token för Microsoft Graph-API:et att se annorlunda ut. För att verifiera att ändringarna accessToken gäller begär du en token för ditt program, inte en annan app.

Valfria anspråk stöder tilläggsattribut och katalogtillägg. Den här funktionen är användbar för att bifoga mer användarinformation som appen kan använda. Till exempel andra identifierare eller viktiga konfigurationsalternativ som användaren har angett. Om programmanifestet begär ett anpassat tillägg och en MSA-användare loggar in i din app returneras inte dessa tillägg.

Formatering av katalogtillägg

När du konfigurerar valfria anspråk för katalogtillägget med hjälp av programmanifestet använder du det fullständiga namnet på tillägget (i formatet: extension_<appid>_<attributename>). <appid> är den avskalade versionen av appId (eller klient-ID) för programmet som begär anspråket.

I JWT genereras dessa anspråk med följande namnformat: extn.<attributename>. I SAML-token genereras dessa anspråk med följande URI-format: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Konfigurera valfria gruppanspråk

Dricks

Stegen i den här artikeln kan variera något beroende på vilken portal du börjar från.

Det här avsnittet beskriver konfigurationsalternativen under valfria anspråk för att ändra gruppattributen som används i gruppanspråk från standardgruppen objectID till attribut som synkroniserats från lokala Windows Active Directory. Du kan konfigurera valfria gruppanspråk för ditt program via Azure Portal eller programmanifestet. Valfria gruppanspråk genereras endast i JWT för användarens huvudnamn. Tjänstens huvudnamn ingår inte i valfria gruppanspråk som genereras i JWT.

Viktigt!

Antalet grupper som genereras i en token är begränsat till 150 för SAML-försäkringar och 200 för JWT, inklusive kapslade grupper. Mer information om gruppgränser och viktiga varningar för gruppanspråk från lokala attribut finns i Konfigurera gruppanspråk för program.

Utför följande steg för att konfigurera valfria grupper med hjälp av Azure Portal:

Välj det program som du vill konfigurera valfria anspråk för.
Under Hantera väljer du Tokenkonfiguration.
Välj Lägg till gruppanspråk.
Välj de grupptyper som ska returneras (säkerhetsgrupper eller katalogroller, Alla grupper och/eller grupper som tilldelats till programmet):
- Alternativet Grupper som tilldelats programmet innehåller endast grupper som tilldelats programmet. Alternativet Grupper som tilldelats till programmet rekommenderas för stora organisationer på grund av gruppnummergränsen i token. Om du vill ändra de grupper som tilldelats programmet väljer du programmet i listan Företagsprogram . Välj Användare och grupper och sedan Lägg till användare/grupp. Välj de grupper som du vill lägga till i programmet från Användare och grupper.
- Alternativet Alla grupper innehåller SecurityGroup, DirectoryRole och DistributionList, men inte Grupper som tilldelats till programmet.
Valfritt: välj egenskaperna för den specifika tokentypen för att ändra anspråksvärdet för grupper så att det innehåller lokala gruppattribut eller för att ändra anspråkstypen till en roll.
Välj Spara.

Utför följande steg för att konfigurera grupper valfria anspråk via programmanifestet:

Välj det program som du vill konfigurera valfria anspråk för.
Under Hantera väljer du Manifest.
Lägg till följande post med hjälp av manifestredigeraren:

Giltiga värden är:
- "Alla" (det här alternativet inkluderar SecurityGroup, DirectoryRole och DistributionList)
- "SecurityGroup"
- "DirectoryRole"
- "ApplicationGroup" (det här alternativet innehåller endast grupper som har tilldelats till programmet)
Till exempel:
```
"groupMembershipClaims": "SecurityGroup"
```
Som standard genereras gruppobjekt-ID:n i gruppanspråksvärdet. Om du vill ändra anspråksvärdet så att det innehåller lokala gruppattribut eller ändra anspråkstypen till roll använder du konfigurationen optionalClaims enligt följande:

Ange valfria anspråk för gruppnamnskonfiguration.

Om du vill att grupper i token ska innehålla de lokala gruppattributen i det valfria anspråksavsnittet anger du vilken tokentyp som valfritt anspråk ska tillämpas på. Du kan också ange namnet på det valfria anspråk som begärs och andra egenskaper som du vill använda.

Flera tokentyper kan visas:

idToken för OIDC-ID-token
accessToken för OAuth-åtkomsttoken
Saml2Token för SAML-token.

Typen Saml2Token gäller för både SAML1.1- och SAML2.0-formattoken.

För varje relevant tokentyp ändrar du gruppanspråket så att avsnittet optionalClaims i manifestet används. Schemat optionalClaims är följande:

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

Valfritt anspråksschema	Värde
`name`	Måste vara `groups`
`source`	Inte använd. Utelämna eller ange null.
`essential`	Inte använd. Utelämna eller ange false.
`additionalProperties`	Lista över andra egenskaper. Giltiga alternativ är `sam_account_name`, `dns_domain_and_sam_account_name`, `netbios_domain_and_sam_account_name`och `emit_as_roles` `cloud_displayname`.

I additionalProperties endast en av sam_account_name, dns_domain_and_sam_account_namenetbios_domain_and_sam_account_name krävs . Om fler än en finns används den första och andra ignoreras. Du kan också lägga till cloud_displayname för att generera visningsnamnet för molngruppen. Det här alternativet fungerar bara när groupMembershipClaims är inställt på ApplicationGroup.

Vissa program kräver gruppinformation om användaren i rollanspråket. Om du vill ändra anspråkstypen från ett gruppanspråk till ett rollanspråk lägger du till emit_as_roles i additionalProperties. Gruppvärdena genereras i rollanspråket.

Om emit_as_roles används finns inga programroller som konfigurerats att användaren (eller ett resursprogram) har tilldelats i rollanspråket.

Följande exempel visar manifestkonfigurationen för gruppanspråk:

Generera grupper som gruppnamn i OAuth-åtkomsttoken i dnsDomainName\sAMAccountName format.

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

Generera gruppnamn som ska returneras i netbiosDomain\sAMAccountName format som rollanspråket i SAML- och OIDC-ID-token.

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

Generera gruppnamn i formatet sam_account_name för lokala synkroniserade grupper och cloud_display namn för molngrupper i SAML- och OIDC-ID-token för de grupper som tilldelats till programmet.

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

Exempel på valfria anspråk

Det finns flera tillgängliga alternativ för att uppdatera egenskaperna i ett programs identitetskonfiguration för att aktivera och konfigurera valfria anspråk:

Du kan använda Azure Portal
Du kan använda manifestet.
Det går också att skriva ett program som använder Microsoft Graph API för att uppdatera ditt program. Typen OptionalClaims i referensguiden för Microsoft Graph API kan hjälpa dig att konfigurera valfria anspråk.

I följande exempel används Azure Portal och manifest för att lägga till valfria anspråk till åtkomst-, ID- och SAML-token som är avsedda för ditt program. Olika valfria anspråk läggs till i varje typ av token som programmet kan ta emot:

ID-token innehåller UPN för federerade användare i fullständigt formulär (<upn>_<homedomain>#EXT#@<resourcedomain>).
De åtkomsttoken som andra klienter begär för det här programmet innehåller anspråket auth_time .
SAML-token innehåller skypeId katalogschematillägget (i det här exemplet är ab603c56068041afb2f6832e2a17e237app-ID:t för den här appen ). SAML-token exponerar Skype-ID:t som extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Konfigurera anspråk i Azure Portal:

Välj det program som du vill konfigurera valfria anspråk för.
Under Hantera väljer du Tokenkonfiguration.
Välj Lägg till valfritt anspråk, välj typ av ID-token , välj upn i listan med anspråk och välj sedan Lägg till.
Välj Lägg till valfritt anspråk, välj typ av åtkomsttoken , välj auth_time i listan med anspråk och välj sedan Lägg till.
På översiktsskärmen Tokenkonfiguration väljer du pennikonen bredvid upn, väljer växlingsknappen Externt autentiserad och väljer sedan Spara.
Välj Lägg till valfritt anspråk, välj TYPEN SAML-token , välj extn.skypeID i listan över anspråk (gäller endast om du har skapat ett Microsoft Entra-användarobjekt med namnet skypeID) och välj sedan Lägg till.

Konfigurera anspråk i manifestet:

Välj det program som du vill konfigurera valfria anspråk för.
Under Hantera väljer du Manifest för att öppna redigeraren för infogade manifest.

Du kan redigera manifestet direkt med den här redigeraren. Manifestet följer schemat för programentiteten och formaterar manifestet automatiskt när det har sparats. Nya element läggs till i egenskapen optionalClaims .

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

När du är klar med att uppdatera manifestet väljer du Spara för att spara manifestet.

Begränsning

Ett program kan utfärda ett maximalt antal 10 tilläggsattribut som valfria anspråk.

Dela via

Konfigurera valfria anspråk

Förutsättningar

Konfigurera valfria anspråk i ditt program

Konfigurera valfria anspråk för katalogtillägg

Formatering av katalogtillägg

Konfigurera valfria gruppanspråk

Exempel på valfria anspråk

Begränsning

Feedback

Ytterligare resurser

Dela via

Konfigurera valfria anspråk

Förutsättningar

Konfigurera valfria anspråk i ditt program

Konfigurera valfria anspråk för katalogtillägg

Formatering av katalogtillägg

Konfigurera valfria gruppanspråk

Exempel på valfria anspråk

Begränsning

Relaterat innehåll

Feedback

Ytterligare resurser