Menggunakan OAuth2 untuk mengakses Edge API

Anda 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 menyiapkan SAML atau LDAP terlebih dahulu.

Cara kerja OAuth2 (dengan Apigee Edge API)

Panggilan ke Apigee Edge API memerlukan autentikasi sehingga kami dapat memastikan bahwa Anda adalah orang yang Anda katakan. Untuk mengautentikasi Anda, kami memerlukan token akses OAuth2 yang dikirim dengan permintaan Anda untuk mengakses API.

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

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

Namun, Anda tidak dapat mengirim permintaan tersebut tanpa memberi tahu kami siapa Anda. Jika tidak, siapa pun dapat melihat detail organisasi Anda.

Di sinilah OAuth2 berperan: untuk mengautentikasi Anda, kami memerlukan Anda untuk mengirimkan token akses kepada kami dalam permintaan tersebut. Token akses memberi tahu kami siapa Anda sehingga kami dapat memastikan bahwa Anda diizinkan untuk melihat detail organisasi.

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

Alur OAuth2: Permintaan awal

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

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; contohnya: 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

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

  3. Anda mengirim permintaan ke Edge API dengan token akses. acurl melampirkan token secara otomatis; contohnya: 
    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 menjalankan permintaan Anda dan biasanya menampilkan respons dengan data.

Alur OAuth2: Permintaan berikutnya

Pada permintaan berikutnya, Anda tidak perlu menukar kredensial Anda dengan token. Sebagai gantinya, Anda dapat menyertakan token akses yang sudah Anda miliki, selama token tersebut belum habis masa berlakunya:

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

Seperti yang ditunjukkan Gambar 2, jika Anda sudah memiliki token akses:

  1. Anda mengirim permintaan ke Edge API dengan token akses. acurl melampirkan token secara otomatis. Jika Anda menggunakan alat lain, Anda harus menambahkan token secara manual.
  2. Edge API menjalankan 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 baru:

Alur OAuth: Memperbarui token akses
Gambar 3: Alur OAuth: Merefresh token akses

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

  1. Anda mengirim permintaan ke Edge API, tetapi masa berlaku token akses Anda telah berakhir.
  2. Edge API menolak permintaan Anda sebagai tidak sah.
  3. Anda mengirim token refresh ke layanan Edge OAuth2. Jika Anda menggunakan acurl, hal ini akan dilakukan secara otomatis untuk Anda.
  4. Layanan Edge OAuth2 merespons dengan token akses baru.
  5. Anda mengirim permintaan ke Edge API dengan token akses baru.
  6. Edge API menjalankan permintaan Anda dan biasanya menampilkan respons dengan data.

Mendapatkan token

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

  • Utilitas get_token: Menukar kredensial Apigee Anda dengan token akses dan refresh yang dapat Anda gunakan untuk memanggil Edge API.
  • Utilitas acurl: Menyediakan wrapper praktis di sekitar perintah standar curl. Membuat permintaan HTTP ke Edge API, mendapatkan token akses dan refresh dari get_token, dan meneruskan token akses ke the Edge API.
  • Endpoint token di layanan Edge OAuth2: Menukar kredial Apigee Anda dengan token akses dan refresh melalui panggilan ke Edge API.

Utilitas ini menukar kredensial akun Apigee Anda (alamat email dan sandi) dengan token yang memiliki durasi berikut:

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

Oleh karena itu, setelah berhasil melakukan panggilan API dengan acurl atau get_token, Anda dapat terus menggunakan pasangan token selama 30 hari. Setelah masa berlaku berakhir, 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 dengan curl dijelaskan di bagian berikut.

Menggunakan acurl

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

Pada permintaan berikutnya, acurl menggunakan token yang disimpan di ~/.sso-cli sehingga Anda tidak perlu menyertakan kredensial Anda lagi hingga masa berlaku token berakhir.

Contoh berikut menunjukkan permintaan acurl awal yang mendapatkan detail untuk organisasi "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" ]

Selain mendapatkan detail tentang organisasi, contoh ini juga menunjukkan permintaan kedua yang mendapatkan daftar kebijakan dalam proxy API "helloworld". Permintaan kedua menggunakan singkatan "o" untuk "organizations" di URL.

Perhatikan bahwa acurl otomatis meneruskan token akses pada permintaan kedua. Anda tidak perlu meneruskan kredensial pengguna setelah acurl menyimpan token OAuth2. Token tersebut akan diambil dari ~/.sso-cli untuk panggilan berikutnya.

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

Menggunakan curl

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

Setelah berhasil menyimpan token akses, Anda meneruskannya di Authorization header panggilan Anda ke Edge API, seperti yang ditunjukkan contoh berikut ini:

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

Token akses berlaku selama 12 jam setelah dikeluarkan. Setelah masa berlaku token akses berakhir, token refresh dapat digunakan selama 30 hari untuk mengeluarkan token akses lain tanpa memerlukan kredensial. Apigee merekomendasikan untuk meminta token akses baru hanya setelah masa berlaku token refresh berakhir, bukan memasukkan kredensial dan membuat permintaan baru dengan setiap panggilan API.

Akhir masa berlaku token

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

Cara Anda merefresh token akses bergantung pada alat yang Anda gunakan:

  • acurl: Tidak ada tindakan yang diperlukan. acurl otomatis merefresh token akses saat Anda mengirim permintaan yang berisi token akses yang sudah tidak berlaku.
  • get_token: Panggil get_token untuk merefresh token akses.
  • Layanan Edge OAuth2: Kirim permintaan yang mencakup:
    • Token refresh
    • Parameter formulir grant_type yang ditetapkan ke "refresh_token"

OAuth2 untuk pengguna mesin

Anda dapat menggunakan utilitas acurl dan get_token untuk membuat skrip akses otomatis ke Edge API dengan autentikasi OAuth2 untuk pengguna mesin. Contoh berikut menunjukkan cara menggunakan 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 mesin diminta untuk memasukkan kode MFA.