Kurumsal uygulamalar için JSON web belirtecinde (JWT) verilen talepleri özelleştirme

  • Makale

Microsoft kimlik platformu, Microsoft Entra uygulama galerisindeki ve özel uygulamalardaki en önceden tümlenmiş uygulamalarla çoklu oturum açmayı (SSO) destekler. Bir kullanıcı OIDC protokolunu kullanarak Microsoft kimlik platformu aracılığıyla bir uygulamada kimlik doğrulaması yaparsa, Microsoft kimlik platformu uygulamaya bir belirteç gönderir. Uygulama, kullanıcı adı ve parola isteme yerine oturum açmak için belirteci doğrular ve kullanır.

OIDC ve OAuth uygulamaları tarafından kullanılan bu JSON Web belirteçleri (JWT), kullanıcı hakkında talep olarak bilinen bilgiler içerir. Talep, kimlik sağlayıcısının bu kullanıcı için verdikleri belirtecin içindeki bir kullanıcı hakkında belirttiği bilgilerdir. OIDC yanıtında talep verileri genellikle kimlik sağlayıcısı tarafından JWT biçiminde verilen Kimlik Belirtecinde yer alır.

Talepleri görüntüleme veya düzenleme

İpucu

Bu makaledeki adımlar, başladığınız portala göre biraz değişiklik gösterebilir.

JWT'de uygulamaya verilen talepleri görüntülemek veya düzenlemek için:

  1. Microsoft Entra yönetim merkezinde en az Bulut Uygulaması Yönetici istrator olarak oturum açın.
  2. Kimlik>Uygulamaları>Kurumsal uygulamaları>Tüm uygulamalar'a göz atın.
  3. Uygulamayı seçin, sol taraftaki menüden Çoklu oturum açma'yı ve ardından Öznitelikler ve Talepler bölümünde Düzenle'yiseçin.

Bir uygulamanın çeşitli nedenlerle talep özelleştirmesi gerekebilir. Örneğin, bir uygulama farklı bir talep URI'leri veya talep değerleri kümesi gerektirdiğinde. Öznitelikler ve Talepler bölümünü kullanarak, uygulamanız için bir talep ekleyebilir veya kaldırabilirsiniz. Ayrıca, kullanım örneğine göre bir uygulamaya özgü bir özel talep de oluşturabilirsiniz.

Aşağıdaki adımlarda sabit bir değerin nasıl atandığı açıklanmaktadır:

  1. Değiştirmek istediğiniz talebi seçin.
  2. Kaynak özniteliğinde, kuruluşunuza göre tırnak işaretleri olmadan sabit değeri girin ve Kaydet'i seçin.

Özniteliklere genel bakış, sabit değeri görüntüler.

Özel talep dönüştürmeleri

Aşağıdaki özel talep dönüştürme işlevlerini kullanabilirsiniz.

İşlev Açıklama
ExtractMailPrefix() E-posta adresinden veya kullanıcı asıl adından etki alanı sonekini kaldırır. Bu işlev, kullanıcı adının yalnızca ilk bölümünü ayıklar. Örneğin, joe_smith yerine joe_smith@contoso.com.
ToLower() Seçili özniteliğin karakterlerini küçük harflere dönüştürür.
ToUpper() Seçili özniteliğin karakterlerini büyük harf karakterlere dönüştürür.

Uygulamaya özgü talepler ekleme

Uygulamaya özgü talepler eklemek için:

  1. Kullanıcı Öznitelikleri ve Talepler bölümünde Yeni talep ekle'yi seçerek Kullanıcı taleplerini yönet sayfasını açın.
  2. Taleplerin adını girin. Değerin kesinlikle bir URI desenini izlemesi gerekmez. URI deseni gerekiyorsa, bunu Ad Alanı alanına yerleştirebilirsiniz.
  3. Talebin değerini alacağı Kaynağı seçin. Kaynak öznitelik açılan listesinden bir kullanıcı özniteliği seçebilir veya bunu talep olarak yaymadan önce kullanıcı özniteliğine dönüştürme uygulayabilirsiniz.

Talep dönüştürmeleri

Kullanıcı özniteliğine dönüştürme uygulamak için:

  1. Talebi yönet bölümünde, Dönüştürmeyi yönet sayfasını açmak için talep kaynağı olarak Dönüştürme'yi seçin.
  2. Dönüştürme açılan listesinden işlevi seçin. Seçilen işleve bağlı olarak, dönüştürmede değerlendirilecek parametreleri ve sabit bir değeri sağlayın.
  3. Kaynağı birden çok değerli olarak kabul etmek, dönüşümün tüm değerlere mi yoksa yalnızca ilk değere mi uygulandığını gösterir. Varsayılan olarak, çok değerli bir talepteki ilk öğe dönüştürmeleri uygulanır. Bu kutuyu işaretlediğinizde, tümüne uygulanmasını sağlar. Bu onay kutusu yalnızca çok değerli öznitelikler için etkinleştirilir. Örneğin, user.proxyaddresses.
  4. Birden çok dönüştürme uygulamak için Dönüştürme ekle'yi seçin. Bir talepe en fazla iki dönüştürme uygulayabilirsiniz. Örneğin, önce öğesinin e-posta ön ekini user.mailayıklayabilirsiniz. Ardından dizeyi büyük harf yapın.

Talepleri dönüştürmek için aşağıdaki işlevleri kullanabilirsiniz.

İşlev Açıklama
ExtractMailPrefix() E-posta adresinden veya kullanıcı asıl adından etki alanı sonekini kaldırır. Bu işlev, kullanıcı adının yalnızca ilk bölümünü ayıklar. Örneğin, joe_smith yerine joe_smith@contoso.com.
Join() İki özniteliği birleştirerek yeni bir değer oluşturur. İsteğe bağlı olarak, iki öznitelik arasında bir ayırıcı kullanabilirsiniz. NameID talep dönüşümü için Join() işlevi, dönüştürme girişinin bir etki alanı parçası olduğunda belirli bir davranışa sahiptir. Etki alanı bölümünü ayırıcı ve seçili parametreyle birleştirmeden önce girdiden kaldırır. Örneğin, dönüşümün joe_smith@contoso.com girişi, ayırıcı @ ise ve parametresi ise fabrikam.com, bu giriş bileşimi ile joe_smith@fabrikam.comsonuçlanır.
ToLowercase() Seçili özniteliğin karakterlerini küçük harflere dönüştürür.
ToUppercase() Seçili özniteliğin karakterlerini büyük harf karakterlere dönüştürür.
Contains() Giriş belirtilen değerle eşleşiyorsa bir öznitelik veya sabit verir. Aksi takdirde, eşleşme yoksa başka bir çıkış belirtebilirsiniz.
Örneğin, etki alanını @contoso.comiçeriyorsa değerin kullanıcının e-posta adresi olduğu bir talep yaymak istiyorsanız, aksi takdirde kullanıcı asıl adını çıkarmak istersiniz. Bu işlevi gerçekleştirmek için aşağıdaki değerleri yapılandırabilirsiniz:
Parametre 1(giriş): user.email
Değer: "@contoso.com"
Parametre 2 (çıkış): user.email
Parametre 3 (eşleşme yoksa çıkış): user.userprincipalname
EndWith() Girişin belirtilen değerle bitmesi durumunda bir öznitelik veya sabit çıkışı verir. Aksi takdirde, eşleşme yoksa başka bir çıkış belirtebilirsiniz.
Örneğin, çalışan kimliği ile 000bitiyorsa değerin kullanıcının çalışan kimliği olduğu bir talep yaymak istiyorsanız, aksi takdirde bir uzantı özniteliği çıkarmak istersiniz. Bu işlevi gerçekleştirmek için aşağıdaki değerleri yapılandırabilirsiniz:
Parametre 1(giriş): user.employeeid
Değer: "000"
Parametre 2 (çıkış): user.employeeid
Parametre 3 (eşleşme yoksa çıkış): user.extensionattribute1
StartWith() Giriş belirtilen değerle başlıyorsa bir öznitelik veya sabit verir. Aksi takdirde, eşleşme yoksa başka bir çıkış belirtebilirsiniz.
Örneğin, ülke/bölge ile USbaşlıyorsa, değerin kullanıcının çalışan kimliği olduğu bir talep yaymak istiyorsanız, aksi takdirde bir uzantı özniteliği çıkarmak istersiniz. Bu işlevi gerçekleştirmek için aşağıdaki değerleri yapılandırabilirsiniz:
Parametre 1(giriş): user.country
Değer: "US"
Parametre 2 (çıkış): user.employeeid
Parametre 3 (eşleşme yoksa çıkış): user.extensionattribute1
Extract() - Eşleştirmeden sonra Belirtilen değerle eşleşdikten sonra alt dizeyi döndürür.
Örneğin, girişin değeri Finance_BSimonise eşleşen değer olur Finance_ve talebin çıktısı olur BSimon.
Extract() - Eşleştirmeden önce Belirtilen değerle eşleşene kadar alt dizeyi döndürür.
Örneğin, girişin değeri BSimon_USise eşleşen değer olur _USve talebin çıktısı olur BSimon.
Extract() - Eşleştirme arasında Belirtilen değerle eşleşene kadar alt dizeyi döndürür.
Örneğin, girişin değeri ise Finance_BSimon_US, ilk eşleşen değer , Finance_ikinci eşleşen değer ise _US, talebin çıktısı olur BSimon.
ExtractAlpha() - Ön Ek Dizenin alfabetik ön ek bölümünü döndürür.
Örneğin, girişin değeri ise BSimon_123döndürür BSimon.
ExtractAlpha() - Sonek Dizenin alfabetik bölümünü döndürür.
Örneğin, girişin değeri ise 123_Simondöndürür Simon.
ExtractNumeric() - Ön Ek Dizenin sayısal bölümünün ön ekini döndürür.
Örneğin, girişin değeri ise 123_BSimondöndürür 123.
ExtractNumeric() - Sonek Dizenin sonek sayısal bölümünü döndürür.
Örneğin, girişin değeri ise BSimon_123döndürür 123.
IfEmpty() Giriş null veya boşsa bir öznitelik veya sabit oluşturur.
Örneğin, belirli bir kullanıcının çalışan kimliği boşsa uzantı özniteliğinde depolanan bir özniteliğin çıktısını almak istiyorsanız. Bu işlevi gerçekleştirmek için aşağıdaki değerleri yapılandırın:
Parametre 1(giriş): user.employeeid
Parametre 2 (çıkış): user.extensionattribute1
Parametre 3 (eşleşme yoksa çıkış): user.employeeid
IfNotEmpty() Giriş null veya boş değilse bir öznitelik veya sabit çıkışı oluşturur.
Örneğin, belirli bir kullanıcının çalışan kimliği boş değilse uzantı özniteliğinde depolanan bir özniteliğin çıktısını almak istiyorsanız. Bu işlevi gerçekleştirmek için aşağıdaki değerleri yapılandırabilirsiniz:
Parametre 1(giriş): user.employeeid
Parametre 2 (çıkış): user.extensionattribute1
Substring() - Sabit Uzunluk Dize talep türünün belirtilen konumdaki karakterden başlayarak bölümlerini ayıklar ve belirtilen karakter sayısını döndürür.
SourceClaim - Yürütülmesi gereken dönüşümün talep kaynağı.
StartIndex - Bu örnekteki bir alt dizenin sıfır tabanlı başlangıç karakteri konumu.
Uzunluk - Alt dizenin karakter cinsinden uzunluğu.
Örneğin:
sourceClaim - PleaseExtractThisNow
StartIndex - 6
Uzunluk - 11
Çıkış: ExtractThis
Substring() - EndOfString Belirtilen konumdaki karakterden başlayarak bir dize talep türünün bölümlerini ayıklar ve belirtilen başlangıç dizininden talebin geri kalanını döndürür.
SourceClaim - Dönüşümün talep kaynağı.
StartIndex - Bu örnekteki bir alt dizenin sıfır tabanlı başlangıç karakteri konumu.
Örneğin:
sourceClaim - PleaseExtractThisNow
StartIndex - 6
Çıkış: ExtractThisNow
RegexReplace() RegexReplace() dönüşümü giriş parametresi olarak kabul eder:
- Parametre 1: regex girişi olarak bir kullanıcı özniteliği
- Kaynağa birden çok değerli olarak güvenme seçeneği
- Regex deseni
- Değiştirme düzeni. Değiştirme düzeni, regex çıkış gruplarını ve daha fazla giriş parametresini işaret eden bir başvuruyla birlikte statik metin biçimi içerebilir.

Başka dönüşümlere ihtiyacınız varsa, fikrinizi SaaS uygulama kategorisi altındaki Microsoft Entra Id'deki geri bildirim forumunda gönderin.

Regex tabanlı talep dönüştürme

Aşağıdaki görüntüde ilk dönüştürme düzeyinin bir örneği gösterilmektedir:

Screenshot of the first level of transformation.

Aşağıdaki tablo, ilk dönüştürme düzeyi hakkında bilgi sağlar. Tabloda listelenen eylemler önceki görüntüdeki etiketlere karşılık gelir. Talep dönüştürme dikey penceresini açmak için Düzenle'yi seçin.

Eylem Alan Açıklama
1 Transformation Dönüştürme seçeneklerinden RegexReplace() seçeneğini belirleyerek beyan dönüştürme için regex tabanlı talep dönüştürme yöntemini kullanın.
2 Parameter 1 Normal ifade dönüşümü için giriş. Örneğin, gibi admin@fabrikam.combir kullanıcı e-posta adresi olan user.mail.
3 Treat source as multivalued Bazı giriş kullanıcı öznitelikleri çok değerli kullanıcı öznitelikleri olabilir. Seçilen kullanıcı özniteliği birden çok değeri destekliyorsa ve kullanıcı dönüştürme için birden çok değer kullanmak istiyorsa, Kaynağı birden çok değerli olarak değerlendir'i seçmesi gerekir. Seçilirse, regex eşleşmesi için tüm değerler kullanılır, aksi takdirde yalnızca ilk değer kullanılır.
4 Regex pattern Parametre 1 olarak seçilen kullanıcı özniteliğinin değerine göre değerlendirilen normal ifade. Örneğin, kullanıcının e-posta adresinden kullanıcı diğer adını ayıklamaya yönelik normal ifade olarak (?'domain'^.*?)(?i)(\@fabrikam\.com)$temsil edilir.
5 Add additional parameter Dönüştürme için birden fazla kullanıcı özniteliği kullanılabilir. Daha sonra özniteliklerin değerleri regex dönüştürme çıkışıyla birleştirilir. En fazla beş parametre daha desteklenir.
6 Replacement pattern Değiştirme düzeni, regex sonucu için yer tutucular içeren metin şablonudur. Tüm grup adları {group-name} gibi küme ayraçlarının içine sarmalanmalıdır. Yönetimin kullanıcı diğer adını başka bir etki alanı adıyla kullanmak istediğini varsayalım; örneğin xyz.com , ülke adını bu adla birleştirin. Bu durumda, değiştirme deseni {country}.{domain}@xyz.comolur; burada {country} giriş parametresinin değeri ve {domain} normal ifade değerlendirmesinin grup çıktısı olur. Böyle bir durumda beklenen sonuç olur US.swmal@xyz.com.

Aşağıdaki görüntüde ikinci dönüştürme düzeyi örneği gösterilmektedir:

Screenshot of second level of claims transformation.

Aşağıdaki tabloda, ikinci dönüştürme düzeyi hakkında bilgi sağlanmaktadır. Tabloda listelenen eylemler önceki görüntüdeki etiketlere karşılık gelir.

Eylem Alan Açıklama
1 Transformation Regex tabanlı talep dönüştürmeleri ilk dönüşümle sınırlı değildir ve ikinci düzey dönüştürme olarak da kullanılabilir. Diğer tüm dönüştürme yöntemleri ilk dönüştürme olarak kullanılabilir.
2 Parameter 1 RegexReplace() ikinci düzey dönüştürme olarak seçilirse, ikinci düzey dönüştürme için giriş olarak birinci düzey dönüşümün çıktısı kullanılır. Dönüşümü uygulamak için ikinci düzey regex ifadesi ilk dönüşümün çıkışıyla eşleşmelidir.
3 Regex pattern Regex deseni , ikinci düzey dönüştürme için normal ifadedir.
4 Parameter input İkinci düzey dönüştürmeler için kullanıcı özniteliği girişleri.
5 Parameter input Yönetici istrator'lar, artık ihtiyaç duymamaları durumunda seçili giriş parametresini silebilir.
6 Replacement pattern Değiştirme düzeni, regex sonuç grubu adı, giriş parametre grubu adı ve statik metin değeri için yer tutucular içeren metin şablonudur. Tüm grup adları gibi {group-name}küme ayraçlarının içine sarmalanmalıdır. Yönetimin kullanıcı diğer adını başka bir etki alanı adıyla kullanmak istediğini varsayalım; örneğin xyz.com , ülke adını bu adla birleştirin. Bu durumda, değiştirme deseni {country}.{domain}@xyz.comolur; burada {country} giriş parametresinin değeri ve {domain} normal ifade değerlendirmesinin grup çıktısı olur. Böyle bir durumda beklenen sonuç olur US.swmal@xyz.com.
7 Test transformation RegexReplace() dönüşümü yalnızca Parametre 1 için seçilen kullanıcı özniteliğinin değeri Regex deseni metin kutusunda sağlanan normal ifadeyle eşleşiyorsa değerlendirilir. Eşleşmiyorsa, varsayılan talep değeri belirteci eklenir. Normal ifadeyi giriş parametresi değerine göre doğrulamak için, dönüştürme dikey penceresinde bir test deneyimi sağlanır. Bu test deneyimi yalnızca sahte değerler üzerinde çalışır. Daha fazla giriş parametresi kullanıldığında, parametrenin adı gerçek değer yerine test sonucuna eklenir. Test bölümüne erişmek için Test dönüştürme'yi seçin.

Aşağıdaki görüntüde dönüştürmeleri test etme örneği gösterilmektedir:

Screenshot of testing the transformation.

Aşağıdaki tabloda, dönüştürmeleri test etme hakkında bilgi sağlanmaktadır. Tabloda listelenen eylemler önceki görüntüdeki etiketlere karşılık gelir.

Eylem Alan Açıklama
1 Test transformation Test bölümünü gizlemek için kapat veya (X) düğmesini seçin ve dikey pencerede Test dönüştürme düğmesini yeniden işleyebilirsiniz.
2 Test regex input Normal ifade testi değerlendirmesi için kullanılan girişi kabul eder. Regex tabanlı talep dönüştürmesinin ikinci düzey dönüştürme olarak yapılandırılması durumunda, ilk dönüşümün beklenen çıkışı olan bir değer sağlayın.
3 Run test Test regex girişi sağlandıktan ve Regex deseni, Değiştirme deseni ve Giriş parametreleri yapılandırıldıktan sonra, ifade Testi çalıştır seçilerek değerlendirilebilir.
4 Test transformation result Değerlendirme başarılı olursa, Test dönüştürme sonucu etiketine karşı bir test dönüştürmesi çıkışı işlenir.
5 Remove transformation İkinci düzey dönüştürme, Dönüşümü kaldır seçilerek kaldırılabilir.
6 Specify output if no match Normal ifadeyle eşleşmeyen Parametre 1'de bir regex giriş değeri yapılandırıldığında dönüştürme atlanır. Bu gibi durumlarda alternatif kullanıcı özniteliği yapılandırılabilir. Bu öznitelik, eşleşme yoksa çıktıyı belirtin seçeneğini işaretleyerek talep belirtecine eklenebilir.
7 Parameter 3 Eşleşme olmadığında alternatif bir kullanıcı özniteliği döndürülmesi gerekiyorsa ve Eşleşme yoksa çıkışı belirtin işaretliyse , açılan liste kullanılarak alternatif bir kullanıcı özniteliği seçilebilir. Bu açılan menü Parametre 3'e göre kullanılabilir (eşleşme yoksa çıkış).
8 Summary Dikey pencerenin en altında, dönüştürmenin basit metindeki anlamını açıklayan biçimin tam özeti görüntülenir.
9 Add Dönüştürmenin yapılandırma ayarları doğrulandıktan sonra, Ekle'yi seçerek bir talep ilkesine kaydedilebilir. Değişiklikleri kaydetmek için Talebi Yönet dikey penceresinde Kaydet'i seçin.

RegexReplace() dönüşümü, grup talepleri dönüşümleri için de kullanılabilir.

Dönüştürme doğrulamaları

Test ekle veya çalıştır'ı seçtikten sonra aşağıdaki koşullar oluştuğunda ileti daha fazla bilgi sağlar:

  • Yinelenen kullanıcı özniteliklerine sahip giriş parametreleri kullanıldı.
  • Kullanılmayan giriş parametreleri bulundu. Tanımlı giriş parametreleri, Değiştirme deseni metninde ilgili kullanıma sahip olmalıdır.
  • Sağlanan test regex girişi, sağlanan normal ifadeyle eşleşmiyor.
  • Değiştirme düzenindeki gruplar için kaynak bulunamadı.

Talepleri koşullara göre yayma

Beyanın kaynağını kullanıcı türü ve kullanıcının ait olduğu grup temelinde belirtebilirsiniz.

Kullanıcı türü:

  • Tümü - Tüm kullanıcıların uygulamaya erişmesine izin verilir.
  • Üyeler: Kiracının yerel üyesi
  • Tüm konuklar: Kullanıcı, Microsoft Entra Kimliği olan veya olmayan bir dış kuruluştan taşındı.
  • Microsoft Entra konukları: Konuk kullanıcı, Microsoft Entra Kimliğini kullanan başka bir kuruluşa aittir.
  • Dış konuklar: Konuk kullanıcı, Microsoft Entra Kimliği olmayan bir dış kuruluşa aittir.

Kullanıcı türünün yararlı olduğu senaryolardan biri, bir talebin kaynağının bir uygulamaya erişen konuk ve çalışan için farklı olmasıdır. Kullanıcı bir çalışansa user.email NameID değerinin alınacağını belirtebilirsiniz. Kullanıcı bir konuksa, NameID user.extensionattribute1'den gelir.

Talep koşulu eklemek için:

  1. Talebi yönet bölümünde Talep koşullarını genişletin.
  2. Kullanıcı türünü seçin.
  3. Kullanıcının ait olması gereken grupları seçin. Belirli bir uygulama için tüm taleplerde en fazla 50 benzersiz grup seçebilirsiniz.
  4. Talebin değerini alacağı Kaynağı seçin. Kaynak öznitelik açılan listesinden bir kullanıcı özniteliği seçebilir veya bunu talep olarak yaymadan önce kullanıcı özniteliğine dönüştürme uygulayabilirsiniz.

Koşulları eklediğiniz sıra önemlidir. Microsoft Entra ilk olarak tüm koşulları kaynakla Attribute değerlendirir ve ardından talepte hangi değerin yayıldığına karar vermek için kaynak Transformation ile tüm koşulları değerlendirir. Microsoft Entra Id, yukarıdan aşağıya doğru aynı kaynağa sahip koşulları değerlendirir. Talep, talepteki ifadeyle eşleşen son değeri yayar. gibi IsNotEmpty dönüştürmeler ve Contains kısıtlamalar gibi davranır.

Örneğin, Britta Simon Contoso kiracısında bir konuk kullanıcıdır. Britta, Microsoft Entra Id kullanan başka bir kuruluşa aittir. Fabrikam uygulaması için aşağıdaki yapılandırma göz önüne alındığında, Britta Fabrikam'da oturum açmaya çalıştığında, Microsoft kimlik platformu koşulları değerlendirir.

İlk olarak, Microsoft kimlik platformu Britta'nın kullanıcı türünün Tüm konuklar olup olmadığını doğrular. Tür Tüm konuklar olduğundan, Microsoft kimlik platformu talebin kaynağını adresine user.extensionattribute1atar. İkincisi, Microsoft kimlik platformu Britta'nın kullanıcı türünün Microsoft Entra konukları olup olmadığını doğrular. Tür Tüm konuklar olduğundan, Microsoft kimlik platformu talebin kaynağını adresine user.mailatar. Son olarak, talep Britta için değeriyle user.mail birlikte yayılır.

Başka bir örnek olarak, Britta Simon aşağıdaki yapılandırmayı kullanarak oturum açmaya çalıştığında göz önünde bulundurun. Microsoft Entra ilk olarak kaynağıyla Attributetüm koşulları değerlendirir. Talebin kaynağı, user.mail Britta'nın kullanıcı türünün Microsoft Entra konukları olmasıdır. Ardından, Microsoft Entra ID dönüştürmeleri değerlendirir. Britta bir konuk olduğundan, user.extensionattribute1 talebin yeni kaynağıdır. Britta Microsoft Entra konuklarında olduğundan, user.othermail bu talebin yeni kaynağıdır. Son olarak, talep Britta için değeriyle user.othermail birlikte yayılır.

Son örnek olarak, Britta yapılandırılmamışsa user.othermail veya boşsa ne olacağını göz önünde bulundurun. Talep, her iki durumda da koşul girişini yoksaymaya geri döner user.extensionattribute1 .

Güvenlik konuları

Belirteçleri alan uygulamalar üzerinde oynanmayan talep değerlerine dayanır. Belirteç içeriğini talep özelleştirmesi aracılığıyla değiştirdiğinizde, bu varsayımlar artık doğru olmayabilir. Uygulamalar, belirteçlerin kendilerini kötü amaçlı aktörler tarafından oluşturulan özelleştirmelerden korumak için değiştirildiğini açıkça kabul etmelidir. Aşağıdaki yöntemlerden biriyle uygunsuz özelleştirmelerden koruyun:

Bu olmadan, Microsoft Entra Id bir AADSTS50146 hata kodu döndürür.

Özel imzalama anahtarı yapılandırma

Çok kiracılı uygulamalar için özel imzalama anahtarı kullanılmalıdır. Uygulama bildiriminde ayarlamayın acceptMappedClaims . Azure portalında bir uygulama ayarlarken kiracınızda bir uygulama kayıt nesnesi ve hizmet sorumlusu alırsınız. Bu uygulama, belirteçlerdeki talepleri özelleştirmek için kullanılamayan Azure genel oturum açma anahtarını kullanıyor. Belirteçlerde özel talepler almak için bir sertifikadan özel bir oturum açma anahtarı oluşturun ve bunu hizmet sorumlusuna ekleyin. Test amacıyla otomatik olarak imzalanan bir sertifika kullanabilirsiniz. Özel imzalama anahtarını yapılandırdıktan sonra uygulama kodunuzun belirteç imzalama anahtarını doğrulaması gerekir.

Hizmet sorumlusuna aşağıdaki bilgileri ekleyin:

  • Özel anahtar (anahtar kimlik bilgisi olarak)
  • Parola (parola kimlik bilgisi olarak)
  • Ortak anahtar (anahtar kimlik bilgisi olarak)

Sertifikanızın PFX dosya dışarı aktarmasından kodlanmış özel ve ortak anahtar base-64'leri ayıklayın. "Sign" için kullanılan için öğesinin keyCredential öğesinin ile eşleştiğinden passwordCredentialkeyId emin keyId olun. Sertifikanın customkeyIdentifier parmak izinin karması alınarak oluşturabilirsiniz.

İste

Not

Hizmet sorumlusunda PATCH gerçekleştirmeye çalışmadan önce microsoft Entra yönetim merkezi uygulama kayıtları dikey penceresinden yeni oluşturulan uygulamalarda hizmet sorumlusu kilit yapılandırmasını devre dışı bırakın ve bu da 400 Hatalı İstekle sonuçlanır.

Aşağıdaki örnekte, bir hizmet sorumlusuna özel imzalama anahtarı eklemek için HTTP PATCH isteğinin biçimi gösterilmektedir. Özelliğindeki keyCredentials "key" değeri okunabilirlik için kısaltılır. Değeri base-64 kodlanmış. Özel anahtar için özellik kullanımı şeklindedir Sign. Ortak anahtar için özellik kullanımı şeklindedir Verify.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/f47a6776-bca7-4f2e-bc6c-eec59d058e3e

Content-type: servicePrincipals/json
Authorization: Bearer {token}

{
    "keyCredentials":[
        {
            "customKeyIdentifier": "lY85bR8r6yWTW6jnciNEONwlVhDyiQjdVLgPDnkI5mA=", 
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "4c266507-3e74-4b91-aeba-18a25b450f6e",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "X509CertAndPassword",
            "usage": "Sign",
            "key":"MIIKIAIBAz.....HBgUrDgMCERE20nuTptI9MEFCh2Ih2jaaLZBZGeZBRFVNXeZmAAgIH0A==",
            "displayName": "CN=contoso"
        },
        {
            "customKeyIdentifier": "lY85bR8r6yWTW6jnciNEONwlVhDyiQjdVLgPDnkI5mA=",
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "e35a7d11-fef0-49ad-9f3e-aacbe0a42c42",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "MIIDJzCCAg+gAw......CTxQvJ/zN3bafeesMSueR83hlCSyg==",
            "displayName": "CN=contoso"
        }

    ],
    "passwordCredentials": [
        {
            "customKeyIdentifier": "lY85bR8r6yWTW6jnciNEONwlVhDyiQjdVLgPDnkI5mA=",
            "keyId": "4c266507-3e74-4b91-aeba-18a25b450f6e",
            "endDateTime": "2022-01-27T19:40:33Z",
            "startDateTime": "2020-04-20T19:40:33Z",
            "secretText": "mypassword"
        }
    ]
}

PowerShell kullanarak özel imzalama anahtarı yapılandırma

Bir MSAL Genel İstemci Uygulaması örneği oluşturmak için PowerShell'i kullanın ve Yetkilendirme Kodu Verme akışını kullanarak Microsoft Graph için temsilcili bir izin erişim belirteci alın. Microsoft Graph'ı çağırmak ve hizmet sorumlusu için özel bir imzalama anahtarı yapılandırmak için erişim belirtecini kullanın. Özel imzalama anahtarını yapılandırdıktan sonra uygulama kodunuzun belirteç imzalama anahtarını doğrulaması gerekir.

Bu betiği çalıştırmak için şunları yapmanız gerekir:

  • Azure portalındaki Kurumsal Uygulamalar'da uygulamanızın girişinin Genel Bakış dikey penceresinde bulunan uygulamanızın hizmet sorumlusunun nesne kimliği.
  • Bir kullanıcıda oturum açmak ve Microsoft Graph'ı çağırmak için erişim belirteci almak için bir uygulama kaydı. Azure portalındaki Uygulama kayıtları uygulama girişinin Genel Bakış dikey penceresinde bu uygulamanın uygulama (istemci) kimliğini alın. Uygulama kaydı aşağıdaki yapılandırmaya sahip olmalıdır:
    • "http://localhost" mobil ve masaüstü uygulamaları platform yapılandırmasında listelenir.
    • API izinlerinde Microsoft Graph, Application.ReadWrite.All ve User.Read izinlerini temsil etti (bu izinler için Yönetici onay verdiğinizden emin olun).
  • Microsoft Graph erişim belirtecini almak için oturum açan bir kullanıcı. Kullanıcı aşağıdaki Microsoft Entra yönetim rollerinden biri olmalıdır (hizmet sorumlusunu güncelleştirmek için gereklidir):
    • Bulut Uygulaması Yöneticisi
    • Uygulama Yöneticisi
    • Genel Yönetici
  • Uygulamamız için özel imzalama anahtarı olarak yapılandırılan bir sertifika. Otomatik olarak imzalanan bir sertifika oluşturabilir veya güvenilen sertifika yetkilinizden bir sertifika alabilirsiniz. Betikte aşağıdaki sertifika bileşenleri kullanılır:
    • ortak anahtar (genellikle bir .cer dosyası)
    • PKCS#12 biçiminde özel anahtar (.pfx dosyasında)
    • özel anahtar için parola (pfx dosyası)

Önemli

Microsoft Entra Id diğer biçim türlerini desteklemediğinden özel anahtar PKCS#12 biçiminde olmalıdır. Hizmet sorumlusuna sertifika bilgilerini içeren bir keyCredentials PATCH uygulamak için Microsoft Graph kullanılırken yanlış biçimin kullanılması "Geçersiz sertifika: Anahtar değeri geçersiz sertifika" hatasına neden olabilir.

$fqdn="fourthcoffeetest.onmicrosoft.com" # this is used for the 'issued to' and 'issued by' field of the certificate
$pwd="mypassword" # password for exporting the certificate private key
$location="C:\\temp" # path to folder where both the pfx and cer file will be written to

# Create a self-signed cert
$cert = New-SelfSignedCertificate -certstorelocation cert:\currentuser\my -DnsName $fqdn
$pwdSecure = ConvertTo-SecureString -String $pwd -Force -AsPlainText
$path = 'cert:\currentuser\my\' + $cert.Thumbprint
$cerFile = $location + "\\" + $fqdn + ".cer"
$pfxFile = $location + "\\" + $fqdn + ".pfx"
 
# Export the public and private keys
Export-PfxCertificate -cert $path -FilePath $pfxFile -Password $pwdSecure
Export-Certificate -cert $path -FilePath $cerFile

$ClientID = "<app-id>"
$loginURL       = "https://login.microsoftonline.com"
$tenantdomain   = "fourthcoffeetest.onmicrosoft.com"
$redirectURL = "http://localhost" # this reply URL is needed for PowerShell Core 
[string[]] $Scopes = "https://graph.microsoft.com/.default"
$pfxpath = $pfxFile # path to pfx file
$cerpath = $cerFile # path to cer file
$SPOID = "<service-principal-id>"
$graphuri = "https://graph.microsoft.com/v1.0/serviceprincipals/$SPOID"
$password = $pwd  # password for the pfx file
 
 
# choose the correct folder name for MSAL based on PowerShell version 5.1 (.Net) or PowerShell Core (.Net Core)
 
if ($PSVersionTable.PSVersion.Major -gt 5)
    { 
        $core = $true
        $foldername =  "netcoreapp2.1"
    }
else
    { 
        $core = $false
        $foldername = "net45"
    }
 
# Load the MSAL/microsoft.identity/client assembly -- needed once per PowerShell session
[System.Reflection.Assembly]::LoadFrom((Get-ChildItem C:/Users/<username>/.nuget/packages/microsoft.identity.client/4.32.1/lib/$foldername/Microsoft.Identity.Client.dll).fullname) | out-null
  
$global:app = $null
  
$ClientApplicationBuilder = [Microsoft.Identity.Client.PublicClientApplicationBuilder]::Create($ClientID)
[void]$ClientApplicationBuilder.WithAuthority($("$loginURL/$tenantdomain"))
[void]$ClientApplicationBuilder.WithRedirectUri($redirectURL)
 
$global:app = $ClientApplicationBuilder.Build()
  
Function Get-GraphAccessTokenFromMSAL {
    [Microsoft.Identity.Client.AuthenticationResult] $authResult  = $null
    $AquireTokenParameters = $global:app.AcquireTokenInteractive($Scopes)
    [IntPtr] $ParentWindow = [System.Diagnostics.Process]::GetCurrentProcess().MainWindowHandle
    if ($ParentWindow)
    {
        [void]$AquireTokenParameters.WithParentActivityOrWindow($ParentWindow)
    }
    try {
        $authResult = $AquireTokenParameters.ExecuteAsync().GetAwaiter().GetResult()
    }
    catch {
        $ErrorMessage = $_.Exception.Message
        Write-Host $ErrorMessage
    }
     
    return $authResult
}
  
$myvar = Get-GraphAccessTokenFromMSAL
if ($myvar)
{
    $GraphAccessToken = $myvar.AccessToken
    Write-Host "Access Token: " $myvar.AccessToken
    #$GraphAccessToken = "eyJ0eXAiOiJKV1QiL ... iPxstltKQ"
    
 
    #  this is for PowerShell Core
    $Secure_String_Pwd = ConvertTo-SecureString $password -AsPlainText -Force
 
    # reading certificate files and creating Certificate Object
    if ($core)
    {
        $pfx_cert = get-content $pfxpath -AsByteStream -Raw
        $cer_cert = get-content $cerpath -AsByteStream -Raw
        $cert = Get-PfxCertificate -FilePath $pfxpath -Password $Secure_String_Pwd
    }
    else
    {
        $pfx_cert = get-content $pfxpath -Encoding Byte
        $cer_cert = get-content $cerpath -Encoding Byte
        # Write-Host "Enter password for the pfx file..."
        # calling Get-PfxCertificate in PowerShell 5.1 prompts for password
        # $cert = Get-PfxCertificate -FilePath $pfxpath
        $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfxpath, $password)
    }
 
    # base 64 encode the private key and public key
    $base64pfx = [System.Convert]::ToBase64String($pfx_cert)
    $base64cer = [System.Convert]::ToBase64String($cer_cert)
 
    # getting id for the keyCredential object
    $guid1 = New-Guid
    $guid2 = New-Guid
 
    # get the custom key identifier from the certificate thumbprint:
    $hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
    $hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($cert.Thumbprint))
    $customKeyIdentifier = [System.Convert]::ToBase64String($hash)
 
    # get end date and start date for our keycredentials
    $endDateTime = ($cert.NotAfter).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
    $startDateTime = ($cert.NotBefore).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
 
    # building our json payload
    $object = [ordered]@{    
    keyCredentials = @(       
         [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid1
            startDateTime = $startDateTime 
            type = "X509CertAndPassword"
            usage = "Sign"
            key = $base64pfx
            displayName = "CN=fourthcoffeetest" 
        },
        [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid2
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Verify"
            key = $base64cer
            displayName = "CN=fourthcoffeetest"   
        }
        )  
    passwordCredentials = @(
        [ordered]@{
            customKeyIdentifier = $customKeyIdentifier
            keyId = $guid1           
            endDateTime = $endDateTime
            startDateTime = $startDateTime
            secretText = $password
        }
    )
    }
 
    $json = $object | ConvertTo-Json -Depth 99
    Write-Host "JSON Payload:"
    Write-Output $json
 
    # Request Header
    $Header = @{}
    $Header.Add("Authorization","Bearer $($GraphAccessToken)")
    $Header.Add("Content-Type","application/json")
 
    try 
    {
        Invoke-RestMethod -Uri $graphuri -Method "PATCH" -Headers $Header -Body $json
    } 
    catch 
    {
        # Dig into the exception to get the Response details.
        # Note that value__ is not a typo.
        Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__ 
        Write-Host "StatusDescription:" $_.Exception.Response.StatusDescription
    }
 
    Write-Host "Complete Request"
}
else
{
    Write-Host "Fail to get Access Token"
}

Belirteç imzalama anahtarını doğrulama

Talep eşlemesi etkin olan uygulamaların, OpenID Bağlan meta veri isteklerine ekleyerek appid={client_id} belirteç imzalama anahtarlarını doğrulamaları gerekir. Aşağıdaki örnek, kullanmanız gereken OpenID Bağlan meta veri belgesinin biçimini gösterir:

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

Uygulama bildirimini güncelleştirme

Tek kiracılı uygulamalar için özelliğini true uygulama bildiriminde olarak ayarlayabilirsinizacceptMappedClaims. Kaynak türünde belgelendiği apiApplication gibi. özelliğinin ayarlanması, bir uygulamanın özel imzalama anahtarı belirtmeden talep eşlemesini kullanmasına olanak tanır.

Uyarı

Çok kiracılı uygulamalar için acceptMappedClaims özelliğini true olarak ayarlamayın. Bu özellik, kötü niyetli aktörlerin uygulamanız için talep eşleme ilkeleri oluşturmasına olanak tanıyabilir.

İstenen belirteç hedef kitlesinin Microsoft Entra kiracınızın doğrulanmış bir etki alanı adını kullanması gerekir. Bu, örneğin veya (yalnızca varsayılan kiracı adını kullanarak) olarak ayarlamanız Application ID URI gerektiği anlamına gelir (uygulama bildiriminde ile gösteriliridentifierUris). https://contoso.onmicrosoft.com/my-apihttps://contoso.com/my-api

Doğrulanmış bir etki alanı kullanmıyorsanız, Microsoft Entra ID "_AcceptMappedClaims yalnızca uygulama GUID'si ile eşleşen bir belirteç hedef kitlesi veya kiracının doğrulanmış etki alanlarındaki bir hedef kitle için desteklenir" iletisini içeren bir AADSTS501461 hata kodu döndürür. Kaynak tanımlayıcısını değiştirin veya uygulamaya özgü bir imzalama anahtarı kullanın."

Gelişmiş talep seçenekleri

SAML belirteçleriyle aynı talebi ortaya çıkarmak için OIDC uygulamaları için gelişmiş talep seçeneklerini yapılandırın. Ayrıca hem SAML2.0 hem de OIDC yanıt belirteçleri için aynı talebi kullanmayı planlayan uygulamalar için.

Talepleri yönet dikey penceresindeki Gelişmiş Talep Seçenekleri'nin altındaki kutuyu işaretleyerek gelişmiş talep seçeneklerini yapılandırın.

Sonraki adımlar

  • Microsoft Entra Id'de kullanılan talepler ve belirteçler hakkında daha fazla bilgi edinin.