Aracılığıyla paylaş

Azure İşlevleri'da belirteç verme başlangıç olayı için REST API oluşturma

  • Makale

Bu makalede, Azure portalında Azure İşlevleri kullanarak belirteç verme başlatma olayıyla REST API oluşturma işlemi açıklanmaktadır. Belirteciniz için ek talep döndürebilen bir Azure İşlevi uygulaması ve HTTP tetikleyici işlevi oluşturursunuz.

Önkoşullar

  • Özel kimlik doğrulama uzantılarına genel bakış bölümünde ele alınan kavramlar hakkında temel bilgiler.
  • Azure İşlevleri oluşturma özelliğine sahip bir Azure aboneliği. Mevcut bir Azure hesabınız yoksa ücretsiz deneme sürümüne kaydolun veya hesap oluştururken Visual Studio Aboneliği avantajlarınızı kullanın.
  • Microsoft Entra Id kiracısı. Bu nasıl yapılır kılavuzu için bir müşteri veya iş gücü kiracısı kullanabilirsiniz.

Bu makalede, Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet kitaplığını kullanarak belirteç verme başlangıç olayı için REST API'nin nasıl oluşturulacağı ve kimlik doğrulaması için nasıl ayarlanacağı açıklanır. Visual Studio veya Visual Studio Code'da bir HTTP tetikleyici işlevi oluşturacak, kimlik doğrulaması için yapılandıracak ve Azure İşlevleri üzerinden erişilebilen Azure portalına dağıtacaksınız.

Önkoşullar

Not

Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet kitaplığı şu anda önizleme aşamasındadır. Bu makaledeki adımlar değiştirilebilir. Belirteç verme başlatma olayının genel kullanılabilirlik uygulaması için Azure portalını kullanarak bunu yapabilirsiniz.

Azure İşlevi uygulamasını oluşturma

HTTP tetikleyici işlevini oluşturmaya devam etmeden önce Azure portalında bir Azure İşlevi uygulaması ve ilişkili kaynağı oluşturun.

  1. Azure portalında en az Uygulama Yöneticisi ve Kimlik Doğrulama Yöneticisi olarak oturum açın.

  2. Azure portalı menüsünde veya Giriş sayfasında Kaynak oluştur'u seçin.

  3. İşlev Uygulaması'yı arayıp seçin ve Oluştur'u seçin.

  4. Temel Bilgiler sayfasında, aşağıdaki tabloda belirtilen ayarları kullanarak bir işlev uygulaması oluşturun:

    Ayar Önerilen değer Açıklama
    Abonelik Aboneliğiniz Yeni işlev uygulamasının oluşturulacağı abonelik.
    Kaynak Grubu myResourceGroup İşlev uygulamanızı oluşturacağınız yeni grup için ve mevcut kaynak grubunu veya adı seçin.
    İşlev Uygulamasının adı Genel olarak benzersiz bir ad Yeni işlev uygulamasını tanımlayan ad. Geçerli karakterler şunlardır: a-z (büyük/küçük harf duyarsız), 0-9 ve -.
    Kod veya kapsayıcı görüntüsü dağıtma Kod Kod dosyalarını veya Docker kapsayıcısını yayımlama seçeneği. Bu öğretici için Kod'a tıklayın.
    Çalışma zamanı yığını .NET Tercih ettiğiniz programlama dili. Bu öğretici için .NET'i seçin.
    Sürüm 6 (LTS) İşlemde .NET çalışma zamanının sürümü. İşlem içi, bu kılavuz için önerilen portalda işlevler oluşturabileceğinizi ve değiştirebileceğinizi bildirir
    Bölge Tercih edilen bölge Size yakın veya işlevlerinizin erişebileceği diğer hizmetlere yakın bir bölge seçin.
    İşletim Sistemi Windows çalışma zamanı yığını seçiminize göre işletim sistemi sizin için önceden seçilmiştir.
    Plan türü Kullanım (Sunucusuz) Kaynakların işlev uygulamanıza nasıl ayrılacağını tanımlayan barındırma planı.

  5. Uygulama yapılandırma seçimlerini gözden geçirmek için Gözden geçir + oluştur'u ve ardından Oluştur'u seçin. Dağıtım birkaç dakika sürer.

  6. Dağıtıldıktan sonra Kaynağa git'i seçerek yeni işlev uygulamanızı görüntüleyin.

HTTP tetikleyici işlevi oluşturma

Azure İşlevi uygulaması oluşturulduktan sonra, uygulama içinde bir HTTP tetikleyici işlevi oluşturun. HTTP tetikleyicisi, HTTP isteği olan bir işlevi çağırmanıza olanak tanır ve Microsoft Entra özel kimlik doğrulama uzantınız tarafından başvurulur.

  1. İşlev uygulamanızın Genel Bakış sayfasında İşlevler bölmesini seçin ve Azure portalında oluştur'un altında İşlev oluştur'u seçin.
  2. İşlev Oluştur penceresinde Geliştirme ortamı özelliğini Portalda geliştir olarak bırakın. Şablon'un altında HTTP tetikleyicisi'ni seçin.
  3. Şablon ayrıntıları altında, Yeni İşlev özelliği için CustomAuthenticationExtensionsAPI girin.
  4. Yetkilendirme düzeyi için İşlev'i seçin.
  5. Oluştur'u belirleyin. Geliştirme ortamının ve şablonun nasıl seçileceğini gösteren ekran görüntüsü.

İşlevi düzenle

Kod gelen JSON nesnesini okur ve Microsoft Entra ID, JSON nesnesini API'nize gönderir. Bu örnekte bağıntı kimliği değerini okur. Ardından kod, Azure İşlevinizin özgün CorrelationIdve ApiVersion Microsoft Entra Id'sine döndürülen a DateOfBirth ve CustomRoles dahil olmak üzere özelleştirilmiş talepler koleksiyonunu döndürür.

  1. Menüden Geliştirici'nin altında Kod + Test'i seçin.

  2. Kodun tamamını aşağıdaki kod parçacığıyla değiştirin ve Kaydet'i seçin.

    #r "Newtonsoft.Json"
using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;
public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);

    // Read the correlation ID from the Microsoft Entra request    
    string correlationId = data?.data.authenticationContext.correlationId;

    // Claims to return to Microsoft Entra
    ResponseContent r = new ResponseContent();
    r.data.actions[0].claims.CorrelationId = correlationId;
    r.data.actions[0].claims.ApiVersion = "1.0.0";
    r.data.actions[0].claims.DateOfBirth = "01/01/2000";
    r.data.actions[0].claims.CustomRoles.Add("Writer");
    r.data.actions[0].claims.CustomRoles.Add("Editor");
    return new OkObjectResult(r);
}
public class ResponseContent{
    [JsonProperty("data")]
    public Data data { get; set; }
    public ResponseContent()
    {
        data = new Data();
    }
}
public class Data{
    [JsonProperty("@odata.type")]
    public string odatatype { get; set; }
    public List<Action> actions { get; set; }
    public Data()
    {
        odatatype = "microsoft.graph.onTokenIssuanceStartResponseData";
        actions = new List<Action>();
        actions.Add(new Action());
    }
}
public class Action{
    [JsonProperty("@odata.type")]
    public string odatatype { get; set; }
    public Claims claims { get; set; }
    public Action()
    {
        odatatype = "microsoft.graph.tokenIssuanceStart.provideClaimsForToken";
        claims = new Claims();
    }
}
public class Claims{
    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public string CorrelationId { get; set; }
    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public string DateOfBirth { get; set; }
    public string ApiVersion { get; set; }
    public List<string> CustomRoles { get; set; }
    public Claims()
    {
        CustomRoles = new List<string>();
    }
}

  3. Üstteki menüden İşlev Url'sini Al'ı seçin ve URL değerini kopyalayın. Bu işlev URL'si, özel bir kimlik doğrulama uzantısı ayarlanırken kullanılabilir.

Azure İşlevi uygulamasını oluşturma ve oluşturma

Bu adımda, IDE'nizi kullanarak bir HTTP tetikleyici işlevi API'sini oluşturur, gerekli NuGet paketlerini yükler ve örnek koda kopyalarsınız. Projeyi oluşturur ve işlevi çalıştırarak yerel işlev URL'sini ayıklarsınız.

Uygulamayı oluşturma

Azure İşlevi uygulaması oluşturmak için şu adımları izleyin:

  1. Visual Studio'yu açın ve Yeni proje oluştur'u seçin.
  2. Azure İşlevleri arayın ve seçin, ardından İleri'yi seçin.
  3. Projeye AuthEventsTrigger gibi bir ad verin. Çözüm adını proje adıyla eşleştirmek iyi bir fikirdir.
  4. Proje için bir konum seçin. İleri'yi seçin.
  5. Hedef çerçeve olarak .NET 6.0 (Uzun Vadeli Destek) seçeneğini belirleyin.
  6. İşlev türü olarak Http tetikleyicisi'niseçin ve Yetkilendirme düzeyi İşlev olarak ayarlanır. Oluştur'u belirleyin.
  7. Çözüm Gezgini Function1.cs dosyasını AuthEventsTrigger.cs olarak yeniden adlandırın ve yeniden adlandırma değişikliği önerisini kabul edin.

NuGet paketlerini yükleme ve projeyi derleme

Projeyi oluşturduktan sonra gerekli NuGet paketlerini yüklemeniz ve projeyi oluşturmanız gerekir.

  1. Visual Studio'nun üst menüsünde Proje'yi ve ardından NuGet paketlerini yönet'i seçin.
  2. Gözat sekmesini seçin, ardından sağ bölmede Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents öğesini arayın ve seçin. Yükle'yi seçin.
  3. Görüntülenen açılır pencerelerde değişiklikleri uygulayın ve kabul edin.

Örnek kod ekleme

İşlev API'si, belirteciniz için ek taleplerin kaynağıdır. Bu makalenin amaçları doğrultusunda, örnek uygulamanın değerlerini sabit bir şekilde kodlıyoruz. Üretimde, dış veri deposundan kullanıcı hakkındaki bilgileri getirebilirsiniz.

AuthEventsTrigger.cs dosyanızda dosyanın tüm içeriğini aşağıdaki kodla değiştirin:

using System;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;

namespace AuthEventsTrigger
{
    public static class AuthEventsTrigger
    {
        [FunctionName("onTokenIssuanceStart")]
        public static WebJobsAuthenticationEventResponse Run(
            [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log)
        {
            try
            {
                // Checks if the request is successful and did the token validation pass
                if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful)
                {
                    // Fetches information about the user from external data store
                    // Add new claims to the token's response
                    request.Response.Actions.Add(
                        new WebJobsProvideClaimsForToken(
                            new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"),
                            new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"),
                            new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"),
                            new WebJobsAuthenticationEventsTokenClaim(
                                "correlationId", 
                                request.Data.AuthenticationContext.CorrelationId.ToString())));
                }
                else
                {
                    // If the request fails, such as in token validation, output the failed request status, 
                    // such as in token validation or response validation.
                    log.LogInformation(request.StatusMessage);
                }
                return request.Completed();
            }
            catch (Exception ex) 
            { 
                return request.Failed(ex);
            }
        }
    }
}

Projeyi yerel olarak derleme ve çalıştırma

Proje oluşturuldu ve örnek kod eklendi. IDE'nizi kullanarak yerel işlev URL'sini ayıklamak için projeyi yerel olarak derlememiz ve çalıştırmamız gerekir.

  1. Üstteki menüden Derle'ye gidin ve Çözüm Derle'yi seçin.
  2. F5 tuşuna basın veya üstteki menüden AuthEventsTrigger'ı seçerek işlevi çalıştırın.
  3. İşlevi çalıştırırken açılan terminalden İşlev URL'sini kopyalayın. Bu, özel bir kimlik doğrulama uzantısı ayarlanırken kullanılabilir.

İşlevi Azure'a dağıtmadan önce yerel olarak test etmek iyi bir fikirdir. Microsoft Entra ID'nin REST API'nize gönderdiği isteği taklit eden sahte bir JSON gövdesi kullanabiliriz. İşlevi doğrudan çağırmak için tercih ettiğiniz API test aracını kullanın.

  1. IDE'nizde local.settings.json açın ve kodu aşağıdaki JSON ile değiştirin. Yerel test amacıyla olarak true ayarlayabiliriz"AuthenticationEvents__BypassTokenValidation".

    {
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "AzureWebJobsSecretStorageType": "files",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation" : true
  }
}

  2. Tercih ettiğiniz API test aracını kullanarak yeni bir HTTP isteği oluşturun ve HTTP yöntemini olarak POSTayarlayın.

  3. Microsoft Entra Id'nin REST API'nize gönderdiği isteği taklit eden aşağıdaki JSON gövdesini kullanın.

    {
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
        "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
        "authenticationContext": {
            "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2023-08-16T00:00:00Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "Casey Jensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

  4. Gönder'i seçtiğinizde aşağıdakine benzer bir JSON yanıtı almanız gerekir:

    {
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "customClaim1": "customClaimValue1",
                    "customClaim2": [
                        "customClaimString1",
                        "customClaimString2" 
                    ]
                }
            }

        ]
    }
}

İşlevi dağıtma ve Azure'da yayımlama

İşlevin IDE'miz kullanılarak Azure'a dağıtılması gerekir. İşlevin yayımlanabilmesi için Azure hesabınızda doğru şekilde oturum açtığınızdan denetleyin.

  1. Çözüm Gezgini projeye sağ tıklayın ve Yayımla'yı seçin.

  2. Hedef'te Azure'ı ve ardından İleri'yi seçin.

  3. Belirli Hedef için Azure İşlev Uygulaması 'nı (Windows) seçin, Azure İşlev Uygulaması (Windows)'ı ve ardından İleri'yi seçin.

  4. İşlev örneğinde Abonelik adı açılan listesini kullanarak yeni işlev uygulamasının oluşturulacağı aboneliği seçin.

  5. Yeni işlev uygulamasını yayımlamak istediğiniz yeri seçin ve ardından Yeni Oluştur'u seçin.

  6. İşlev Uygulaması (Windows) sayfasında, aşağıdaki tabloda belirtilen işlev uygulaması ayarlarını kullanın ve oluştur'u seçin.

    Ayar Önerilen değer Veri Akışı Açıklaması
    Adı Genel olarak benzersiz bir ad Yeni işlev uygulamasını tanımlayan ad. Geçerli karakterler şunlardır: a-z (büyük/küçük harf duyarsız), 0-9 ve -.
    Abonelik Aboneliğiniz Yeni işlev uygulamasının oluşturulduğu abonelik.
    Kaynak Grubu myResourceGroup Mevcut bir kaynak grubunu seçin veya işlev uygulamanızı oluşturacağınız yeni kaynak grubunu adlandırın.
    Plan türü Kullanım (Sunucusuz) Kaynakların işlev uygulamanıza nasıl ayrılacağını tanımlayan barındırma planı.
    Konum Tercih edilen bölge Size yakın veya işlevlerinizin erişebileceği diğer hizmetlere yakın bir bölge seçin.
    Azure Depolama Depolama hesabınız İşlevler çalışma zamanı için bir Azure depolama hesabı gereklidir. Genel amaçlı bir depolama hesabı yapılandırmak için Yeni'yi seçin.
    Application Insights Varsayılan Azure İzleyici'nin bir özelliği. Bu otomatik olarak seçilir, kullanmak istediğiniz kişiyi seçin veya yenisini yapılandırın.

  7. İşlev uygulamanızın dağıtılması için birkaç dakika bekleyin. Pencere kapandıktan sonra Son'u seçin.

  8. Yeni bir Yayımla bölmesi açılır. Üst kısımda Yayımla'yı seçin. İşlev uygulamanızın dağıtılması ve Azure portalında gösterilmesi için birkaç dakika bekleyin.

Azure İşleviniz için kimlik doğrulamasını yapılandırma

Azure İşleviniz için kimlik doğrulamasını ayarlamanın üç yolu vardır:

Varsayılan olarak kod, ortam değişkenleri kullanılarak Azure portalında kimlik doğrulaması için ayarlanmıştır. Ortam değişkenlerini uygulamak için tercih ettiğiniz yöntemi seçmek için aşağıdaki sekmeleri kullanın veya alternatif olarak yerleşik Azure Uygulaması hizmet kimlik doğrulaması ve yetkilendirmesine bakın. Ortam değişkenlerini ayarlamak için aşağıdaki değerleri kullanın:

Veri Akışı Adı Değer
AuthenticationEvents__AudienceAppId Belirteç verme olayı için özel talep sağlayıcısı yapılandırma bölümünde ayarlanan özel kimlik doğrulama uzantısı uygulama kimliği
AuthenticationEvents__AuthorityUrl • İş gücü kiracısı https://login.microsoftonline.com/<tenantID>
• Dış kiracı https://<mydomain>.ciamlogin.com/<tenantID>
AuthenticationEvents__AuthorizedPartyAppId 99045fe1-7639-4a75-9d4a-577b6ca3810f veya başka bir yetkili taraf

Ortam değişkenlerini kullanarak Azure portalında kimlik doğrulamasını ayarlama

  1. Azure portalında en az Uygulama Yöneticisi veya Kimlik Doğrulama Yöneticisi olarak oturum açın.
  2. Oluşturduğunuz işlev uygulamasına gidin ve Ayarlar'ın altında Yapılandırma'yı seçin.
  3. Uygulama ayarları'nın altında Yeni uygulama ayarı'nı seçin ve tablodan ortam değişkenlerini ve ilişkili değerlerini ekleyin.
  4. Uygulama ayarlarını kaydetmek için Kaydet'i seçin.

Sonraki adım

Özel talep sağlayıcı belirteci verme olayını yapılandırma