Chính sách GenerateJWT

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Nội dung

Tạo JWT có chữ ký kèm theo một tập hợp các thông báo xác nhận quyền sở hữu có thể định cấu hình. Sau đó, JWT có thể được trả về cho ứng dụng khách, được truyền đến các mục tiêu phụ trợ hoặc dùng theo những cách khác. Hãy xem bài viết Tổng quan về các chính sách JWS và JWT để nắm được nội dung giới thiệu chi tiết.

Video

Xem video ngắn để tìm hiểu cách tạo JWT có chữ ký.

Mẫu

• Tạo một JWT được ký bằng thuật toán HS256
• Tạo một JWT được ký bằng thuật toán RS256

Tạo một JWT được ký bằng thuật toán HS256

Chính sách mẫu này tạo ra một JWT mới và ký bằng thuật toán HS256. HS256 dựa vào một khoá bí mật dùng chung để ký và xác minh chữ ký.

Khi hành động chính sách này được kích hoạt, Edge sẽ mã hoá tiêu đề và tải trọng JWT, sau đó ký JWT dưới dạng kỹ thuật số. Xem video ở trên để biết ví dụ hoàn chỉnh, bao gồm cả cách gửi yêu cầu đối với chính sách.

Cấu hình chính sách ở đây sẽ tạo một JWT với một tập hợp các thông báo xác nhận quyền sở hữu chuẩn như được xác định trong bản đặc tả JWT, bao gồm cả thời gian hết hạn là 1 giờ cũng như một xác nhận bổ sung. Bạn có thể thêm bao nhiêu thông báo xác nhận quyền sở hữu bổ sung tuỳ thích. Hãy xem Tài liệu tham khảo về phần tử để biết thông tin chi tiết về các yêu cầu và lựa chọn cho từng phần tử trong chính sách mẫu này.

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

JWT thu được sẽ có tiêu đề này ...

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

... và sẽ có tải trọng với nội dung giống như sau:

{ 
  "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."
}

Giá trị của các thông báo xác nhận quyền sở hữu iat, exp và jti sẽ khác nhau.

Tạo một JWT được ký bằng thuật toán RS256

Chính sách trong ví dụ này tạo ra một JWT mới và ký bằng thuật toán RS256. Việc tạo chữ ký RS256 cần dựa trên khoá riêng tư RSA và khoá này phải được cung cấp ở dạng được mã hoá PEM. Xem video ở trên để biết ví dụ hoàn chỉnh, bao gồm cả cách gửi yêu cầu đối với chính sách.

Khi hành động này của chính sách được kích hoạt, Edge sẽ mã hoá và ký JWT dưới dạng kỹ thuật số, bao gồm cả các thông báo xác nhận quyền sở hữu. Để tìm hiểu về các thành phần của JWT cũng như cách các thành phần đó được mã hoá và ký, hãy tham khảo RFC7519.

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

Thiết lập thành phần chính

Các phần tử mà bạn sử dụng để chỉ định khoá dùng để tạo JWT phụ thuộc vào thuật toán đã chọn, như minh hoạ trong bảng sau:

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

Tài liệu tham khảo phần tử cho Tạo JWT

Tài liệu tham khảo về chính sách mô tả các phần tử và thuộc tính của chính sách Tạo JWT.

Lưu ý: Cấu hình sẽ khác nhau đôi chút tuỳ thuộc vào thuật toán mã hoá mà bạn sử dụng. Hãy tham khảo phần Ứng dụng mẫu để xem các ví dụ minh hoạ cấu hình cho các trường hợp sử dụng cụ thể.

Những thuộc tính áp dụng cho phần tử cấp cao nhất

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

Những thuộc tính sau đây là những thuộc tính chung của tất cả phần tử mẹ của chính sách.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Sử dụng cùng với thuộc tính tên để gắn nhãn cho chính sách bằng một tên khác bằng ngôn ngữ tự nhiên trong trình chỉnh sửa proxy giao diện người dùng quản lý.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Chỉ định thuật toán mã hoá để ký mã thông báo.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

Chính sách này tạo một JWT chứa thông báo xác nhận quyền sở hữu aud được đặt thành giá trị đã chỉ định. Thông báo xác nhận quyền sở hữu này xác định người nhận mục đích của tệp JWT. Đây là một trong những thông báo xác nhận quyền sở hữu đã được đăng ký và được đề cập trong RFC7519.

<AdditionalClaims/Claim> (Xác nhận bổ sung/Xác nhận quyền sở hữu>)

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

Cho phép bạn chỉ định(các) cặp giá trị/tên xác nhận quyền sở hữu bổ sung trong tải trọng của JWT. Bạn có thể chỉ định rõ ràng thông báo dưới dạng chuỗi, số, boolean, tệp ánh xạ hoặc mảng. Tệp ánh xạ chỉ đơn giản là một tập hợp các cặp tên/giá trị.

Phần tử <Claim> có các thuộc tính sau:

• name – (Bắt buộc) Tên của thông báo xác nhận quyền sở hữu.
• ref – (Không bắt buộc) Tên của biến luồng. Nếu có, chính sách này sẽ sử dụng giá trị của biến này làm thông báo xác nhận quyền sở hữu. Nếu bạn chỉ định cả thuộc tính ref và giá trị tuyên bố rõ ràng, thì giá trị tường minh sẽ là giá trị mặc định và được dùng nếu biến luồng được tham chiếu không được phân giải.
• type – (Không bắt buộc) Một trong các loại: string (mặc định), number, boolean hoặc map
• mảng – (Không bắt buộc) Đặt thành true để cho biết liệu giá trị có phải là một mảng các loại hay không. Mặc định: false.

Khi bạn thêm phần tử <Claim>, tên thông báo xác nhận quyền sở hữu sẽ được đặt cố định khi bạn định cấu hình chính sách. Ngoài ra, bạn có thể truyền đối tượng JSON để chỉ định tên xác nhận quyền sở hữu. Vì đối tượng JSON được truyền dưới dạng biến nên tên xác nhận quyền sở hữu trong JWT đã tạo sẽ được xác định trong thời gian chạy.

Ví dụ:

<AdditionalClaims ref='json_claims'/>

Trong đó biến json_claims chứa đối tượng JSON ở dạng:

{
  "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 }
  }
}

JWT được tạo bao gồm tất cả các xác nhận quyền sở hữu trong đối tượng JSON.

<AdditionalHeaders/Claim> (Thông tin bổ sung/Xác nhận quyền sở hữu>)

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

Đặt(các) cặp tên/giá trị xác nhận quyền sở hữu bổ sung vào tiêu đề cho JWT.

Phần tử <Claim> có các thuộc tính sau:

• name – (Bắt buộc) Tên của thông báo xác nhận quyền sở hữu.
• ref – (Không bắt buộc) Tên của biến luồng. Nếu có, chính sách này sẽ sử dụng giá trị của biến này làm thông báo xác nhận quyền sở hữu. Nếu bạn chỉ định cả thuộc tính ref và giá trị tuyên bố rõ ràng, thì giá trị tường minh sẽ là giá trị mặc định và được dùng nếu biến luồng được tham chiếu không được phân giải.
• type – (Không bắt buộc) Một trong các loại: string (mặc định), number, boolean hoặc map
• mảng – (Không bắt buộc) Đặt thành true để cho biết liệu giá trị có phải là một mảng các loại hay không. Mặc định: false.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Thêm tiêu đề quan trọng, crit, vào tiêu đề JWT. Tiêu đề crit là một dãy tên tiêu đề mà bộ thu JWT phải biết và nhận dạng. Ví dụ:

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

Trong thời gian chạy, chính sáchVerifyJWT kiểm tra tiêu đề crit. Đối với mỗi mục được liệt kê trong tiêu đề crit, hệ thống sẽ kiểm tra để đảm bảo rằng phần tử <KnownHeaders> của chính sách VerifyJWT cũng liệt kê tiêu đề đó. Bất kỳ tiêu đề nào mà chính sách VerifyJWT tìm thấy trong crit mà cũng không được liệt kê trong <KnownHeaders> đều sẽ khiến chính sách VerifyJWT không hoạt động.

<CustomClaims>

Lưu ý: Hiện tại, phần tử CustomClaims sẽ được chèn khi bạn thêm một chính sách GenerateJWT mới thông qua giao diện người dùng. Phần tử này không hoạt động và bị bỏ qua. Phần tử chính xác cần sử dụng thay thế là <AdditionalClaims> (Giao diện người dùng). Giao diện người dùng sẽ được cập nhật để chèn đúng phần tử sau này.

<ExpiresIn>

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

Chỉ định thời gian hoạt động của JWT tính bằng mili giây, giây, phút, giờ hoặc ngày.

<Mã nhận dạng>

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

Tạo JWT có xác nhận quyền sở hữu jti cụ thể. Khi cả giá trị văn bản và thuộc tính ref đều trống, chính sách này sẽ tạo một jti chứa UUID ngẫu nhiên. Tuyên bố xác nhận quyền sở hữu mã JWT (jti) là giá trị nhận dạng duy nhất của JWT. Để biết thêm thông tin về jti, hãy tham khảo RFC7519.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Đặt thành false nếu bạn muốn chính sách này báo lỗi khi không thể giải quyết mọi biến được tham chiếu đã chỉ định trong chính sách. Đặt thành true để coi mọi biến không thể phân giải là chuỗi trống (null).

<Issuer>

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

Chính sách này tạo một JWT chứa thông báo xác nhận quyền sở hữu có tên iss, với một giá trị được đặt thành giá trị đã chỉ định. Đơn khiếu nại xác định bên phát hành JWT. Đây là một trong nhóm thông báo xác nhận quyền sở hữu đã đăng ký và được đề cập trong RFC7519.

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

Chỉ định thời điểm mã thông báo có hiệu lực. Mã thông báo không hợp lệ cho đến thời điểm được chỉ định. Bạn có thể chỉ định giá trị thời gian tuyệt đối hoặc thời gian tương đối so với thời điểm tạo mã thông báo.

Giá trị thời gian hợp lệ cho phần tử NotBefore cho giá trị thời gian tuyệt đối

Đối với các giá trị thời gian tương đối, hãy chỉ định một số nguyên và một khoảng thời gian, ví dụ:

• 10 giây
• 60 triệu
• 12 giờ

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Chỉ định vị trí đặt JWT do chính sách này tạo. Theo mặc định, thuộc tính này được đặt vào biến luồng jwt.POLICYNAME.generated_jwt.

<PrivateKey/Id>

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

or

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

Chỉ định mã nhận dạng khoá (kid) để đưa vào tiêu đề JWT. Chỉ sử dụng khi thuật toán là một trong các giá trị RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.

<PrivateKey/Password>

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

Chỉ định mật khẩu mà chính sách nên sử dụng để giải mã khoá riêng tư, nếu cần. Sử dụng thuộc tính ref để truyền khoá vào một biến luồng. Chỉ sử dụng khi thuật toán là một trong các giá trị RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.

<PrivateKey/Value>

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

Chỉ định một khoá riêng tư được mã hoá PEM, dùng để ký JWT. Hãy sử dụng thuộc tính tham chiếu để truyền khoá vào một biến luồng. Chỉ sử dụng khi thuật toán là một trong các giá trị RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.

<SecretKey/Id>

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

or

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

Chỉ định giá trị nhận dạng khoá (kid) để đưa vào tiêu đề JWT của JWT được ký bằng thuật toán HMAC. Chỉ sử dụng khi thuật toán là một trong các mã HS256/HS384/HS512.

<SecretKey/Value>

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

Cung cấp khoá bí mật dùng để xác minh hoặc ký mã thông báo bằng thuật toán HMAC. Chỉ sử dụng khi thuật toán là một trong các mã HS256/HS384/HS512. Sử dụng thuộc tính ref để truyền khoá vào một biến luồng.

Edge thực thi độ mạnh khoá tối thiểu cho các thuật toán HS256/HS384/HS512. Độ dài khoá tối thiểu của HS256 là 32 byte, HS384 là 48 byte và đối với HS512 là 64 byte. Việc sử dụng khoá có độ mạnh thấp hơn gây ra lỗi thời gian chạy.

<Subject>

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

<Subject ref="flow_variable" />

Ví dụ:

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

Chính sách này tạo một JWT chứa thông báo xác nhận quyền sở hữu phụ, được đặt thành giá trị được chỉ định.Thông báo xác nhận quyền sở hữu này xác định hoặc đưa ra tuyên bố về chủ thể của JWT. Đây là một trong nhóm thông báo xác nhận quyền sở hữu tiêu chuẩn được đề cập trong RFC7519.

Biến luồng

Chính sách Tạo JWT không đặt các biến luồng.

Tham chiếu lỗi

Phần này mô tả các mã lỗi và thông báo lỗi được trả về, cũng như các biến lỗi do Edge đặt khi chính sách này kích hoạt lỗi. Thông tin này đóng vai trò quan trọng trong việc phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.

Lỗi thời gian chạy

Những lỗi này có thể xảy ra khi thực thi chính sách.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai proxy chứa chính sách này.

Biến lỗi

Các biến này được đặt khi xảy ra lỗi thời gian chạy. Để biết thêm thông tin, hãy xem Những điều bạn cần biết về lỗi chính sách.

Ví dụ về phản hồi lỗi

Để xử lý lỗi, phương pháp hay nhất là giữ phần errorcode của phản hồi lỗi. Đừng dựa vào văn bản trong faultstring vì văn bản này có thể thay đổi.

Ví dụ về quy tắc lỗ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>