Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Titik akhir penerbit token
[Titik akhir token OAuth ](https://www.rfc-editor.org/rfc/rfc6749#section-3.2) 2.0 pada `/oauth2/token` mengeluarkan token web JSON (JWTs) ke aplikasi yang ingin menyelesaikan alur hibah kode otorisasi dan kredensyal klien. Token ini adalah hasil akhir dari otentikasi dengan kumpulan pengguna. Mereka berisi informasi tentang pengguna (token ID), tingkat akses pengguna (token akses), dan hak pengguna untuk mempertahankan sesi masuk mereka (token penyegaran). Library relying-party OpenID Connect (OIDC) menangani permintaan dan muatan respons dari titik akhir ini. Token memberikan bukti otentikasi yang dapat diverifikasi, informasi profil, dan mekanisme untuk akses ke sistem back-end.
Server otorisasi kumpulan pengguna OAuth 2.0 Anda mengeluarkan token web JSON (JWTs) dari titik akhir token ke jenis sesi berikut:
1. Pengguna yang telah menyelesaikan permintaan untuk pemberian kode otorisasi. Penukaran kode yang berhasil mengembalikan ID, akses, dan token penyegaran.
1. Machine-to-machine (M2M) sesi yang telah menyelesaikan hibah kredensial-klien. Otorisasi yang berhasil dengan rahasia klien mengembalikan token akses.
1. Pengguna yang sebelumnya telah masuk dan menerima token penyegaran. Segarkan otentikasi token mengembalikan ID baru dan token akses.
**catatan**
Pengguna yang masuk dengan pemberian kode otorisasi dalam login terkelola atau melalui federasi selalu dapat menyegarkan token mereka dari titik akhir token. Pengguna yang masuk dengan operasi API `InitiateAuth` dan `AdminInitiateAuth` dapat menyegarkan token mereka dengan titik akhir token saat [perangkat yang diingat](amazon-cognito-user-pools-device-tracking.md) *tidak* aktif di kumpulan pengguna Anda. Jika perangkat yang diingat aktif, segarkan token dengan [operasi penyegaran token API atau SDK yang relevan untuk klien aplikasi](amazon-cognito-user-pools-using-the-refresh-token.md#using-the-refresh-token-api) Anda.
Titik akhir token menjadi tersedia untuk umum saat Anda menambahkan domain ke kumpulan pengguna Anda. Ia menerima permintaan HTTP POST. Untuk keamanan aplikasi, gunakan PKCE dengan peristiwa login kode otorisasi Anda. PKCE memverifikasi bahwa pengguna yang melewati kode otorisasi adalah pengguna yang sama yang diautentikasi. Untuk informasi lebih lanjut tentang PKCE, lihat [IETF](https://datatracker.ietf.org/doc/html/rfc7636) RFC 7636.
Anda dapat mempelajari lebih lanjut tentang klien aplikasi kumpulan pengguna dan jenis hibah, rahasia klien, cakupan yang diizinkan, dan klien IDs di[Pengaturan khusus aplikasi dengan klien aplikasi](user-pool-settings-client-apps.md). Anda dapat mempelajari lebih lanjut tentang otorisasi M2M, hibah kredensi klien, dan otorisasi dengan cakupan token akses di. [Lingkup, M2M, dan server sumber daya](cognito-user-pools-define-resource-servers.md)
Untuk mengambil informasi tentang pengguna dari token akses mereka, teruskan ke permintaan Anda [Titik akhir UserInfo](userinfo-endpoint.md) atau ke [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html)API. Token akses harus berisi cakupan yang sesuai untuk permintaan ini,
## Format permintaan POST ke titik akhir token
Titik akhir `/oauth2/token` hanya mendukung `HTTPS POST`. Titik akhir ini tidak interaktif pengguna. Menangani permintaan token dengan [pustaka OpenID Connect (OIDC)](https://openid.net/developers/certified-openid-connect-implementations/) di aplikasi Anda.
Titik akhir token mendukung `client_secret_basic` dan `client_secret_post` otentikasi. Untuk informasi selengkapnya tentang spesifikasi OIDC, lihat Otentikasi [Klien](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). Untuk informasi selengkapnya tentang titik akhir token dari spesifikasi OpenID Connect[, lihat](http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) Titik Akhir Token.
### Minta parameter di header
Anda dapat meneruskan parameter berikut di header permintaan Anda ke titik akhir token.
**`Authorization`**
Jika klien dikeluarkan rahasia, klien dapat melewati `client_id` dan `client_secret` di header otorisasi sebagai otorisasi `client_secret_basic` HTTP. Anda juga dapat memasukkan `client_id` dan `client_secret` dalam badan permintaan sebagai `client_secret_post` otorisasi.
String header otorisasi adalah [Basic](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side)`Base64Encode(client_id:client_secret)`. Contoh berikut adalah header otorisasi untuk klien aplikasi `djc98u3jiedmi283eu928` dengan rahasia klien`abcdef01234567890`, menggunakan versi string yang dienkode Base64: `djc98u3jiedmi283eu928:abcdef01234567890`
```
Authorization: Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw
```
**`Content-Type`**
Tetapkan nilai parameter ini ke`'application/x-www-form-urlencoded'`.
### Minta parameter dalam tubuh
Berikut ini adalah parameter yang dapat Anda minta dalam `x-www-form-urlencoded` format di badan permintaan ke titik akhir token.
**`grant_type`**
*Diperlukan.*
Jenis hibah OIDC yang ingin Anda minta.
Harus `authorization_code` atau `refresh_token` atau `client_credentials`. Anda dapat meminta token akses untuk cakupan kustom dari titik akhir token dalam kondisi berikut:
+ Anda mengaktifkan cakupan yang diminta dalam konfigurasi klien aplikasi Anda.
+ Anda mengonfigurasi klien aplikasi Anda dengan rahasia klien.
+ Anda mengaktifkan pemberian kredensi klien di klien aplikasi Anda.
Titik akhir token mengembalikan token penyegaran hanya jika `grant_type` ada`authorization_code`.
**`client_id`**
*Opsional. Tidak diperlukan saat Anda memberikan ID klien aplikasi di `Authorization` header.*
ID klien aplikasi di kumpulan pengguna Anda. Tentukan klien aplikasi yang sama yang mengautentikasi pengguna Anda.
Anda harus memberikan parameter ini jika klien bersifat publik dan tidak memiliki rahasia, atau dengan `client_secret` `client_secret_post` otorisasi.
**`client_secret`**
*Opsional. Tidak diperlukan saat Anda memberikan rahasia klien di `Authorization` header dan ketika klien aplikasi tidak memiliki rahasia.*
Rahasia klien aplikasi, jika klien aplikasi memilikinya, untuk `client_secret_post` otorisasi.
**`scope`**
*Opsional.*
Dapat berupa kombinasi cakupan apa pun yang terkait dengan klien aplikasi Anda. Amazon Cognito mengabaikan cakupan dalam permintaan yang tidak diizinkan untuk klien aplikasi yang diminta. Jika Anda tidak memberikan parameter permintaan ini, server otorisasi akan mengembalikan `scope` klaim token akses dengan semua cakupan otorisasi yang Anda aktifkan dalam konfigurasi klien aplikasi Anda. Anda dapat meminta cakupan apa pun yang diizinkan untuk klien aplikasi yang diminta: cakupan standar, cakupan khusus dari server sumber daya, dan cakupan layanan mandiri `aws.cognito.signin.user.admin` pengguna.
**`redirect_uri`**
*Opsional. Tidak diperlukan untuk hibah kredensial-klien.*
Harus sama dengan `redirect_uri` yang digunakan untuk mendapatkan `authorization_code` di `/oauth2/authorize`.
Anda harus memberikan parameter ini jika `grant_type` ada`authorization_code`.
**`refresh_token`**
*Opsional. Digunakan hanya ketika pengguna sudah memiliki token penyegaran dan ingin mendapatkan ID baru dan token akses.*
Untuk menghasilkan token akses dan ID baru untuk sesi pengguna, tetapkan nilai `refresh_token` ke token penyegaran valid yang dikeluarkan klien aplikasi yang diminta.
Mengembalikan token penyegaran baru dengan ID baru dan token akses saat [rotasi token refresh](amazon-cognito-user-pools-using-the-refresh-token.md#using-the-refresh-token-rotation) aktif, jika tidak, hanya mengembalikan ID dan token akses. Jika token akses asli [terikat ke sumber daya API](cognito-user-pools-define-resource-servers.md#cognito-user-pools-resource-binding), token akses baru mempertahankan url API yang diminta dalam `aud` klaim.
**`code`**
*Opsional. Hanya diperlukan dalam hibah kode otorisasi.*
Kode otorisasi dari hibah kode otorisasi. Anda harus memberikan parameter ini jika permintaan otorisasi Anda termasuk a`grant_type`. `authorization_code`
**`aws_client_metadata`**
*Opsional.*
Informasi yang ingin Anda teruskan ke aliran otorisasi [Pemicu Lambda generasi pra token](user-pool-lambda-pre-token-generation.md) in [machine-to-machine (M2M)](cognito-user-pools-define-resource-servers.md). Aplikasi Anda dapat mengumpulkan informasi konteks tentang sesi dan meneruskannya dalam parameter ini. Saat Anda meneruskan format `aws_client_metadata` JSON yang disandikan URL, Amazon Cognito menyertakannya dalam peristiwa input ke fungsi Lambda pemicu Anda. Versi peristiwa pemicu pra token atau versi pemicu Lambda global Anda harus dikonfigurasi untuk versi tiga atau yang lebih baru. Meskipun Amazon Cognito menerima permintaan ke titik akhir ini dalam kode otorisasi dan alur M2M kredensyal klien, kumpulan pengguna Anda hanya diteruskan `aws_client_metadata` ke pemicu pembuatan token pra dari permintaan kredensyal klien.
**`code_verifier`**
Tidak wajib. Diperlukan hanya jika Anda memberikan `code_challenge_method` dan `code_challenge` parameter dalam permintaan otorisasi awal Anda.
[Pemverifikasi kode yang dihasilkan `code_challenge` dari aplikasi Anda dalam permintaan hibah kode otorisasi dengan PKCE.](using-pkce-in-authorization-code.md)
## Menukar kode otorisasi untuk token
Permintaan berikut berhasil menghasilkan ID, akses, dan token penyegaran setelah otentikasi dengan hibah kode otorisasi. Permintaan melewati rahasia klien dalam `client_secret_basic` format di `Authorization` header.
```
POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token&
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw
grant_type=authorization_code&
client_id=1example23456789&
code=AUTHORIZATION_CODE&
redirect_uri=com.myclientapp://myclient/redirect
```
Respons mengeluarkan ID baru, akses, dan token penyegaran kepada pengguna, dengan metadata tambahan.
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJra1example",
"id_token": "eyJra2example",
"refresh_token": "eyJj3example",
"token_type": "Bearer",
"expires_in": 3600
}
```
## Kredensi klien dengan otorisasi dasar
Permintaan berikut dari aplikasi M2M meminta hibah kredensil klien. Karena kredensi klien memerlukan rahasia klien, permintaan tersebut diotorisasi dengan `Authorization` header yang berasal dari ID klien aplikasi dan rahasia. Permintaan menghasilkan token akses dengan dua cakupan yang diminta. Permintaan ini juga mencakup metadata klien yang menyediakan informasi alamat IP dan token yang dikeluarkan untuk pengguna yang memberikan hibah ini atas nama. Amazon Cognito meneruskan metadata klien ke pemicu Lambda generasi pra token.
```
POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw
grant_type=client_credentials&
client_id=1example23456789&
scope=resourceServerIdentifier1%2Fscope1%20resourceServerIdentifier2%2Fscope2&
&aws_client_metadata=%7B%22onBehalfOfToken%22%3A%22eyJra789ghiEXAMPLE%22,%20%22ClientIpAddress%22%3A%22192.0.2.252%22%7D
```
Amazon Cognito meneruskan peristiwa input berikut ke pemicu Lambda pembuatan token pra.
```
{
version: '3',
triggerSource: 'TokenGeneration_ClientCredentials',
region: 'us-east-1',
userPoolId: 'us-east-1_EXAMPLE',
userName: 'ClientCredentials',
callerContext: {
awsSdkVersion: 'aws-sdk-unknown-unknown',
clientId: '1example23456789'
},
request: {
userAttributes: {},
groupConfiguration: null,
scopes: [
'resourceServerIdentifier1/scope1',
'resourceServerIdentifier2/scope2'
],
clientMetadata: {
'onBehalfOfToken': 'eyJra789ghiEXAMPLE',
'ClientIpAddress': '192.0.2.252'
}
},
response: { claimsAndScopeOverrideDetails: null }
}
```
Respons mengembalikan token akses. Hibah kredensi klien adalah untuk otorisasi machine-to-machine (M2M) dan hanya token akses kembali.
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJra1example",
"token_type": "Bearer",
"expires_in": 3600
}
```
## Kredensi klien dengan otorisasi badan POST
Permintaan hibah kredensial-klien berikut menyertakan `client_secret` parameter dalam badan permintaan dan tidak menyertakan header. `Authorization` Permintaan ini menggunakan sintaks `client_secret_post` otorisasi. Permintaan menghasilkan token akses dengan cakupan yang diminta. Permintaan ini juga mencakup metadata klien yang menyediakan informasi alamat IP dan token yang dikeluarkan untuk pengguna yang memberikan hibah ini atas nama. Amazon Cognito meneruskan metadata klien ke pemicu Lambda generasi pra token.
```
POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
X-Amz-Target: AWSCognitoIdentityProviderService.Client credentials request
User-Agent: USER_AGENT
Accept: /
Accept-Encoding: gzip, deflate, br
Content-Length: 177
Referer: http://auth.example.com/oauth2/token
Host: auth.example.com
Connection: keep-alive
grant_type=client_credentials&
client_id=1example23456789&
scope=my_resource_server_identifier%2Fmy_custom_scope&
client_secret=9example87654321&
aws_client_metadata=%7B%22onBehalfOfToken%22%3A%22eyJra789ghiEXAMPLE%22,%20%22ClientIpAddress%22%3A%22192.0.2.252%22%7D
```
Amazon Cognito meneruskan peristiwa input berikut ke pemicu Lambda pembuatan token pra.
```
{
version: '3',
triggerSource: 'TokenGeneration_ClientCredentials',
region: 'us-east-1',
userPoolId: 'us-east-1_EXAMPLE',
userName: 'ClientCredentials',
callerContext: {
awsSdkVersion: 'aws-sdk-unknown-unknown',
clientId: '1example23456789'
},
request: {
userAttributes: {},
groupConfiguration: null,
scopes: [
'resourceServerIdentifier1/my_custom_scope'
],
clientMetadata: {
'onBehalfOfToken': 'eyJra789ghiEXAMPLE',
'ClientIpAddress': '192.0.2.252'
}
},
response: { claimsAndScopeOverrideDetails: null }
}
```
Respons mengembalikan token akses. Hibah kredensi klien adalah untuk otorisasi machine-to-machine (M2M) dan hanya token akses kembali.
```
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Tue, 05 Dec 2023 16:11:11 GMT
x-amz-cognito-request-id: 829f4fe2-a1ee-476e-b834-5cd85c03373b
{
"access_token": "eyJra12345EXAMPLE",
"expires_in": 3600,
"token_type": "Bearer"
}
```
## Pemberian kode otorisasi dengan PKCE
[Contoh permintaan berikut melengkapi permintaan otorisasi yang disertakan `code_challenge_method` dan `code_challenge` parameter dalam permintaan hibah kode otorisasi dengan PKCE.](using-pkce-in-authorization-code.md)
```
POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw
grant_type=authorization_code&
client_id=1example23456789&
code=AUTHORIZATION_CODE&
code_verifier=CODE_VERIFIER&
redirect_uri=com.myclientapp://myclient/redirect
```
Respons mengembalikan ID, akses, dan token refresh dari verifikasi PKCE yang berhasil oleh aplikasi.
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJra1example",
"id_token": "eyJra2example",
"refresh_token": "eyJj3example",
"token_type": "Bearer",
"expires_in": 3600
}
```
## Penyegaran token tanpa menyegarkan rotasi token
Contoh permintaan berikut menyediakan token penyegaran ke klien aplikasi di mana [rotasi token refresh](amazon-cognito-user-pools-using-the-refresh-token.md#using-the-refresh-token-rotation) tidak aktif. Karena klien aplikasi memiliki rahasia klien, permintaan menyediakan `Authorization` header.
```
POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw
grant_type=refresh_token&
client_id=1example23456789&
refresh_token=eyJj3example
```
Respons mengembalikan ID baru dan token akses.
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJra1example",
"id_token": "eyJra2example",
"token_type": "Bearer",
"expires_in": 3600
}
```
## Penyegaran token dengan rotasi token penyegaran
Contoh permintaan berikut menyediakan token penyegaran ke klien aplikasi tempat [rotasi token refresh](amazon-cognito-user-pools-using-the-refresh-token.md#using-the-refresh-token-rotation) aktif. Karena klien aplikasi memiliki rahasia klien, permintaan menyediakan `Authorization` header.
```
POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw
grant_type=refresh_token&
client_id=1example23456789&
refresh_token=eyJj3example
```
Respons mengembalikan ID baru, akses, dan token refresh.
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJra1example",
"id_token": "eyJra2example",
"refresh_token": "eyJj4example",
"token_type": "Bearer",
"expires_in": 3600
}
```
## Contoh tanggapan negatif
Permintaan yang salah bentuk menghasilkan kesalahan dari titik akhir token. Berikut ini adalah peta umum badan respons saat permintaan token menghasilkan kesalahan.
```
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"error":"invalid_request|invalid_client|invalid_grant|unauthorized_client|unsupported_grant_type"
}
```
**`invalid_request`**
Permintaan tidak memiliki parameter yang diperlukan, menyertakan nilai parameter yang tidak didukung (selain `unsupported_grant_type`), atau formatnya salah. Misalnya, `grant_type` adalah `refresh_token` tetapi `refresh_token` tidak disertakan.
**`invalid_client`**
Autentikasi klien gagal. Misalnya, ketika klien menyertakan `client_id` dan `client_secret` di header otorisasi, tetapi tidak ada klien dengan `client_id` dan `client_secret` itu.
**`invalid_grant`**
Token refresh telah dicabut.
Kode otorisasi telah digunakan atau tidak ada.
Klien aplikasi tidak memiliki akses baca ke semua [atribut](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html) dalam lingkup yang diminta. Misalnya, aplikasi Anda meminta `email` cakupan dan klien aplikasi Anda dapat membaca `email` atribut, tetapi tidak`email_verified`.
**`unauthorized_client`**
Klien tidak diperbolehkan untuk alur pemberian kode atau untuk untuk menyegarkan token.
**`unsupported_grant_type`**
Dikembalikan jika `grant_type` ada sesuatu selain `authorization_code` atau `refresh_token` atau`client_credentials`.