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

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.

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:

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

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.

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

POST https://login.microsoftonline.com/MICROSOFT-TENANT-ID/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)

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
}

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

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.

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.

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
}

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.

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

Ö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
}

Güvenlik protokolü değişiklikleri

Bot-Bağlan veya kimlik doğrulaması

OAuth oturum açma URL'si

OAuth kapsamı

Bot kimlik doğrulamasına Bağlan

OpenID meta veri belgesi

JWT Veren

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

OAuth oturum açma URL'si

OAuth kapsamı

JWT Hedef Kitlesi

JWT Veren

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

OpenID meta veri belgesi

Ek kaynaklar

• Bot Framework kimlik doğrulaması sorunlarını giderme
• Bot Framework Etkinlik şeması
• JSON Web Belirteci (JWT) draft-jones-json-web-token-07
• JSON Web İmzası (JWS) draft-jones-json-web-signature-04
• JSON Web Anahtarı (JWK) RFC 7517