Aracılığıyla paylaş

Web uygulaması oluşturmak için Azure DevOps OAuth 2.0 kullanma

  • Makale

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

  1. Uygulamanızı kaydetmek için adresine https://app.vsaex.visualstudio.com/app/register gidin.

  2. 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.

  3. Uygulama oluştur'u seçin.

    Uygulama ayarları sayfası görüntülenir.

    Uygulamanızın Uygulama ayarlarını gösteren ekran görüntüsü.

    • 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.

      Şirket ve uygulama bilgilerinizi içeren Visual Studio Codespaces yetkilendirme sayfasını gösteren ekran görüntüsü.

    • 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.

  4. 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/viewulaşabilirsiniz.

2. Uygulamanızı yetkilendirme

  1. 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.
  1. 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.

Gizli dizi yenilenmesini onaylayan ekran görüntüsü.

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/organizationPolicyaracı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:

  1. İş öğ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}

  2. Ek ayrıntılarını almak için URL'ye aşağıdaki parametreyi ekleyin:

    $expand=all

  3. 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