Microsoft Entra-appmanifest
Programmanifestet innehåller en definition av alla attribut för ett programobjekt i Microsofts identitetsplattform. Det fungerar också som en mekanism för att uppdatera programobjektet. Mer information om entiteten Program och dess schema finns i dokumentationen för Graph API Application-entitet.
Du kan konfigurera en apps attribut via administrationscentret för Microsoft Entra eller programmatiskt med hjälp av Microsoft Graph API eller Microsoft Graph PowerShell SDK. Det finns dock vissa scenarier där du behöver redigera appmanifestet för att konfigurera en apps attribut. Några vanliga scenarier:
- Om du har registrerat appen som Microsoft Entra-konton för flera innehavare och personliga Microsoft-konton kan du inte ändra de Microsoft-konton som stöds i användargränssnittet. I stället måste du använda programmanifestredigeraren för att ändra kontotypen som stöds.
- Om du vill definiera behörigheter och roller som din app stöder måste du ändra programmanifestet.
Konfigurera appmanifestet
Så här konfigurerar du programmanifestet:
- Logga in på administrationscentret för Microsoft Entra som minst programutvecklare.
- Bläddra till Identitetsprogram>> Appregistreringar.
- Välj den app som du vill konfigurera.
- På appens översiktssida väljer du avsnittet Manifest. En webbaserad manifestredigerare öppnas så att du kan redigera manifestet. Du kan också välja Ladda ned för att redigera manifestet lokalt och sedan använda Ladda upp för att tillämpa det på programmet igen.
Manifestreferens
I det här avsnittet beskrivs de attribut som finns i programmanifestet.
id-attribut
Nyckel | Värdetyp |
---|---|
id | String |
Den unika identifieraren för appen i katalogen. Det här ID:t är inte den identifierare som används för att identifiera appen i någon protokolltransaktion. Använd det för att referera till objektet i katalogfrågor.
Exempel:
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
acceptMappedClaims-attribut
Nyckel | Värdetyp |
---|---|
acceptMappedClaims | Booleskt värde med null |
Enligt beskrivningen i apiApplication
resurstypen kan ett program använda anspråksmappning utan att ange en anpassad signeringsnyckel. Program som tar emot token förlitar sig på att anspråksvärdena auktoritativt utfärdas av Microsoft Entra-ID och inte kan manipuleras. Men när du ändrar tokeninnehållet via principer för anspråksmappning kanske dessa antaganden inte längre är korrekta. Program måste uttryckligen bekräfta att token har ändrats av skaparen av principen för anspråksmappning för att skydda sig mot principer för anspråksmappning som skapats av skadliga aktörer.
Varning
Ange acceptMappedClaims
inte egenskapen till true
för appar med flera klientorganisationer, vilket kan göra det möjligt för skadliga aktörer att skapa principer för anspråksmappning för din app.
Exempel:
"acceptMappedClaims": true,
accessTokenAcceptedVersion-attribut
Nyckel | Värdetyp |
---|---|
accessTokenAcceptedVersion | Nullable Int32 |
Anger den åtkomsttokenversion som förväntas av resursen. Den här parametern ändrar version och format för JWT som skapats oberoende av slutpunkten eller klienten som används för att begära åtkomsttoken.
Slutpunkten som används, v1.0 eller v2.0, väljs av klienten och påverkar endast versionen av id_tokens. Resurser måste uttryckligen konfigureras accesstokenAcceptedVersion
för att ange det åtkomsttokenformat som stöds.
Möjliga värden för accesstokenAcceptedVersion
är 1, 2 eller null. Om värdet är null är den här parametern standardvärdet 1, vilket motsvarar v1.0-slutpunkten.
Om signInAudience
är AzureADandPersonalMicrosoftAccount
måste värdet vara 2
.
Exempel:
"accessTokenAcceptedVersion": 2,
addIns-attribut
Nyckel | Värdetyp |
---|---|
Addins | Samling |
Definierar anpassat beteende som en förbrukningstjänst kan använda för att anropa en app i specifika kontexter. Till exempel kan program som kan återge filströmmar ange addIns
egenskapen för dess "FileHandler"-funktioner. Med den här parametern kan tjänster som Microsoft 365 anropa programmet i kontexten för ett dokument som användaren arbetar med.
Exempel:
"addIns": [
{
"id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
"type":" FileHandler",
"properties": [
{
"key": "version",
"value": "2"
}
]
}
],
allowPublicClient-attribut
Nyckel | Värdetyp |
---|---|
allowPublicClient | Booleskt |
Anger programtypen för återställning. Microsoft Entra ID härleder programtypen från replyUrlsWithType som standard. Det finns vissa scenarier där Microsoft Entra-ID inte kan fastställa klientapptypen. Ett sådant scenario är till exempel ROPC-flödet där HTTP-begäran sker utan en URL-omdirigering). I dessa fall tolkar Microsoft Entra-ID programtypen baserat på värdet för den här egenskapen. Om det här värdet är inställt på true anges programtypen för återställning som offentlig klient, till exempel en installerad app som körs på en mobil enhet. Standardvärdet är falskt, vilket innebär att programtypen för återställning är konfidentiell klient, till exempel webbapp.
Exempel:
"allowPublicClient": false,
appId-attribut
Nyckel | Värdetyp |
---|---|
appId | String |
Anger den unika identifieraren för appen som har tilldelats till en app av Microsoft Entra-ID.
Exempel:
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
appRoles-attribut
Nyckel | Värdetyp |
---|---|
appRoles | Samling |
Anger den samling roller som en app kan deklarera. Dessa roller kan tilldelas till användare, grupper eller tjänstens huvudnamn. Fler exempel och information finns i Lägga till approller i ditt program och ta emot dem i token.
Exempel:
"appRoles": [
{
"allowedMemberTypes": [
"User"
],
"description": "Read-only access to device information",
"displayName": "Read Only",
"id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
"isEnabled": true,
"value": "ReadOnly"
}
],
errorUrl-attribut
Nyckel | Värdetyp |
---|---|
errorUrl | String |
Stöds inte.
groupMembershipClaims-attribut
Nyckel | Värdetyp |
---|---|
groupMembershipClaims | String |
Konfigurerar anspråket groups
som utfärdats i en användare eller OAuth 2.0-åtkomsttoken som appen förväntar sig. Om du vill ange det här attributet använder du något av följande giltiga strängvärden:
"None"
"SecurityGroup"
(för säkerhetsgrupper och Microsoft Entra-roller)"ApplicationGroup"
(det här alternativet innehåller endast grupper som har tilldelats till programmet)"DirectoryRole"
(hämtar Microsoft Entra-katalogrollerna som användaren är medlem i)"All"
(detta hämtar alla säkerhetsgrupper, distributionsgrupper och Microsoft Entra-katalogroller som den inloggade användaren är medlem i).
Exempel:
"groupMembershipClaims": "SecurityGroup",
optionalClaims-attribut
Nyckel | Värdetyp |
---|---|
optionalClaims | String |
De valfria anspråk som returneras i token av säkerhetstokentjänsten för den här specifika appen.
Appar som stöder både personliga konton och Microsoft Entra-ID kan inte använda valfria anspråk. Appar som är registrerade för bara Microsoft Entra-ID med v2.0-slutpunkten kan dock hämta de valfria anspråk som de begärde i manifestet. Mer information finns i Valfria anspråk.
Exempel:
"optionalClaims": null,
identifierUris-attribut
Nyckel | Värdetyp |
---|---|
identifierUris | Strängmatris |
Användardefinierade URI:er som unikt identifierar en webbapp i sin Microsoft Entra-klientorganisation eller verifierade kundägda domäner. När ett program används som en resursapp används identifierUri-värdet för att unikt identifiera och komma åt resursen. För ett offentligt klientprogram kan det inte ha värde för identifierUris.
Följande API- och HTTP-schemabaserade program-ID URI-format stöds. Ersätt platshållarvärdena enligt beskrivningen i listan som följer tabellen.
Program-ID som stöds URI-format |
Exempel på app-ID-URI:er |
---|---|
<api:// appId> | api://00001111-aaaa-2222-bbbb-3333cccc4444 |
<api:// tenantId>/<appId> | api://aaaabbbb-0000-cccc-1111-dddd2222eeee/00001111-aaaa-2222-bbbb-3333cccc4444 |
<api:// tenantId>/<string> | api://aaaabbbb-0000-cccc-1111-dddd2222eeee/api |
<api:// string>/<appId> | api://productapi/00001111-aaaa-2222-bbbb-3333cccc4444 |
<https:// tenantInitialDomain.onmicrosoft.com/>< string> | https://contoso.onmicrosoft.com/productsapi |
<https:// verifieradCustomDomain>/<sträng> | https://contoso.com/productsapi |
<https:// sträng.><verifiedCustomDomain> | https://product.contoso.com |
<https:// sträng.><verifiedCustomDomain>/<string> | https://product.contoso.com/productsapi |
- <appId> – programidentifieraregenskapen (appId) för programobjektet.
- <string> – strängvärdet för värden eller api-sökvägssegmentet.
- <tenantId> – ett GUID som genereras av Azure för att representera klientorganisationen i Azure.
- <tenantInitialDomain> - <tenantInitialDomain.onmicrosoft.com>, där< tenantInitialDomain> är det första domännamnet som klientskapare angav när klientorganisationen skapades.
- <verifiedCustomDomain> – en verifierad anpassad domän som konfigurerats för din Microsoft Entra-klientorganisation.
Kommentar
Om du använder api:// -schemat lägger du till ett strängvärde direkt efter "api://". Till exempel api://< sträng.> Strängvärdet kan vara ett GUID eller en godtycklig sträng. Om du lägger till ett GUID-värde måste det matcha antingen app-ID:t eller klientorganisations-ID:t. URI-värdet för program-ID måste vara unikt för din klientorganisation. Om du lägger till api://< tenantId> som program-ID-URI kan ingen annan använda den URI:n i någon annan app. Rekommendationen är att använda api://< appId> i stället eller HTTP-schemat.
Viktigt!
URI-värdet för program-ID får inte sluta med snedstrecket "/".
Exempel:
"identifierUris": "https://contoso.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444",
informationalUrls-attribut
Nyckel | Värdetyp |
---|---|
informationalUrls | String |
Anger länkarna till appens användarvillkor och sekretesspolicy. Användarvillkoren och sekretesspolicyn visas för användarna via användarmedgivandeupplevelsen. Mer information finns i How to: Add Terms of service and privacy statement for registered Microsoft Entra apps (Lägga till användarvillkor och sekretesspolicy för registrerade Microsoft Entra-appar).
Exempel:
"informationalUrls": {
"termsOfService": "https://MyRegisteredApp/termsofservice",
"support": "https://MyRegisteredApp/support",
"privacy": "https://MyRegisteredApp/privacystatement",
"marketing": "https://MyRegisteredApp/marketing"
},
keyCredentials-attribut
Nyckel | Värdetyp |
---|---|
keyCredentials | Samling |
Innehåller referenser till apptilldelade autentiseringsuppgifter, strängbaserade delade hemligheter och X.509-certifikat. Dessa autentiseringsuppgifter används när du begär åtkomsttoken (när appen fungerar som en klient i stället för som en resurs).
Exempel:
"keyCredentials": [
{
"customKeyIdentifier":null,
"endDateTime":"2018-09-13T00:00:00Z",
"keyId":"<guid>",
"startDateTime":"2017-09-12T00:00:00Z",
"type":"AsymmetricX509Cert",
"usage":"Verify",
"value":null
}
],
attributet knownClientApplications
Nyckel | Värdetyp |
---|---|
knownClientApplications | Strängmatris |
Används för att kombinera medgivande om du har en lösning som innehåller två delar: en klientapp och en anpassad webb-API-app. Om du anger appID för klientappen i det här värdet behöver användaren bara ge sitt medgivande en gång till klientappen. Microsoft Entra-ID vet att medgivande till klienten innebär implicit medgivande till webb-API:et. Tjänstens huvudnamn etableras automatiskt för både klienten och webb-API:et samtidigt. Både klienten och webb-API-appen måste vara registrerade i samma klientorganisation.
Exempel:
"knownClientApplications": ["00001111-aaaa-2222-bbbb-3333cccc4444"],
logoUrl-attribut
Nyckel | Värdetyp |
---|---|
logoUrl | String |
Skrivskyddat värde som pekar på CDN-URL:en till logotypen som laddades upp.
Exempel:
"logoUrl": "https://MyRegisteredAppLogo",
logoutUrl-attribut
Nyckel | Värdetyp |
---|---|
logoutUrl | String |
URL:en för att logga ut från appen.
Exempel:
"logoutUrl": "https://MyRegisteredAppLogout",
namnattribut
Nyckel | Värdetyp |
---|---|
name | String |
Appens visningsnamn.
Exempel:
"name": "MyRegisteredApp",
oauth2AllowImplicitFlow-attribut
Nyckel | Värdetyp |
---|---|
oauth2AllowImplicitFlow | Booleskt |
Anger om den här webbappen kan begära OAuth2.0 implicita flödesåtkomsttoken. Standardvärdet är falskt. Den här flaggan används för webbläsarbaserade appar, till exempel JavaScript-appar med en sida. Om du vill veta mer anger du OAuth 2.0 implicit grant flow
i innehållsförteckningen och läser avsnitten om implicit flöde. Vi avråder dock från att använda implicit beviljande även i SPA:er och rekommenderar att du använder auktoriseringskodflödet med PKCE.
Exempel:
"oauth2AllowImplicitFlow": false,
oauth2AllowIdTokenImplicitFlow-attribut
Nyckel | Värdetyp |
---|---|
oauth2AllowIdTokenImplicitFlow | Booleskt |
Anger om den här webbappen kan begära implicitAuth2.0-flödes-ID-token. Standardvärdet är falskt. Den här flaggan används för webbläsarbaserade appar, till exempel JavaScript-appar med en sida. Vi avråder dock från att använda implicit beviljande även i SPA:er och rekommenderar att du använder auktoriseringskodflödet med PKCE.
Exempel:
"oauth2AllowIdTokenImplicitFlow": false,
attributet oauth2Permissions
Nyckel | Värdetyp |
---|---|
oauth2Permissions | Samling |
Anger samlingen med OAuth 2.0-behörighetsomfång som webb-API:et (resursappen) exponerar för klientappar. Dessa behörighetsomfång kan beviljas klientappar under medgivandet.
Exempel:
"oauth2Permissions": [
{
"adminConsentDescription": "Allow the app to access resources on behalf of the signed-in user.",
"adminConsentDisplayName": "Access resource1",
"id": "<guid>",
"isEnabled": true,
"type": "User",
"userConsentDescription": "Allow the app to access resource1 on your behalf.",
"userConsentDisplayName": "Access resources",
"value": "user_impersonation"
}
],
oauth2RequiredPostResponse-attribut
Nyckel | Värdetyp |
---|---|
oauth2RequiredPostResponse | Booleskt |
Anger om Microsoft Entra-ID som en del av OAuth 2.0-tokenbegäranden tillåter POST-begäranden i stället för GET-begäranden. Standardvärdet är falskt, vilket anger att endast GET-begäranden tillåts.
Exempel:
"oauth2RequirePostResponse": false,
parentalControl Inställningar-attribut
Nyckel | Värdetyp |
---|---|
parentalControl Inställningar | String |
countriesBlockedForMinors
anger de länder/regioner där appen blockeras för minderåriga.legalAgeGroupRule
anger den regel för juridiska åldersgrupper som gäller för appens användare. Kan anges tillAllow
,RequireConsentForPrivacyServices
,RequireConsentForMinors
,RequireConsentForKids
ellerBlockMinors
.
Exempel:
"parentalControlSettings": {
"countriesBlockedForMinors": [],
"legalAgeGroupRule": "Allow"
},
passwordCredentials-attribut
Nyckel | Värdetyp |
---|---|
passwordCredentials | Samling |
Se beskrivningen för egenskapen keyCredentials
.
Exempel:
"passwordCredentials": [
{
"customKeyIdentifier": null,
"displayName": "Generated by App Service",
"endDateTime": "2022-10-19T17:59:59.6521653Z",
"hint": "Nsn",
"keyId": "<guid>",
"secretText": null,
"startDateTime":"2022-10-19T17:59:59.6521653Z"
}
],
preAuthorizedApplications-attribut
Nyckel | Värdetyp |
---|---|
preAuthorizedApplications | Samling |
Visar en lista över program och begärda behörigheter för implicit medgivande. Kräver att en administratör ger medgivande till programmet. preAuthorizedApplications kräver inte att användaren godkänner de begärda behörigheterna. Behörigheter som anges i preAuthorizedApplications kräver inte användarmedgivande. Ytterligare begärda behörigheter som inte anges i preAuthorizedApplications kräver dock användarmedgivande.
Exempel:
"preAuthorizedApplications": [
{
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"permissionIds": [
"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
]
}
],
publisherDomain-attribut
Nyckel | Värdetyp |
---|---|
publisherDomain | String |
Den verifierade utgivardomänen för programmet. Skrivskyddat.
Exempel:
"publisherDomain": "{tenant}.onmicrosoft.com",
attributet replyUrlsWithType
Nyckel | Värdetyp |
---|---|
replyUrlsWithType | Samling |
Den här egenskapen med flera värden innehåller listan över registrerade redirect_uri värden som Microsoft Entra-ID accepterar som mål när token returneras. Varje URI-värde ska innehålla ett associerat apptypsvärde. Typvärden som stöds är:
Web
InstalledClient
Spa
Mer information finns i begränsningar och begränsningar för replyUrl.
Exempel:
"replyUrlsWithType": [
{
"url": "https://localhost:4400/services/office365/redirectTarget.html",
"type": "InstalledClient"
}
],
requiredResourceAccess-attribut
Nyckel | Värdetyp |
---|---|
requiredResourceAccess | Samling |
Med dynamiskt medgivande requiredResourceAccess
styrs upplevelsen av administratörsmedgivande och användarmedgivande för användare som använder statiskt medgivande. Den här parametern styr dock inte användarmedgivandeupplevelsen för det allmänna fallet.
resourceAppId
är den unika identifieraren för den resurs som appen behöver åtkomst till. Det här värdet ska vara lika med det appId som deklareras i målresursappen.resourceAccess
är en matris som visar de OAuth2.0-behörighetsomfång och approller som appen kräver från den angivna resursen. Innehållerid
värdena ochtype
för de angivna resurserna.
Exempel:
"requiredResourceAccess": [
{
"resourceAppId": "00000002-0000-0000-c000-000000000000",
"resourceAccess": [
{
"id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
"type": "Scope"
}
]
}
],
samlMetadataUrl-attribut
Nyckel | Värdetyp |
---|---|
samlMetadataUrl | String |
URL:en till SAML-metadata för appen.
Exempel:
"samlMetadataUrl": "https://MyRegisteredAppSAMLMetadata",
signInUrl-attribut
Nyckel | Värdetyp |
---|---|
signInUrl | String |
Anger URL:en till appens startsida.
Exempel:
"signInUrl": "https://MyRegisteredApp",
signInAudience-attribut
Nyckel | Värdetyp |
---|---|
signInAudience | String |
Anger vilka Microsoft-konton som stöds för det aktuella programmet. Värden som stöds är:
AzureADMyOrg
– Användare med ett Microsoft-arbets- eller skolkonto i min organisations Microsoft Entra-klientorganisation (till exempel enskild klientorganisation)AzureADMultipleOrgs
– Användare med ett Microsoft-arbets- eller skolkonto i någon organisations Microsoft Entra-klientorganisation (till exempel flera klientorganisationer)AzureADandPersonalMicrosoftAccount
– Användare med ett personligt Microsoft-konto eller ett arbets- eller skolkonto i någon organisations Microsoft Entra-klientorganisationPersonalMicrosoftAccount
– Personliga konton som används för att logga in på tjänster som Xbox och Skype.
Exempel:
"signInAudience": "AzureADandPersonalMicrosoftAccount",
taggattribut
Nyckel | Värdetyp |
---|---|
taggar | Strängmatris |
Anpassade strängar som kan användas för att kategorisera och identifiera programmet.
Exempel:
"tags": [
"ProductionApp"
],
Vanliga problem
Manifestgränser
Ett programmanifest har flera attribut som kallas samlingar. till exempel appRoles, keyCredentials, knownClientApplications, identifierUris, redirectUris, requiredResourceAccess och oauth2Permissions. I det fullständiga programmanifestet för alla program har det totala antalet poster i alla kombinerade samlingar begränsats till 1200. Om du tidigare har angett 100 omdirigerings-URI:er i programmanifestet har du bara 1100 återstående poster att använda i alla andra samlingar som utgör manifestet.
Kommentar
Om du försöker lägga till fler än 1 200 poster i programmanifestet kan du se felet "Det gick inte att uppdatera programmet xxxxxx. Felinformation: Manifestets storlek har överskridit gränsen. Minska antalet värden och försök igen."
Attribut som inte stöds
Programmanifestet representerar schemat för den underliggande programmodellen i Microsoft Entra-ID. När det underliggande schemat utvecklas uppdateras manifestredigeraren så att det återspeglar det nya schemat då och då. Därför kan du märka att nya attribut visas i programmanifestet. I sällsynta fall kan du märka en syntaktisk eller semantisk ändring i de befintliga attributen eller så kanske du hittar ett attribut som fanns tidigare stöds inte längre. Du ser till exempel nya attribut i Appregistreringar, som är kända med ett annat namn i Appregistreringar (äldre) upplevelse.
Appregistreringar (äldre) | Appregistreringar |
---|---|
availableToOtherTenants |
signInAudience |
displayName |
name |
errorUrl |
- |
homepage |
signInUrl |
objectId |
Id |
publicClient |
allowPublicClient |
replyUrls |
replyUrlsWithType |
Beskrivningar för dessa attribut finns i avsnittet manifestreferens .
När du försöker ladda upp ett tidigare nedladdat manifest kan något av följande fel visas. Det här felet beror troligen på att manifestredigeraren nu stöder en nyare version av schemat, som inte matchar den som du försöker ladda upp.
- "Det gick inte att uppdatera xxxxxx-programmet. Felinformation: Ogiltig objektidentifierare "odefinierad". []."
- "Det gick inte att uppdatera xxxxxx-programmet. Felinformation: Ett eller flera angivna egenskapsvärden är ogiltiga. []."
- "Det gick inte att uppdatera xxxxxx-programmet. Felinformation: Tillåts inte att ange tillgängligaToOtherTenants i den här API-versionen för uppdatering. []."
- "Det gick inte att uppdatera xxxxxx-programmet. Felinformation: Uppdateringar till egenskapen "replyUrls" tillåts inte för det här programmet. Använd egenskapen "replyUrlsWithType" i stället. []."
- "Det gick inte att uppdatera xxxxxx-programmet. Felinformation: Ett värde utan ett typnamn hittades och ingen förväntad typ är tillgänglig. När modellen har angetts måste varje värde i nyttolasten ha en typ som antingen kan anges i nyttolasten, uttryckligen av anroparen eller implicit härledas från det överordnade värdet. []"
När du ser något av dessa fel rekommenderar vi följande åtgärder:
- Redigera attributen individuellt i manifestredigeraren i stället för att ladda upp ett tidigare nedladdat manifest. Använd manifestreferenstabellen för att förstå syntaxen och semantiken för gamla och nya attribut så att du kan redigera de attribut som du är intresserad av.
- Om arbetsflödet kräver att du sparar manifesten i källlagringsplatsen för användning senare föreslår vi att du gör om de sparade manifesten på lagringsplatsen med det du ser i Appregistreringar upplevelse.
Nästa steg
- Mer information om relationen mellan en apps program- och tjänstobjekt finns i Objekt för program och tjänstens huvudnamn i Microsoft Entra-ID.
- Se Microsofts identitetsplattform utvecklarordlista för definitioner av några grundläggande Microsofts identitetsplattform utvecklarkoncept.
Använd följande kommentarsavsnitt för att ge feedback som hjälper dig att förfina och forma vårt innehåll.