MSAL Önleyici

MSAL Angular, Angular http istemcisini kullanarak bilinen korumalı kaynaklara gönderilen istekler için belirteçleri otomatik olarak alan bir Interceptor sınıfı sağlar. Bu belge, yapılandırma ve kullanma MsalInterceptorhakkında daha fazla bilgi sağlar.

acquireTokenSilent API’sini doğrudan kullanmak yerine MsalInterceptor kullanmanızı öneririz, ancak MsalInterceptor kullanımının isteğe bağlı olduğunu lütfen unutmayın. Bunun yerine, belirteçleri açıkça edinmek için acquireToken API’lerini kullanmak isteyebilirsiniz.

Kolaylık sağlamak için sağlandığını ve tüm kullanım örneklerine MsalInterceptor uymayabileceğini lütfen unutmayın. MsalInterceptor tarafından karşılanmayan belirli gereksinimleriniz varsa, kendi önleyicinizi yazmanızı öneririz.

Configuration

app.module.ts içinde MsalInterceptor yapılandırma

MsalInterceptor, yapılandırmasıyla birlikte app.module.ts içinde uygulamanıza bir sağlayıcı olarak eklenebilir. İçe aktarma işlemleri, bir MSAL örneğinin yanı sıra Angular’a özgü iki yapılandırma nesnesini de alır. Üçüncü bağımsız değişken, interactionType, bir protectedResourceMap ve isteğe bağlı bir authRequest için değerleri içeren bir MsalInterceptorConfiguration nesnesidir.

Yapılandırmanız aşağıdaki gibi görünebilir. Uygulamanız için MSAL Angular'ı yapılandırmanın diğer yolları hakkında yapılandırma belgemize bakın.

import { NgModule } from '@angular/core';
import { HTTP_INTERCEPTORS, HttpClientModule } from "@angular/common/http";
import { AppComponent } from './app.component';
import { MsalModule, MsalRedirectComponent, MsalGuard, MsalInterceptor } from '@azure/msal-angular'; // Import MsalInterceptor
import { InteractionType, PublicClientApplication } from '@azure/msal-browser';

@NgModule({
    declarations: [
        AppComponent,
    ],
    imports: [
        MsalModule.forRoot( new PublicClientApplication({
            // MSAL Configuration
        }), {
            // MSAL Guard Configuration
        }, {
            // MSAL Interceptor Configurations
            interactionType: InteractionType.Redirect,
            protectedResourceMap: new Map([ 
                ['Enter_the_Graph_Endpoint_Here/v1.0/me', ['user.read']]
            ])
        })
    ],
    providers: [
        {
            provide: HTTP_INTERCEPTORS, // Provides as HTTP Interceptor
            useClass: MsalInterceptor,
            multi: true
        },
        MsalGuard
    ],
    bootstrap: [AppComponent, MsalRedirectComponent]
})
export class AppModule { }

Etkileşim Türü

MsalInterceptor sessiz belirteçleri alacak şekilde tasarlanmıştır ancak sessiz bir isteğin başarısız olması durumunda belirteçleri etkileşimli olarak almaya geri döner. InteractionType, @azure/msal-browser içinden içeri aktarılabilir ve Popup veya Redirect olarak ayarlanabilir.

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map([ 
        ['Enter_the_Graph_Endpoint_Here/v1.0/me', ['user.read']]
    ])
}

Korumalı Kaynak Eşlemesi

Korumalı kaynaklar ve bunlara karşılık gelen kapsamlar, MsalInterceptor yapılandırmasında protectedResourceMap olarak sağlanır.

protectedResourceMap koleksiyonunda sağladığınız URL'ler büyük/küçük harfe duyarlıdır. Her kaynak için erişim belirtecinde döndürülmesini istenen kapsamları ekleyin.

Örneğin:

  • ["user.read"]Microsoft Graph için
  • ["<Application ID URL>/scope"]özel web API'leri için (yani ) api://<Application ID>/access_as_user

Bir kaynak için kapsamlar aşağıdaki yollarla belirtilebilir:

  1. HTTP yöntemi ne olursa olsun, bu kaynağa yapılan her HTTP isteğine eklenecek kapsam dizisi.
{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map<string, Array<string> | null>([
        ["https://graph.microsoft.com/v1.0/me", ["user.read", "profile"]],
        ["https://myapplication.com/user/*", ["customscope.read"]]
    ]),
}
  1. Yalnızca belirli HTTP yöntemleri için kapsamları ekleyecek bir ProtectedResourceScopes dizisi.
{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map<string, Array<string|ProtectedResourceScopes> | null>([
        ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        ["http://myapplication.com", [
            {
                httpMethod: "POST",
                scopes: ["write.scope"]
            }
        ]]
    ])
}

Bir kaynağa yönelik kapsamların, dizeler ile ProtectedResourceScopes birleşimini içerebileceğini unutmayın. Aşağıdaki örnekte, bir GET isteğinin kapsamları "all.scope" ve "read.scope" olurken, PUT isteği yalnızca "all.scope" kapsamına sahip olur.

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map<string, Array<string|ProtectedResourceScopes> | null>([
        ["http://myapplication.com", [
            "all.scope",
            {
                httpMethod: "GET",
                scopes: ["read.scope"]
            },
            {
                httpMethod: "POST",
                scopes: ["info.scope"]
            }
        ]]
    ])
}
  1. Bir kaynağın korumasız bırakılacağını ve belirteç almayacağını belirten null kapsam değeri. içinde protectedResourceMap bulunmayan kaynaklar varsayılan olarak korunmaz. Belirli bir kaynağın korumasız olarak belirtilmesi, bir kaynak üzerindeki bazı yolların korunacağı ve bazılarının korunmadığı durumlarda yararlı olabilir. içindeki sıranın protectedResourceMap önemli olduğunu, dolayısıyla null kaynağın benzer temel URL'lerden veya joker karakterlerden önce koyulması gerektiğini unutmayın.
{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map<string, Array<string> | null>([
        ["https://graph.microsoft.com/v1.0/me", ["user.read", "profile"]],
        ["https://myapplication.com/unprotected", null],
        ["https://myapplication.com/unprotected/post", [{ httpMethod: 'POST', scopes: null }]],
        ["https://myapplication.com", ["custom.scope"]]
    ]),
}

protectedResourceMap ile ilgili dikkat edilmesi gereken diğer noktalar:

  • Joker karakterler: protectedResourceMap, joker karakterler için * kullanımını destekler. Joker karakterler kullanılırken, protectedResourceMap içinde eşleşen birden çok giriş bulunursa, ilk bulunan eşleşme kullanılır (protectedResourceMap sıralamasına göre).
  • Göreli yollar: Uygulamanızda göreli kaynak yolları varsa, içinde protectedResourceMapgöreli yolu sağlamanız gerekebilir. Bu, ngx-translate ile ortaya çıkabilecek sorunlar için de geçerlidir. protectedResourceMap içindeki göreli yolun, uygulamanıza bağlı olarak, başında eğik çizgi gerekip gerekmeyebileceğini ve her iki durumu da denemeniz gerekebileceğini unutmayın.

Katı Eşleştirme (strictMatching)

msal-angular v5'te, protectedResourceMap girdileri için URL bileşeni desen eşleştirmesi varsayılan olarak katı eşleştirme anlambilimini kullanır. üzerindeki strictMatchingMsalInterceptorConfiguration alanı bu davranışı denetler.

Important

Uygulamanız protectedResourceMap anahtarlarını dinamik olarak ayarlıyorsa (örneğin ortam dosyalarından, APP_INITIALIZER veya JSON yapılandırmasından) ve bu anahtarlar alt yol veya joker karakter içermeyen temel URL'lerse, katı eşleştirme Authorization başlığının eklenmesini sessizce engelleyebilir. Bu, derleme sırasında hata olmadan ve istek başına herhangi bir uyarı verilmeden 401 hatalarına yol açar; strictMatching açıkça yapılandırılmamışsa yalnızca bir defalık bir başlatma uyarısı gösterilir. Ayrıntılar için bkz. Katı eşleştirme sorunlarını giderme .

Tam eşleme değişiklikleri

Behavior Eski (strictMatching: false) Katı (v5'te varsayılan)
Meta karakterlerden kaçış . ve diğer regex metacharacter'ları kaçış değildir ; regex işleçleri olarak hareket ederler Tüm meta karakterler (. dahil) sıradan karakterler olarak işlenir
Bağlama Desen, dizenin içinde herhangi bir yerde eşleşebilir Desen tam dizeyle eşleşmelidir (^…$)
Konak joker karakteri (*) * aşağıdakiler dahil olmak üzere herhangi bir karakter dizisiyle eşleşir . *, . içermeyen herhangi bir karakter dizisiyle eşleşir (jokerler tek bir DNS etiketi içinde kalır)
Yol/arama/karma joker karakteri (*) * herhangi bir karakter dizisiyle eşleşir * herhangi bir karakter dizisiyle eşleşir (değişmeden)
? Karakter Alttaki regex'e iletildi Normal karakter? olarak değerlendirilir (joker karakter değil, URL sorgu dizesi ayırıcısı olarak)

Katı eşleştirme ile (v5 varsayılanı):

  • *.contoso.com gibi bir desen, app.contoso.com ile eşleşir ancak eşleşmeza.b.contoso.com (joker karakter nokta ayırıcılarına yayılamaz).
  • Gibi https://graph.microsoft.com/v1.0/me bir desen yalnızca tam URL ile eşleşir.

Yaygın hata desenleri

Aşağıdaki protectedResourceMap anahtar desenleri eski eşleştirme altında çalışır ancak katı eşleştirme ile sessizce başarısız olur:

Anahtar modeli Giden istek URL'si Katı eşleştirme altında sonuç Düzelt
https://api.example.com https://api.example.com/v1/users Eşleşme yok — anahtarın çözümlendiği yol /, isteğin yolu ise /v1/users https://api.example.com/*
https://api.example.com/ https://api.example.com/v1/users Eşleşme yok — sondaki eğik çizgi, deseni tam olarak / öğesine sabitler https://api.example.com/*
environment.apiConfig.uri (örneğin, https://api.example.com) https://api.example.com/v1/users Eşleşme yok — yukarıdakiyle aynı `${environment.apiConfig.uri}/*`

v5'te varsayılan davranış (yapılandırma gerekmez)

Katı eşleştirme varsayılan olarak etkindir. Ek yapılandırma gerekmez:

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map([
        ["https://*.contoso.com/api", ["contoso.scope"]],
        ["https://graph.microsoft.com/v1.0/me", ["user.read"]]
    ])
    // strictMatching defaults to true in v5
}

Eski eşleştirme sistemini devre dışı bırakma

Desenleriniz v4'ten gelen daha gevşek eşleştirmeyi kullanırsa, eski davranışı geçici olarak korumak için ayarlayabilirsiniz strictMatching: false :

Note

Geriye dönük uyumluluk için eski eşleştirme (strictMatching: false) sağlanır ve gelecekteki bir ana sürümde kaldırılabilir. protectedResourceMap desenlerinizi tam eşleşmeyle çalışacak şekilde güncellemenizi öneririz.

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map([
        ["https://*.contoso.com/api", ["contoso.scope"]],
        ["https://graph.microsoft.com/v1.0/me", ["user.read"]]
    ]),
    strictMatching: false  // Use legacy matching for backwards compatibility
}

Ortam temelli yapılandırmalar için yönergeler

Anahtarlarınız protectedResourceMap Angular environment değerlerine (örneğin, ) başvuruda bulunursa, environment.apiConfig.uribu değerlerin tam yollar (örneğin, https://graph.microsoft.com/v1.0/me) veya çıplak temel URL'ler (örneğin, https://api.example.com) olup olmadığını denetleyin. Tam yollar katı eşleştirme ile doğru şekilde çalışır ve özel işlemeye gerek yoktur:

export function MSALInterceptorConfigFactory(): MsalInterceptorConfiguration {
  const protectedResourceMap = new Map<string, Array<string>>();
  // environment.apiConfig.uri is an exact path (e.g. "https://graph.microsoft.com/v1.0/me")
  // — strict matching works correctly
  protectedResourceMap.set(environment.apiConfig.uri, environment.apiConfig.scopes);

  return {
    interactionType: InteractionType.Redirect,
    protectedResourceMap,
  };
}

Ortam değeri yalnızca temel URL'den oluşuyorsa ve alt yolları eşleştirmeniz gerekiyorsa, bir /* joker karakteri ekleyin:

  // environment.apiConfig.uri is a base URL (e.g. "https://api.example.com")
  // Append /* to match all sub-paths
  protectedResourceMap.set(`${environment.apiConfig.uri}/*`, environment.apiConfig.scopes);

Anahtar şeklinin derleme zamanında bilinmediği gerçekten dinamik yapılandırmalar için (örneğin, APP_INITIALIZER, veya fetcharacılığıyla platformBrowserDynamicyüklenen JSON), geçici bir güvenli varsayılan olarak ayarlayınstrictMatching: false. Kod örneği için bkz . Düzeltme seçenekleri—B Seçeneği .

Katı eşleştirme sorunlarını giderme

Symptoms
  • API istekleri, v5'e yükselttikten sonra (veya 5.0.x → 5.1.x gibi v5 ikincil sürümleri arasında) @azure/msal-angular döndürür.
  • Authorization: Bearer <token> üst bilgisi, giden HTTP isteklerinden eksik.
  • Derleme zamanı veya çalışma zamanı hatası bildirilmemiştir; hata sessizdir.
  • Sorun yalnızca API temel URL'sinin geliştirmeden farklı olduğu belirli ortamlarda (örneğin hazırlama/üretim) görünebilir.
Düzeltme seçenekleri

A Seçeneği: Anahtarları katı eşleştirmeyle çalışacak şekilde güncelleştirin (önerilir)

Anahtarlarınızı protectedResourceMap , katı eşleştirme kuralları altında eşleşen tam yolları veya joker karakterleri kullanacak şekilde güncelleştirin. Katı eşleştirme daha güvenli ve tahmin edilebilir olduğundan bu yaklaşım tercih edilir:

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map([
        // Exact path — matches only this URL
        ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        // Wildcard — matches all sub-paths of the API
        ["https://api.example.com/v1/*", ["api.scope"]]
    ])
    // strictMatching defaults to true — no need to set it
}

Seçenek B: Ayarla strictMatching: false (dinamik yapılandırmalar için geri dönüş)

protectedResourceMap anahtarlarınız çalışma zamanında dinamik olarak yükleniyorsa (örneğin APP_INITIALIZER, JSON yapılandırması veya platformBrowserDynamic içinden) ve bunların tam yollar ya da joker karakterler içerdiğini garanti edemiyorsanız, geçici olarak güvenli bir varsayılan değer olarak strictMatching: false ayarlayın:

{
    interactionType: InteractionType.Redirect,
    protectedResourceMap: new Map([
        [config.apiUri, config.apiScopes]
    ]),
    // Dynamic keys may be base URLs without wildcards.
    // Remove once keys are migrated to exact paths or wildcard patterns.
    strictMatching: false
}

Note

Geriye dönük uyumluluk için eski eşleştirme (strictMatching: false) sağlanır ve gelecekteki bir ana sürümde kaldırılabilir.

Çalışma zamanı uyarısı

MsalInterceptoraçıkça yapılandırılmadığında başlatma sırasında MSAL günlükçü aracılığıyla strictMatching gönderir. Bu uyarıyı görürseniz yukarıdaki düzeltme seçeneklerini izleyin.

İsteğe bağlı authRequest

MsalInterceptorConfiguration içinde ayarlanabilen isteğe bağlı authRequest hakkında daha fazla bilgi için lütfen çok kiracılı dokümanımızı burada inceleyin.

msal-angular v1'den v2'ye yapılan değişiklikler

Note

MSAL Angular v1'deki MsalAngularConfiguration içindeki unprotectedResourceMap kullanımdan kaldırıldı ve artık çalışmıyor.

  • protectedResourceMap MsalInterceptorConfiguration nesnesine taşındı ve Map<string, Array<string|ProtectedResourceScopes>> olarak iletilebilir. MsalAngularConfiguration kullanım dışı bırakıldı ve artık çalışmıyor.
  • Tüm rotaları korumak için kök etki alanını protectedResourceMap içine yerleştirmek artık desteklenmiyor. Lütfen bunun yerine joker karakter eşleştirmesini kullanın.

Kapsamların nasıl yapılandırılacağı hakkında daha fazla bilgi için lütfen SSS bölümümüze göz atın.

  • Last updated on