Halaman ini diterjemahkan oleh Cloud Translation API.

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 bagi akun Cloud. Jika 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 agar kami dapat memastikan identitas yang Anda inginkan. Untuk mengautentikasi Anda, kami mengharuskan token akses OAuth2 dikirim bersama permintaan Anda untuk mengakses API.

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

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

Tetapi Anda tidak boleh begitu saja mengirimkan permintaan tanpa memberi tahu kami identitas Anda. Jika tidak, siapa saja dapat melihat detail organisasi Anda.

Di sinilah OAuth2 berperan: untuk mengautentikasi Anda, Anda juga perlu 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 merespons dengan token akses dan refresh.

Alur OAuth2: Permintaan awal

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

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

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

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

Layanan OAuth2 Edge merespons dengan token akses, dan mencetaknya ke stdout; misalnya:

Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

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

Anda mengirimkan permintaan ke Edge API dengan token akses. acurl akan 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"
```
Edge API akan 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 cukup menyertakan token akses yang sudah Anda miliki, selama token tersebut belum habis masa berlakunya:

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

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

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

Alur OAuth2: Saat masa berlaku token akses berakhir

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

Alur OAuth: Memperbarui token akses — **Gambar 3:** Alur OAuth: Memuat ulang token akses

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

Anda mengirimkan permintaan ke Edge API, tetapi masa berlaku token akses Anda telah berakhir.
Edge API menolak permintaan Anda sebagai permintaan yang tidak sah.
Anda mengirimkan token refresh ke layanan OAuth2 Edge. Jika Anda menggunakan acurl, proses ini dilakukan secara otomatis untuk Anda.
Layanan OAuth2 Edge merespons dengan token akses baru.
Anda mengirimkan permintaan ke Edge API dengan token akses baru.
Edge API akan menjalankan 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 berikut, selain utilitas seperti curl:

utilitas get_token: Menukarkan kredensial Apigee Anda dengan akses dan token refresh yang dapat Anda gunakan untuk memanggil Edge API.
Utilitas acurl: Menyediakan wrapper praktis untuk perintah curl standar. Membuat permintaan HTTP ke Edge API, mendapatkan akses dan token refresh dari get_token, serta meneruskan token akses ke Edge API.
Endpoint token di layanan OAuth2 Edge: Tukar kredensial 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 dengan 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 berlakunya habis, Anda harus memasukkan kembali kredensial dan mendapatkan token baru.

Mengakses Edge API dengan OAuth2

Untuk mengakses Edge API, kirim permintaan ke endpoint API dan sertakan 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 di bagian berikut.

Menggunakan acurl

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

Pada permintaan berikutnya, acurl akan menggunakan token yang disimpan di ~/.sso-cli, sehingga Anda tidak perlu menyertakan kredensial Anda lagi sampai 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 menampilkan permintaan kedua yang mendapatkan daftar kebijakan dalam proxy API "helloworld". Permintaan kedua menggunakan pemendekan "o" untuk "organisasi" di URL.

Perlu diperhatikan bahwa acurl akan otomatis meneruskan token akses pada permintaan kedua. Anda tidak perlu meneruskan kredensial pengguna setelah acurl menyimpan token OAuth2. Metode ini mendapatkan token 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, teruskan token tersebut di header Authorization panggilan Anda ke Edge API, seperti yang ditunjukkan pada contoh berikut:

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 menerbitkan token akses lain tanpa memerlukan kredensial. Apigee merekomendasikan untuk meminta token akses baru hanya setelah token perujuk berakhir, bukan memasukkan kredensial dan membuat permintaan baru dengan setiap panggilan API.

Akhir masa berlaku token

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

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

acurl: Tidak perlu melakukan tindakan apa pun. acurl akan otomatis memperbarui token akses saat Anda mengirim permintaan yang berisi token akses yang sudah tidak berlaku.
get_token: Panggil get_token untuk memperbarui token akses.
Layanan OAuth2 Edge: Mengirim permintaan yang menyertakan:
- Token refresh
- grant_type parameter formulir ditetapkan ke "refresh_token"

OAuth2 untuk pengguna perangkat

Anda dapat menggunakan aplikasi 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 tersebut 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 memasukkan kode MFA.