Sử dụng OAuth2 để truy cập API Edge

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

Apigee Edge cho phép bạn thực hiện các lệnh gọi API Edge được xác thực bằng mã thông báo OAuth2. Theo mặc định, tính năng hỗ trợ cho OAuth2 sẽ được bật trên Edge cho các tài khoản Cloud. Nếu đang dùng Edge cho Đám mây riêng tư, thì bạn không thể dùng OAuth2 khi chưa thiết lập SAML hoặc LDAP trước tiên.

Cách hoạt động của OAuth2 (với API Apigee Edge)

Các lệnh gọi đến API Apigee Edge đều yêu cầu xác thực để chúng tôi có thể chắc chắn rằng bạn chính là người như bạn nói. Để xác thực bạn, chúng tôi yêu cầu bạn phải gửi mã truy cập OAuth2 cùng với yêu cầu truy cập API.

Ví dụ: nếu muốn biết thông tin chi tiết về một tổ chức trên Edge, bạn sẽ gửi yêu cầu tới một URL như sau:

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

Nhưng bạn không thể gửi yêu cầu đó mà không cho chúng tôi biết bạn là ai. Nếu không, bất kỳ ai đều có thể xem thông tin chi tiết về tổ chức của bạn.

Đây là nơi OAuth2 xuất hiện: để xác thực bạn, chúng tôi cũng cần bạn gửi cho chúng tôi mã truy cập trong yêu cầu đó. Mã truy cập cho chúng tôi biết bạn là ai để chúng tôi có thể chắc chắn rằng bạn được phép xem thông tin chi tiết về tổ chức.

Rất may là bạn có thể nhận được mã thông báo bằng cách gửi thông tin xác thực đến dịch vụ Edge OAuth2. Dịch vụ này phản hồi bằng mã truy cập và làm mới.

Quy trình OAuth2: Yêu cầu ban đầu

Hình ảnh sau đây cho thấy quy trình OAuth2 khi bạn truy cập vào API Edge lần đầu tiên:

Quy trình OAuth: Yêu cầu đầu tiên
Hình 1: Luồng OAuth: Yêu cầu đầu tiên

Như Hình 1 cho thấy, khi bạn gửi yêu cầu ban đầu đến Edge API:

  1. Bạn yêu cầu mã truy cập. Bạn có thể thực hiện việc này bằng API Edge, acurl hoặc get_token. Ví dụ:
    get_token
    Enter username:
    ahamilton@apigee.com
    Enter the password for user 'ahamilton@apigee.com'
    [hidden input]
    Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
    123456
  2. Dịch vụ OAuth2 của Edge phản hồi bằng mã truy cập và in mã đó ra stdout; ví dụ:
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
    AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
    NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
    GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
    ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
    RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
    420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
    2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    Các tiện ích acurlget_token sẽ tự động lưu mã truy cập và làm mới vào ~/.sso-cli (Mã làm mới không được ghi vào stdout.) Nếu sử dụng dịch vụ Edge OAuth2 để nhận mã thông báo, bạn cần lưu các mã này để tự sử dụng sau này.

  3. Bạn gửi một yêu cầu đến API Edge kèm mã truy cập. acurl sẽ tự động đính kèm mã thông báo; ví dụ:
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    Nếu bạn dùng một ứng dụng HTTP khác, hãy nhớ thêm mã truy cập. Ví dụ:

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"
  4. Edge API thực thi yêu cầu của bạn và thường trả về phản hồi kèm theo dữ liệu.

Quy trình OAuth2: Các yêu cầu tiếp theo

Trong các yêu cầu tiếp theo, bạn không cần phải trao đổi thông tin xác thực của mình để lấy mã thông báo. Thay vào đó, bạn có thể chỉ cần bao gồm mã truy cập mà bạn đã có, miễn là mã đó chưa hết hạn:

Luồng OAuth: Các yêu cầu tiếp theo
Hình 2: Luồng OAuth: Các yêu cầu tiếp theo

Như Hình 2 cho thấy, khi bạn đã có mã truy cập:

  1. Bạn gửi một yêu cầu đến API Edge kèm mã truy cập. acurl sẽ tự động đính kèm mã thông báo. Nếu sử dụng các công cụ khác, bạn cần thêm mã thông báo theo cách thủ công.
  2. Edge API thực thi yêu cầu của bạn và thường trả về phản hồi kèm theo dữ liệu.

Quy trình OAuth2: Khi mã truy cập của bạn hết hạn

Khi mã truy cập hết hạn (sau 12 giờ), bạn có thể sử dụng mã làm mới để nhận mã truy cập mới:

Quy trình OAuth: Làm mới mã truy cập
Hình 3: Luồng OAuth: Làm mới mã truy cập

Như Hình 3 cho thấy, khi mã truy cập của bạn đã hết hạn:

  1. Bạn gửi yêu cầu tới API Edge nhưng mã truy cập của bạn đã hết hạn.
  2. Edge API từ chối yêu cầu của bạn là trái phép.
  3. Bạn gửi một mã làm mới đến dịch vụ Edge OAuth2. Nếu bạn đang dùng acurl, thì quá trình này sẽ tự động được thực hiện cho bạn.
  4. Dịch vụ OAuth2 của Edge phản hồi bằng mã truy cập mới.
  5. Bạn gửi một yêu cầu tới API Edge bằng mã truy cập mới.
  6. Edge API thực thi yêu cầu của bạn và thường trả về phản hồi kèm theo dữ liệu.

Lấy mã thông báo

Để lấy mã truy cập mà bạn có thể gửi tới API Edge, bạn có thể dùng các tiện ích Apigee sau, ngoài một tiện ích như curl:

  • Tiện ích get_token: Trao đổi thông tin xác thực Apigee của bạn để lấy quyền truy cập và mã làm mới mà bạn có thể dùng để gọi API Edge.
  • Tiện ích acurl: Cung cấp một trình bao bọc tiện lợi xung quanh lệnh curl tiêu chuẩn. Tạo các yêu cầu HTTP cho API Edge, lấy mã truy cập và làm mới từ get_token, đồng thời chuyển mã truy cập đến API Edge.
  • Điểm cuối mã thông báo trong dịch vụ Edge OAuth2: Trao đổi thông tin xác thực Apigee của bạn để lấy mã truy cập và làm mới thông qua lệnh gọi đến API Edge.

Các tiện ích này sẽ trao đổi thông tin xác thực của tài khoản Apigee bạn (địa chỉ email và mật khẩu) để lấy mã thông báo trong thời gian như sau:

  • Mã truy cập sẽ hết hạn sau 12 giờ.
  • Mã làm mới sẽ hết hạn sau 30 ngày.

Do đó, sau khi thực hiện lệnh gọi API thành công bằng acurl hoặc get_token, bạn có thể tiếp tục sử dụng cặp mã thông báo này trong 30 ngày. Sau khi hết hạn, bạn phải nhập lại thông tin đăng nhập và nhận mã thông báo mới.

Truy cập vào API Edge bằng OAuth2

Để truy cập vào API Edge, bạn cần gửi yêu cầu đến một điểm cuối API và kèm theo mã truy cập. Bạn có thể thực hiện việc này bằng bất kỳ ứng dụng HTTP nào, bao gồm cả tiện ích dòng lệnh như curl, giao diện người dùng dựa trên trình duyệt như Postman hoặc một tiện ích Apigee như acurl.

Bạn có thể truy cập vào API Edge bằng acurlcurl trong các phần tiếp theo.

Sử dụng acurl

Để truy cập vào API Edge bằng acurl, yêu cầu ban đầu của bạn phải bao gồm thông tin đăng nhập của bạn. Dịch vụ OAuth2 của Edge phản hồi bằng mã truy cập và làm mới. acurl lưu mã thông báo cục bộ.

Trong các yêu cầu tiếp theo, acurl sẽ sử dụng mã thông báo đã lưu trong ~/.sso-cli để bạn không phải thêm lại thông tin xác thực của mình cho đến khi mã thông báo hết hạn.

Ví dụ sau đây cho thấy một yêu cầu acurl ban đầu lấy thông tin chi tiết về tổ chức "ahamilton-eval":

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

Ngoài việc nhận thông tin chi tiết về tổ chức, ví dụ này còn cho thấy yêu cầu thứ hai nhận danh sách các chính sách trong proxy API "helloworld". Yêu cầu thứ hai sử dụng cách rút gọn "o" cho "tổ chức" trong URL.

Xin lưu ý rằng acurl sẽ tự động chuyển mã truy cập vào yêu cầu thứ hai. Bạn không cần truyền thông tin xác thực người dùng sau khi acurl lưu trữ mã thông báo OAuth2. Phương thức này nhận mã thông báo từ ~/.sso-cli cho các lệnh gọi tiếp theo.

Để biết thêm thông tin, hãy xem phần Sử dụng acurl để truy cập vào API Edge.

Sử dụng curl

Bạn có thể dùng curl để truy cập vào API Edge. Để làm điều này, trước tiên, bạn phải có được mã truy cập và làm mới. Bạn có thể nhận các mã này bằng một tiện ích như get_token hoặc dịch vụ Edge OAuth2..

Sau khi lưu thành công mã truy cập, hãy chuyển mã truy cập đó vào tiêu đề Authorization của các lệnh gọi đến Edge API, như trong ví dụ sau:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

Mã truy cập có hiệu lực trong 12 giờ kể từ khi được phát hành. Sau khi mã truy cập hết hạn, bạn có thể sử dụng mã làm mới trong 30 ngày để cấp một mã truy cập khác mà không cần thông tin xác thực. Bạn chỉ nên yêu cầu một mã truy cập mới sau khi mã thông báo giới thiệu hết hạn, thay vì nhập thông tin xác thực và thực hiện yêu cầu mới cho mỗi lệnh gọi API.

Thời hạn của mã thông báo

Sau khi mã truy cập hết hạn, bạn có thể sử dụng mã làm mới để nhận mã truy cập mới mà không phải gửi lại thông tin đăng nhập của mình.

Cách bạn làm mới mã truy cập của mình phụ thuộc vào công cụ bạn đang sử dụng:

  • acurl: Bạn không cần làm gì cả. acurl tự động làm mới mã truy cập khi bạn gửi yêu cầu có chứa một yêu cầu lỗi thời.
  • get_token: Gọi get_token để làm mới mã truy cập.
  • Dịch vụ Edge OAuth2: Gửi một yêu cầu bao gồm:
    • Làm mới mã thông báo
    • Đã đặt tham số biểu mẫu grant_type thành "refresh_token"

OAuth2 cho người dùng sử dụng máy

Bạn có thể sử dụng các tiện ích acurlget_token để tập lệnh cho quyền truy cập tự động vào các API Edge bằng phương thức xác thực OAuth2 cho người dùng máy. Ví dụ sau đây cho thấy cách sử dụng get_token để yêu cầu mã truy cập và sau đó thêm giá trị mã thông báo vào lệnh gọi curl:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

Ngoài ra, bạn có thể kết hợp yêu cầu mã thông báo và lệnh gọi curl bằng tiện ích acurl. Ví dụ:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'
  

Trong cả hai ví dụ, việc đặt giá trị -m thành một chuỗi trống sẽ ngăn người dùng máy được nhắc nhập mã MFA.