Konfigurera en anpassad anspråksprovider för en tokenutfärdingshändelse

Den här artikeln beskriver hur du konfigurerar en anpassad anspråksprovider för en starthändelse för tokenutfärdning. Med hjälp av ett befintligt REST-API för Azure Functions registrerar du ett anpassat autentiseringstillägg och lägger till attribut som du förväntar dig att det ska parsa från rest-API:et. Om du vill testa tillägget för anpassad autentisering registrerar du ett OpenID-exempelprogram Anslut för att hämta en token och visa anspråken.

Förutsättningar

• En Azure-prenumeration med möjlighet att skapa Azure Functions. Om du inte har ett befintligt Azure-konto registrerar du dig för en kostnadsfri utvärderingsversion eller använder dina Visual Studio-prenumerationsförmåner när du skapar ett konto.
• En HTTP-utlösarfunktion som konfigurerats för en tokenutfärdingshändelse som distribuerats till Azure Functions. Om du inte har något följer du stegen i skapa ett REST API för en tokenutfärdarstarthändelse i Azure Functions.
• En grundläggande förståelse av de begrepp som beskrivs i översikten över anpassade autentiseringstillägg.
• En Microsoft Entra-ID-klientorganisation. Du kan använda antingen en kund- eller personalklientorganisation för den här instruktionsguiden.
  • För externa klienter använder du ett användarflöde för registrering och inloggning.

Steg 1: Registrera ett anpassat autentiseringstillägg

Nu ska du konfigurera ett anpassat autentiseringstillägg som ska användas av Microsoft Entra-ID för att anropa din Azure-funktion. Det anpassade autentiseringstillägget innehåller information om rest-API-slutpunkten, de anspråk som det parsar från rest-API:et och hur du autentiserar till rest-API:et. Följ de här stegen för att registrera ett anpassat autentiseringstillägg till azure-funktionsappen.

Kommentar

Du kan ha högst 100 anpassade tilläggsprinciper.

Azure-portalen

Registrera ett anpassat autentiseringstillägg

1. Logga in på Azure-portalen som minst programadministratöroch autentiseringsadministratör.
2. Sök efter och välj Microsoft Entra-ID och välj Företagsprogram.
3. Välj Anpassade autentiseringstillägg och välj sedan Skapa ett anpassat tillägg.
4. I Grundläggande väljer du händelsetypen TokenIssuanceStart och väljer Nästa.
5. Fyll i följande egenskaper i Slutpunktskonfiguration:
   • Namn – Ett namn på ditt anpassade autentiseringstillägg. Till exempel tokenutfärdingshändelse.
   • Mål-URL – Url:en för {Function_Url} din Azure-funktion. Gå till sidan Översikt för azure-funktionsappen och välj sedan den funktion som du skapade. På funktionsöversiktssidan väljer du Hämta funktions-URL och använder kopieringsikonen för att kopiera url:en för customauthenticationextension_extension (systemnyckel).
   • Beskrivning – En beskrivning av dina anpassade autentiseringstillägg.
6. Välj Nästa.
7. I API-autentisering väljer du alternativet Skapa ny appregistrering för att skapa en appregistrering som representerar din funktionsapp.
8. Ge appen ett namn, till exempel API för Azure Functions-autentiseringshändelser.
9. Välj Nästa.
10. I Anspråk anger du de attribut som du förväntar dig att ditt anpassade autentiseringstillägg ska parsa från rest-API:et och sammanfogas till token. Lägg till följande anspråk:
    • dateOfBirth
    • customRoles
    • apiVersion
    • correlationId
11. Välj Nästa och sedan Skapa, som registrerar det anpassade autentiseringstillägget och den associerade programregistreringen.
12. Observera app-ID :t under API-autentisering, som behövs för att konfigurera autentisering för din Azure-funktion i azure-funktionsappen.

Microsoft Graph

Registrera en app

1. Logga in på Graph Explorer med ett konto vars hemklient är den klientorganisation där du vill hantera ditt anpassade autentiseringstillägg. Det här kontot måste ha behörighet att skapa och hantera en programregistrering i klientorganisationen.

2. Kör följande begäran.

   POST https://graph.microsoft.com/v1.0/applications
   Content-type: application/json
   
   {
       "displayName": "authenticationeventsAPI"
   }
   

3. Från svaret registrerar du värdet för ID och appId för den nyligen skapade appregistreringen. Dessa värden refereras i den här artikeln som {authenticationeventsAPI_ObjectId} respektive {authenticationeventsAPI_AppId} .

Skapa ett huvudnamn för tjänsten i klientorganisationen för appregistreringen authenticationeventsAPI.

Kör följande begäran i Graph Explorer. Ersätt {authenticationeventsAPI_AppId} med värdet för appId som du registrerade från föregående steg.

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json
    
{
    "appId": "{authenticationeventsAPI_AppId}"
}

Ange app-ID-URI, åtkomsttokenversion och nödvändig resursåtkomst

Uppdatera det nyligen skapade programmet för att ange URI-värdet för program-ID, åtkomsttokenversionen och nödvändig resursåtkomst.

Kör följande begäran i Graph Explorer.

• Ange URI-värdet för program-ID i egenskapen identifierUris . Ersätt {Function_Url_Hostname} med värdnamnet för du {Function_Url} registrerade tidigare.
• Ange värdet {authenticationeventsAPI_AppId} med det appId som du registrerade tidigare.
• Ett exempelvärde är api://authenticationeventsAPI.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444. Anteckna det här värdet när du använder det senare i den här artikeln i stället för {functionApp_IdentifierUri}.

POST https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}
Content-type: application/json

{
"identifierUris": [
    "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"
],    
"api": {
    "requestedAccessTokenVersion": 2,
    "acceptMappedClaims": null,
    "knownClientApplications": [],
    "oauth2PermissionScopes": [],
    "preAuthorizedApplications": []
},
"requiredResourceAccess": [
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                "type": "Role"
            }
        ]
    }
]
}

Registrera ett anpassat autentiseringstillägg

Om du vill registrera det anpassade autentiseringstillägget associerar du det med appregistreringen för Azure-funktionen och azure-funktionsslutpunkten {Function_Url}.

1. Kör följande begäran i Graph Explorer. Ersätt {Function_Url} med värdnamnet för din Azure-funktionsapp. Ersätt {functionApp_IdentifierUri} med identifierarenUri som användes i föregående steg.

   • Du behöver behörigheten CustomAuthenticationExtension.ReadWrite.All delegated.

   POST https://graph.microsoft.com/beta/identity/customAuthenticationExtensions
   Content-type: application/json
   
   {
       "@odata.type": "#microsoft.graph.onTokenIssuanceStartCustomExtension",
       "displayName": "onTokenIssuanceStartCustomExtension",
       "description": "Fetch additional claims from custom user store",
       "endpointConfiguration": {
           "@odata.type": "#microsoft.graph.httpRequestEndpoint",
           "targetUrl": "{Function_Url}"
       },
       "authenticationConfiguration": {
           "@odata.type": "#microsoft.graph.azureAdTokenAuthentication",
           "resourceId": "{functionApp_IdentifierUri}"
       },
       "claimsForTokenConfiguration": [
           {
               "claimIdInApiResponse": "DateOfBirth"
           },
           {
               "claimIdInApiResponse": "CustomRoles"
           }
       ]
   }
   

2. Registrera värdet för id det skapade objektet för anpassade anspråksprovider. Du använder värdet senare i den här självstudien i stället för {customExtensionObjectId}.

1.2 Bevilja administratörsmedgivande

När det anpassade autentiseringstillägget har skapats måste du bevilja behörigheter till API:et. Det anpassade autentiseringstillägget använder client_credentials för att autentisera till Azure-funktionsappen med hjälp av behörigheten Receive custom authentication extension HTTP requests .

1. Öppna sidan Översikt för ditt nya anpassade autentiseringstillägg. Anteckna app-ID:t under API-autentisering, eftersom det behövs när du lägger till en identitetsprovider.

2. Under API-autentisering väljer du Bevilja behörighet.

3. Ett nytt fönster öppnas och när det har loggat in begär det behörigheter för att ta emot HTTP-begäranden för anpassat autentiseringstillägg. Detta gör att det anpassade autentiseringstillägget kan autentisera till ditt API. Välj Acceptera.

   

Steg 2: Konfigurera en OpenID Anslut-app för att ta emot berikade token

Om du vill hämta en token och testa tillägget för anpassad autentisering kan du använda https://jwt.ms appen. Det är ett Microsoft-ägt webbprogram som visar det avkodade innehållet i en token (innehållet i token lämnar aldrig webbläsaren).

2.1 Registrera ett testwebbprogram

Följ dessa steg för att registrera jwt.ms webbappen:

1. På sidan Start i Azure-portalen väljer du Microsoft Entra-ID.

2. Välj Appregistreringar> Ny registrering.

3. Ange ett namn för programmet. Till exempel Mitt testprogram.

4. Under Kontotyper som stöds väljer du Endast Konton i den här organisationskatalogen.

5. I listrutan Välj en plattform i Omdirigerings-URI väljer du Webb och anger https://jwt.ms sedan i textrutan URL.

6. Välj Registrera för att slutföra appregistreringen.

   

7. På sidan Översikt för din appregistrering kopierar du program-ID:t (klient). App-ID:t kallas {App_to_enrich_ID} i senare steg. I Microsoft Graph refereras den av egenskapen appId .

   

2.2 Aktivera implicit flöde

Det jwt.ms testprogrammet använder det implicita flödet. Aktivera implicit flöde i registreringen av mitt testprogram :

1. Under Hantera väljer du Autentisering.
2. Under Implicit beviljande och hybridflöden markerar du kryssrutan ID-token (används för implicita flöden och hybridflöden).
3. Välj Spara.

2.3 Aktivera din app för en princip för anspråksmappning

En princip för anspråksmappning används för att välja vilka attribut som returneras från det anpassade autentiseringstillägget som mappas till token. Om du vill tillåta att token utökas måste du uttryckligen aktivera programregistreringen för att acceptera mappade anspråk:

1. I registreringen av mitt testprogram går du till Hantera och väljer Manifest.
2. Leta upp attributet i acceptMappedClaims manifestet och ange värdet till true.
3. Ange accessTokenAcceptedVersion till 2.
4. Välj Spara för att spara ändringarna.

Följande JSON-kodfragment visar hur du konfigurerar dessa egenskaper.

{
	"id": "22222222-0000-0000-0000-000000000000",
	"acceptMappedClaims": true,
	"accessTokenAcceptedVersion": 2,  
    ...
}

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. Konfigurera i stället en anpassad signeringsnyckel.

Personalklientorganisation

Fortsätt till nästa steg: Tilldela en anpassad anspråksprovider till din app.

Extern klientorganisation

3.4 Associera din app med ett användarflöde

För externa klienter måste du associera din app med ett användarflöde. Ett användarflöde definierar de autentiseringsmetoder som en kund kan använda för att logga in på ditt program och den information de behöver ange under registreringen. Se till att du slutför stegen i Lägg till ett program i ett användarflöde innan du fortsätter att lägga till Mitt testprogram i användarflödet.

Steg 3: Tilldela en anpassad anspråksprovider till din app

För att token ska utfärdas med anspråk som inkommande från det anpassade autentiseringstillägget måste du tilldela en anpassad anspråksprovider till ditt program. Detta baseras på token-målgruppen, så providern måste tilldelas till klientprogrammet för att ta emot anspråk i en ID-token och till resursprogrammet för att ta emot anspråk i en åtkomsttoken. Providern för anpassade anspråk förlitar sig på det anpassade autentiseringstillägget som konfigurerats med tokenutfärdarens starthändelselyssnare . Du kan välja om alla, eller en delmängd av anspråk, från den anpassade anspråksprovidern ska mappas till token.

Kommentar

Du kan bara skapa 250 unika tilldelningar mellan program och anpassade tillägg. Om du vill använda samma anpassade tilläggsanrop för flera appar rekommenderar vi att du använder authenticationEventListeners Microsoft Graph API för att skapa lyssnare för flera program. Detta stöds inte i Azure-portalen.

Följ de här stegen för att ansluta programmet Mitt test med ditt anpassade autentiseringstillägg:

Azure-portalen

Tilldela det anpassade autentiseringstillägget som en källa för en anpassad anspråksprovider.

1. På sidan Start i Azure-portalen väljer du Microsoft Entra-ID.

2. VäljFöretagsprogram och välj sedan Alla program under Hantera. Leta upp och välj Mitt testprogram i listan.

3. Gå till Hantera på översiktssidan i mitt testprogram och välj Enkel inloggning.

4. Under Attribut och anspråk väljer du Redigera.

   

5. Expandera menyn Avancerade inställningar.

6. Bredvid Anpassad anspråksprovider väljer du Konfigurera.

7. Expandera listrutan Anpassad anspråksprovider och välj händelsen Tokenutfärdande som du skapade tidigare.

8. Välj Spara.

Tilldela sedan attributen från den anpassade anspråksprovidern, som ska utfärdas till token som anspråk:

1. Välj Lägg till nytt anspråk för att lägga till ett nytt anspråk. Ange ett namn på det anspråk som du vill utfärda, till exempel dateOfBirth.

2. Under Källa väljer du Attribut och väljer customClaimsProvider.dateOfBirth i listrutan Källattribut .

   

3. Välj Spara.

4. Upprepa den här processen för att lägga till attributen customClaimsProvider.customRoles, customClaimsProvider.apiVersion och customClaimsProvider.correlationId och motsvarande namn. Det är en bra idé att matcha namnet på anspråket med namnet på attributet.

Microsoft Graph

Skapa först en händelselyssnare för att utlösa ett anpassat autentiseringstillägg för programmet Mitt test med hjälp av starthändelsen för tokenutfärdning.

1. Logga in på Graph Explorer med ett konto vars hemklientorganisation är den klientorganisation som du vill hantera ditt anpassade autentiseringstillägg i.

2. Kör följande begäran. Ersätt {App_to_enrich_ID} med app-ID :t för mitt testprogram som registrerats tidigare. Ersätt {customExtensionObjectId} med det anpassade autentiseringstilläggs-ID som registrerats tidigare.

   • Du behöver behörigheten EventListener.ReadWrite.All delegated.

   POST https://graph.microsoft.com/beta/identity/authenticationEventListeners
   Content-type: application/json
   
   {
       "@odata.type": "#microsoft.graph.onTokenIssuanceStartListener",
       "conditions": {
           "applications": {
               "includeAllApplications": false,
               "includeApplications": [
                   {
                       "appId": "{App_to_enrich_ID}"
                   }
               ]
           }
       },
       "priority": 500,
       "handler": {
           "@odata.type": "#microsoft.graph.onTokenIssuanceStartCustomExtensionHandler",
           "customExtension": {
               "id": "{customExtensionObjectId}"
           }
       }
   }
   

Skapa sedan principen för anspråksmappning, som beskriver vilka anspråk som kan utfärdas till ett program från en anpassad anspråksprovider.

1. Kör följande begäran i Graph Explorer. Du behöver behörigheten Policy.ReadWrite.ApplicationConfiguration delegerad.

   POST https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies
   Content-type: application/json
   
   {
       "definition": [
           "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"CustomClaimsProvider\",\"ID\":\"DateOfBirth\",\"JwtClaimType\":\"dob\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CustomRoles\",\"JwtClaimType\":\"my_roles\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CorrelationId\",\"JwtClaimType\":\"correlationId\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"ApiVersion\",\"JwtClaimType\":\"apiVersion \"},{\"Value\":\"tokenaug_V2\",\"JwtClaimType\":\"policy_version\"}]}}"
       ],
       "displayName": "MyClaimsMappingPolicy",
       "isOrganizationDefault": false
   }
   

2. Registrera den ID genererade i svaret, senare kallas {claims_mapping_policy_ID}det .

Hämta objekt-ID:t för tjänstens huvudnamn:

1. Kör följande begäran i Graph Explorer. Ersätt {App_to_enrich_ID} med appIdför mitt testprogram.

   GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='{App_to_enrich_ID}')
   

Registrera värdet för ID.

Tilldela principen för anspråksmappning till tjänstens huvudnamn för Mitt testprogram.

1. Kör följande begäran i Graph Explorer. Du behöver behörigheten Policy.ReadWrite.ApplicationConfiguration och Application.ReadWrite.All delegated.

   POST https://graph.microsoft.com/v1.0/servicePrincipals/{test_App_Service_Principal_ObjectId}/claimsMappingPolicies/$ref
   Content-type: application/json
   
   {
       "@odata.id": "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/{claims_mapping_policy_ID}"
   }
   

Steg 4: Skydda din Azure-funktion

Microsoft Entra-tillägget för anpassad autentisering använder server-till-server-flöde för att hämta en åtkomsttoken som skickas i HTTP-huvudet till din Azure-funktion Authorization . När du publicerar din funktion till Azure, särskilt i en produktionsmiljö, måste du verifiera token som skickas i auktoriseringshuvudet.

Om du vill skydda din Azure-funktion följer du de här stegen för att integrera Microsoft Entra-autentisering för att verifiera inkommande token med din Api-programregistrering för Azure Functions-autentiseringshändelser. Välj någon av följande flikar baserat på din klienttyp.

Kommentar

Om Azure-funktionsappen finns i en annan Azure-klientorganisation än den klient där ditt anpassade autentiseringstillägg är registrerat väljer du fliken Öppna ID Anslut.

4.1 Använda Microsoft Entra-identitetsprovider

Använd följande steg för att lägga till Microsoft Entra som identitetsprovider i azure-funktionsappen.

Personalklientorganisation

1. I Azure-portalen letar du upp och väljer den funktionsapp som du tidigare publicerade.

2. Under Inställningar väljer du Autentisering.

3. Välj Lägg till identitetsprovider.

4. Välj Microsoft som identitetsprovider.

5. Välj Personal som klientorganisationstyp.

6. Under Appregistrering väljer du Välj en befintlig appregistrering i den här katalogen för appregistreringstypen och välj api-appregistreringenför Azure Functions-autentiseringshändelser som du skapade tidigare när du registrerade den anpassade anspråksprovidern.

7. Ange följande utfärdar-URL, , https://login.microsoftonline.com/{tenantId}/v2.0där {tenantId} är klientorganisations-ID:t för din arbetsstyrkas klientorganisation.

8. Under Oautentiserade begäranden väljer du HTTP 401 Obehörig som identitetsprovider.

9. Avmarkera alternativet Tokenlagring .

10. Välj Lägg till för att lägga till autentisering i din Azure-funktion.

    

Extern klientorganisation

1. I Azure-portalen letar du upp och väljer den funktionsapp som du tidigare publicerade.

2. Under Inställningar väljer du Autentisering.

3. Välj Lägg till identitetsprovider.

4. Välj Microsoft som identitetsprovider.

5. Välj Kund som klienttyp.

6. Under Appregistrering anger du client_id den api-appregistrering för Azure Functions-autentiseringshändelser som du skapade tidigare när du registrerade den anpassade anspråksprovidern.

7. För utfärdarens URL anger du följande URL https://{domainName}.ciamlogin.com/{tenant_id}/v2.0, där

   • {domainName} är domännamnet för den externa klientorganisationen i formuläret {domainName}.contoso.com.
   • {tenantId} är klientorganisations-ID för din externa klientorganisation.

8. Under Oautentiserade begäranden väljer du HTTP 401 Obehörig som identitetsprovider.

9. Avmarkera alternativet Tokenlagring .

10. Välj Lägg till för att lägga till autentisering i din Azure-funktion.

    

4.2 Använda OpenID Anslut identitetsprovider

Om du har konfigurerat Microsofts identitetsprovider hoppar du över det här steget. Om Azure-funktionen annars finns i en annan klientorganisation än klientorganisationen där ditt anpassade autentiseringstillägg är registrerat följer du dessa steg för att skydda din funktion:

Skapa en klienthemlighet

1. På startsidan i Azure-portalen väljer du Microsoft Entra-ID> Appregistreringar.
2. Välj api-appregistreringen för Azure Functions-autentiseringshändelser som du skapade tidigare.
3. Välj Certifikat och hemligheter>Klienthemligheter>Ny klienthemlighet.
4. Välj en förfallotid för hemligheten eller ange en anpassad livslängd, lägg till en beskrivning och välj Lägg till.
5. Registrera hemlighetens värde för användning i klientprogramkoden. Hemlighetens värde visas aldrig igen när du har lämnat den här sidan.

Lägg till OpenID-Anslut identitetsprovider i azure-funktionsappen.

1. Leta upp och välj den funktionsapp som du publicerade tidigare.

2. Under Inställningar väljer du Autentisering.

3. Välj Lägg till identitetsprovider.

4. Välj OpenID Anslut som identitetsprovider.

5. Ange ett namn, till exempel Contoso Microsoft Entra-ID.

6. Under posten Metadata anger du följande URL till dokument-URL:en. Ersätt med ditt Klient-ID för {tenantId} Microsoft Entra.

   https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
   

7. Under Appregistrering anger du program-ID (klient-ID) för api-appregistreringen för Azure Functions-autentiseringshändelser som du skapade tidigare.

8. Gå tillbaka till Azure-funktionen under Appregistreringen och ange klienthemligheten.

9. Avmarkera alternativet Tokenlagring .

10. Välj Lägg till för att lägga till OpenID-Anslut identitetsprovider.

Steg 5: Testa programmet

Följ dessa steg för att testa din anpassade anspråksprovider:

Personalklientorganisation

1. Öppna en ny privat webbläsare och navigera och logga in via följande URL.

   https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
   

2. Ersätt {tenantId} med ditt klientorganisations-ID, klientnamn eller något av dina verifierade domännamn. Exempel: contoso.onmicrosoft.com

3. Ersätt {App_to_enrich_ID} med klient-ID för mitt testprogram .

4. När du har loggat in visas din avkodade token på https://jwt.ms. Kontrollera att anspråken från Azure-funktionen visas i den avkodade token, till exempel dateOfBirth.

Extern klientorganisation

1. Öppna en ny privat webbläsare och navigera och logga in via följande URL.

   https://{domainName}.ciamlogin.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
   

2. Ersätt {domainName} med ditt domännamn, till exempel contoso.

3. Ersätt {tenantId} med ditt klientorganisations-ID, klientnamn eller något av dina verifierade domännamn. Exempel: contoso.onmicrosoft.com

4. Ersätt {App_to_enrich_ID} med klient-ID för mitt testprogram .

5. Gå igenom det inloggningsanvändarflöde som du har konfigurerat och godkänn de begärda behörigheterna.

6. När du har loggat in visas din avkodade token på https://jwt.ms. Kontrollera att anspråken från Azure-funktionen visas i den avkodade token, till exempel dateOfBirth.

Se även

• Konfigurera en SAML-app för att ta emot token med anspråk från ett externt arkiv
• Referens för anpassad anspråksprovider
• Felsöka API:et för anpassade autentiseringstillägg