JJT politikası oluştur

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

Ne

Yapılandırılabilir hak talebi grubuyla imzalı bir JWT oluşturur. JWT daha sonra istemcilere döndürülebilir, arka uç hedeflerine iletilebilir veya başka şekillerde kullanılabilir. Ayrıntılı tanıtım için JWS ve JWT politikalarına genel bakış başlıklı makaleyi inceleyin.

Video

İmzalanmış bir JWT'nin nasıl oluşturulacağını öğrenmek için kısa bir video izleyin.

Örnekler

• HS256 algoritmasıyla imzalanmış bir JWT oluşturma
• RS256 algoritmasıyla imzalanmış bir JWT oluşturma

HS256 algoritmasıyla imzalanmış bir JWT oluşturun

Bu örnek politika, yeni bir JWT oluşturur ve bunu HS256 algoritmasını kullanarak imzalar. HS256, hem imzalama hem de imzayı doğrulamak için paylaşılan bir gizli anahtardan yararlanır.

Bu politika işlemi tetiklendiğinde Edge, JWT başlığını ve yükünü kodlar, ardından JWT'yi dijital olarak imzalar. Politikadan nasıl istekte bulunulacağını da içeren eksiksiz bir örnek için yukarıdaki videoyu izleyin.

Buradaki politika yapılandırması, 1 saatlik geçerlilik süresi ve ek bir hak talebi dahil olmak üzere, JWT spesifikasyonunda tanımlandığı şekilde bir dizi standart hak talebinden oluşan bir JWT oluşturur. İstediğiniz kadar ek hak talebi ekleyebilirsiniz. Bu örnek politikadaki her bir öğeyle ilgili koşullar ve seçenekler hakkında ayrıntılı bilgi için Öğe referansına bakın.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Sonuçta elde edilen JWT şu başlığa sahip olur...

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

... ve şuna benzer içeriklerle bir yükü olur:

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

iat, exp ve jti hak taleplerinin değeri değişiklik gösterir.

RS256 algoritmasıyla imzalanmış bir JWT oluşturun

Bu örnek politika, yeni bir JWT oluşturur ve RS256 algoritmasını kullanarak bunu imzalar. RS256 imzası oluşturmak için RSA özel anahtarı kullanılır. Bu anahtarın PEM kodlu biçimde sağlanması gerekir. Politikadan nasıl istekte bulunulacağını da içeren eksiksiz bir örnek için yukarıdaki videoyu izleyin.

Bu politika işlemi tetiklendiğinde Edge, hak talepleri dahil olmak üzere JWT'yi kodlayıp dijital olarak imzalar. JWT'nin parçaları ve nasıl şifrelenip imzalandığı hakkında bilgi edinmek için RFC7519 sayfasına bakın.

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Temel unsurları ayarlama

JWT'yi oluşturmak için kullanılan anahtarı belirtmek için kullandığınız öğeler, aşağıdaki tabloda gösterildiği gibi seçilen algoritmaya bağlıdır:

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

JWT Oluşturma için öğe referansı

Politika referansında, JWT Oluştur politikasının öğeleri ve özellikleri açıklanmaktadır.

Not: Yapılandırma, kullandığınız şifreleme algoritmasına bağlı olarak biraz farklılık gösterir. Belirli kullanım alanlarına yönelik yapılandırmaları gösteren örnekler için Örnekler bölümüne bakın.

Üst düzey öğe için geçerli olan özellikler

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

Aşağıdaki özellikler, tüm politika üst öğelerinde ortaktır.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Yönetim arayüzü proxy düzenleyicisinde politikayı farklı bir doğal dil adıyla etiketlemek için name özelliğine ek olarak kullanın.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Jetonu imzalayacak şifreleme algoritmasını belirtir.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

Politika, belirtilen değere ayarlanmış aud talebi içeren bir JWT oluşturur. Bu hak talebi, JWT'nin hedeflendiği alıcıları tanımlar. Bu, RFC7519'da bahsedilen kayıtlı hak taleplerinden biridir.

<AdditionalClaims/Claims> (EkHak Talebi/Hak Talebi)

<AdditionalClaims>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

JWT'nin yükünde ek hak talebi adı/değer çiftleri belirtmenizi sağlar. İddiayı dize, sayı, boole, harita veya dizi olarak açık bir şekilde belirtebilirsiniz. Harita, basit bir şekilde ifade etmek gerekirse, bir dizi ad/değer çiftinden oluşur.

<Claim> öğesi şu özellikleri alır:

• name - (Zorunlu) Hak talebinin adı.
• ref - (İsteğe bağlı) Bir akış değişkeninin adı. Politika varsa bu değişkenin değerini iddia olarak kullanır. Hem ref özelliği hem de açık hak talebi değeri belirtilirse açıkça belirtilen değer varsayılan değer olur ve başvurulan akış değişkeni çözümlenmemişse kullanılır.
• type - (İsteğe bağlı) Şunlardan biri: dize (varsayılan), sayı, boole veya harita
• array - (İsteğe bağlı) Değerin bir tür dizisi olup olmadığını belirtmek için true olarak ayarlayın. Varsayılan: false.

<Claim> öğesini eklediğinizde, politikayı yapılandırırken hak talebi adları statik olarak ayarlanır. Alternatif olarak, hak talebi adlarını belirtmek için bir JSON nesnesi aktarabilirsiniz. JSON nesnesi değişken olarak iletildiğinden, oluşturulan JWT'deki hak talebi adları çalışma zamanında belirlenir.

Örneğin:

<AdditionalClaims ref='json_claims'/>

Burada, json_claims değişkeni şu biçimde bir JSON nesnesi içerir:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

Oluşturulan JWT, JSON nesnesindeki tüm hak taleplerini içerir.

<Ek Başlık/Hak Talebi>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

Ek hak talebi adını/değer çiftini JWT'nin başlığına yerleştirir.

<Claim> öğesi şu özellikleri alır:

• name - (Zorunlu) Hak talebinin adı.
• ref - (İsteğe bağlı) Bir akış değişkeninin adı. Politika varsa bu değişkenin değerini iddia olarak kullanır. Hem ref özelliği hem de açık hak talebi değeri belirtilirse açıkça belirtilen değer varsayılan değer olur ve başvurulan akış değişkeni çözümlenmemişse kullanılır.
• type - (İsteğe bağlı) Şunlardan biri: dize (varsayılan), sayı, boole veya harita
• array - (İsteğe bağlı) Değerin bir tür dizisi olup olmadığını belirtmek için true olarak ayarlayın. Varsayılan: false.

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

JWT başlığına crit kritik başlığını ekler. crit başlığı, JWT alıcısı tarafından bilinmesi ve tanınması gereken başlık adları dizisidir. Örneğin:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

Çalışma zamanında VerifyJWT politikası, crit üstbilgisini inceler. crit başlığında listelenen her öğe için, VerificationJWT politikasının <KnownHeaders> öğesinin bu başlığın da listelenip listelenmediğini kontrol eder. VerificationJWT politikasının crit içinde bulduğu, ancak <KnownHeaders> içinde de listelenmeyen herhangi bir üstbilgi, VerificationJWT politikasının başarısız olmasına neden olur.

<CustomClaims>

Not: Şu anda kullanıcı arayüzü üzerinden yeni bir GenerateJWT politikası eklediğinizde bir CustomClaims öğesi ekleniyor. Bu öğe çalışmıyor ve yoksayıldı. Bunun yerine kullanılacak doğru öğe, <AdditionalClaims> öğesidir. Kullanıcı arayüzü, doğru öğeleri daha sonra eklemek için güncellenecektir.

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

JWT'nin kullanım ömrünü milisaniye, saniye, dakika, saat veya gün cinsinden belirtir.

<Kimlik>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Belirli jti talebine sahip bir JWT oluşturur. Metin değeri ve ref özelliği boş olduğunda politika, rastgele UUID içeren bir jti oluşturur. JWT kimliği (jti) hak talebi, JWT için benzersiz bir tanımlayıcıdır. jti hakkında daha fazla bilgi için RFC7519'a bakın.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Politikada belirtilen referans verilen herhangi bir değişken çözümlenemez durumda olduğunda politikanın hata vermesini istiyorsanız "false" (yanlış) değerine ayarlayın. Çözümlenemeyen değişkenleri boş dize (null) olarak ele almak için değeri true olarak ayarlayın.

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

Politika,iss adlı ve belirtilen değere ayarlanmış bir hak talebi içeren bir JWT oluşturur. JWT'yi veren kuruluşu tanımlayan bir hak talebi. Bu, RFC7519'da belirtilen kayıtlı hak taleplerinden biridir.

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

Jetonun geçerli olacağı zamanı belirtir. Jeton, belirtilen zamana kadar geçersizdir. Mutlak zaman değeri veya jetonun oluşturulduğu zamana göre bir zaman belirtebilirsiniz.

Mutlak zaman değerleri için NotBefore öğesine yönelik geçerli zaman değerleri

Göreli zaman değerleri için bir tam sayı ve dönem belirtin. Örneğin:

• 10 saniye
• 60 dk.
• 12 s

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Bu politika tarafından oluşturulan JWT'nin nereye yerleştirileceğini belirtir. Varsayılan olarak jwt.POLICYNAME.generated_jwt akış değişkenine yerleştirilir.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

JWT üstbilgisine dahil edilecek anahtar kimliğini (kid) belirtir. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 değerlerinden biri olduğunda kullanın.

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Gerekirse politikanın özel anahtarın şifresini çözmek için kullanması gereken şifreyi belirtin. Anahtarı bir akış değişkeninde iletmek için ref özelliğini kullanın. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 değerlerinden biri olduğunda kullanın.

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

JWT'yi imzalamak için kullanılan PEM kodlu özel anahtarı belirtir. Anahtarı bir akış değişkeninde iletmek için ref özelliğini kullanın. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 değerlerinden biri olduğunda kullanın.

<Gizli Anahtar/Kimlik>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

HMAC algoritmasıyla imzalanmış bir JWT'nin JWT üstbilgisine dahil edilecek anahtar kimliğini (kid) belirtir. Yalnızca algoritma, HS256/HS384/HS512 değerlerinden biri olduğunda kullanın.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

Jetonları bir HMAC algoritmasıyla doğrulamak veya imzalamak için kullanılan gizli anahtarı sağlar. Yalnızca algoritmanın HS256/HS384/HS512 olması durumunda kullanın. Anahtarı bir akış değişkeninde iletmek için ref özelliğini kullanın.

Edge, HS256/HS384/HS512 algoritmaları için minimum bir anahtar gücü uygular. Minimum anahtar uzunluğu HS256 için 32 bayt, HS384 için 48 bayt, HS512 için ise 64 bayttır. Daha düşük güçlü bir anahtarın kullanılması, çalışma zamanı hatasına neden olur.

<Subject>

<Subject>subject-string-here</Subject>

<Subject ref="flow_variable" />

Örneğin:

<Subject ref="apigee.developer.email"/>

Politika, belirtilen değere ayarlanmış alt hak talebi içeren bir JWT oluşturur.Bu hak talebi, JWT'nin konusunu tanımlar veya ifade eder. Bu, RFC7519'da belirtilen standart iddia gruplarından biridir.

Akış değişkenleri

JWT Oluştur politikası akış değişkenlerini ayarlamaz.

Hata referansı

Bu bölümde, bu politika bir hatayı tetiklediğinde Edge tarafından ayarlanan hata kodları ile hata mesajları ve döndürülen hata mesajları ile Edge tarafından ayarlanan hata değişkenleri açıklanmaktadır. Bu bilgiyi, hataları ele almak için hata kuralları geliştirip geliştirmediğinizi bilmeniz önemlidir. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler ve Hataları işleme bölümlerine bakın.

Çalışma zamanı hataları

Politika yürütüldüğünde bu hatalar ortaya çıkabilir.

Dağıtım hataları

Bu hatalar, bu politikayı içeren bir proxy dağıttığınızda ortaya çıkabilir.

Hata değişkenleri

Bu değişkenler, bir çalışma zamanı hatası oluştuğunda ayarlanır. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler bölümüne bakın.

Örnek hata yanıtı

Hata işleme için en iyi uygulama, hata yanıtının errorcode bölümünü yakalamaktır. Değişebileceği için faultstring içindeki metne güvenmeyin.

Hata kuralı örneği

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>