JJT politikası oluştur

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

Ne?

Yapılandırılabilir bir talep 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ı bir giriş için JWS ve JWT politikalarına genel bakış başlıklı makaleyi inceleyin.

Video

İmzalı bir JWT oluşturmayı öğrenmek için kısa bir video izleyin.

Örnekler

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

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

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

Bu politika işlemi tetiklendiğinde Edge, JWT başlığını ve yükünü kodlar, ardından JWT'yi dijital olarak imzalar. Politikayla ilgili nasıl talepte bulunacağınız da dahil olmak üzere eksiksiz bir örnek için yukarıdaki videoyu izleyin.

Buradaki politika yapılandırması, JWT spesifikasyonunda tanımlandığı şekilde bir dizi standart talep içeren bir JWT oluşturur. Bu talepler arasında 1 saatlik geçerlilik süresi ve ek bir talep yer alır. İstediğiniz kadar ek iddia ekleyebilirsiniz. Bu örnek politikadaki her bir öğeyle ilgili şartlar 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>

Elde edilen JWT'nin başlığı şu şekilde olur:

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

… ve şu gibi içeriklere sahip 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 taleplerinin değeri değişir.

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

Bu örnek politika, yeni bir JWT oluşturur ve RS256 algoritmasını kullanarak imzalar. RS256 imzası oluşturmak için RSA özel anahtarı gerekir. Bu anahtar, PEM kodlamalı biçimde sağlanmalıdır. Politikayla ilgili nasıl talepte bulunacağınız da dahil olmak üzere eksiksiz bir örnek için yukarıdaki videoyu izleyin.

Bu politika işlemi tetiklendiğinde Edge, talepler de dahil olmak üzere JWT'yi kodlar ve dijital olarak imzalar. JWT'nin bölümleri ve bunların nasıl şifrelenip imzalandığı hakkında bilgi edinmek için RFC7519'a 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 öğeleri ayarlama

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

<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şturma 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.

En üst düzey öğeye uygulanan özellikler

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

Aşağıdaki özellikler tüm politika üst öğeleri için ortaktır.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Politikayı yönetim kullanıcı arayüzü proxy düzenleyicisinde farklı bir doğal dil adıyla etiketlemek için ad özelliğine ek olarak kullanılır.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Jetonu imzalamak için kullanılacak şifreleme algoritmasını belirtir.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

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

<AdditionalClaims/Claim>

<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 talep adı/değer çiftleri belirtmenize olanak tanır. İddiayı dize, sayı, Boole, eşlem veya dizi olarak açıkça belirtebilirsiniz. Harita, yalnızca bir ad/değer çiftleri kümesidir.

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

• name: (Zorunlu) Hak talebinin adı.
• ref: (İsteğe bağlı) Bir akış değişkeninin adı. Bu değişken varsa politika, bu değişkenin değerini talep olarak kullanır. Hem ref özelliği hem de açık bir talep değeri belirtilirse açık değer varsayılan değer olur ve referans verilen akış değişkeni çözümlenmemişse kullanılır.
• type: (İsteğe bağlı) Şu değerlerden biri: dize (varsayılan), sayı, Boole veya eşlem
• 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 iletebilirsiniz. JSON nesnesi değişken olarak iletildiğinden, oluşturulan JWT'deki talep 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 talepleri içerir.

<AdditionalHeaders/Claim>

<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 talep adı/değer çiftlerini JWT'nin üstbilgisine yerleştirir.

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

• name: (Zorunlu) Hak talebinin adı.
• ref: (İsteğe bağlı) Bir akış değişkeninin adı. Bu değişken varsa politika, bu değişkenin değerini talep olarak kullanır. Hem ref özelliği hem de açık bir talep değeri belirtilirse açık değer varsayılan değer olur ve referans verilen akış değişkeni çözümlenmemişse kullanılır.
• type: (İsteğe bağlı) Şu değerlerden biri: dize (varsayılan), sayı, Boole veya eşlem
• 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 üstbilgisine kritik üstbilgi olan crit'i ekler. crit üstbilgisi, JWT alıcısı tarafından bilinmesi ve tanınması gereken üstbilgi adlarından oluşan bir dizidir. Örneğin:

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

Çalışma zamanında VerifyJWT politikası, crit üstbilgisini inceler. crit üstbilgisinde listelenen her öğe için, VerifyJWT politikasının <KnownHeaders> öğesinin de bu üstbilgiyi listelediği kontrol edilir. VerifyJWT politikasının crit içinde bulduğu ve <KnownHeaders> içinde listelenmeyen tüm üstbilgiler, VerifyJWT 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 CustomClaims öğesi eklenir. Bu öğe işlevsel değildir ve yoksayılır. Bunun yerine kullanılması gereken doğru öğe <AdditionalClaims>'dir. Kullanıcı arayüzü, doğru öğeleri daha sonra ekleyecek şekilde güncellenecektir.

<ExpiresIn>

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

JWT'nin geçerlilik süresini milisaniye, saniye, dakika, saat veya gün cinsinden belirtir.

<Id>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Politikada belirtilen referans verilen değişkenlerden herhangi biri çözümlenemediğinde politikanın hata vermesini istiyorsanız yanlış olarak ayarlayın. Çözülemeyen değişkenleri boş dize (null) olarak değerlendirmek için true olarak ayarlayın.

<Issuer>

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

Politika,iss adlı bir talep içeren ve değeri belirtilen değere ayarlanmış bir JWT oluşturur. JWT'nin yayınlayıcısını tanımlayan talep. Bu, RFC7519'da belirtilen kayıtlı talep grubundan 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>

Kodun geçerli olacağı zamanı belirtir. Belirtilen zamana kadar jeton geçersizdir. Mutlak bir zaman değeri veya jetonun oluşturulduğu zamana göreceli bir zaman belirtebilirsiniz.

Mutlak zaman değerleri için NotBefore öğesinin geçerli zaman değerleri

Göreceli zaman değerleri için bir tam sayı ve bir zaman aralığı belirtin. Örneğin:

• 10 saniye
• 60m
• 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 başlığına eklenecek anahtar kimliğini (kid) belirtir. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 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 olduğunda kullanın.

<PrivateKey/Value>

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

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

<SecretKey/Id>

<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 başlığına eklenecek anahtar kimliğini (kid) belirtir. Yalnızca algoritma HS256/HS384/HS512 olduğunda kullanın.

<SecretKey/Value>

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

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

Edge, HS256/HS384/HS512 algoritmaları için minimum anahtar gücü uygular. HS256 için minimum anahtar uzunluğu 32 bayt, HS384 için 48 bayt ve HS512 için 64 bayttır. Daha düşük güçlü bir anahtar kullanmak ç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ğerle ayarlanan bir sub talebi içeren bir JWT oluşturur.Bu talep, JWT'nin konusunu tanımlar veya konuyla ilgili bir ifade oluşturur. Bu, RFC7519'da belirtilen standart talep grubundan biridir.

Akış değişkenleri

JWT oluşturma 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, çalışma zamanı hatası oluştuğunda ayarlanır. Daha fazla bilgi için Bilmeniz gerekenler hakkında daha fazla bilgi edinin.

Örnek hata yanıtı

Hata giderme için en iyi uygulama, hatanın errorcode kısmını yakalamaktır tıklayın. Değişebileceği için faultstring içindeki metne güvenmeyin.

Örnek hata kuralı

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