Chính sách GenerateJWT

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Nội dung

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

Video

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

Mẫu

• Tạo 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 JWT được ký bằng thuật toán HS256

Chính sách mẫu này tạo 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à phần dữ liệu thực tế của JWT, sau đó ký JWT bằng chữ ký số. Hãy xem video ở trên để biết ví dụ đầy đủ, bao gồm cả cách đưa ra 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 khai báo tiêu chuẩn theo quy cách JWT, bao gồm cả thời gian hết hạn là 1 giờ, cũng như một khai báo bổ sung. Bạn có thể đưa thêm bao nhiêu tuyên bố bổ sung tuỳ thích. Hãy xem phần 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 kết quả sẽ có tiêu đề này …

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

… và sẽ có một tải trọng với nội dung 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 khai báo iat, exp và jti sẽ khác nhau.

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

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

Khi thao tác chính sách này được kích hoạt, Edge sẽ mã hoá và ký điện tử JWT, bao gồm cả các khai báo. Để tìm hiểu về các phần của JWT và cách mã hoá cũng như ký các phần đó, 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 các phần tử chính

Các phần tử mà bạn dùng để chỉ định khoá dùng để tạo JWT phụ thuộc vào thuật toán đã chọn, như 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 về phần tử cho Generate JWT

Tài liệu tham khảo về chính sách này 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 Mẫu để xem các ví dụ minh hoạ cấu hình cho những trường hợp sử dụng cụ thể.

Các 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">

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<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 ra một JWT chứa một yêu cầu aud được đặt thành giá trị đã chỉ định. Khai báo này xác định những người nhận mà JWT hướng đến. Đây là một trong những giá trị xác nhận đã đăng ký được đề cập trong RFC7519.

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

Cho phép bạn chỉ định(các) cặp tên/giá trị của yêu cầu bổ sung trong tải trọng của JWT. Bạn có thể chỉ định rõ ràng yêu cầu dưới dạng chuỗi, số, boolean, bản đồ hoặc mảng. Bản đồ 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 yêu cầu xác nhận quyền sở hữu.
• ref – (Không bắt buộc) Tên của một biến luồng. Nếu có, chính sách sẽ sử dụng giá trị của biến này làm yêu cầu. Nếu bạn chỉ định cả thuộc tính ref và giá trị khai báo rõ ràng, thì giá trị rõ ràng 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: chuỗi (mặc định), số, boolean hoặc bản đồ
• array – (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 của yêu cầu xác nhận quyền sở hữu sẽ được đặt tĩnh khi bạn định cấu hình chính sách. Ngoài ra, bạn có thể truyền một đối tượng JSON để chỉ định tên của các yêu cầu. Vì đối tượng JSON được truyền dưới dạng một biến, nên tên của các xác nhận quyền sở hữu trong JWT được 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 một đố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 khai báo trong đối tượng JSON.

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

Đặt(các) cặp tên/giá trị của yêu cầ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 yêu cầu xác nhận quyền sở hữu.
• ref – (Không bắt buộc) Tên của một biến luồng. Nếu có, chính sách sẽ sử dụng giá trị của biến này làm yêu cầu. Nếu bạn chỉ định cả thuộc tính ref và giá trị khai báo rõ ràng, thì giá trị rõ ràng 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: chuỗi (mặc định), số, boolean hoặc bản đồ
• array – (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. Phần đầu crit là một mảng tên phần đầu mà người nhận JWT phải biết và nhận dạng được. Ví dụ:

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

Trong thời gian chạy, chính sách VerifyJWT sẽ kiểm tra tiêu đề crit. Đối với mỗi mục được liệt kê trong tiêu đề crit, nó 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 đề đó. Mọi tiêu đề mà chính sách VerifyJWT tìm thấy trong crit không có trong <KnownHeaders> đều khiến chính sách VerifyJWT không thành công.

<CustomClaims>

Lưu ý: Hiện tại, phần tử CustomClaims sẽ được chèn khi bạn thêm 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à sẽ 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 sẽ được cập nhật để chèn các phần tử chính xác vào thời điểm khác.

<ExpiresIn>

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

Chỉ định thời gian tồn tại của JWT theo mili giây, giây, phút, giờ hoặc ngày.

<Id>

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

Tạo một JWT có xác nhận quyền sở hữu jti cụ thể. Khi giá trị văn bản và thuộc tính ref đều trống, chính sách sẽ tạo một jti chứa UUID ngẫu nhiên. Thông báo nhận dạng JWT (jti) là giá trị nhận dạng duy nhất cho 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 đưa ra lỗi khi không thể phân giải bất kỳ biến nào được tham chiếu mà bạn chỉ định trong chính sách. Đặt thành true để coi mọi biến không phân giải được là một chuỗi trống (rỗng).

<Issuer>

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

Chính sách này tạo ra một JWT chứa một xác nhận quyền sở hữu có tên là iss,với một giá trị được đặt thành giá trị đã chỉ định. Một khai báo xác định tổ chức phát hành JWT. Đây là một trong những tập hợp các khai báo đã đăng ký đượ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 gian đượ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 mã thông báo được tạo.

Giá trị thời gian hợp lệ cho phần tử NotBefore đối với các 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
• 60m
• 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, giá trị 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ã khoá (kid) cần đưa vào tiêu đề JWT. Chỉ sử dụng khi thuật toán là một trong các thuật toán RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.

<PrivateKey/Password>

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

Nếu cần, hãy chỉ định mật khẩu mà chính sách sẽ dùng để giải mã khoá riêng tư. Sử dụng thuộc tính ref để truyền khoá trong một biến luồng. Chỉ sử dụng khi thuật toán là một trong các thuật toán 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á dạng PEM dùng để ký JWT. Sử dụng thuộc tính ref để truyền khoá trong một biến luồng. Chỉ sử dụng khi thuật toán là một trong các thuật toán 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) cần đưa vào tiêu đề JWT của một 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 thuật toán 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 thuật toán HS256/HS384/HS512. Sử dụng thuộc tính ref để truyền khoá trong một biến luồng.

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

<Tiêu đề>

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

<Subject ref="flow_variable" />

Ví dụ:

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

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

Biến dò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 bài viết Những điều bạn cần biết về lỗi chính sách.

Ví dụ về phản hồi khi gặp lỗi

Để xử lý lỗi, phương pháp hay nhất là bẫy phần errorcode của lỗi của bạn. Đừ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>