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

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

SAML hỗ trợ môi trường đăng nhập một lần (SSO). Khi sử dụng SAML với Edge, bạn có thể hỗ trợ SSO cho Giao diện người dùng và API Edge ngoài mọi dịch vụ khác mà bạn cung cấp và cũng hỗ trợ SAML.

Điều kiện tiên quyết: Bạn phải bật SAML cho ít nhất một tổ chức thì mới có thể dùng SAML để truy cập vào Edge API.

Sự khác biệt giữa SAML và OAuth2

Sau khi thiết lập SAML, việc sử dụng SAML rất giống với việc sử dụng OAuth2 để truy cập vào Edge API. Khi gọi Edge API, bạn sẽ thêm mã truy cập OAuth2 vào yêu cầu của mình.

Điểm khác biệt chính giữa SAML và OAuth2 khi truy cập vào Edge API là cách bạn nhận được mã thông báo. Với SAML, bạn phải thêm những thông tin sau khi nhận cặp mã thông báo:

  1. Vùng: Người dùng Edge cho Đám mây công cộng phải tham chiếu tên vùng của họ khi nhận mã thông báo.
  2. Mật mã: Thêm mật mã một lần khi yêu cầu một cặp mã truy cập/mã làm mới.

SAML sử dụng cùng các điểm cuối trên dịch vụ Edge OAuth2, cùng với tên miền thích hợp.

Để nhận mã truy cập bằng SAML, bạn có thể sử dụng một trong những phương thức sau đây (được mô tả trong phần này):

Ngoài ra, bạn có thể tự động hoá quy trình tạo mã thông báo cho người dùng máy, như mô tả trong phần Tự động hoá quy trình tạo mã thông báo.

Lấy mã truy cập bằng get_token

Bạn có thể dùng tiện ích get_token để trao đổi thông tin đăng nhập của mình để lấy mã truy cập và mã làm mới OAuth2 mà bạn dùng với SAML.

Cách lấy mã truy cập bằng get_token:

  1. Đặt biến môi trường SSO_LOGIN_URL thành URL đăng nhập của bạn. URL đăng nhập có dạng như sau: 
    https://zoneName.login.apigee.com

    Ví dụ: đối với một vùng có tên "acme", hãy đặt SSO_LOGIN_URL thành "https://acme.login.apigee.com", như ví dụ sau đây minh hoạ:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. Gọi get_token để lấy mã truy cập OAuth2: 
    get_token -u me@example.com

    Bạn sẽ được nhắc truy cập vào URL hiển thị để lấy mật mã một lần:

    Get passcode from https://acme.login.apigee.com/passcode
[Note:  Passcode can be used only time time and expires] Input passcode (no spaces) and then press ENTER:

    Nếu gần đây bạn chưa đăng nhập thông qua nhà cung cấp danh tính, bạn sẽ được nhắc đăng nhập.

    URL này trả về một mật mã một lần vẫn còn hiệu lực cho đến khi bạn làm mới URL đó để lấy mật mã mới hoặc bạn dùng mật mã đó với get_token để tạo mã truy cập. Ví dụ:

  3. Nhập mật mã. Tiện ích get_token sẽ lấy mã thông báo OAuth2, in mã truy cập vào stdout và ghi mã truy cập và mã làm mới vào ~/.sso-cli.

  4. Gọi Edge API và truyền mã truy cập trong tiêu đề Authorization: Bearer, như ví dụ sau đây minh hoạ: 
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

    Bạn có thể sao chép giá trị của mã truy cập từ stdout.

    Ví dụ này lấy thông tin chi tiết về tổ chức đã cho. Để xem danh sách đầy đủ các điểm cuối API quản lý, hãy xem Tài liệu tham khảo về API Apigee Edge.

Khi mã truy cập hết hạn, bạn có thể gọi lại get_token để nhận mã truy cập mới. Ví dụ:

get_token -u me@example.com

Bạn sẽ không được nhắc nhập mật mã mới cho đến khi mã làm mới hết hạn.

Khi mã làm mới hết hạn, get_token sẽ nhắc bạn nhập mật mã mới. Bạn phải tạo một mã truy cập mới trước khi có thể tạo mã thông báo truy cập OAuth2 mới.

Lấy mã truy cập bằng dịch vụ Edge OAuth2

Bạn có thể sử dụng dịch vụ Edge OAuth2 để nhận mã truy cập mà bạn dùng với SAML. Để xác thực bằng Edge API, bạn sử dụng một mật mã trong yêu cầu ban đầu để nhận một cặp mã thông báo truy cập/làm mới và sử dụng lại để nhận một cặp mã thông báo mới.

Cách lấy một cặp mã thông báo bằng Edge API:

  1. Trong trình duyệt, hãy chuyển đến URL sau để lấy mật mã một lần: 
    https://zoneName.login.apigee.com/passcode

    Ví dụ: đối với một vùng có tên "acme", hãy truy cập vào URL sau:

    https://acme.login.apigee.com/passcode

    Nếu gần đây bạn chưa đăng nhập thông qua nhà cung cấp danh tính, bạn sẽ được nhắc đăng nhập.

    URL này trả về một mật mã một lần đóng vai trò là thông tin đăng nhập của bạn để nhận mã thông báo và vẫn có hiệu lực cho đến khi bạn làm mới URL để lấy mật mã mới, hoặc bạn có thể sử dụng mật mã này với get_token để tạo mã truy cập. Ví dụ:

  2. Gửi yêu cầu đến Edge API, như ví dụ sau đây minh hoạ: 
    curl https://zoneName.login.apigee.com/oauth/token \
      -s \
      -H "Accept: application/json" \
      -d 'grant_type=password&response_type=token&passcode=passcode'

    passcode đóng vai trò là thông tin đăng nhập của bạn để uỷ quyền.

    Trong trường hợp:

    • Tiêu đề Authorization là "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (sử dụng chính xác giá trị này).
    • Loại yêu cầu là POST.
    • Nội dung yêu cầu chứa những thông tin sau:
      • grant_type là "mật khẩu".
      • response_type là "token".
      • passcode, trong đó passcode là mật mã được trả về ở bước trước.

    Lệnh gọi này in mã truy cập và mã làm mới lên màn hình.

Cách làm mới mã truy cập:

Gửi yêu cầu đến https://zoneName.login.apigee.com/oauth/token, như trong ví dụ sau:

curl https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

Trong trường hợp:

  • Nội dung yêu cầu chứa những thông tin sau:
    • grant_type là "refresh_token".
    • refresh_token là giá trị của mã làm mới.
  • Tiêu đề Authorization là "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (sử dụng chính xác giá trị này).
  • Loại yêu cầu là POST.

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

Bạn có thể sử dụng các công cụ như curl hoặc tiện ích Apigee acurl để truy cập vào Edge API.

Với curl, bạn gọi Edge API và truyền mã truy cập trong tiêu đề Authorization: Bearer, như trong ví dụ sau:

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

Khi dùng acurl, bạn không cần chỉ định tiêu đề Authorization. Ví dụ:

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

Các ví dụ này gọi một điểm cuối API Edge để lấy thông tin chi tiết về tổ chức đã cho. Để xem danh sách đầy đủ các điểm cuối của API Edge, hãy xem Tài liệu tham khảo về API Apigee Edge.

Để biết thêm các phương thức gọi API, bao gồm cả cách đảm bảo mã thông báo của bạn luôn mới, hãy xem phần Truy cập vào Edge API bằng OAuth2.

Người dùng máy trong các vùng SAML

Bạn có thể sử dụng các tiện ích acurl và get_token để tạo tập lệnh truy cập tự động vào các API Edge cho người dùng máy trong các vùng SAML. Ví dụ sau đây cho biết cách sử dụng get_token để yêu cầu mã truy cập, 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 '' --force-basic-auth)
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

Trong ví dụ trên, việc đặt giá trị của -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. Việc sử dụng cờ --force-basic-auth sẽ ghi đè lời nhắc tiêu chuẩn cho một mật mã do các yêu cầu có vùng SAML kích hoạt.

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 '' --force-basic-auth 'https://api.enterprise.apigee.com/v1/organizations/...'