Nasıl yapılır: OAuth WRAP Protokolü aracılığıyla ACS'den Belirteç İsteme
Uygulanan Öğe
- Microsoft Azure Active Directory Access Control (Access Control Hizmeti veya ACS olarak da bilinir)
Genel Bakış
Web uygulamalarınız ve hizmetleriniz ACS kullanarak kimlik doğrulamasını işlediğinde, istemcinin uygulamanızda veya hizmetinizde oturum açmak için ACS tarafından verilen bir güvenlik belirteci alması gerekir. Bu ACS tarafından verilen belirteci (çıkış belirteci) almak için istemcinin acs ile doğrudan kimlik doğrulaması yapması veya ACS'ye kimlik sağlayıcısı (giriş belirteci) tarafından verilen bir güvenlik belirteci göndermesi gerekir. ACS bu giriş güvenlik belirtecini doğrular, BU belirteçteki kimlik taleplerini ACS kural altyapısı aracılığıyla işler, çıkış kimliği taleplerini hesaplar ve bir çıkış güvenlik belirteci verir.
Bu konuda, OAuth WRAP protokolü aracılığıyla ACS'den belirteç isteme yöntemleri açıklanmaktadır. OAuth WRAP protokolü aracılığıyla yapılan tüm belirteç istekleri SSL üzerinden iletilir. ACS, doğru biçimlendirilmiş bir belirteç isteğine yanıt olarak her zaman OAuth WRAP protokolü aracılığıyla basit bir Web Belirteci (SWT) verir. OAuth WRAP protokolü aracılığıyla yapılan tüm belirteç istekleri BIR HTTP POST'ta ACS'ye gönderilir. HTTPS FORM POST yapabilen herhangi bir platformdan OAuth WRAP protokolü aracılığıyla ACS belirteci isteyebilirsiniz: .NET Framework, Windows Communication Foundation (WCF), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash ve diğer platformlar.
Aşağıdaki tabloda, OAuth WRAP protokolü aracılığıyla ACS tarafından verilen bir SWT belirteci istemek için desteklenen üç yöntem listelenmektedir.
OAuth WRAP protokolü aracılığıyla ACS'den belirteç istemenin üç yöntemi
Belirteç isteği yöntemi | Description |
---|---|
Parola belirteci istekleri |
Bu en basit yöntem, istemcinin kimlik doğrulaması için OAuth WRAP protokolü aracılığıyla bir hizmet kimliğinden doğrudan ACS'ye kullanıcı adı ve parola göndermesini gerektirir. |
SWT belirteci istekleri |
Bu yöntem, istemcinin kimlik doğrulaması için OAuth WRAP protokolü aracılığıyla ACS'ye hizmet kimliği simetrik anahtarı veya kimlik sağlayıcısı simetrik anahtarıyla imzalanabilen bir SWT belirteci göndermesini gerektirir. |
SAML belirteci istekleri |
Öncelikli olarak Active Directory Federasyon Hizmeti (AD FS) 2.0 tümleştirmesi için tasarlanan Güvenlik Onaylama İşaretleme Dili (SAML) yöntemi, istemcinin kimlik doğrulaması için OAuth WRAP protokolü aracılığıyla ACS'ye imzalı bir SAML belirteci göndermesini gerektirir. Bu yaklaşım, istemcinin ACS ile kimlik doğrulaması yapmak için kurumsal kimlik kullanmasına olanak tanır. |
Belirteç veren uç nokta
OAuth WRAP protokolü aracılığıyla yapılan tüm ACS belirteç istekleri, ACS belirteci veren bir uç noktaya yönlendirilir. Bu uç noktanın URI'si Access Control ad alanına bağlıdır. Ad alanı, belirteç isteği URI'sinde DNS adı ön eki olarak görünür. DNS adının geri kalanı, yol gibi sabittir. Örneğin, Access Control ad alanından "mysnservice" adlı bir belirteç istemek istiyorsanız, belirteç isteğini şu URI'ye yönlendirebilirsiniz: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.
Parola belirteci istekleri
Parola belirteci isteğiyle istemci, kimlik doğrulaması için OAuth WRAP protokolü aracılığıyla bir hizmet kimliğinden doğrudan ACS'ye kullanıcı adı ve parola gönderebilir. Bu, OAuth WRAP protokolunu kullanarak ACS'den belirteç istemenin en kolay yoludur. SSL bağlantısı kurmanın dışında, bu yaklaşım şifreleme özelliği gerektirmez. Uygulamada, REST Web hizmetlerinde yaygın olarak bulunan kullanıcı adı/parola modeline benzer. Bu belirteç isteği türü aslında BIR HTTPS formu POST'tür. Parola belirteci isteğindeki parametreler form olarak kodlanmıştır.
Aşağıda, "mysnservice" adlı ad alanına düz metin isteğinin kablo izlemesi örneği verilmiştir.
POST /WRAPv0.9/ HTTP/1.1
Host: mysnservice.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded
wrap_scope=http%3A%2F%2Fmysnservice.com%2Fservices%2F&
wrap_name=mysncustomer1&
wrap_password=5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ%3D
Aşağıdaki tabloda, parola belirteci isteğinde bulunması gereken parametrelerin adları, açıklamaları ve değer gereksinimleri sağlanır:
Parametre adı | Açıklama | Değer gereksinimleri |
---|---|---|
wrap_scope |
Belirteç isteğini bir dizi kuralla eşleştirir. Bu parametrenin değerini bağlı olan taraf uygulama alanının değerine ayarlayın. Bağlı Olan Taraf Uygulamaları sayfasından uygun bağlı olan taraf uygulamasını seçerek bu değeri (Bölge alanında) ACS Yönetim Portalı aracılığıyla alabilirsiniz. |
|
wrap_name |
Sonraki parametrenin anahtarını doğrular. Bu parametrenin değerini Access Control ad alanınızdaki bir hizmet kimliğinin adına ayarlayın. Hizmet Kimlikleri sayfasından uygun hizmet kimliğini seçerek ACS Yönetim Portalı aracılığıyla bu değeri (Ad alanında) alabilirsiniz. |
|
wrap_password |
Gelen isteğin kimliğini doğrular. Bu parametrenin değerini, Access Control ad alanınızdaki bir hizmet kimliğinin parolası olarak ayarlayın. Bu değeri (Kimlik Bilgilerini Düzenle sayfasındaki Parola alanında), ACS Yönetim Portalı aracılığıyla, önce Hizmet Kimlikleri sayfasında uygun hizmet kimliğini ve ardından Hizmet Kimliğini Düzenle sayfasındaki Kimlik Bilgileri tablosunda uygun parolayı seçerek elde edebilirsiniz. |
|
İsteği ACS'ye göndermeden önce bu parametrelerin değerleri URL ile kodlanmış olmalıdır. Web uygulamanız veya hizmetiniz wrap_scope değerini istemciye sağlayabilir veya istemci wrap_scope parametresinin değerini web uygulamasının veya hizmet kaynak hedefinin URI'sine ayarlamaya karar verebilir.
OAuth WRAP protokolü aracılığıyla yapılan parola belirteci istekleri, ACS'nin çıkış talebi hesaplama işlemi sırasında kullanabileceği ek parametreler de içerebilir. Bu ek parametre adları ve değerleri URL ile kodlanmış olmalı ve değerler tırnak içine alınmamalıdır.
Parola belirteci istek yöntemi kullanılarak oldukça basittir.
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");
// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);
// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);
Çıkış belirtecini ACS'den çıkarma ve web uygulamasına veya hizmetine gönderme hakkında bilgi için bkz. Belirteci kaldırma ve bir web uygulamasına veya hizmetine gönderme.
SWT belirteci istekleri
Ayrıca simetrik anahtar tarafından imzalanan bir SWT belirteci kullanarak OAuth WRAP protokolü aracılığıyla ACS'den belirteç isteyebilirsiniz. Tüm SWT belirteci istekleri BIR HTTPS formu POST aracılığıyla yapılır. Bu belirteç isteği yöntemindeki parametre değerleri form kodlamalı.
Aşağıda, "mysnservice" ad alanına yönelik BIR SWT belirteci isteğinin kablo izlemesi örneği verilmiştir.
POST /WRAPv0.9/ HTTP/1.1
Host: mysnservice.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded
wrap_scope=http%3A%2F%2Fmysnservice.com%2Fservices%2F&
wrap_assertion_format=SWT&
wrap_assertion=Issuer%3dmysncustomer1%26HMACSHA256%3db%252f%252bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%253d
SWT belirteci isteği aşağıdaki parametrelere ve değerlere sahip olmalıdır:
Parametre adı | Açıklama | Değer gereksinimleri |
---|---|---|
wrap_scope |
Belirteç isteğini bir dizi kuralla eşleştirir. |
|
wrap_assertion |
Bu, ACS'ye gönderilen giriş belirtecidir. |
|
wrap_assertion_format |
Bu, ACS'ye gönderilen giriş belirtecinin biçimidir. |
SWT |
Aşağıdaki örnekte gösterildiği gibi, SWT belirteci isteğinde bulunmak için gereken kod, parola belirteci isteğinde bulunmak için gereken koda benzer.
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
NameValueCollection values = new NameValueCollection();
// add the wrap_scope
values.Add("wrap_scope", "http://mysnservice.com/services");
// add the format
values.Add("wrap_assertion_format", "SWT");
// add the SWT
values.Add("wrap_assertion", "Issuer=mysncustomer1&HMACSHA256=b%2f%2bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%3d");
// WebClient takes care of the remaining URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);
// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);
Yanıtı ACS'den açma ve web uygulamanıza veya hizmetinize gönderme hakkında bilgi için bkz. Belirteci kaldırma ve bir web uygulamasına veya hizmetine gönderme.
SWT belirteci oluşturma
SWT belirteci, veren anahtarla (simetrik anahtar) imzalanan bir dizi anahtar/değer çiftidir. BIR SWT belirteci isteğinde ACS'ye gönderilen bir SWT belirteci, Veren ve HMACSHA256 parametrelerinin yanı sıra ExpiresOn, Audience ve istemciye özgü diğer talepler gibi ek parametreleri içermelidir. Aşağıdaki tabloda SWT belirteci parametrelerinin adları ve açıklamaları sağlanır:
Parametre adı | Açıklama |
---|---|
Veren |
ACS'de belirteci imzalamak için kullanılan anahtarı arar. İmza geçerliyse, bu değer çıkış talebi hesaplaması yapmak için kullanılır. Bu parametreyi, Access Control ad alanınızdaki bir kimlik sağlayıcısının alanının değerine veya Access Control ad alanınızdaki bir hizmet kimliğinin adına ayarlayabilirsiniz. Bu değeri (Kimlik Sağlayıcısını Düzenle sayfasındaki Bölge alanında) ACS Yönetim Portalı aracılığıyla, Kimlik Sağlayıcıları sayfasında uygun kimlik sağlayıcısını seçerek elde edebilirsiniz. Bu değeri ACS Yönetim Hizmeti aracılığıyla da alabilirsiniz. Bu, her kimlik sağlayıcısı için oluşturulan "Veren" kaydının ad özelliğidir. |
HMACSHA256 |
ACS'de SWT imzasını doğrular ve Veren parametresinde adlı veren anahtarını arar. SWT imzası, bir hizmet kimliğine veya Access Control ad alanınızdaki bir kimlik sağlayıcısına eklenmiş simetrik imzalama anahtarı kullanılarak oluşturulur. |
Hedef kitle |
Varsa, ACS, SWT belirtecinin hedeflenen hedefinin ACS olduğundan emin olmak için bu değeri kullanır. Bu, Access Control ad alanınızın URL'sidir, örneğin,https://contoso.accesscontrol.windows.net/ |
ExpiresOn |
Varsa (Dönem içinde), belirtecin süresinin dolup dolmadığını gösterir. Örneğin, bu parametrenin değeri olabilir |
Ek talepler |
Varsa, ACS çıkış talebi hesaplaması yapmak için bu parametreleri kullanır. Her talep türü yalnızca bir kez görünmelidir. Aynı talep türündeki birden çok talep değeri bir "," (virgül) karakteriyle birleştirilmelidir. ACS'de talepleri onaylama hakkında daha fazla bilgi için bkz. OAuth WRAP protokolü aracılığıyla talep onaylama. |
Aşağıdaki kod örneğinde kullanarak swt belirtecinin nasıl oluşturulacağı gösterilmektedir. Veren ve HMACSHA256 parametrelerini içeren SWT belirteçleri oluşturan bir tür içerir.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Web;
public class TokenFactory
{
string signingKey;
string issuer;
public TokenFactory(string issuer, string signingKey)
{
this.issuer = issuer;
this.signingKey = signingKey;
}
public string CreateToken()
{
StringBuilder builder = new StringBuilder();
// add the issuer name
builder.Append("Issuer=");
builder.Append(HttpUtility.UrlEncode(this.issuer));
string signature = this.GenerateSignature(builder.ToString(), this.signingKey);
builder.Append("&HMACSHA256=");
builder.Append(signature);
return builder.ToString();
}
private string GenerateSignature(string unsignedToken, string signingKey)
{
HMACSHA256 hmac = new HMACSHA256(Convert.FromBase64String(signingKey));
byte[] locallyGeneratedSignatureInBytes = hmac.ComputeHash(Encoding.ASCII.GetBytes(unsignedToken));
string locallyGeneratedSignature = HttpUtility.UrlEncode(Convert.ToBase64String(locallyGeneratedSignatureInBytes));
return locallyGeneratedSignature;
}
}
SAML belirteci istekleri
SAML belirteci istek yöntemi temel olarak AD FS 2.0 tümleştirmesine yöneliktir ve istemcinin ACS ile kimlik doğrulaması yapmak için bir kurumsal kimlik (Active Directory) kullanmasına izin verir. SAML belirteci istek yöntemiyle, OAuth WRAP protokolü aracılığıyla ACS'ye AD FS 2.0 (giriş belirteci) tarafından verilen imzalı bir SAML 1.1 veya SAML 2.0 belirteci gönderebilirsiniz.
ACS, çıkış taleplerini hesaplamak, bunları bir SWT belirteci (çıkış belirteci) olarak gruplandırmak, imzalar ve OAuth WRAP protokolü aracılığıyla istemciye döndürmek için kurallarını kullanır.
SAML belirteci isteği aşağıdaki parametrelere ve değerlere sahip olmalıdır:
Parametre adı | Açıklama | Değer gereksinimleri |
---|---|---|
wrap_scope |
Belirteç isteğiyle bir dizi kuralla eşleşir. |
|
wrap_assertion |
Bu, ACS'ye gönderilen giriş belirtecidir. |
|
wrap_assertion_format |
Bu, ACS'ye gönderilen giriş belirtecinin biçimidir. |
SAML |
Aşağıda, SAML belirteci isteğinde bulunmak için gereken kodun bir örneği verilmiştir.
private static string SendSAMLTokenToACS(string samlToken)
{
try
{
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
NameValueCollection parameters = new NameValueCollection();
parameters.Add("wrap_assertion_format", "SAML");
parameters.Add("wrap_assertion", samlToken);
parameters.Add("wrap_scope", "http://mysnservice.com/services");
byte[] responseBytes = client.UploadValues("WRAPv0.9", parameters);
string response = Encoding.UTF8.GetString(responseBytes);
return response
.Split('&')
.Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase))
.Split('=')[1];
}
catch (WebException wex)
{
string value = new StreamReader(wex.Response.GetResponseStream()).ReadToEnd();
throw;
}
}
Yanıtı ACS'den açma ve web uygulamanıza veya hizmetinize gönderme hakkında bilgi için bkz. Belirteci kaldırma ve bir web uygulamasına veya hizmetine gönderme.
OAuth WRAP protokolü aracılığıyla talep onaylama
ACS 1.0 belirteç isteği davranışıyla geriye dönük uyumluluğu etkinleştirmek için ACS, belirteç isteklerinin bir parçası olarak talepleri onaylama özelliğini destekler.
Onaylayan uygulamayı veya hizmeti ACS kimlik sağlayıcısı olarak kaydedin.
Bunu yapmak için önerilen yol, onaylayan uygulamayı veya hizmeti ACS kimlik sağlayıcısı olarak kaydetmektir. Ardından uygulama veya hizmet, doğrulamak istediği talepleri içeren bir SAML veya SWT belirteci sunarak ACS'den bir belirteç ister ve bu belirteç ACS'de depolanan bir Kimlik Sağlayıcısı Anahtarı kullanılarak imzalanır. Örneğin, AD FS 2.0'dan OAuth WRAP protokolü aracılığıyla veya Windows Identity Foundation (WIF) kullanılarak oluşturulan ve ACS'ye WS-Federation kimlik sağlayıcısı olarak kaydedilen herhangi bir özel Güvenlik Belirteci Hizmeti 'nden (STS) ACS'ye onaylanan taleplerle bir SAML belirteç isteği gönderebilirsiniz.
WS-Federation meta verileri kullanarak bir kimlik sağlayıcısını kaydetmek için ACS Yönetim Portalı'nı veya kimlik sağlayıcısı özelliklerini, adreslerini ve anahtarlarını ayrı ayrı ayarlamak için ACS Yönetim Hizmeti'ni kullanabilirsiniz. (Örneğin, bkz. Nasıl yapılır: AD FS 2.0'ı Enterprise Kimlik Sağlayıcısı olarak yapılandırmak için ACS Yönetim Hizmeti'ni kullanma.) Belirteç isteğinde talepleri onaylamanın bu yönteminde hizmet kimlikleri gerekmez. Bu yöntem, ACS tarafından desteklenen tüm protokoller aracılığıyla çalışır.
Belirteci kaldırma ve bir web uygulamasına veya hizmetine gönderme
Belirteç isteğinin kimliği başarıyla doğrulanırsa, ACS form kodlamalı iki parametre döndürür: wrap_token ve wrap_token_expires_in. Bu parametrelerin değerleri, istemcinin web uygulamanıza veya hizmetinize erişim elde etmek için kullanabileceği gerçek SWT belirteci ve bu belirtecin yaklaşık kalan ömrü (saniye olarak).
SWT belirtecini web uygulamasına veya hizmetine göndermeden önce istemcinin ACS yanıtından ayıklaması ve URL kodunu çözmesi gerekir. Web uygulaması veya hizmeti belirtecin HTTP Authorization
üst bilgisinde sunulmasını gerektiriyorsa, belirtecin önünde düzeni WRAPv0.9
bulunmalıdır.
Aşağıdaki kod örneğinde bir belirtecin nasıl paketten çıkarılıp üst bilgi biçimlendirilir gösterilmektedir Authorization
.
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");
// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);
// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);
string token = response
.Split('&')
.Single(value => value.StartsWith("wrap_token=", StringComparison.OrdinalIgnoreCase))
.Split('=')[1];
string.Format("WRAP access_token=\"{0}\"", HttpUtility.UrlDecode(token));
ACS Hata Kodları ve Açıklamaları
ACS, belirteç isteğini karşılayamadığında hatalar döndürür. REST tasarımına uygun olarak, hata bir HTTP yanıt kodu içerir. Çoğu durumda ACS hataları, başarısız olanlarla ilgili bağlam sağlayan bir SubCode
ve Detail
de içerir. Hata biçimi: Error:Code:<httpStatus>:Sub-Code:<code>:D etail:<message>. Hatanın Content-Type
değeri her zaman metin/düzdür.
HTTP/1.1 401 Access Forbidden
Content-Type: text/plain; charset=us-ascii
Error:Code:401:SubCode:T0:Detail:ACS50009: SWT token is invalid. :TraceID:<trace id value>:TimeStamp:<timestamp value>
ACS hata kodları hakkında daha fazla bilgi için bkz. ACS Hata Kodları.
ACS'den döndürülen bir hatada hata ayıklama veya kurtarma yaparken genellikle yanıt gövdesini okumak gerekir. Aşağıdaki kod örneği, bir WebException nesnesinden hata iletisinin nasıl okunmasını gösterir.
try
{
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");
// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);
// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);
string token = response
.Split('&')
.Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase))
.Split('=')[1];
}
catch (WebException wex)
{
if (wex.Response != null)
{
// the response Stream contains the error message
StreamReader reader = new StreamReader(wex.Response.GetResponseStream());
string message = reader.ReadToEnd();
}
// Throw as appropriate
}