Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

OAuth2 kapsamlarıyla çalışma

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

Bu konuda, Apigee Edge'de OAuth 2.0 kapsamlarının nasıl kullanılacağı açıklanmaktadır.

OAuth2 kapsamı nedir?

OAuth 2.0 kapsamları, erişim jetonuna verilen erişim miktarını sınırlamanın bir yolunu sunar. Örneğin, bir istemci uygulamasına verilen erişim jetonu, korunan kaynaklara OKUMA ve YAZMA erişimi veya yalnızca OKUMA erişimi verebilir. API'lerinizi, istediğiniz kapsamı veya kapsam kombinasyonunu zorunlu kılacak şekilde uygulayabilirsiniz. Bu nedenle, bir istemci READ kapsamına sahip bir jeton alırsa ve WRITE erişimi gerektiren bir API uç noktasını çağırmaya çalışırsa çağrı başarısız olur.

Bu konuda, kapsamların erişim jetonlarına nasıl atandığı ve Apigee Edge'in OAuth 2.0 kapsamlarını nasıl zorunlu kıldığı ele alınacaktır. Bu konuyu okuduktan sonra kapsamları güvenle kullanabilirsiniz.

Kapsamlar erişim jetonlarına nasıl atanır?

Edge, bir erişim jetonu oluşturduğunda bu jetona bir kapsam atayabilir. Bunun nasıl gerçekleştiğini anlamak için öncelikle şu Apigee Edge varlıklarını bilmeniz gerekir: API ürünleri, geliştiriciler ve geliştirici uygulamaları. Giriş için Yayıncılığa giriş başlıklı makaleyi inceleyin. Devam etmeden önce bu materyali incelemenizi öneririz.

Erişim jetonu, Edge'in gelen API isteklerini doğrulamasına olanak tanıyan, rastgele görünümlü uzun bir karakter dizisidir (Bunu, normal kullanıcı adı/şifre kimlik bilgilerinin yerine geçen bir öğe olarak düşünebilirsiniz). Teknik olarak jeton, aşağıdaki gibi görünen bir meta veri koleksiyonunu ifade eden bir anahtardır:

{
  "issued_at" : "1416962591727",
  "application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781",
  "scope" : "A",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-bs0cSuqS9y]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-AdBmANhsag@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun",
  "access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Jetonun meta verileri; gerçek erişim jetonu dizesini, geçerlilik bitişi bilgilerini, geliştirici uygulamasının, geliştiricinin ve jetonla ilişkili ürünlerin tanımlanmasını içerir. Meta verilerde "kapsam"ın da yer aldığını göreceksiniz.

Jeton kapsamını nasıl alır?

Kapsamı anlamanın ilk anahtarı, geliştirici uygulamasındaki her ürüne sıfır veya daha fazla kapsam atanabileceğini hatırlamaktır. Bu kapsamlar, ürün oluşturulurken atanabilir veya daha sonra eklenebilir. Ad listesi olarak bulunur ve her ürünle ilişkili "meta veriler"e dahil edilir.

Bir geliştirici uygulaması oluşturup bu uygulamaya ürün eklediğinizde Edge, geliştirici uygulamasındaki tüm ürünlere bakar ve bu ürünlerin tüm kapsamlarının bir listesini oluşturur (uygulamanın ana veya genel kapsam listesi; tanınan tüm kapsamların birleşimi).

Bir istemci uygulaması Apigee Edge'den erişim jetonu istediğinde, isteğe bağlı olarak bu jetonla ilişkilendirmek istediği kapsamları belirtebilir. Örneğin, aşağıdaki istek "A" kapsamını ister. Yani istemci, yetkilendirme sunucusundan (Edge) kapsamı "A" olan bir erişim jetonu oluşturmasını istiyor (bu, uygulamaya kapsamı "A" olan API'leri çağırma yetkisi veriyor). Uygulama şu şekilde bir POST isteği gönderir:

curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG -H content-type:application/x-www-form-urlencoded http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A

Süreç

Edge bu isteği aldığında hangi uygulamanın istekte bulunduğunu ve istemcinin hangi geliştirici uygulamasına kaydolduğunu bilir (istemci kimliği ve istemci gizli anahtarları, temel kimlik doğrulama üstbilgisinde kodlanır). scope sorgu parametresi dahil edildiğinden Edge'in, geliştirici uygulamasıyla ilişkili API ürünlerinden herhangi birinin "A" kapsamına sahip olup olmadığına karar vermesi gerekir. Bu durumda, kapsamı "A" olan bir erişim jetonu oluşturulur. Bunu yorumlamanın başka bir yolu da kapsam sorgusu parametresinin bir tür filtre olduğudur. Geliştirici uygulaması "A, B, X" kapsamlarını tanıyorsa ve sorgu parametresi "scope=X Y Z" olarak belirtilmişse jetona yalnızca "X" kapsamı atanır.

İstemci bir kapsam parametresi eklemezse ne olur? Bu durumda Edge, geliştirici uygulaması tarafından tanınan tüm kapsamları içeren bir jeton oluşturur. Varsayılan davranışın, geliştirici uygulamasına dahil edilen tüm ürünler için tüm kapsamların birleşimini içeren bir erişim jetonu döndürmek olduğunu anlamak önemlidir.

Bir geliştirici uygulamasıyla ilişkili ürünlerin hiçbirinde kapsam belirtilmemişse ve jetonun kapsamı varsa bu jetonla yapılan çağrılar başarısız olur.

Bir geliştirici uygulamasının şu kapsamları tanıdığını varsayalım: A B C D. Bu, uygulamanın kapsamlarla ilgili ana listesidir. Uygulamadaki bir ürünün A ve B kapsamı, ikinci bir ürünün ise C ve D kapsamı veya herhangi bir kombinasyon olabilir. İstemci bir scope parametresi belirtmezse (veya kapsam parametresini değer olmadan belirtirse) jetona dört kapsamın tamamı (A, B, C ve D) verilir. Yine, jeton, geliştirici uygulaması tarafından tanınan tüm kapsamların birleşimi olan bir kapsam grubu alır.

Varsayılan davranışın, tanınan tüm kapsamlarla birlikte bir erişim jetonu döndürmek olduğu bir durum daha vardır. Bu durum, GenerateAccessToken politikası (erişim jetonları oluşturan Apigee Edge politikası) bir <Scope> öğesi belirtmediğinde geçerlidir. Örneğin, <Scope> is değerinin belirtildiği bir GenerateAccessToken politikası aşağıda verilmiştir. Bu <Scope> öğesi eksikse (veya mevcutsa ancak boşsa) varsayılan davranış yürütülür.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken">
    <DisplayName>OAuthV2 - Generate Access Token</DisplayName>
    <Attributes>
      <Attribute name='hello' ref='system.time' display='false'>value1</Attribute>
    </Attributes>
    <Scope>request.queryparam.scope</Scope> 
    <GrantType>request.formparam.grant_type</GrantType>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Kapsamlar nasıl uygulanır?

Öncelikle, Apigee Edge'de erişim jetonlarının OAuthV2 politikasıyla (genellikle bir proxy akışının en başında yer alır) doğrulandığını unutmayın. Politikada VerifyAccessToken işlemi belirtilmelidir. Şimdi bu politikaya göz atalım:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
    <GenerateResponse enabled="true"/>
</OAuthV2>

<Scope> öğesine dikkat edin. Politikanın hangi kapsamları kabul edeceğini belirtmek için kullanılır.

Bu örnekte, politika yalnızca erişim jetonu "A" kapsamını içeriyorsa başarılı olur. Bu <Scope> öğesi atlanırsa veya değeri yoksa politika, erişim jetonunun kapsamını yoksayar.

Artık erişim jetonlarını kapsama göre doğrulama özelliği sayesinde API'lerinizi belirli kapsamları zorunlu kılacak şekilde tasarlayabilirsiniz. Bunu, kapsam duyarlı VerifyAccessToken politikaları eklenmiş özel akışlar tasarlayarak yaparsınız.

API'nizin /resourceA uç noktası için tanımlanmış bir akışı olduğunu varsayalım:

<Flow name="resourceA">
            <Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
            <Description>Get a resource A</Description>
            <Request>
                <Step>
                    <Name>OAuthV2-VerifyAccessTokenA</Name>
                </Step>
            </Request>
            <Response>
                <Step>
                    <Name>AssignMessage-CreateResponse</Name>
                </Step>
            </Response>
        </Flow>

Bu akış tetiklendiğinde (yol sonekinde /resourceA bulunan bir istek geldiğinde) OAuthV2-VerifyAccessTokenA politikası hemen çağrılır. Bu politika, erişim jetonunun geçerli olup olmadığını doğrular ve jetonun hangi kapsamları desteklediğini kontrol eder. Politika, aşağıdaki örnekte olduğu gibi <Scope>A</Scope> ile yapılandırılırsa politika yalnızca erişim jetonunun kapsamı "A" ise başarılı olur. Aksi takdirde hata döndürülür.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Özetlemek gerekirse API geliştiriciler, kapsam zorunluluğunu API'lerine dahil etmekten sorumludur. Bunu, belirli kapsamları işlemek için özel akışlar oluşturarak ve bu kapsamları zorunlu kılmak için VerifyAccessToken politikaları ekleyerek yaparlar.

Kod örnekleri

Son olarak, jetonların nasıl kapsam aldığını ve kapsamların nasıl uygulandığını göstermek için bazı örnek API çağrılarına göz atalım.

Varsayılan durum

Ürünler içeren bir geliştirici uygulamanız olduğunu ve bu ürünlerin kapsamlarının birleşiminin A, B ve C olduğunu varsayalım. Bu API çağrısı, erişim jetonu istiyor ancak bir kapsam sorgusu parametresi belirtmiyor.

curl -X POST -H content-type:application/x-www-form-urlencoded http://wwitman-test.apigee.net/scopecheck1/token?grant_type=client_credentials

Bu durumda, oluşturulan jetona A, B ve C kapsamları verilir (varsayılan davranış). Jetonun meta verileri şu şekilde görünür:

{
  "issued_at" : "1417016208588",
  "application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360",
  "scope" : "A B C",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-yEgQbQqjRR]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-yxiuHuZcDW@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW",
  "access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Şimdi de "A" kapsamına sahip bir API uç noktanız olduğunu varsayalım (yani VerifyAccessToken, "A" kapsamını gerektiriyor). VerifyAccessToken politikası aşağıda verilmiştir:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Kapsam A'yı zorunlu kılan bir uç noktaya yapılan örnek çağrı:

curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI http://wwitman-test.apigee.net/scopecheck1/resourceA

Bu GET çağrısı başarılı olur:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

Bu işlem, uç nokta çağrıldığında tetiklenen VerifyAccessToken politikası A kapsamını gerektirdiği ve erişim jetonuna A, B ve C kapsamlarının (varsayılan davranış) verildiği için başarılı olur.

Filtreleme durumu

Kapsamları A, B, C ve X olan ürünler içeren bir geliştirici uygulamanız olduğunu varsayalım. Aşağıdaki gibi bir erişim jetonu isteğinde bulunup scope sorgu parametresini eklersiniz:

curl -i -X POST -H content-type:application/x-www-form-urlencoded 'http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A X'

Bu durumda, hem A hem de X geçerli kapsamlar olduğundan, oluşturulan jetona A ve X kapsamları verilir. Geliştirici uygulamasının A, B, C ve X kapsamlarını tanıdığını unutmayın. Bu durumda, API ürünlerinin listesini bu kapsamları temel alarak filtreliyorsunuz. Bir ürünün kapsamı A veya X ise bu kapsamları zorunlu kılacak API uç noktaları yapılandırabilirsiniz. Bir ürünün A veya X kapsamı yoksa (örneğin, B, C ve Z kapsamları varsa) A veya X kapsamlarını zorunlu kılan API'ler jetonla çağrılamaz.

API'yi yeni jetonla çağırdığınızda:

curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG http://wwitman-test.apigee.net/scopecheck1/resourceX

Erişim jetonu, API proxy'si tarafından doğrulanır. Örneğin:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A X</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

GET çağrısı tetiklenir ve yanıt döndürülür. Örneğin:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

VerifyAccessToken politikası A veya X kapsamını gerektirdiğinden ve erişim jetonu A ve X kapsamını içerdiğinden bu işlem başarılı olur. Elbette, <Scope> öğesi "B" olarak ayarlanmışsa bu çağrı başarısız olur.

Özet

Apigee Edge'in OAuth 2.0 kapsamlarını nasıl işlediğini anlamak önemlidir. Önemli noktalar:

Bir geliştirici uygulaması, tüm ürünleri için tanımlanan tüm kapsamların birleşimini "tanır".
Bir uygulama erişim jetonu istediğinde hangi kapsamları kullanmak istediğini belirtebilir. (a) İstenen kapsamlar ve (b) geliştirici uygulaması tarafından tanınan kapsamlar temelinde erişim jetonuna hangi kapsamların atanacağını belirlemek Apigee Edge'in (yetkilendirme sunucusu) sorumluluğundadır.
Apigee Edge, kapsamı kontrol edecek şekilde yapılandırılmamışsa (<Scope> öğesi VerifyAccessToken politikasında eksik veya boşsa) erişim jetonuna yerleştirilmiş kapsam, kayıtlı geliştirici uygulaması tarafından tanınan kapsamlardan biriyle (uygulamanın kapsamlar "ana" listesindeki kapsamlardan biri) eşleştiği sürece API çağrısı başarılı olur.
Erişim jetonunun kapsamı yoksa yalnızca Edge'in kapsamı dikkate almadığı durumlarda (VerifyAccessToken politikasında <Scope> öğesi eksik veya boş) başarılı olur.