Configuring and using token exchange

Penukaran token adalah proses yang memungkinkan aplikasi klien untuk menukar satu token dengan token lainnya. Di NQRust-Identity, fitur berikut menerapkan penukaran token:

• Penukaran token standar: versi 2 (V2) - Fitur ini adalah implementasi penukaran token yang sepenuhnya didukung dan diaktifkan secara default saat server NQRust-Identity dimulai.
• Penukaran token lama: versi 1 (V1) - Fitur pratinjau ini sudah usang dan tidak diaktifkan secara default saat server NQRust-Identity dimulai. Di versi mendatang, penukaran Token Lama akan diganti oleh versi 2, hak otorisasi JWT, dan fitur lainnya.

Kemampuan NQRust-Identity untuk penukaran token sebagai berikut:

1. Sebuah klien dapat menukar token NQRust-Identity yang ada untuk klien tertentu dengan token baru yang ditargetkan pada klien berbeda di realm yang sama.
2. Sebuah klien dapat menukar token NQRust-Identity yang ada dengan token eksternal, seperti akun Facebook yang terhubung.
3. Sebuah klien dapat menukar token eksternal dengan token NQRust-Identity.
4. Sebuah klien dapat menggantikan pengguna.

Penukaran token standar hanya mendukung kasus penggunaan (1). Penukaran token lama mendukung empat kasus penggunaan, tetapi merupakan fitur pratinjau dan sudah usang. Oleh karena itu, penukaran token standar V2 disarankan karena didukung dan akan dipelihara untuk masa depan. Penukaran token lama berguna untuk tiga kasus penggunaan terakhir, tetapi mungkin tidak kompatibel mundur dengan versi NQRust-Identity mendatang, dan akhirnya akan dihapus. Anda juga dapat mengaktifkan kedua fitur penukaran token dan menggunakannya bersama. Misalnya, Anda dapat menggunakan penukaran internal-internal yang disediakan oleh V2 bersama dengan kasus penggunaan lainnya yang didukung oleh V1. Untuk detail lebih lanjut, lihat perbandingan penukaran token.

Standar Pintu Token Exchange

Standar token exchange di NQRust-Identity mengimplementasikan spesifikasi token exchange (opens in a new tab). Ini memungkinkan aplikasi klien untuk menukar token NQRust-Identity yang ada untuk klien tertentu dengan token baru yang dikeluarkan untuk klien yang memicu permintaan token exchange. Kedua klien harus berada dalam realm yang sama.

Alur Token Exchange

Pertimbangkan alur token exchange yang umum ini:

1. Pengguna mengotentikasi dengan menggunakan NQRust-Identity SSO ke aplikasi klien initial-client. Token dikeluarkan untuk initial-client.

2. Klien initial-client mungkin perlu untuk menggunakan layanan REST requester-client, yang memerlukan otentikasi. Jadi initial-client mengirimkan token akses dari langkah 1 ke requester-client dengan penggunaan token.

3. Untuk melayani permintaan, requester-client mungkin perlu untuk memanggil layanan target-client. Namun, itu mungkin tidak dapat menggunakan token yang dikirimkan dari initial-client. Sebagai contoh:

   Token tidak memiliki izin atau scope yang mencukupi. target-client tidak ditentukan sebagai audiens token; token dimaksudkan untuk digunakan untuk menginvokasi requester-client. Token memiliki izin yang terlalu banyak; oleh karena itu, requester-client mungkin tidak ingin berbagi dengan target-client.

Keadaan mana pun dari ini bisa menjadi alasan untuk menginvokasi token exchange. requester-client mungkin perlu untuk mengirimkan permintaan token exchange ke server NQRust-Identity dan menggunakan token asli dari langkah 1 sebagai token subjek dan menukarnya dengan token lain token yang diminta. 4. Token yang diminta dikembalikan ke requester-client. Token ini sekarang dapat dikirim ke target-client. 5. target-client dapat memenuhi permintaan dan mengembalikan respons ke requester-client. requester-client kemudian dapat mengikuti dan mengembalikan respons ke permintaan dari langkah 2.

Banyak kasus penggunaan lainnya untuk token exchange, tetapi contoh sebelumnya adalah yang paling umum.

Contoh Permintaan Token Exchange

Berikut adalah contoh permintaan token exchange dari klien requester-client di realm test. Perhatikan bahwa subject_token adalah token akses yang dikeluarkan untuk initial-client:

POST /realms/test/protocol/openid-connect/token
Authorization: Basic cmVxdWVzdGVyLWNsaWVudDpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded
Accept: application/json
 
grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=$SUBJECT_TOKEN&
subject_token_type=urn:ietf:params:oauth:token-type:access_token&
requested_token_type=urn:ietf:params:oauth:token-type:access_token

Contoh respons token exchange mungkin tampak seperti ini:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsIn...",
  "expires_in": 300,
  "token_type": "Bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "session_state": "287f3c57-32b8-4c0f-8b00-8c7db231d701",
  "scope": "default-scope1",
  "refresh_expires_in": 0,
  "not-before-policy": 0
}

Cara Mengaktifkan Token Exchange

Untuk standar token exchange, token-exchange-standard:v2 diaktifkan secara default. Namun, Anda juga perlu untuk mengaktifkan tombol Standar token exchange untuk klien yang seharusnya mengirim permintaan token exchange, seperti requester-client dari contoh sebelumnya. Perhatikan bahwa requester-client harus menjadi klien rahasia. Juga, seperti halnya untuk permintaan grant lainnya, permintaan token exchange harus diotentikasi dengan metode otentikasi klien yang sesuai yang dikonfigurasi untuk klien.

Parameter Permintaan dan Respons

Parameter ini sejalan dengan spesifikasi token exchange (opens in a new tab), yang dijelaskan sebagai berikut:

WAJIB. Nilai parameter ini harus urn:ietf:params:oauth:grant-type:token-exchange.

WAJIB. Token keamanan yang mewakili identitas pihak atas nama yang diminta.

WAJIB. Parameter ini adalah tipe token yang diteruskan dalam parameter subject_token. Ini harus urn:ietf:params:oauth:token-type:access_token ketika penggunaan token exchange standar karena NQRust-Identity tidak mendukung tipe lainnya untuk token exchange standar.

OPSIOMAL. Parameter ini mewakili tipe token yang klien inginkan untuk ditukar. Dalam versi ini, hanya tipe token oauth dan OpenID Connect yang didukung. Nilai default untuk ini adalah urn:ietf:params:oauth:token-type:access_token. Nilai lain yang mungkin adalah urn:ietf:params:oauth:token-type:id_token jika token ID yang dikeluarkan untuk requester-client diminta. Nilai yang mungkin juga bisa urn:ietf:params:oauth:token-type:refresh_token; dalam hal ini, Anda akan menerima token akses dan token refresh dalam respons. Namun, token refresh diizinkan jika opsi konfigurasi klien Allow refresh token in Standard Token Exchange diaktifkan sebagai yang ditentukan dalam bagian detail token exchange standar.

OPSIOMAL. Parameter ini mewakili set scope OAuth dan OpenID Connect yang dipisahkan spasi yang klien minta. Anda dapat menggunakan optional client scopes dari requester-client. Untuk lebih jelas, lihat scopes and audiences. Mengabaikan parameter ini berarti bahwa hanya default client scopes yang efektif digunakan.

OPSIOMAL. Audiens menentukan client_id dari klien, yang diharapkan untuk digunakan sebagai audiens token. Dalam contoh di atas, itu bisa menjadi target-client. Beberapa nilai parameter ini diizinkan, yang berarti Anda ingin token untuk berisi beberapa audiens untuk digunakan oleh requester-client dalam beberapa layanan berbeda. Misalnya audience=target-client1&audience=target-client2 dapat digunakan dalam permintaan. Detail lebih lanjut dalam bagian tentang scopes and audiences.

Respon sukses dikembalikan dalam format JSON. Ini berisi parameter serupa seperti respons dari grant lainnya. Berikut adalah beberapa spesifik token exchange yang lebih penting dari parameter:

Token akses yang diminta. Perhatikan bahwa jika permintaan menentukan requested_token_type=urn:ietf:params:oauth:token-type:id_token, parameter ini mungkin sebenarnya berisi token ID bukan token akses. Perilaku ini sesuai spesifikasi token exchange (opens in a new tab).

Token refresh. Ini dimasukkan hanya jika requested_token_type=urn:ietf:params:oauth:token-type:refresh_token digunakan dan klien telah mengaktifkan pengeluaran token refresh dari token exchange

Jenis token yang diminta yang dikeluarkan. Nilai yang sama seperti requested_token_type yang digunakan dalam permintaan.

Biasanya Bearer jika jenis token yang dikeluarkan adalah token akses atau token refresh. Dalam kasus token ID yang diminta, nilainya adalah N_A

Scopes dan Audiens

Parameter scope dalam permintaan token exchange memiliki arti yang sama seperti grant lainnya. Parameter ini opsional. Ketika itu diabaikan, scope klien yang efektif digunakan dalam permintaan adalah default client scopes dari requester-client. Ketika parameter ini digunakan, scope klien yang efektif adalah scope default bersama dengan optional client scopes.

Secara default, scope klien yang digunakan akan menambahkan audiens ke klaim aud berdasarkan scope klien yang digunakan dan peran klien.

Parameter audience dapat digunakan untuk filtering audiens, sehingga klaim aud akan berisi hanya audiens yang ditentukan oleh parameter audience. Demikian pula peran klien dalam token akan difilter dan token akan memiliki hanya peran klien dari klien yang ditentukan oleh parameter audience.

Dengan tambahan, parameter audience dapat digunakan untuk filtering scope klien juga. Ini bekerja dengan cara yang serupa dengan izin scope klien untuk pengguna. Jika scope klien tidak berisi peran klien (misalnya, itu berisi nol peran atau hanya berisi peran realm), tidak ada filtering tambahan yang terjadi untuk scope klien. Namun, jika scope klien berisi beberapa pemetaan peran klien, itu harus mencakup beberapa peran klien dari klien yang diminta oleh parameter audience. Peran komposit juga termasuk untuk pertimbangan. Jika scope klien tidak berisi peran klien dari klien yang diminta oleh parameter audience, scope klien akan difilter.

Contoh

Berikut adalah beberapa contoh untuk lebih jelas ilustrasi perilaku scope dan audiens.

Anggaplah kita memiliki realm dengan:

• Klien target-client1 dengan peran klien target-client1-role
• Klien target-client2 dengan peran klien target-client2-role
• Klien target-client3 dengan peran klien target-client3-role
• Scope klien default-scope1. Scope klien ini memiliki pemetaan peran scope untuk peran klien target-client1/target-client1-role
• Scope klien optional-scope2. Scope klien ini memiliki pemetaan peran scope untuk peran klien target-client2/target-client2-role
• Klien requester-client, yang memiliki scope klien default-scope1 ditambahkan sebagai default klien scope dan scope optional-scope2 ditambahkan sebagai opsi klien scope
• Pengguna yang terverifikasi, yang merupakan anggota dari kedua target-client1-role dan target-client2-role

Pengaturan di atas berarti bahwa menggunakan scope default-scope1 akan menambahkan audiens target-client1 ke token dan menggunakan optional-scope2 akan menambahkan audiens target-client2. Ini karena cara audiens diselesaikan dari pemetaan peran scope klien.

Contoh 1

Permintaan token exchange dikirimkan dengan scope=optional-scope2 dan tanpa parameter audiens:

Tidak ada filtering audiens. Scope dan audiens akan diselesaikan sesuai dengan hal yang biasa terjadi untuk grant lainnya. Token respons akan serupa dengan ini (klaim yang tidak menarik untuk contoh ini diabaikan untuk singkat):

{
  "azp": "requester-client",
  "scope": "default-scope1 optional-scope2",
  "aud": [ "target-client1", "target-client2" ],
  "resource_access": {
	"target-client1": {
  	  "roles": [ "target-client1-role" ]
	},
	"target-client2": {
  	  "roles": [ "target-client2-role" ]
	}
  },
  ...
}

Contoh 2

Permintaan token exchange dikirimkan dengan scope=optional-scope2 dan dengan audience=target-client2

Sama seperti contoh sebelumnya, tetapi audiens target-client1 dan peran klien difilter karena parameter audiens termasuk, tetapi hanya dengan klien ini target-client2. Scope klien default-scope1 akan juga difilter karena ia berisi beberapa peran klien tetapi tidak ada peran klien dari audiens klien yang diminta target-client2. Jadi token akan seperti berikut:

{
  "azp": "requester-client",
  "scope": "optional-scope2",
  "aud": [ "target-client2" ],
  "resource_access": {
    "target-client2": {
      "roles": [ "target-client2-role" ]
    }
  },
  ...
}

Contoh 3

Permintaan token exchange dikirimkan dengan scope=optional-scope2 dan dengan audience=target-client2&audience=target-client3

target-client3 bukan bagian dari audiens token karena pengguna tidak memiliki peran apapun. Jadi dalam hal ini, permintaan akan ditolak karena beberapa audiens yang diminta tidak tersedia.

Token Exchange - Detail Tambahan

Titik tambahan ini menjelaskan perilaku token exchange.

• Tidak didukung untuk klien publik untuk mengirim permintaan token exchange. Token exchange V1 mencakup dukungan yang sangat terbatas untuk klien publik, memungkinkan klien publik untuk menukar token ke diri sendiri dengan kurang scope. Skenario ini dapat diganti dengan grant token refresh.

• Token subject_token yang dikirim ke endpoint token exchange harus memiliki klien pengguna sebagai audiens dalam klaim aud. Jika tidak, permintaan akan ditolak. Pengecualian satu-satunya adalah, jika klien menukar token miliknya sendiri, yang dikeluarkan untuk itu. Menukar ke diri sendiri mungkin berguna untuk downscope/upscope token atau filtering audiens token yang tidak diperlukan dan seterusnya.

• Token terbatas pengirim (seperti yang didefinisikan dalam RFC 7800) tidak dapat digunakan sebagai subject_token. Ini termasuk token DPoP terikat dan token sertifikat X.509 terikat. Token Exchange Standar hanya menerima akses Bearer sebagai subjek token. Jika Anda menyediakan token terbatas pengirim, permintaan akan ditolak dengan kesalahan invalid_request. Namun, Anda dapat memperoleh token DPoP terikat sebagai output dari token exchange dengan menyertakan bukti DPoP yang valid dalam permintaan. Untuk detail lebih lanjut, lihat Mengamankan aplikasi dengan Demonstrating Proof-of-Possession (DPoP).

• Persetujuan - Jika klien pengguna memiliki Persetujuan diperlukan diaktifkan, token exchange diizinkan hanya jika pengguna sudah memberikan persetujuan untuk semua scope yang diminta

• Izin admin halus (FGAP) tidak diperlukan untuk token exchange standar. Kami berencana untuk akhirnya integrasi dengan FGAP untuk masa depan, tetapi integrasi itu mungkin tersedia untuk semua grant. Itu tidak akan spesifik hanya untuk token exchange seperti yang ada di token exchange V1.

• Integrasi token exchange dengan Klien Kebijakan dimungkinkan. Integrasi ini bisa berguna untuk menangani beberapa kasus penggunaan. Misalnya, pertimbangkan skenario untuk menolak permintaan token exchange jika klien pengguna mengirimkan permintaan dengan scope=some-confidential-scope. Dalam contoh ini, mungkin berguna untuk membuat kondisi kebijakan klien dengan kombinasi kondisi untuk client-scope, grant-type dan client-roles.

• Meminta token refresh diizinkan hanya jika klien memiliki switch Allow refresh token in Standard Token Exchange diatur ke nilai lain selain No (nilai default). Switch ini tersedia di Konsol Admin di tab Advanced dari klien OIDC di bagian OpenID Connect Compatibility Modes. Nilai lain yang tersedia untuk switch adalah Same session, yang berarti token refresh diizinkan hanya jika token refresh dapat menggunakan sesi pengguna yang sama dengan token subjek. Jika token subjek datang dari Sesi Transient atau dari Sesi Offline, meminta token refresh tidak akan diizinkan. Demikian juga tidak akan diizinkan untuk meminta token offline (menggunakan scope=offline_access).

  

• Token exchange tidak pernah membuat sesi pengguna baru. Jika requested_token_type adalah token refresh, itu mungkin akhirnya membuat sesi klien baru untuk klien pengguna (jika sesi klien belum dibuat).

• NQRust-Identity Token exchange belum mendukung parameter resource.

• Spesifikasi token exchange menyebutkan konsep pembebasan dan delegasi (opens in a new tab). NQRust-Identity mendukung skenario pembebasan, tetapi belum mendukung skenario delegasi.

Pencabutan

Dengan asumsi bahwa ada token subjek access-token1 yang dikeluarkan untuk klien initial-client, di sini adalah beberapa pertimbangan terkait pencabutan token:

• Untuk kasus ketika access-token1 ditukar dengan access-token2 dari klien requester-client, pencabutan access-token1 tidak akan mencabut access-token2. Mendukung "rantai pencabutan" untuk token akses akan berarti beban kerja yang cukup. Jadi dengan pertimbangan ini, administrator harus memastikan bahwa token akses memiliki umur panjang yang singkat dan dicabut secara otomatis setelah beberapa waktu.

• Untuk kasus ketika access-token1 ditukar dengan refresh-token2 dari klien requester-client, kami mencoba untuk mendukung rantai pencabutan. Ini berarti bahwa:

  • Pencabutan access-token1 akan mencabut juga refresh-token2. Selain itu ini akan menghapus sesi klien klien requester-client dari sesi pengguna dan oleh karena itu semua token refresh dari requester-client dalam sesi pengguna ini akan efektif dicabut
  • Jika refresh-token2 dan token akses terkait digunakan untuk token exchange lebih lanjut ke klien berbeda, maka pencabutan access-token1 akan mencabut token exchange berikutnya juga. Dalam kata lain, seluruh "rantai" dari token yang ditukar akan dicabut.
  • Perhatikan bahwa token akses harus valid ketika endpoint pencabutan dipanggil. Jika Anda tidak memiliki token akses yang valid ketika access-token1 asli telah kedaluwarsa, Anda bisa potensial menggunakan token akses yang dikeluarkan untuk klien yang sama dalam sesi pengguna yang sama. Token yang ditukar seperti refresh-token2 dan lainnya dari "rantai" harus dicabut.

Perbandingan Standar Token Exchange dan Token Exchange Legacy

Sementara bagian sebelumnya mendetailkan token exchange standar dan legacy, berikut adalah ringkasan umum yang membandingkan dua metode token exchange ini.