Menggunakan OAuth2 untuk mengakses Edge API

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X. info

Apigee Edge memungkinkan Anda melakukan panggilan Edge API yang diautentikasi dengan token OAuth2. Dukungan untuk OAuth2 diaktifkan secara default di Edge untuk akun Cloud. Jika Anda menggunakan Edge untuk Private Cloud, Anda tidak dapat menggunakan OAuth2 tanpa pertama-tama menyiapkan SAML atau LDAP.

Cara kerja OAuth2 (dengan Apigee Edge API)

Panggilan ke Apigee Edge API memerlukan autentikasi agar kami dapat yakin bahwa Andalah yang Anda katakan begitu. Untuk mengautentikasi Anda, kami mewajibkan pengiriman token akses OAuth2 bersama permintaan Anda untuk mengakses API.

Misalnya, jika Anda ingin mendapatkan detail tentang suatu organisasi di Edge, Anda akan mengirim permintaan ke URL seperti berikut:

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

Namun, Anda tidak bisa begitu saja mengirimkan permintaan tersebut tanpa memberi tahu kami siapa Anda. Jika tidak, siapa saja dapat melihat detail organisasi Anda.

Di sinilah OAuth2 berperan: untuk mengautentikasi Anda, Anda harus mengirimkan token akses kepada kami. dalam permintaan tersebut. Token akses memberi tahu kami siapa Anda sehingga kami yakin bahwa Anda diizinkan untuk melihat detail organisasinya.

Untungnya, Anda bisa mendapatkan token dengan mengirimkan kredensial ke layanan OAuth2 Edge. Tujuan merespons dengan token akses dan refresh.

Alur OAuth2: Permintaan awal

Gambar berikut menunjukkan alur OAuth2 saat Anda mengakses Edge API untuk waktu:

Alur OAuth: Permintaan pertama
Gambar 1: Alur OAuth: Permintaan pertama

Seperti yang ditunjukkan Gambar 1, saat Anda membuat permintaan awal ke Edge API:

  1. Anda meminta token akses. Anda dapat melakukannya dengan Edge API, acurl, atau get_token. Contoh: 
    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. Layanan Edge OAuth2 merespons dengan token akses, dan mencetaknya ke stdout; misalnya: 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    Utilitas acurl dan get_token secara otomatis menyimpan akses dan token refresh ke ~/.sso-cli (Token refresh tidak ditulis ke stdout.) Jika menggunakan layanan Edge OAuth2 untuk mendapatkan token, Anda harus menyimpannya untuk gunakanlah diri Anda sendiri.

  3. Anda mengirimkan permintaan ke Edge API dengan token akses. acurl melampirkan token secara otomatis; misalnya: 
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    Jika Anda menggunakan klien HTTP lain, pastikan untuk menambahkan token akses. Contoh:

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. Edge API mengeksekusi permintaan Anda dan biasanya menampilkan respons dengan data.

Alur OAuth2: Permintaan berikutnya

Pada permintaan berikutnya, Anda tidak perlu menukar kredensial dengan token. Sebagai gantinya, Anda cukup menyertakan token akses yang sudah Anda miliki, selama token tersebut belum kedaluwarsa:

Alur OAuth: Permintaan berikutnya
Gambar 2: Alur OAuth: Permintaan berikutnya

Jika Anda sudah memiliki token akses, seperti yang ditunjukkan pada Gambar 2:

  1. Anda mengirimkan permintaan ke Edge API dengan token akses. acurl melampirkan token secara otomatis. Jika menggunakan alat lain, Anda perlu menambahkan token secara manual.
  2. Edge API mengeksekusi permintaan Anda dan biasanya menampilkan respons dengan data.

Alur OAuth2: Saat masa berlaku token akses Anda berakhir

Saat masa berlaku token akses berakhir (setelah 12 jam), Anda dapat menggunakan token refresh untuk mendapatkan token akses:

Alur OAuth: Memuat ulang token akses
Gambar 3: Alur OAuth: Memuat ulang token akses

Seperti yang ditunjukkan pada Gambar 3, saat masa berlaku token akses Anda berakhir:

  1. Anda mengirimkan permintaan ke Edge API, tetapi token akses Anda sudah tidak berlaku.
  2. Edge API menolak permintaan Anda sebagai tidak sah.
  3. Anda mengirim token refresh ke layanan OAuth2 Edge. Jika Anda menggunakan acurl, ini sudah selesai secara otomatis untuk Anda.
  4. Layanan OAuth2 Edge merespons dengan token akses baru.
  5. Anda mengirimkan permintaan ke Edge API dengan token akses baru.
  6. Edge API mengeksekusi permintaan Anda dan biasanya menampilkan respons dengan data.

Mendapatkan token

Untuk mendapatkan token akses yang dapat dikirim ke Edge API, Anda dapat menggunakan Utilitas Apigee, selain utilitas seperti curl:

  • get_token utility: Menukarkan kredensial Apigee Anda untuk mendapatkan akses token baru yang dapat digunakan untuk memanggil Edge API.
  • utilitas acurl: Menyediakan wrapper praktis seputar standar Perintah curl. Membuat permintaan HTTP ke Edge tertentu, mendapatkan token akses dan refresh dari get_token, lalu meneruskan token akses tersebut ke Edge API.
  • Endpoint token di layanan Edge OAuth2: Tukarkan Kredensial Apigee untuk akses dan token refresh melalui panggilan ke Edge API.

Utilitas ini bertukar kredensial akun Apigee Anda (alamat email dan sandi) untuk token dengan durasi berikut:

  • Masa berlaku token akses berakhir dalam 12 jam.
  • Masa berlaku token refresh akan berakhir dalam 30 hari.

Akibatnya, setelah Anda berhasil melakukan panggilan API dengan acurl atau get_token, Anda dapat terus menggunakan pasangan token selama 30 hari. Setelah masa berlaku habis, Anda harus memasukkan kembali kredensial, dan mendapatkan token baru.

Mengakses Edge API dengan OAuth2

Untuk mengakses Edge API, Anda mengirim permintaan ke endpoint API dan menyertakan token akses. Anda dapat melakukannya dengan klien HTTP apa pun, termasuk utilitas command line seperti curl, UI berbasis browser seperti Postman, atau utilitas Apigee seperti acurl.

Mengakses Edge API dengan acurl dan curl dijelaskan dalam bagian-bagian berikutnya.

Gunakan acurl

Untuk mengakses Edge API dengan acurl, permintaan awal Anda harus menyertakan memiliki kredensial yang lengkap. Layanan OAuth2 Edge merespons dengan token akses dan refresh. acurl menyimpan token secara lokal.

Pada permintaan berikutnya, acurl menggunakan token yang disimpan di ~/.sso-cli, jadi Anda tidak perlu memasukkan kredensial Anda lagi hingga token tersebut kedaluwarsa.

Contoh berikut menunjukkan permintaan acurl awal yang mendapatkan detail untuk "Ahamilton-eval" organisasi:

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

Selain mendapatkan detail tentang organisasi, contoh ini juga menampilkan permintaan kedua yang berisi daftar kebijakan dalam "helloworld" Proxy API. Permintaan kedua menggunakan mempersingkat "o" untuk "organisasi" di URL.

Perlu diperhatikan bahwa acurl akan otomatis meneruskan token akses pada permintaan kedua. Anda tidak perlu meneruskan kredensial pengguna Anda setelah acurl menyimpan token OAuth2. Ini mendapatkan token dari ~/.sso-cli untuk panggilan berikutnya.

Untuk informasi selengkapnya, lihat Menggunakan acurl untuk mengakses Edge API.

Gunakan curl

Anda dapat menggunakan curl untuk mengakses Edge API. Untuk melakukannya, Anda terlebih dahulu harus mendapatkan akses dan token refresh. Anda bisa mendapatkannya menggunakan utilitas seperti get_token atau Layanan OAuth2 Edge.

Setelah berhasil menyimpan token akses, Anda meneruskannya di Header Authorization panggilan Anda ke Edge API, seperti contoh berikut menampilkan:

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

Token akses berlaku selama 12 jam setelah diterbitkan. Setelah masa berlaku token akses berakhir, token refresh dapat digunakan selama 30 hari untuk menerbitkannya token akses lainnya tanpa memerlukan kredensial. Apigee merekomendasikan untuk meminta token akses baru hanya setelah token rujukan berakhir, bukan memasukkan kredensial dan membuat permintaan baru pada setiap panggilan API.

Akhir masa berlaku token

Setelah masa berlaku token akses berakhir, Anda dapat menggunakan token refresh untuk mendapatkan token akses baru tanpa dan mengirimkan kredensial lagi.

Cara Anda memuat ulang token akses bergantung pada alat yang Anda gunakan:

  • acurl: Anda tidak perlu melakukan tindakan apa pun. acurl otomatis memperbarui token akses saat Anda mengirim permintaan berisi permintaan yang sudah usang.
  • get_token: Panggil get_token untuk memuat ulang token akses.
  • Layanan OAuth2 Edge: Mengirim permintaan yang menyertakan:
    • Token refresh
    • Parameter formulir grant_type ditetapkan ke "refresh_token"

OAuth2 untuk pengguna komputer

Anda dapat menggunakan utilitas acurl dan get_token untuk membuat skrip akses otomatis ke API Edge dengan autentikasi OAuth2 untuk pengguna mesin. Contoh berikut menunjukkan cara gunakan get_token untuk meminta token akses, lalu menambahkan nilai token ke panggilan 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/...'

Atau, Anda dapat menggabungkan permintaan token dan panggilan curl menggunakan utilitas acurl. Contoh:

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

Dalam kedua contoh tersebut, menetapkan nilai -m ke string kosong akan mencegah pengguna perangkat agar tidak dimintai kode MFA.