Dela via


Microsoft Entra-appmanifest (Azure AD Graph-format)

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 klienter 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:

  1. Logga in på administrationscentret för Microsoft Entra som minst programutvecklare.
  2. Bläddra till Identitetsprogram>> Appregistreringar.
  3. Välj den app som du vill konfigurera.
  4. I avsnittet Hantera i appen väljer du 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 AzureADandPersonalMicrosoftAccountmå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,

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 till Allow, RequireConsentForPrivacyServices, RequireConsentForMinors, RequireConsentForKidseller BlockMinors.

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åller id värdena och type 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 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.

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 ä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."

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å kan du hitta 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 av 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:

  1. 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.
  2. 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

Använd följande kommentarsavsnitt för att ge feedback som hjälper dig att förfina och forma vårt innehåll.