Share via

Bot Bağlan or API'siyle kimlik doğrulaması

  • Makale

Botunuz güvenli bir kanal (SSL/TLS) üzerinden HTTP kullanarak Bot Bağlan veya hizmetiyle iletişim kurar. Botunuz Bağlan veya hizmetine bir istek gönderdiğinde, Bağlan veya hizmetin kimliğini doğrulamak için kullanabileceği bilgileri içermesi gerekir. Benzer şekilde, Bağlan veya hizmeti botunuza bir istek gönderdiğinde, botunun kimliğini doğrulamak için kullanabileceği bilgileri içermelidir. Bu makalede, bot ile Bot Bağlan or hizmeti arasında gerçekleşen hizmet düzeyi kimlik doğrulaması için kimlik doğrulama teknolojileri ve gereksinimleri açıklanmaktadır. Kendi kimlik doğrulama kodunuzu yazıyorsanız botunuzun Bot Bağlan veya hizmetiyle ileti alışverişi yapmasını sağlamak için bu makalede açıklanan güvenlik yordamlarını uygulamanız gerekir.

Önemli

Kendi kimlik doğrulama kodunuzu yazıyorsanız, tüm güvenlik yordamlarını doğru bir şekilde uygulamanız kritik önem taşır. Bu makaledeki tüm adımları uygulayarak, bir saldırganın botunuza gönderilen iletileri okuyabilmesi, botunuzun kimliğine bürünen iletiler gönderebilmesi ve gizli anahtarlar çalması riskini azaltabilirsiniz.

Bot Framework SDK'sını kullanıyorsanız, SDK bunu sizin için otomatik olarak yaptığı için bu makalede açıklanan güvenlik yordamlarını uygulamanız gerekmez. Projenizi kayıt sırasında botunuz için aldığınız Uygulama Kimliği ve parolayla yapılandırmanız yeterlidir; sdk gerisini işler.

Kimlik doğrulama teknolojileri

Bot ile Bot Bağlan arasında güven oluşturmak için dört kimlik doğrulama teknolojisi kullanılır:

Teknoloji Açıklama
SSL/TLS SSL/TLS, tüm hizmet-hizmet bağlantıları için kullanılır. X.509v3 sertifikalar, tüm HTTPS hizmetlerinin kimliğini oluşturmak için kullanılır. İstemciler her zaman güvenilir ve geçerli olduklarından emin olmak için hizmet sertifikalarını incelemelidir. (İstemci sertifikaları bu düzenin bir parçası olarak KULLANıLMAZ.)
OAuth 2.0 OAuth 2.0, botların ileti göndermek için kullanabileceği güvenli bir belirteç oluşturmak için Microsoft Entra ID hesabı oturum açma hizmetini kullanır. Bu belirteç bir hizmet-hizmet belirtecidir; kullanıcı oturum açması gerekmez.
JSON Web Belirteci (JWT) JSON Web Belirteçleri, bota gönderilen ve bottan gönderilen belirteçleri kodlamak için kullanılır. İstemciler, bu makalede açıklanan gereksinimlere göre aldıkları tüm JWT belirteçlerini tam olarak doğrulamalıdır.
OpenID meta verileri Bot Bağlan or hizmeti, iyi bilinen, statik bir uç noktada OpenID meta verilerinde kendi JWT belirteçlerini imzalamak için kullandığı geçerli belirteçlerin listesini yayımlar.

Bu makalede, standart HTTPS ve JSON aracılığıyla bu teknolojilerin nasıl kullanılacağı açıklanmaktadır. Özel SDK'lar gerekli değildir, ancak OpenID ve diğerleri için yardımcıların yararlı olduğunu fark edebilirsiniz.

Botunuzdan Bot Bağlan veya hizmetine yönelik isteklerin kimliğini doğrulama

Bot Bağlan or hizmetiyle iletişim kurmak için, şu biçimi kullanarak her API isteğinin üst bilgisinde Authorization bir erişim belirteci belirtmeniz gerekir:

Authorization: Bearer ACCESS_TOKEN

Botunuz için bir JWT belirteci almak ve kullanmak için:

  1. Botunuz MSA Oturum Açma Hizmeti'ne bir GET HTTP isteği gönderir.
  2. Hizmetten gelen yanıt, kullanılacak JWT belirtecini içerir.
  3. Botunuz, Bot Bağlan veya hizmetine yönelik isteklerde yetkilendirme üst bilgisine bu JWT belirtecini içerir.

1. Adım: Microsoft Entra ID hesabı oturum açma hizmetinden erişim belirteci isteme

Önemli

Henüz yapmadıysanız AppID ve parolasını almak için botunuzu Bot Framework'e kaydetmeniz gerekir. Erişim belirteci istemek için bot uygulama kimliğine ve parolasına ihtiyacınız vardır.

Bot kimliğiniz Azure'da birkaç farklı yolla yönetilebilir.

  • Kullanıcı tarafından atanan yönetilen kimlik olarak bot kimlik bilgilerini kendiniz yönetmeniz gerekmez.
  • Tek kiracılı bir uygulama olarak.
  • Çok kiracılı bir uygulama olarak.

Botunuzun uygulama türüne göre bir erişim belirteci isteyin.

Oturum açma hizmetinden erişim belirteci istemek için aşağıdaki isteği gönderin ve MICROSOFT-APP-ID ve MICROSOFT-APP-PASSWORD yerine botunuzu Bot Hizmeti kaydettiğinizde elde ettiğiniz AppID ve parolayı yazın.

POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

2. Adım: Microsoft Entra ID hesabı oturum açma hizmeti yanıtından JWT belirtecini alma

Uygulamanız oturum açma hizmeti tarafından yetkilendirilmişse, JSON yanıt gövdesi erişim belirtecinizi, türünü ve süre sonunu (saniye olarak) belirtir.

Belirteci isteğin Authorization üst bilgisine eklerken, bu yanıtta belirtilen tam değeri kullanmanız gerekir; belirteç değerinden kaçmayın veya kodlamayın. Erişim belirteci süresi dolana kadar geçerlidir. Belirteç süre sonunun botunuzun performansını etkilemesini önlemek için belirteci önbelleğe almayı ve proaktif olarak yenilemeyi seçebilirsiniz.

Bu örnekte, Microsoft Entra ID hesabı oturum açma hizmetinden bir yanıt gösterilmektedir:

HTTP/1.1 200 OK
... (other headers)

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

3. Adım: İsteklerin Yetkilendirme üst bilgisinde JWT belirtecini belirtin

Bot Bağlan veya hizmetine bir API isteği gönderdiğinizde, şu biçimi kullanarak isteğin Authorization üst bilgisinde erişim belirtecini belirtin:

Authorization: Bearer ACCESS_TOKEN

Bot Bağlan veya hizmetine gönderdiğiniz tüm istekler üst bilgide erişim belirtecini Authorization içermelidir. Belirteç doğru biçimlendirilmişse, süresi dolmamışsa ve Microsoft Entra ID hesabı oturum açma hizmeti tarafından oluşturulduysa Bot Bağlan veya hizmeti isteği yetkilendirecektir. Belirtecin isteği gönderen bota ait olduğundan emin olmak için ek denetimler gerçekleştirilir.

Aşağıdaki örnek, isteğin üst bilgisinde Authorization erişim belirtecinin nasıl belirtileceğini gösterir.

POST https://smba.trafficmanager.net/teams/v3/conversations/12345/activities
Authorization: Bearer eyJhbGciOiJIUzI1Ni...

(JSON-serialized Activity message goes here)

Önemli

Yalnızca Bot Bağlan veya hizmetine gönderdiğiniz isteklerin üst bilgisinde Authorization JWT belirtecini belirtin. Belirteci güvenli olmayan kanallar üzerinden göndermeYIN ve diğer hizmetlere gönderdiğiniz HTTP isteklerine EKLEMEYİN. Microsoft Entra ID hesabı oturum açma hizmetinden aldığınız JWT belirteci bir parola gibidir ve çok dikkatli bir şekilde ele alınmalıdır. Belirteci sahip olan herkes botunuz adına işlem gerçekleştirmek için bu belirteci kullanabilir.

Bot-Bağlan or: örnek JWT bileşenleri

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "https://api.botframework.com",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  appid: "<YOUR MICROSOFT APP ID>",
  ... other fields follow
}

Dekont

Gerçek alanlar pratikte farklılık gösterebilir. Yukarıda belirtildiği gibi tüm JWT belirteçlerini oluşturun ve doğrulayın.

Bot Bağlan veya hizmetinden botunuza gelen isteklerin kimliğini doğrulama

Bot Bağlan veya hizmeti botunuza bir istek gönderdiğinde, isteğin Authorization üst bilgisinde imzalı bir JWT belirteci belirtir. Botunuz, imzalı JWT belirtecinin orijinalliğini doğrulayarak Bot Bağlan veya hizmetinden gelen çağrıların kimliğini doğrulayabilir.

Bot Bağlan veya hizmetinden gelen çağrıların kimliğini doğrulamak için:

  1. Botunuz, Bot Bağlan veya hizmetinden gönderilen isteklerde yetkilendirme üst bilgisinden JWT belirtecini alır.
  2. Botunuz, Bot Bağlan veya hizmeti için OpenID meta veri belgesini alır.
  3. Botunuz geçerli imzalama anahtarlarının listesini belgeden alır.
  4. Botunuz JWT belirtecinin orijinalliğini doğrular.

2. Adım: OpenID meta veri belgesini alma

OpenID meta veri belgesi, Bot Bağlan veya hizmetin geçerli imzalama anahtarlarını listeleyen ikinci bir belgenin konumunu belirtir. OpenID meta veri belgesini almak için https aracılığıyla bu isteği bildirin:

GET https://login.botframework.com/v1/.well-known/openidconfiguration

Bahşiş

Bu, uygulamanıza sabit kodlayabileceğiniz statik bir URL'dir.

Aşağıdaki örnekte, isteğe yanıt olarak GET döndürülen bir OpenID meta veri belgesi gösterilmektedir. özelliği, jwks_uri Bot Bağlan veya hizmetin geçerli imzalama anahtarlarını içeren belgenin konumunu belirtir.

{
    "issuer": "https://api.botframework.com",
    "authorization_endpoint": "https://invalid.botframework.com",
    "jwks_uri": "https://login.botframework.com/v1/.well-known/keys",
    "id_token_signing_alg_values_supported": [
      "RS256"
    ],
    "token_endpoint_auth_methods_supported": [
      "private_key_jwt"
    ]
}

3. Adım: Geçerli imzalama anahtarlarının listesini alma

Geçerli imzalama anahtarlarının listesini almak için, OpenID meta veri belgesinde özelliği tarafından jwks_uri belirtilen URL'ye HTTPS aracılığıyla bir GET istekte bulunun. Örneğin:

GET https://login.botframework.com/v1/.well-known/keys

Yanıt gövdesi belgeyi JWK biçiminde belirtir, ancak her anahtar için ek bir özellik de içerir: endorsements.

Bahşiş

Anahtarların listesi kararlıdır ve önbelleğe alınabilir, ancak istediğiniz zaman yeni anahtarlar eklenebilir. Bu anahtarlar kullanılmadan önce botunuzun belgenin güncel bir kopyasına sahip olduğundan emin olmak için tüm bot örneklerinin belgenin yerel önbelleğini en az 24 saatte bir yenilemesi gerekir.

Her anahtarın endorsements içindeki özellik, gelen isteğin Activity nesnesi içinde özelliğinde channelId belirtilen kanal kimliğinin orijinal olduğunu doğrulamak için kullanabileceğiniz bir veya daha fazla onay dizesi içerir. Onay gerektiren kanal kimliklerinin listesi her bot içinde yapılandırılabilir. Varsayılan olarak, bot geliştiricileri seçilen kanal kimliği değerlerini her iki şekilde de geçersiz kılabilir ancak bu, yayımlanan tüm kanal kimliklerinin listesi olacaktır.

4. Adım: JWT belirtecini doğrulama

Bot Bağlan or hizmeti tarafından gönderilen belirtecin orijinalliğini doğrulamak için, isteğin üst bilgisinden Authorization belirteci ayıklamanız, belirteci ayrıştırmanız, içeriğini doğrulamanız ve imzasını doğrulamanız gerekir.

JWT ayrıştırma kitaplıkları birçok platform için kullanılabilir ve çoğu JWT belirteçleri için güvenli ve güvenilir ayrıştırma uygular, ancak bu kitaplıkları genellikle belirtecin belirli özelliklerinin (veren, hedef kitle vb.) doğru değerler içermesini gerektirecek şekilde yapılandırmanız gerekir. Belirteci ayrıştırırken, ayrıştırma kitaplığını yapılandırmanız veya belirtecin şu gereksinimleri karşıladığından emin olmak için kendi doğrulamanızı yazmanız gerekir:

  1. Belirteç HTTP Authorization üst bilgisinde "Taşıyıcı" düzeniyle gönderildi.
  2. Belirteç, JWT standardına uyan geçerli bir JSON'dır.
  3. Belirteç, değerine https://api.botframework.comsahip bir "veren" talebi içerir.
  4. Belirteç, botunun Microsoft Uygulama Kimliği'ne eşit bir değere sahip bir "hedef kitle" talebi içerir.
  5. Belirteç geçerlilik süresi içindedir. Endüstri standardı saat dengesizliği 5 dakikadır.
  6. Belirtecin, 3. Adımda alınan OpenID anahtarları belgesinde, 2. Adımda alınan Açık Kimlik Meta Verileri belgesinin özelliğinde id_token_signing_alg_values_supported belirtilen imzalama algoritması kullanılarak listelenen anahtarla geçerli bir şifreleme imzası vardır.
  7. Belirteç, gelen isteğin Activity nesnesinin kökündeki serviceUrlözelliğiyle eşleşen değere sahip bir "serviceUrl" talebi içerir.

Kanal kimliği için onay gerekiyorsa:

  • Botunuza bu kanal kimliğiyle gönderilen tüm Activity nesnelerin, ilgili kanal için onay ile imzalanmış bir JWT belirteci ile birlikte gönderilmesini zorunlu kılarsınız.
  • Onay yoksa, botunuz http 403 (Yasak) durum kodu döndürerek isteği reddetmelidir.

Önemli

Bu gereksinimlerin tümü, özellikle 4. ve 6. gereksinimler önemlidir. Tüm bu doğrulama gereksinimlerinin uygulanmaması botu saldırılara açık bırakır ve bu da botun JWT belirtecini açığa çıkarmasına neden olabilir.

Uygulayıcılar, bota gönderilen JWT belirtecinin doğrulamasını devre dışı bırakmanın bir yolunu sunmamalıdır.

bota Bağlan: örnek JWT bileşenleri

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOU MICROSOFT APP ID>",
  iss: "https://api.botframework.com",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Dekont

Gerçek alanlar pratikte farklılık gösterebilir. Yukarıda belirtildiği gibi tüm JWT belirteçlerini oluşturun ve doğrulayın.

Bot Framework Öykünücüsü'nden botunuza gelen isteklerin kimliğini doğrulama

Bot Framework Emulator, botunuzun işlevselliğini test etmek için kullanabileceğiniz bir masaüstü aracıdır. Bot Framework Öykünücüsü yukarıda açıklandığı gibi aynı kimlik doğrulama teknolojilerini kullansa da, gerçek Bot Bağlan veya hizmetinin kimliğine bürünemez. Bunun yerine, Emulator'ı botunuza bağladığınızda belirttiğiniz Microsoft Uygulama Kimliği ve Microsoft Uygulama Parolası'nı kullanarak bot tarafından oluşturulan belirteçlerle aynı belirteçleri oluşturur. Öykünücü botunuza bir istek gönderdiğinde isteğin üst bilgisinde Authorization JWT belirtecini belirtir; temelde isteğin kimliğini doğrulamak için botun kendi kimlik bilgilerini kullanır.

Bir kimlik doğrulama kitaplığı uyguluyorsanız ve Bot Framework Öykünücüsü'nden gelen istekleri kabul etmek istiyorsanız, bu ek doğrulama yolunu eklemeniz gerekir. Yol yapısal olarak Bağlan or -> Bot doğrulama yoluna benzer, ancak Bot Bağlan or'un OpenID belgesi yerine MSA'nın OpenID belgesini kullanır.

Bot Framework Öykünücüsü'nden gelen çağrıların kimliğini doğrulamak için:

  1. Botunuz, Bot Framework Öykünücüsü'nden gönderilen isteklerde yetkilendirme üst bilgisinden JWT belirtecini alır.
  2. Botunuz, Bot Bağlan veya hizmeti için OpenID meta veri belgesini alır.
  3. Botunuz geçerli imzalama anahtarlarının listesini belgeden alır.
  4. Botunuz JWT belirtecinin orijinalliğini doğrular.

2. Adım: MSA OpenID meta veri belgesini alma

OpenID meta veri belgesi, geçerli imzalama anahtarlarını listeleyen ikinci bir belgenin konumunu belirtir. MSA OpenID meta veri belgesini almak için https aracılığıyla bu isteği bildirin:

GET https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Aşağıdaki örnekte, isteğe yanıt olarak GET döndürülen bir OpenID meta veri belgesi gösterilmektedir. jwks_uri özelliği, geçerli imzalama anahtarlarını içeren belgenin konumunu belirtir.

{
    "authorization_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
    "token_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/token",
    "token_endpoint_auth_methods_supported":["client_secret_post","private_key_jwt"],
    "jwks_uri":"https://login.microsoftonline.com/common/discovery/v2.0/keys",
    ...
}

3. Adım: Geçerli imzalama anahtarlarının listesini alma

Geçerli imzalama anahtarlarının listesini almak için, OpenID meta veri belgesinde özelliği tarafından jwks_uri belirtilen URL'ye HTTPS aracılığıyla bir GET istekte bulunun. Örneğin:

GET https://login.microsoftonline.com/common/discovery/v2.0/keys
Host: login.microsoftonline.com

Yanıt gövdesi, belgeyi JWK biçiminde belirtir.

4. Adım: JWT belirtecini doğrulama

Öykünücü tarafından gönderilen belirtecin orijinalliğini doğrulamak için, belirteci isteğin üst bilgisinden Authorization ayıklamanız, belirteci ayrıştırmanız, içeriğini doğrulamanız ve imzasını doğrulamanız gerekir.

JWT ayrıştırma kitaplıkları birçok platform için kullanılabilir ve çoğu JWT belirteçleri için güvenli ve güvenilir ayrıştırma uygular, ancak bu kitaplıkları genellikle belirtecin belirli özelliklerinin (veren, hedef kitle vb.) doğru değerler içermesini gerektirecek şekilde yapılandırmanız gerekir. Belirteci ayrıştırırken, ayrıştırma kitaplığını yapılandırmanız veya belirtecin şu gereksinimleri karşıladığından emin olmak için kendi doğrulamanızı yazmanız gerekir:

  1. Belirteç HTTP Authorization üst bilgisinde "Taşıyıcı" düzeniyle gönderildi.
  2. Belirteç, JWT standardına uyan geçerli bir JSON'dır.
  3. Belirteç, kamu dışı durumlar için vurgulanan değerlerden birine sahip bir "veren" talebi içerir. Her iki veren değerinin de denetlenmesi hem güvenlik protokolü v3.1 hem de v3.2 veren değerlerini denetlemenizi sağlar.
  4. Belirteç, botunun Microsoft Uygulama Kimliği'ne eşit bir değere sahip bir "hedef kitle" talebi içerir.
  5. Öykünücü, sürüme bağlı olarak AppId'yi appid talebi (sürüm 1) veya yetkili taraf talebi (sürüm 2) aracılığıyla gönderir.
  6. Belirteç geçerlilik süresi içindedir. Endüstri standardı saat dengesizliği 5 dakikadır.
  7. Belirtecin, 3. Adımda alınan OpenID anahtarları belgesinde listelenen anahtarı içeren geçerli bir şifreleme imzası vardır.

Dekont

Gereksinim 5, Öykünücü doğrulama yoluna özgüdür.

Belirteç bu gereksinimlerin tümünü karşılamıyorsa, botunuz http 403 (Yasak) durum kodu döndürerek isteği sonlandırmalıdır.

Önemli

Bu gereksinimlerin tümü, özellikle 4. ve 7. gereksinimler önemlidir. Tüm bu doğrulama gereksinimlerinin uygulanmaması botu saldırılara açık bırakır ve bu da botun JWT belirtecini açığa çıkarmasına neden olabilir.

Öykünücüden Bota: örnek JWT bileşenleri

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOUR MICROSOFT APP ID>",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Dekont

Gerçek alanlar pratikte farklılık gösterebilir. Yukarıda belirtildiği gibi tüm JWT belirteçlerini oluşturun ve doğrulayın.

Güvenlik protokolü değişiklikleri

Bot-Bağlan veya kimlik doğrulaması

OAuth oturum açma URL'si

Protokol sürümü Geçerli değer
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth kapsamı

Protokol sürümü Geçerli değer
v3.1 & v3.2 https://api.botframework.com/.default

Bot kimlik doğrulamasına Bağlan

OpenID meta veri belgesi

Protokol sürümü Geçerli değer
v3.1 & v3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

JWT Veren

Protokol sürümü Geçerli değer
v3.1 & v3.2 https://api.botframework.com

Öykünücüden Bota kimlik doğrulaması

OAuth oturum açma URL'si

Protokol sürümü Geçerli değer
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth kapsamı

Protokol sürümü Geçerli değer
v3.1 & v3.2 Botunuzun Microsoft Uygulama Kimliği + /.default

JWT Hedef Kitlesi

Protokol sürümü Geçerli değer
v3.1 & v3.2 Botunuzun Microsoft Uygulama Kimliği

JWT Veren

Protokol sürümü Geçerli değer
v3.1 1.0 https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/
v3.1 2.0 https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0
v3.2 1.0 https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/
v3.2 2.0 https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0

Ayrıca resmi olmayan vakalar için vurgulanan değerlere de bakın.

OpenID meta veri belgesi

Protokol sürümü Geçerli değer
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Ek kaynaklar