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

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về 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ợ tính năng SSO cho giao diện người dùng và API của Edge, ngoài những 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 API Edge.

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 API Edge. Khi gọi API Edge, bạn sẽ đưa 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 API Edge là ở cách bạn nhận được mã thông báo. Với SAML, bạn phải cung cấp những thông tin sau đây khi nhận cặp mã thông báo:

  1. Khu vực:Người dùng Edge dành cho Cloud công cộng phải tham chiếu đến tên khu vực của mình khi nhận mã thông báo.
  2. Mật mã: Bao gồm mật mã một lần khi yêu cầu cặp mã truy cập/làm mới.

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

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

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

Nhận mã truy cập bằng get_token

Bạn có thể dùng tiện ích get_token để trao đổi thông tin xác thực nhằm truy cập vào OAuth2 và mã thông báo làm mới mà bạn sử 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. URL đăng nhập có dạng như sau:
    https://zoneName.login.apigee.com

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

    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 được nhắc truy cập vào URL hiển thị để nhận 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 không đă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ã một lần vẫn có hiệu lực cho đến khi bạn làm mới URL đó để nhận mật mã mới hoặc bạn sử 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 lấy mã thông báo OAuth2, in mã truy cập vào stdout, đồng thời ghi mã truy cập và làm mới vào ~/.sso-cli.

  4. Hãy gọi API Edge và chuyển mã truy cập trong tiêu đề Authorization: Bearer như ví dụ sau:
    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 cụ thể. Để 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 API về API API 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ật mã mới thì mới có thể tạo mã truy cập OAuth2 mới.

Nhận mã truy cập thông qua dịch vụ Edge OAuth2

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

Cách nhận cặp mã thông báo với API Edge:

  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 vùng có tên "acme", hãy truy cập URL sau:

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

    Nếu gần đây bạn không đă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ã một lần, dùng làm thông tin xác thực 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ã với get_token để tạo mã truy cập. Ví dụ:

  2. Gửi yêu cầu đến API Edge, như trong ví dụ sau:
    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 xác thực của bạn để được uỷ quyền.

    Trong trường hợp:

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

    Lệnh gọi sẽ in mã truy cập và làm mới ra 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:

  • Phần nội dung của yêu cầu này có 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 giá trị chính xác này).
  • Loại yêu cầu là POST.

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

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

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

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

Với 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 để nhận thông tin chi tiết về tổ chức nhất định. Để biết danh sách đầy đủ các điểm cuối API Edge, hãy xem Tài liệu tham khảo API API Edge.

Để biết thêm các phương thức gọi API, bao gồm cả cách đảm bảo rằng mã thông báo luôn mới, hãy xem phần Truy cập vào API Edge 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 acurlget_token để viết tập lệnh cho quyền 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 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 '' --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ã 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/...'