Web uygulaması oluşturmak için Azure DevOps OAuth 2.0 kullanma
Azure DevOps Services
Önemli
Bu bilgiler yalnızca mevcut Azure DevOps OAuth uygulamalarına yöneliktir. Yeni uygulama geliştiricileri, Azure DevOps ile tümleştirmek için Microsoft Entra ID OAuth kullanmalıdır.
Azure DevOps, OAuth 2.0 uygulamaları için bir kimlik sağlayıcısıdır. OAuth 2.0 uygulamamız, geliştiricilerin uygulamalarını kullanıcılar için yetkilendirmesine ve Azure DevOps kaynakları için erişim belirteçleri almasına olanak tanır.
Azure DevOps OAuth'u kullanmaya başlama
1. Uygulamanızı kaydetme
Uygulamanızı kaydetmek için adresine
https://app.vsaex.visualstudio.com/app/register
gidin.Uygulamanızın ihtiyaç duyduğu kapsamları seçin ve uygulamanızı yetkilerken aynı kapsamları kullanın. Uygulamanızı önizleme API'lerini kullanarak kaydettiyseniz, kullandığınız kapsamlar artık kullanım dışı olduğundan yeniden kaydedin.
Uygulama oluştur'u seçin.
Uygulama ayarları sayfası görüntülenir.
Azure DevOps Services yetkilendirme onay sayfasını kullanıcınıza sunduğunda şirketinizin adını, uygulama adını ve açıklamalarını kullanır. Ayrıca şirketinizin web sitesi, uygulama web sitesi ve hizmet koşulları ile gizlilik bildirimleri için URL'leri kullanır.
Azure DevOps Services bir kullanıcının yetkilendirmesini istediğinde ve kullanıcı bunu onayladığında, kullanıcının tarayıcısı yetkilendirme koduyla yetkilendirme geri çağırma URL'nize yönlendirilir. Kodu uygulamaya geri aktarmak ve uygulamanızda kayıtlı URL ile tam olarak eşleştirmek için geri arama URL'si güvenli bir bağlantı (https) olmalıdır. Aksi takdirde, kullanıcıdan uygulamanıza yetkilendirme vermesini isteyen bir sayfa yerine 400 hata sayfası görüntülenir.
Bir kullanıcının uygulamanızı kuruluşuna erişmesi için yetkilendirmesini istediğinizde yetkilendirme URL'sini çağırın ve uygulama kimliğinizi ve yetkili kapsamlarınızı geçirin. Azure DevOps Services REST API'sini çağırmak için erişim belirteci almak istediğinizde erişim belirteci URL'sini çağırın.
Kaydettiğiniz her uygulamanın ayarlarına profilinizden https://app.vssps.visualstudio.com/profile/view
ulaşabilirsiniz.
2. Uygulamanızı yetkilendirme
- Kullanıcınız uygulamanıza kuruluşuna erişim yetkisi vermemişse yetkilendirme URL'sini çağırın. Kullanıcı yetkilendirmeyi onaylarsa sizi bir yetkilendirme koduyla geri çağırır.
https://app.vssps.visualstudio.com/oauth2/authorize
?client_id={app ID}
&response_type={Assertion}
&state={state}
&scope={scope}
&redirect_uri={callback URL}
Parametre | Türü | Notlar |
---|---|---|
client_id | GUID | Kayıtlıyken uygulamanıza atanan kimlik. |
response_type | Dize | Assertion |
semt | Dize | Herhangi bir değer olabilir. Genellikle, geri çağırmayı ilişkili yetkilendirme isteğiyle ilişkilendiren oluşturulan bir dize değeridir. |
kapsam | Dize | Uygulamayla kaydedilen kapsamlar. Boşlukla ayrılmış. Kullanılabilir kapsamlara bakın. |
redirect_uri | URL | Uygulamanız için geri arama URL'si. Uygulamayla kaydedilen URL ile tam olarak eşleşmelidir. |
- Kullanıcıyı Azure DevOps Services yetkilendirme uç noktasına götüren bir bağlantı veya düğme ekleyin:
https://app.vssps.visualstudio.com/oauth2/authorize
?client_id=88e2dd5f-4e34-45c6-a75d-524eb2a0399e
&response_type=Assertion
&state=User1
&scope=vso.work%20vso.code_write
&redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback
Azure DevOps Services, kullanıcıdan uygulamanızı yetkilendirmesini ister.
Kullanıcının kabul ettigini varsayarsak Azure DevOps Services, kısa süreli yetkilendirme kodu ve yetkilendirme URL'sinde sağlanan durum değeri de dahil olmak üzere kullanıcının tarayıcısını geri çağırma URL'nize yönlendirir:
https://fabrikam.azurewebsites.net/myapp/oauth-callback
?code={authorization code}
&state=User1
3. Kullanıcı için erişim ve yenileme belirteci alma
Kullanıcı için erişim belirteci (ve yenileme belirteci) istemek için yetkilendirme kodunu kullanın. Hizmetinizin Azure DevOps Services'e hizmet-hizmet HTTP isteğinde bulunması gerekir.
URL - uygulamayı yetkilendirme
POST https://app.vssps.visualstudio.com/oauth2/token
HTTP isteği üst bilgileri - uygulamayı yetkilendirme
Üst bilgi | Değer |
---|---|
İçerik Türü | application/x-www-form-urlencoded |
Content-Type: application/x-www-form-urlencoded
HTTP isteği gövdesi - uygulamayı yetkilendirme
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}
Önceki örnek istek gövdesindeki yer tutucu değerlerini değiştirin:
- {0}: Uygulama kaydedildiğinde alınan URL kodlanmış istemci gizli dizisi
- {1}: Sorgu parametresi aracılığıyla
code
geri çağırma URL'nize sağlanan URL kodlanmış "kod" - {2}: uygulamaya kayıtlı geri çağırma URL'si
İstek gövdesini oluşturmak için C# örneği - uygulamayı yetkilendirme
public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl)
{
return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}",
HttpUtility.UrlEncode(appSecret),
HttpUtility.UrlEncode(authCode),
callbackUrl
);
}
Yanıt - uygulamayı yetkilendirme
{
"access_token": { access token for the user },
"token_type": { type of token },
"expires_in": { time in seconds that the token remains valid },
"refresh_token": { refresh token to use to acquire a new access token }
}
Önemli
Uygulamanızın kullanıcıdan yeniden yetkilendirmesini istemesine gerek olmaması için refresh_token güvenli bir şekilde kalıcı hale getirmek. Erişim belirteçlerinin süresi hızla dolar ve kalıcı hale gelmemelidir.
4. Erişim belirtecini kullanın
Erişim belirtecini kullanmak için HTTP isteğinizin Yetkilendirme üst bilgisine taşıyıcı belirteç olarak ekleyin:
Authorization: Bearer {access_token}
Örneğin, bir proje için son derlemeleri almak için HTTP isteği:
GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}
5. Süresi dolan erişim belirtecini yenileme
Kullanıcının erişim belirtecinin süresi dolarsa, yetkilendirme akışında edindikleri yenileme belirtecini kullanarak yeni bir erişim belirteci alabilirsiniz. Bu, bir erişim ve yenileme belirtecinin yetkilendirme kodunun değişmesine yönelik özgün işlem gibidir.
URL - yenileme belirteci
POST https://app.vssps.visualstudio.com/oauth2/token
HTTP isteği üst bilgileri - yenileme belirteci
Üst bilgi | Değer |
---|---|
İçerik türü | application/x-www-form-urlencoded |
İçerik uzunluğu | İstek gövdesinin hesaplanan dize uzunluğu (aşağıdaki örne bakın) |
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654
HTTP isteği gövdesi - yenileme belirteci
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}
Önceki örnek istek gövdesindeki yer tutucu değerlerini değiştirin:
- {0}: Uygulama kaydedildiğinde alınan URL kodlanmış istemci gizli dizisi
- {1}: Kullanıcı için URL ile kodlanmış yenileme belirteci
- {2}: uygulamaya kayıtlı geri çağırma URL'si
Yanıt - yenileme belirteci
{
"access_token": { access token for this user },
"token_type": { type of token },
"expires_in": { time in seconds that the token remains valid },
"refresh_token": { new refresh token to use when the token has timed out }
}
Önemli
Kullanıcı için yeni bir yenileme belirteci verilir. Bu yeni belirteci kalıcı hale getirmek ve kullanıcı için yeni bir erişim belirteci almanız gerektiğinde bu belirteci kullanın.
Örnekler
C# OAuth GitHub Örneğimizde Azure DevOps Services REST API'lerini çağırmak için OAuth uygulayan bir C# örneği bulabilirsiniz.
İstemci gizli dizilerini yeniden oluşturma
Her 5 yılda bir uygulama gizli dizinizin süresi dolar. Erişim belirteçleri oluşturup kullanmaya ve belirteçleri yenilemeye devam etmek için uygulama gizli dizinizi yeniden oluşturmanız beklenir. Bunu yapmak için" Gizli diziyi yeniden oluştur" düğmesine tıklayabilirsiniz. Bu düğme, bu eylemi tamamlamak istediğinizi onaylamak için bir iletişim kutusu açar.
Yeniden oluşturmak istediğinizi onayladığınızda, önceki uygulama gizli dizisi artık çalışmaz ve bu gizli diziyle basılan önceki tüm belirteçler de çalışmayı durdurur. Müşterinin kapalı kalma süresini en aza indirmek için bu istemci gizli dizi döndürmesini iyi zamanladığından emin olun.
Sık sorulan sorular (SSS)
S: Cep telefonu uygulamamla OAuth kullanabilir miyim?
Y: Hayır. Azure DevOps Services yalnızca web sunucusu akışını desteklediğinden, uygulama gizli dizisini güvenli bir şekilde depolayamazsınız.
S: Kodumda hangi hataları veya özel koşulları işlemem gerekiyor?
Y: Aşağıdaki koşulları işlediğinize emin olun:
- Kullanıcınız uygulama erişiminizi reddederse, hiçbir yetkilendirme kodu döndürülemez. Reddetme denetimi yapmadan yetkilendirme kodunu kullanmayın.
- Kullanıcınız uygulamanızın yetkilendirmesini iptal ederse erişim belirteci artık geçerli olmaz. Uygulamanız verilere erişmek için belirteci kullandığında 401 hatası döndürülüyor. Yetkilendirmeyi yeniden isteyin.
S: Web uygulamamda yerel olarak hata ayıklamak istiyorum. Uygulamamı kaydederken geri çağırma URL'si için localhost kullanabilir miyim?
Y: Evet. Azure DevOps Services artık geri arama URL'nizde localhost'a izin veriyor. Uygulamanızı kaydederken geri arama URL'nizin başlangıcı olarak kullandığınızdan https://localhost
emin olun.
S: Erişim belirteci almaya çalıştığımda HTTP 400 hatası alıyorum. Sorun ne olabilir?
Y: İçerik türünü istek üst bilginizde application/x-www-form-urlencoded olarak ayarladığınızdan denetleyin.
S: OAuth tabanlı erişim belirteci kullandığımda HTTP 401 hatası alıyorum, ancak aynı kapsama sahip bir PAT düzgün çalışıyor. Neden?
Y: Kuruluşunuzun yöneticisinin konumunda OAuth https://dev.azure.com/{your-org-name}/_settings/organizationPolicy
aracılığıyla Üçüncü taraf uygulama erişimini devre dışı bırakmadığını doğrulayın.
Bu senaryoda, bir uygulamayı yetkilendirme ve erişim belirteci oluşturma akışı çalışır, ancak tüm REST API'leri yalnızca bir hata döndürür, örneğin TF400813: The user "<GUID>" is not authorized to access this resource.
S: SOAP uç noktaları ve REST API'leri ile OAuth kullanabilir miyim?
Y: Hayır. OAuth yalnızca REST API'lerinde desteklenir.
S: Azure DevOps REST API'lerini kullanarak iş öğem için ek ayrıntılarını nasıl alabilirim?
Y: Aşağıdaki adımları uygulayın:
İş öğeleri ile iş öğesi ayrıntılarını alma - İş öğesi REST API'sini alma:
GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}
Ek ayrıntılarını almak için URL'ye aşağıdaki parametreyi ekleyin:
$expand=all
Sonuçlarla, ilişkiler özelliğini alırsınız. Burada eklerin URL'sini ve URL'nin içinde kimliği bulabilirsiniz. Örneğin:
$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=6.0 $workItem = Invoke-RestMethod -Uri $url -Method Get -ContentType application/json $split = ($workItem.relations.url).Split('/') $attachmentId = $split[$split.count - 1] # Result: 1244nhsfs-ff3f-25gg-j64t-fahs23vfs