Förstå appmanifestet (Microsoft Graph-format)
Programmanifestet innehåller alla attribut och deras värden för en appregistrering i Microsofts identitetsplattform.
Ett Microsoft Graph-appmanifest är ett JSON-objekt som representerar en appregistrering. Den kallas även resurstypen Microsoft Graph-program eller Microsoft Graph-appobjektet (programobjekt). Den innehåller alla attribut och deras värden för en appregistrering.
Programobjektet som du får med hjälp av Microsoft Graph Get Application-metoden är samma JSON-objekt som visas på manifestsidan för appregistrering i administrationscentret för Microsoft Entra.
Kommentar
För appar som registrerats med ditt personliga Microsoft-konto (MSA-konto) fortsätter du att se appmanifest i Azure AD Graph-format i administrationscentret för Microsoft Entra tills vidare. Mer information finns i Microsoft Entra-appmanifest (Azure AD Graph-format).
Konfigurera Microsoft Graph-appmanifestet
Om du vill konfigurera Microsoft Graph App Manifest programmatiskt kan du antingen använda Microsoft Graph API eller Microsoft Graph PowerShell SDK.
Du kan också konfigurera appmanifestet via administrationscentret för Microsoft Entra. De flesta attribut kan konfigureras med hjälp av ett gränssnittselement i Appregistreringar. Vissa attribut måste dock konfigureras genom att redigera appmanifestet direkt på manifestsidan .
Konfigurera appmanifestet i administrationscentret för Microsoft Entra
Så här konfigurerar du Microsoft Graph-appmanifestet:
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 Microsoft Graph-appmanifestet.
id-attribut
Nyckel | Värdetyp |
---|---|
id | String |
Den här egenskapen kallas objekt-ID i administrationscentret för Microsoft Entra. Det är en unik identifierare för programobjektet i katalogen.
Det här ID:t är inte den identifierare som används för att identifiera appen i någon protokolltransaktion. Det används för att referera till objektet i katalogfrågor.
Det är ett inte null-attribut och skrivskyddat attribut.
Exempel:
"id": "f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd",
appId-attribut
Nyckel | Värdetyp |
---|---|
appId | String |
Den här egenskapen kallas program-ID (klient-ID) i administrationscentret för Microsoft Entra. Det är en unik identifierare för programobjektet i katalogen.
Det här ID:t är identifieraren som används för att identifiera appen i alla protokolltransaktioner.
Det är ett inte nullbart och skrivskyddat attribut.
Exempel:
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
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": "968A844F-7A47-430C-9163-07AE7C31D407",
"type":" FileHandler",
"properties": [
{
"key": "version",
"value": "2"
}
]
}
],
appRoles
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": "00001111-aaaa-2222-bbbb-3333cccc4444",
"isEnabled": true,
"value": "ReadOnly"
}
],
groupMembershipClaims
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":{
"idToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
"accessToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
"saml2Token": [{"@odata.type": "microsoft.graph.optionalClaim"}]
}
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ö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.
- < > , där - > ä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/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed",
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
}
],
displayName-attribut
Nyckel | Värdetyp |
---|---|
displayName | String |
Appens visningsnamn.
Exempel:
" displayName": "MyRegisteredApp",
oauth2RequiredPostResponse-attribut
Nyckel | Värdetyp |
---|---|
oauth2RequiredPostResponse | Booleskt |
Anger om Microsoft Entra-ID tillåter POST-begäranden i stället för GET-begäranden som en del av OAuth 2.0-tokenbegäranden. Standardvärdet är falskt, vilket anger att endast GET-begäranden tillåts.
Exempel:
"oauth2RequirePostResponse": false,
parentalControlSettings-attribut
Nyckel | Värdetyp |
---|---|
parentalControlSettings | 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"
}
],
publisherDomain-attribut
Nyckel | Värdetyp |
---|---|
publisherDomain | String |
Den verifierade utgivardomänen för programmet. Skrivskyddat. Om du vill redigera utgivardomänen för din appregistrering följer du stegen i Konfigurera en apps utgivardomän.
Exempel:
"publisherDomain": "{tenant}.onmicrosoft.com",
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",
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 multitenant) -
AzureADandPersonalMicrosoftAccount
– Användare med ett personligt Microsoft-konto eller ett arbets- eller skolkonto i någon organisations Microsoft Entra-klientorganisation -
PersonalMicrosoftAccount
– 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.
Enskilda taggar måste vara mellan 1 och 256 tecken (inklusive). Inga blanksteg eller duplicerade taggar tillåts. Det finns ingen specifik gräns för hur många taggar som kan läggas till, med förbehåll för allmänna manifeststorleksgränser.
Exempel:
"tags": [
"ProductionApp"
],
isFallbackPublicClient-attribut
Nyckel | Värdetyp |
---|---|
isFallbackPublicClient | Booleskt |
Anger programtypen för återställning som offentlig klient, till exempel ett installerat program som körs på en mobil enhet. Standardvärdet för det här attributet är falskt, vilket innebär att programtypen för återställning är konfidentiell klient, till exempel en webbapp. Det finns vissa scenarier där Microsoft Entra-ID inte kan fastställa klientprogramtypen. Till exempel ropc-flödet där det konfigureras utan att ange en omdirigerings-URI. I dessa fall tolkar Microsoft Entra-ID programtypen baserat på värdet för den här egenskapen.
Exempel:
"isFallbackPublicClient ": "false",
info-attribut
Nyckel | Värdetyp |
---|---|
information | informationalUrl |
Anger grundläggande profilinformation för programmet, inklusive appens marknadsföring, support, användarvillkor, sekretesspolicy och logotyp-URL:er.
Tänk på följande:
"logoUrl" är en skrivskyddad egenskap. Du kan inte redigera den i appmanifestet. Gå till sidan "varumärkesanpassning och egenskap" i din önskade appregistrering och använd "Ladda upp ny logotyp" för att ladda upp en ny logotyp.
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:
Info: {
"termsOfService": "https://MyRegisteredApp/termsofservice",
"support": "https://MyRegisteredApp/support",
"privacy": "https://MyRegisteredApp/privacystatement",
"marketing": "https://MyRegisteredApp/marketing"
"logoUrl": "https://MyRegisteredApp/logoUrl",
}
api-attribut
Nyckel | Värdetyp |
---|---|
api | apiApplication-resurstyp |
Anger inställningar för ett program som implementerar ett webb-API. Den innehåller fem egenskaper:
Property | Type | Beskrivning |
---|---|---|
acceptMappedClaims | Booleskt | När värdet är true 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 inte egenskapen acceptMappedClaims 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. |
knownClientApplications | samling | 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 till det här värdet godkänner användaren bara en gång till klientappen. Microsoft Entra-ID vet att medgivande till klienten innebär implicit medgivande till webb-API:et och etablerar automatiskt tjänstens huvudnamn för båda API:erna samtidigt. Både klienten och webb-API-appen måste vara registrerade i samma klientorganisation. |
oauth2PermissionScopes | permissionScope-samling | Definitionen av de delegerade behörigheter som exponeras av webb-API:et som representeras av den här programregistreringen. Dessa delegerade behörigheter kan begäras av ett klientprogram och kan beviljas av användare eller administratörer under medgivande. Delegerade behörigheter kallas ibland OAuth 2.0-omfång. |
preAuthorizedApplications | preAuthorizedApplication-samling | Visar en lista över klientprogram som är förauktoriserade med de angivna delegerade behörigheterna för att få åtkomst till programmets API:er. Användarna behöver inte godkänna något förauktoriserat program (för de angivna behörigheterna). Men alla andra behörigheter som inte anges i preAuthorizedApplications (begärs via inkrementellt medgivande till exempel) kräver användarmedgivande. |
requestedAccessTokenVersion | Int32 | Anger den åtkomsttokenversion som förväntas av den här resursen. Detta ä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 konfigurera requestedAccessTokenVersion för att ange formatet för åtkomsttoken som stöds. Möjliga värden för requestedAccessTokenVersion är 1, 2 eller null. Om värdet är null är standardvärdet 1, vilket motsvarar v1.0-slutpunkten. Om signInAudience i programmet har konfigurerats som AzureADandPersonalMicrosoftAccount eller PersonalMicrosoftAccount måste värdet för den här egenskapen vara 2. |
Exempel:
Api:{
"acceptMappedClaims": true,
"knownClientApplications": ["f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd"],
"oauth2PermissionScopes": [
{
"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"
}
],
"preAuthorizedApplications": [{
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"permissionIds": [
"8748f7db-21fe-4c83-8ab5-53033933c8f1"
]
}],
"requestedAccessTokenVersion": 2
}
webbattribut
Nyckel | Värdetyp |
---|---|
webb | webApplication-resurstyp |
Anger inställningar för ett webbprogram. Den innehåller fyra egenskaper.
Property | Type | Beskrivning |
---|---|---|
homePageUrl | String | Startsida eller landningssida för programmet. |
implicitGrantSettings | implicitGrantSettings | Anger om det här webbprogrammet kan begära token med hjälp av implicit OAuth 2.0-flöde. |
logoutUrl | String | Anger den URL som används av Microsofts auktoriseringstjänst för att logga ut en användare med hjälp av protokoll för front-channel, back-channel eller SAML-utloggning. |
redirectUris | Strängsamling | Anger url:er där användartoken skickas för inloggning eller omdirigerings-URI:er där OAuth 2.0-auktoriseringskoder och åtkomsttoken skickas på webbplattformen. |
Exempel:
web: {
"homePageUrl": "String",
"implicitGrantSettings": {
"enableIdTokenIssuance": "Boolean",
"enableAccessTokenIssuance": "Boolean"}
"logoutUrl": "String",
"redirectUris": ["String"]
}
spa-attribut
Nyckel | Värdetyp |
---|---|
brunn | spaApplication-resurstyp |
Anger inställningar för ett ensidesprogram, inklusive utloggnings-URL:er och omdirigerings-URL:er för auktoriseringskoder och åtkomsttoken.
Property | Type | Beskrivning |
---|---|---|
redirectUris | Strängsamling | Anger URL:er där användartoken skickas för inloggning eller omdirigerings-URI:er där OAuth 2.0-auktoriseringskoder och åtkomsttoken skickas. |
Exempel:
spa: {
"redirectUris": ["String"]
}
publicClient-attribut
Nyckel | Värdetyp |
---|---|
publicClient | publicClientApplication-resurstyp |
Anger inställningar för icke-webbapp eller icke-webb-API (till exempel iOS, Android, mobila eller andra offentliga klienter, till exempel ett installerat program som körs på en stationär enhet).
Property | Type | Beskrivning |
---|---|---|
redirectUris | Strängsamling | Anger URL:er där användartoken skickas för inloggning eller omdirigerings-URI:er där OAuth 2.0-auktoriseringskoder och åtkomsttoken skickas. |
Exempel:
publicClient: {
"redirectUris": ["String"]
}
Vanliga problem
Manifestgränser
Ett programmanifest har flera attribut som kallas samlingar. till exempel appRoles, keyCredentials, knownClientApplications, identifierUris, redirectUris, requiredResourceAccess och oauth2PermissionScopes. 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 appRoles i programmanifestet är du bara kvar med 1 100 återstående poster att använda i alla andra samlingar tillsammans 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."
Felsöka manifestmigrering från Azure AD Graph-format till Microsoft Graph-format
När du laddar upp ett tidigare nedladdat appmanifest i Azure AD Graph-format kan du få följande fel:
Det gick inte att uppdatera programmet {appnamn}. Felinformation: ogiltig egenskap {egenskapsnamn}.**
Detta kan bero på migreringen från Azure AD Graph till Microsoft Graph-appmanifestet. För det första bör du kontrollera om appmanifestet är i Azure AD Graph-format. Om så är fallet bör du konvertera appmanifestet till Microsoft Graph-format.
Jag hittar inte attributet trustedCertificateSubjects
attributet trustedCertificateSubjects är en intern Microsoft-egenskap. Administrationscentret för Microsoft Entra visar version 1.0 av Microsoft Graph-appmanifestet, attributet trustedCertificateSubjects finns bara i betaversionen av appmanifestet (Microsoft Graph-format). Fortsätt att redigera den här egenskapen med hjälp av appmanifestet (Azure AD Graph-format) i administrationscentret för Microsoft Entra.
FEL: Programmet hittades inte. Om programmet just har skapats väntar du några minuter och uppdaterar sidan.**
Om programmet inte bara har skapats kanske du får det här felet eftersom du har lagt till ett ogiltigt attribut i Microsoft Graph-appmanifestet. Granska attributskillnaderna mellan Azure AD Graph- och Microsoft Graph-format och se om du har lagt till ett attribut som inte stöds i Microsoft Graph-format v1.0 som visas i portalen.
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.