Bu sayfa, Cloud Translation API ile çevrilmiştir.

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ı, bir erişim jetonuna verilen erişim miktarını sınırlandırma yöntemi sunar. Örneğin, bir istemci uygulamasına verilen erişim jetonuna korunan kaynaklara OKUMA ve YAZMA erişimi veya yalnızca OKUMA erişimi verilebilir. Dilediğiniz kapsamı veya kapsam kombinasyonunu zorunlu kılmak için API'lerinizi uygulayabilirsiniz. Bu nedenle, bir istemci READ kapsamına sahip bir jeton alır ve YAZMA erişimi gerektiren bir API uç noktasını çağırmaya çalışırsa çağrı başarısız olur.

Bu konuda, erişim jetonlarına kapsamların nasıl atandığını ve Apigee Edge'in OAuth 2.0 kapsamlarını nasıl uyguladığını ele alacağız. Bu konuyu okuduktan sonra kapsamları güvenle kullanabileceksiniz.

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 olduğunu anlamak için öncelikle Apigee Edge'in şu varlıklarına (API ürünleri, geliştiriciler ve geliştirici uygulamaları) aşina olmanız gerekir. Tanıtım için Yayınlamaya giriş bölümünü inceleyin. Devam etmeden önce gerekirse bu materyali incelemenizi öneririz.

Erişim jetonu, Edge'in gelen API isteklerini doğrulamasına olanak tanıyan, rastgele görünümlü karakterlerden oluşan uzun bir dizedir (bunu tipik kullanıcı adı/şifre kimlik bilgilerinin yedeği 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, süre sonu bilgilerini, geliştirici uygulamasının kimliğini, geliştiriciyi ve jetonla ilişkilendirilmiş ürünleri içerir. Meta verilerde "kapsam" ifadesinin de bulunduğunu göreceksiniz.

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

Kapsamı anlamanın ilk anahtarı, bir geliştirici uygulamasındaki her ürüne sıfır veya daha fazla kapsam atanabileceğini unutmamaktır. Bu kapsamlar, ürün oluşturulduğunda atanabilir veya daha sonra eklenebilir. Bir ad listesi şeklinde bulunurlar ve her ürünle ilişkili "meta verilere" eklenirler.

Bir geliştirici uygulaması oluşturup buna ü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 (uygulamanın ana veya genel kapsam listesi, yani tanınan tüm kapsamların birleşimi) oluşturur.

Bir istemci uygulaması Apigee Edge'den erişim jetonu istediğinde, isteğe bağlı olarak bu jetonla ilişkilendirilmesini istediği kapsamları belirtebilir. Örneğin, aşağıdaki istekte "A" kapsamı istenir. Yani istemci, yetkilendirme sunucusunun (Edge) "A" kapsamına sahip bir erişim jetonu oluşturmasını ister (uygulamaya "A" kapsamına sahip API'leri çağırma yetkisi verir). Uygulama şuna benzer 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

Ne olur?

Edge bu isteği aldığında hangi uygulamanın istekte bulunduğunu ve istemcinin hangi geliştirici uygulamasını kaydettiğini bilir (istemci kimliği ve istemci gizli anahtarı anahtarları temel kimlik doğrulama başlığında kodlanır). scope sorgu parametresi eklendiğinden Edge'in, geliştirici uygulamasıyla ilişkilendirilmiş API ürünlerinden herhangi birinin "A" kapsamına sahip olup olmadığına karar vermesi gerekir. Destekleniyorsa "A" kapsamıyla bir erişim jetonu oluşturulur. Kapsam sorgu parametresinin bir tür filtre olduğu da düşünülebilir. Geliştirici uygulaması "A, B, X" kapsamlarını tanırsa ve sorgu parametresi "scope=X Y Z"yi belirtirse jetona yalnızca "X" kapsamı atanır.

Müşteri 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ında yer alan tüm ürünlerin tüm kapsamlarının birleşimini içeren bir erişim jetonu döndürmek olduğunun anlaşılması önemlidir.

Bir geliştirici uygulamasıyla ilişkilendirilmiş ürünlerden hiçbiri kapsam belirtmiyorsa ve bir 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 ana kapsam listesidir. Uygulamadaki bir ürün A ve B kapsamına ve ikinci ürünün kapsamı C ve D'ye ya da bunların herhangi bir kombinasyonuna sahip olabilir. İstemci bir scope parametresi belirtmezse (veya herhangi bir değer içermeyen kapsam parametresi belirtirse) jetona dört kapsamın tümü verilir: A, B, C ve D. Jeton da geliştirici uygulaması tarafından tanınan tüm kapsamların birleşimi olan bir dizi kapsam alır.

Varsayılan davranışın, tanınan tüm kapsamları içeren bir erişim jetonu döndürmek olduğu bir durum daha vardır. GenerateAccessToken politikası (erişim jetonları oluşturan Apigee Edge politikası) bir <Scope> öğesi belirtmez. Örneğin, <Scope> belirtilen bir GenerateAccessToken politikasını burada görebilirsiniz. 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 doğrulandığını unutmayın (genellikle bir proxy akışının en başına yerleştirilir). Politikada VerificationAccessToken işlemi belirtilmelidir. Şimdi bu politikayı inceleyelim:

<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 jetonunun "A" kapsamını içeriyorsa başarılı olur. Bu <Scope> öğesi atlanırsa veya değer yoksa politika, erişim jetonunun kapsamını yoksayar.

Artık erişim jetonlarını kapsama göre doğrulama özelliğiyle API'lerinizi belirli kapsamları zorunlu kılacak şekilde tasarlayabilirsiniz. Bunu, kapsama duyarlı ValidAccessToken politikalarına sahip özel akışlar tasarlayarak yapabilirsiniz.

API'nizde /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 son ekinde /resourceA bulunan bir istek gelir) OAuthV2-VerifyAccessTokenA politikası hemen çağrılır. Bu politika, erişim jetonunun geçerli olduğunu doğrular ve jetonun hangi kapsamları desteklediğini kontrol eder. Politika, aşağıdaki örneğe benzer şekilde ve <Scope>A</Scope> ile yapılandırılırsa politika yalnızca erişim jetonunun "A" kapsamını içerdiğinde başarılı olur. Aksi takdirde, bir 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>

Özetle, API geliştiricileri API'lerinde kapsam yaptırımı tasarlamaktan sorumludur. Bunu, belirli kapsamları işlemek için özel akışlar oluşturarak ve bu kapsamları uygulamak için VerificationAccessToken politikaları ekleyerek yaparlar.

Kod örnekleri

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

Varsayılan büyük/küçük harf

Ürünlerin bulunduğu 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ı bir erişim jetonu isteğinde bulunuyor, ancak kapsam sorgu 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 aşağıdaki gibi 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, "A" kapsamına sahip bir API uç noktanız olduğunu varsayalım (yani, VerificationAccessToken için "A" kapsamı gerekir). VerificationAccessToken politikası aşağıdaki gibidir:

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

Aşağıda, A kapsamını zorunlu kılan bir uç noktaya yapılan örnek çağrı verilmiştir:

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

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

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

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

Filtreleme büyük/küçük harf durumu

A, B, C ve X kapsamlarına sahip ürünler içeren bir geliştirici uygulamanız olduğunu varsayalım. Erişim jetonu ister ve scope sorgu parametresini şu şekilde 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 bir kapsam olduğu için, 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ün listesini bu kapsamlara göre filtrelersiniz. Bir ürünün kapsamı A veya X ise bu kapsamları zorunlu kılacak API uç noktaları yapılandırabilirsiniz. Bir ürünün kapsamı A veya X değilse (örneğin, B, C ve Z'ye sahipse) A veya X kapsamlarını zorunlu kılan API'ler bu 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ı başarılı olur ve bir yanıt döndürür. Örneğin:

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

VerificationAccessToken politikası A veya X kapsamını gerektirdiği ve erişim jetonu A ve X kapsamını içerdiği için başarılı olur. Elbette <Scope> öğesi "B" olarak ayarlanırsa bu çağrı başarısız olur.

Özet

Apigee Edge'in OAuth 2.0 kapsamlarını nasıl işlediğini anlamak önemlidir. Ana çıkarımlar şu şekildedir:

Bir geliştirici uygulaması, tüm ürünleri için tanımlanmış tüm kapsamların birleşimini "tanır".
Bir uygulama erişim jetonu istediğinde, hangi kapsamlara sahip olmak istediğini belirtme fırsatına sahip olur. (a) İstenen kapsamlara ve (b) geliştirici uygulaması tarafından tanınan kapsamlara göre erişim jetonuna hangi kapsamları atayacağını belirlemek Apigee Edge'e (yetkilendirme sunucusu) bağlıdır.
Apigee Edge, kapsamı kontrol edecek şekilde yapılandırılmadıysa (<Scope> öğesi, VerificationAccessToken politikasında yoksa veya boşsa), erişim jetonuna yerleştirilen kapsam, kayıtlı geliştirici uygulaması tarafından tanınan kapsamlardan biriyle (uygulamanın "ana" kapsam listesindeki kapsamlardan biri) eşleştiği sürece API çağrısı başarılı olur.
Erişim jetonuyla ilişkilendirilmiş kapsam yoksa erişim jetonu, yalnızca Edge'in kapsamı dikkate almadığı (Doğrulama ErişimToken politikasında <Scope> öğesi eksik veya boş olduğu) durumlarda başarılı olur.