기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 토큰 발급자 엔드포인트
`/oauth2/token`의 OAuth 2.0 [토큰 엔드포인트](https://www.rfc-editor.org/rfc/rfc6749#section-3.2)는 권한 부여 코드 및 클라이언트 자격 증명 부여 흐름을 완료하려는 애플리케이션에 JSON 웹 토큰(JWTs)을 발급합니다. 이러한 토큰은 사용자 풀을 사용한 인증의 최종 결과입니다. 여기에는 사용자(ID 토큰), 사용자의 액세스 수준(액세스 토큰) 및 로그인 세션을 유지할 수 있는 사용자의 권한(토큰 새로 고침)에 대한 정보가 포함되어 있습니다. OIDC(OpenID Connect) 신뢰 당사자 라이브러리는 이 엔드포인트의 요청 및 응답 페이로드를 처리합니다. 토큰은 검증 가능한 인증 증명, 프로필 정보 및 백엔드 시스템에 대한 액세스 메커니즘을 제공합니다.
사용자 풀 OAuth 2.0 권한 부여 서버는 토큰 엔드포인트에서 다음과 같은 유형의 세션에 JWT(JSON 웹 토큰)을 발급합니다.
1. 권한 부여 코드 부여 요청을 완료한 사용자. 코드를 성공적으로 사용하면 ID, 액세스 및 새로 고침 토큰이 반환됩니다.
1. 클라이언트 보안 인증 권한 부여를 완료한 M2M(Machine-to-Machine) 세션. 클라이언트 보안 암호로 인증에 성공하면 액세스 토큰이 반환됩니다.
1. 이전에 로그인하고 새로 고침 토큰을 받은 사용자. 새로 고침 토큰 인증은 새 ID와 액세스 토큰을 반환합니다.
**참고**
관리형 로그인 또는 페더레이션을 통해 권한 부여 코드 부여로 로그인하는 사용자는 항상 토큰 엔드포인트에서 토큰을 새로 고칠 수 있습니다. 사용자 풀에서 [기억된 디바이스](amazon-cognito-user-pools-device-tracking.md)가 활성화되어 있지 *않은* 경우 API 작업 `InitiateAuth` 및 `AdminInitiateAuth`로 로그인한 사용자는 토큰 엔드포인트를 통해 토큰을 새로 고칠 수 있습니다. 기억된 디바이스가 활성 상태인 경우 앱 클라이언트에 대한 [관련 API 또는 SDK 토큰 새로 고침 작업](amazon-cognito-user-pools-using-the-refresh-token.md#using-the-refresh-token-api)을 사용하여 토큰을 새로 고칩니다.
도메인을 사용자 풀에 추가하면 토큰 엔드포인트를 공개적으로 사용할 수 있게 됩니다. 토큰 엔드포인트는 HTTP POST 요청을 수락합니다. 애플리케이션 보안을 위해 인증 코드 로그인 이벤트와 함께 PKCE를 사용하세요. PKCE는 인증 코드를 전달하는 사용자가 인증을 받은 사용자와 동일한지 확인합니다. PKCE에 대한 자세한 내용은 [IETF RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)을 참조하세요.
사용자 풀 앱 클라이언트와 해당 권한 부여 유형, 클라이언트 보안 암호, 허용된 범위 및 클라이언트 ID에 대한 자세한 내용은 [앱 클라이언트를 사용한 애플리케이션별 설정](user-pool-settings-client-apps.md)에서 확인할 수 있습니다. M2M 권한 부여, 클라이언트 자격 증명 부여, 액세스 토큰 범위를 사용한 권한 부여에 대한 자세한 내용은 [범위, M2M 및 리소스 서버](cognito-user-pools-define-resource-servers.md)에서 확인할 수 있습니다.
액세스 토큰에서 사용자 관련 정보를 검색하려면 토큰을 [userInfo 엔드포인트](userinfo-endpoint.md) 또는 [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 요청으로 전달합니다. 액세스 토큰에는 이러한 요청에 대한 적절한 범위가 포함되어야 합니다.
## POST 요청을 토큰 엔드포인트로 형식 지정
`/oauth2/token` 엔드포인트는 `HTTPS POST`만 지원합니다. 이 엔드포인트는 사용자 대화형이 아닙니다. 애플리케이션에서 [OpenID Connect(OIDC) 라이브러리](https://openid.net/developers/certified-openid-connect-implementations/)를 사용하여 토큰 요청을 처리합니다.
토큰 엔드포인트는 `client_secret_basic` 및 `client_secret_post` 인증을 지원합니다. OIDC 사양에 대한 자세한 내용은 [클라이언트 인증](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)을 참조하세요. OpenID Connect 사양의 Token 엔드포인트에 대한 자세한 내용은 [토큰 엔드포인트](http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint)를 참조하세요.
### 헤더의 요청 파라미터
요청의 헤더에 있는 다음 파라미터를 토큰 엔드포인트에 전달할 수 있습니다.
**`Authorization`**
클라이언트에 보안 암호가 발급된 경우 클라이언트는 권한 부여 헤더에서 `client_secret_basic` HTTP 권한 부여로 해당 `client_id` 및 `client_secret`을 전달할 수 있습니다. 요청 본문에 `client_secret_post` 권한 부여로 `client_id` 및 `client_secret`을 포함할 수도 있습니다.
인증 헤더 문자열은 [기본](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side) `Base64Encode(client_id:client_secret)` 입니다. 다음 예제는 앱 클라이언트 `djc98u3jiedmi283eu928`에 대한 권한 부여 헤더로 `djc98u3jiedmi283eu928:abcdef01234567890` 문자열의 Base64 인코딩 버전을 사용하는 클라이언트 보안 암호 `abcdef01234567890`을 포함합니다.
```
Authorization: Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw
```
**`Content-Type`**
이 파라미터의 값을 `'application/x-www-form-urlencoded'`으로 설정합니다.
### 본문의 요청 파라미터
다음은 토큰 엔드포인트에 대한 요청 본문에서 `x-www-form-urlencoded` 형식으로 요청할 수 있는 파라미터입니다.
**`grant_type`**
*필수 여부*.
요청하려는 OIDC 권한 부여 유형입니다.
`authorization_code`, `refresh_token` 또는 `client_credentials`가 있습니다. 다음 조건에서 토큰 엔드포인트에서 사용자 지정 범위에 대한 액세스 토큰을 요청할 수 있습니다.
+ 앱 클라이언트 구성에서 요청 범위를 활성화했습니다.
+ 클라이언트 보안 암호로 앱 클라이언트를 구성했습니다.
+ 앱 클라이언트에서 클라이언트 자격 증명 권한 부여를 활성화합니다.
토큰 엔드포인트는 `grant_type`이 `authorization_code`일 때만 새로 고침 토큰을 반환합니다.
**`client_id`**
*선택 사항. `Authorization` 헤더에 앱 클라이언트 ID를 제공할 때는 필요하지 않습니다.*
사용자 풀에서 앱 클라이언트의 ID입니다. 사용자를 인증한 것과 동일한 앱 클라이언트를 지정합니다.
클라이언트가 공개이고 보안 암호가 없거나 `client_secret_post` 권한 부여에서 `client_secret`를 사용하는 경우 이 파라미터를 제공해야 합니다.
**`client_secret`**
*선택 사항. `Authorization` 헤더에 클라이언트 보안 암호를 제공하고 앱 클라이언트에 보안 암호가 없는 경우 필요하지 않습니다.*
앱 클라이언트에 `client_secret_post` 권한이 있는 경우 앱 클라이언트 보안 암호입니다.
**`scope`**
*선택 사항*.
앱 클라이언트와 연결된 범위를 조합하여 사용할 수 있습니다. Amazon Cognito는 요청된 앱 클라이언트에 허용되지 않는 요청의 범위를 무시합니다. 이 요청 파라미터를 제공하지 않으면 권한 부여 서버는 앱 클라이언트 구성에서 활성화한 모든 권한 부여 범위가 포함된 액세스 토큰 `scope` 클레임을 반환합니다. 표준 범위, 리소스 서버의 사용자 지정 범위, `aws.cognito.signin.user.admin` 사용자 셀프 서비스 범위 등 요청된 앱 클라이언트에 허용되는 모든 범위를 요청할 수 있습니다.
**`redirect_uri`**
*선택 사항. 클라이언트 자격 증명 부여에는 필요하지 않습니다.*
`/oauth2/authorize`에서 `authorization_code`를 얻기 위해 사용했던 `redirect_uri`와 같아야 합니다.
`grant_type`가 `authorization_code`인 경우 이 파라미터를 제공해야 합니다.
**`refresh_token`**
*선택 사항. 사용자에게 이미 새로 고침 토큰이 있고 새 ID 및 액세스 토큰을 가져오려는 경우에만 사용됩니다.*
사용자 세션에 대한 새로운 액세스 및 ID 토큰을 생성하려면 `refresh_token` 값을 요청된 앱 클라이언트가 발행한 유효한 새로 고침 토큰으로 설정합니다.
[새로 고침 토큰 교체](amazon-cognito-user-pools-using-the-refresh-token.md#using-the-refresh-token-rotation)가 활성 상태일 때 새 ID 및 액세스 토큰이 있는 새 새로 고침 토큰을 반환하고, 그렇지 않으면 ID 및 액세스 토큰만 반환합니다. 원래 액세스 토큰이 [API 리소스에 바인딩](cognito-user-pools-define-resource-servers.md#cognito-user-pools-resource-binding)된 경우 새 액세스 토큰은 요청된 API URL을 `aud` 클레임에 유지합니다.
**`code`**
*선택 사항. 권한 부여 코드 부여에만 필요합니다.*
권한 부여 코드 부여의 권한 부여 코드입니다. 권한 부여 요청에 `authorization_code`의 `grant_type`가 포함된 경우 이 파라미터를 제공해야 합니다.
**`aws_client_metadata`**
*선택 사항*.
[M2M(머신 간)](cognito-user-pools-define-resource-servers.md) 권한 부여 흐름에서 [사전 토큰 생성 Lambda 트리거](user-pool-lambda-pre-token-generation.md)에 전달하려는 정보입니다. 애플리케이션은 세션에 대한 컨텍스트 정보를 수집하여 이 파라미터에 전달할 수 있습니다. URL로 인코딩된 JSON 형식으로 `aws_client_metadata`를 전달하면 Amazon Cognito는 이를 트리거 Lambda 함수에 대한 입력 이벤트에 포함합니다. 사전 토큰 트리거 이벤트 버전 또는 글로벌 Lambda 트리거 버전은 버전 3 이상에 맞게 구성해야 합니다. Amazon Cognito는 권한 부여 코드 및 클라이언트 자격 증명 M2M 흐름에서 이 엔드포인트에 대한 요청을 수락하지만 사용자 풀은 `aws_client_metadata`를 클라이언트 자격 증명 요청의 사전 토큰 생성 트리거에만 전달합니다.
**`code_verifier`**
선택 사항. 초기 권한 부여 요청에서 `code_challenge_method` 및 `code_challenge` 파라미터를 제공한 경우에만 필요합니다.
애플리케이션이 [PKCE](using-pkce-in-authorization-code.md)를 통한 권한 부여 코드 부여 요청에서 `code_challenge`를 계산한 생성된 코드 확인자입니다.
## 인증 코드를 토큰으로 교환
다음 요청은 권한 부여 코드 부여로 인증한 후 ID, 액세스 및 새로 고침 토큰을 성공적으로 생성합니다. 요청은 `Authorization` 헤더에 클라이언트 보안 암호를 `client_secret_basic` 형식으로 전달합니다.
```
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
```
응답은 추가 메타데이터와 함께 사용자에게 새 ID, 액세스 및 새로 고침 토큰을 발급합니다.
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJra1example",
"id_token": "eyJra2example",
"refresh_token": "eyJj3example",
"token_type": "Bearer",
"expires_in": 3600
}
```
## 기본 권한이 있는 클라이언트 자격 증명
M2M 애플리케이션의 다음 요청은 클라이언트 자격 증명 부여를 요청합니다. 클라이언트 자격 증명에는 클라이언트 보안 암호가 필요하므로 요청은 앱 클라이언트 ID 및 보안 암호에서 파생된 `Authorization` 헤더로 승인됩니다. 요청으로 인해 요청된 두 범위가 있는 액세스 토큰이 생성됩니다. 이 요청에는 IP 주소 정보를 제공하는 클라이언트 메타데이터와 이 권한 부여가 대리하는 사용자에게 발급된 토큰도 포함됩니다. Amazon Cognito는 클라이언트 메타데이터를 사전 토큰 생성 Lambda 트리거에 전달합니다.
```
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는 다음 입력 이벤트를 사전 토큰 생성 Lambda 트리거에 전달합니다.
```
{
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 }
}
```
응답은 액세스 토큰을 반환합니다. 클라이언트 자격 증명 부여는 M2M(머신 간) 인증을 위한 것이며 액세스 토큰만 반환합니다.
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJra1example",
"token_type": "Bearer",
"expires_in": 3600
}
```
## POST 본문 권한이 있는 클라이언트 자격 증명
다음 클라이언트 자격 증명 권한 부여 요청은 요청 본문에 `client_secret` 파라미터를 포함하고 `Authorization` 헤더를 포함하지 않습니다. 이 요청은 `client_secret_post` 권한 부여 구문을 사용합니다. 요청으로 인해 요청된 범위가 있는 액세스 토큰이 생성됩니다. 이 요청에는 IP 주소 정보를 제공하는 클라이언트 메타데이터와 이 권한 부여가 대리하는 사용자에게 발급된 토큰도 포함됩니다. Amazon Cognito는 클라이언트 메타데이터를 사전 토큰 생성 Lambda 트리거에 전달합니다.
```
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는 다음 입력 이벤트를 사전 토큰 생성 Lambda 트리거에 전달합니다.
```
{
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 }
}
```
응답은 액세스 토큰을 반환합니다. 클라이언트 자격 증명 부여는 M2M(머신 간) 인증을 위한 것이며 액세스 토큰만 반환합니다.
```
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"
}
```
## PKCE를 통한 인증 코드 권한 부여
다음 예제 요청은 [PKCE](using-pkce-in-authorization-code.md)를 사용한 권한 부여 코드 부여 요청에 `code_challenge_method` 및 `code_challenge` 파라미터를 포함한 권한 부여 요청을 완료합니다.
```
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
```
응답은 애플리케이션의 성공적인 PKCE 확인에서 ID, 액세스 및 새로 고침 토큰을 반환합니다.
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJra1example",
"id_token": "eyJra2example",
"refresh_token": "eyJj3example",
"token_type": "Bearer",
"expires_in": 3600
}
```
## 새로 고침 토큰 교체 없이 토큰 새로 고침
다음 예제 요청은 새로 고침 토큰 교체가 비활성 상태인 [앱 클라이언트에 새로 고침 토큰](amazon-cognito-user-pools-using-the-refresh-token.md#using-the-refresh-token-rotation)을 제공합니다. 앱 클라이언트에는 클라이언트 보안 암호가 있으므로 요청은 `Authorization` 헤더를 제공합니다.
```
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
```
응답은 새 ID와 액세스 토큰을 반환합니다.
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJra1example",
"id_token": "eyJra2example",
"token_type": "Bearer",
"expires_in": 3600
}
```
## 새로 고침 토큰 교체를 통한 토큰 새로 고침
다음 예제 요청은 [새로 고침 토큰 교체](amazon-cognito-user-pools-using-the-refresh-token.md#using-the-refresh-token-rotation)가 활성화된 앱 클라이언트에 새로 고침 토큰을 제공합니다. 앱 클라이언트에는 클라이언트 보안 암호가 있으므로 요청은 `Authorization` 헤더를 제공합니다.
```
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
```
응답은 새로운 ID, 액세스 및 새로 고침 토큰을 반환합니다.
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJra1example",
"id_token": "eyJra2example",
"refresh_token": "eyJj4example",
"token_type": "Bearer",
"expires_in": 3600
}
```
## 부정 응답 예제
형식이 잘못된 요청은 토큰 엔드포인트에서 오류를 생성합니다. 다음은 토큰 요청에서 오류가 발생할 때 응답 본문의 일반적인 맵입니다.
```
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`**
요청에 필수 파라미터가 누락되거나, 지원되지 않는 파라미터 값(`unsupported_grant_type` 아님)이 포함되거나, 잘못되었습니다. 예를 들어, `grant_type`이 `refresh_token`이지만 `refresh_token`이 포함되어 있지 않습니다.
**`invalid_client`**
클라이언트 인증에 실패했습니다. 예를 들어, 클라이언트가 권한 부여 헤더에 `client_id` 및 `client_secret`을 포함하지만 `client_id` 및 `client_secret`이 있는 클라이언트가 없는 경우입니다.
**`invalid_grant`**
새로 고침 토큰이 취소되었습니다.
권한 부여 코드를 이미 사용했거나 해당 코드가 존재하지 않습니다.
앱 클라이언트에는 요청한 범위의 일부 [속성](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html)에 대한 읽기 액세스 권한이 없습니다. 예를 들어, 앱이 `email` 범위를 요청하면 앱 클라이언트는 `email` 속성을 읽을 수 있지만, `email_verified` 속성은 읽을 수 없습니다.
**`unauthorized_client`**
클라이언트가 코드 부여 흐름이나 토큰 새로 고침에 대해 허용되지 않습니다.
**`unsupported_grant_type`**
`grant_type`이 `authorization_code` 또는 `refresh_token` 또는 `client_credentials` 이외의 것인 경우 반환됩니다.