요청 형식 예: 권한 부여 코드 예: 기본 권한이 있는 클라이언트 자격 증명 예: 본문 권한이 있는 클라이언트 자격 증명 예: PKCE를 사용한 권한 부여 코드 예: 교체 없이 토큰 권한 부여 새로 고침 예: 토큰 교체 새로 고침 오류 응답

토큰 발급자 엔드포인트

의 OAuth 2.0 토큰 엔드포인트는 권한 부여 코드 및 클라이언트 자격 증명 권한 부여 흐름을 완료하려는 애플리케이션에 JSON 웹 토큰(JWTs)을 /oauth2/token 발급합니다. 이러한 토큰은 사용자 풀을 사용한 인증의 최종 결과입니다. 여기에는 사용자(ID 토큰), 사용자의 액세스 수준(액세스 토큰) 및 로그인 세션을 유지할 수 있는 사용자의 권한(토큰 새로 고침)에 대한 정보가 포함되어 있습니다. OIDC(OpenID Connect) 신뢰 당사자 라이브러리는 이 엔드포인트의 요청 및 응답 페이로드를 처리합니다. 토큰은 검증 가능한 인증 증명, 프로필 정보 및 백엔드 시스템에 대한 액세스 메커니즘을 제공합니다.

사용자 풀 OAuth 2.0 권한 부여 서버는 토큰 엔드포인트에서 다음과 같은 유형의 세션에 JWT(JSON 웹 토큰)을 발급합니다.

권한 부여 코드 부여 요청을 완료한 사용자. 코드를 성공적으로 사용하면 ID, 액세스 및 새로 고침 토큰이 반환됩니다.
클라이언트 보안 인증 권한 부여를 완료한 M2M(Machine-to-Machine) 세션. 클라이언트 보안 암호로 인증에 성공하면 액세스 토큰이 반환됩니다.
이전에 로그인하고 새로 고침 토큰을 받은 사용자. 새로 고침 토큰 인증은 새 ID와 액세스 토큰을 반환합니다.

참고
관리형 로그인 또는 페더레이션을 통해 권한 부여 코드 권한 부여로 로그인하는 사용자는 항상 토큰 엔드포인트에서 토큰을 새로 고칠 수 있습니다. 사용자 풀에서 기억된 디바이스가 활성화되어 있지 않은 경우 API 작업 InitiateAuth 및 AdminInitiateAuth로 로그인한 사용자는 토큰 엔드포인트를 통해 토큰을 새로 고칠 수 있습니다. 기억된 디바이스가 활성 상태인 경우 앱 클라이언트에 대한 관련 API 또는 SDK 토큰 새로 고침 작업을 사용하여 토큰을 새로 고칩니다.

도메인을 사용자 풀에 추가하면 토큰 엔드포인트를 공개적으로 사용할 수 있게 됩니다. 토큰 엔드포인트는 HTTP POST 요청을 수락합니다. 애플리케이션 보안을 위해 인증 코드 로그인 이벤트와 함께 PKCE를 사용하세요. PKCE는 인증 코드를 전달하는 사용자가 인증을 받은 사용자와 동일한지 확인합니다. PKCE에 대한 자세한 내용은 IETF RFC 7636을 참조하세요.

에서 사용자 풀 앱 클라이언트와 해당 권한 부여 유형, 클라이언트 보안 암호, 허용된 범위 및 클라이언트 IDs 있습니다앱 클라이언트를 사용한 애플리케이션별 설정. M2M 권한 부여, 클라이언트 자격 증명 부여, 액세스 토큰 범위를 사용한 권한 부여에 대한 자세한 내용은 리소스 서버가 있는 범위, M2M 및 API에서 확인할 수 있습니다.

액세스 토큰에서 사용자 관련 정보를 검색하려면 토큰을 userInfo 엔드포인트 또는 GetUser API 요청으로 전달합니다. 액세스 토큰에는 이러한 요청에 대한 적절한 범위가 포함되어야 합니다.

POST 요청을 토큰 엔드포인트로 형식 지정

/oauth2/token 엔드포인트는 HTTPS POST만 지원합니다. 이 엔드포인트는 사용자 대화형이 아닙니다. 애플리케이션에서 OpenID Connect(OIDC) 라이브러리를 사용하여 토큰 요청을 처리합니다.

토큰 엔드포인트는 client_secret_basic 및 client_secret_post 인증을 지원합니다. OIDC 사양에 대한 자세한 내용은 클라이언트 인증을 참조하세요. OpenID Connect 사양의 Token 엔드포인트에 대한 자세한 내용은 토큰 엔드포인트를 참조하세요.

헤더의 요청 파라미터

요청의 헤더에 있는 다음 파라미터를 토큰 엔드포인트에 전달할 수 있습니다.

Authorization

클라이언트에 보안 암호가 발급된 경우 클라이언트는 권한 부여 헤더에서 client_secret_basic HTTP 권한 부여로 해당 client_id 및 client_secret을 전달할 수 있습니다. 요청 본문에 client_secret_post 권한 부여로 client_id 및 client_secret을 포함할 수도 있습니다.

인증 헤더 문자열은 기본 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으로 설정합니다.

새로 고침 토큰 교체가 활성 상태일 때 새 ID 및 액세스 토큰이 있는 새 새로 고침 토큰을 반환하고, 그렇지 않으면 ID 및 액세스 토큰만 반환합니다.

code

선택 사항. 권한 부여 코드 부여에만 필요합니다.

권한 부여 코드 권한 부여의 권한 부여 코드입니다. 권한 부여 요청에 authorization_code의 grant_type가 포함된 경우 이 파라미터를 제공해야 합니다.

aws_client_metadata

선택 사항.

에 전달하려는 정보입니다사전 토큰 생성 Lambda 트리거. 애플리케이션은 사용자 또는 시스템 세션에 대한 컨텍스트 정보를 수집하여이 파라미터에 전달할 수 있습니다. aws_client_metadata URL로 인코딩된 JSON 형식을 전달하면 Amazon Cognito는 이를 트리거 Lambda 함수에 대한 입력 이벤트에 포함합니다. 사전 토큰 트리거 이벤트 버전 또는 글로벌 Lambda 트리거 버전은 버전 2 이상에 맞게 구성해야 합니다.

code_verifier

선택 사항. 초기 권한 부여 요청에서 code_challenge_method 및 code_challenge 파라미터를 제공한 경우에만 필요합니다.

애플리케이션이 PKCE를 통한 권한 부여 코드 부여 요청에서 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(Machinemachine-to-machine) 권한 부여용이며 액세스 토큰만 반환합니다.


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(Machinemachine-to-machine) 권한 부여용이며 액세스 토큰만 반환합니다.


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를 사용한 권한 부여 코드 권한 부여 요청에 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
}

새로 고침 토큰 교체 없이 토큰 새로 고침

다음 예제 요청은 새로 고침 토큰 교체가 비활성화된 앱 클라이언트에 새로 고침 토큰을 제공합니다. 앱 클라이언트에는 클라이언트 보안 암호가 있으므로 요청은 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
}

새로 고침 토큰 교체를 통한 토큰 새로 고침

다음 예제 요청은 새로 고침 토큰 교체가 활성화된 앱 클라이언트에 새로 고침 토큰을 제공합니다. 앱 클라이언트에는 클라이언트 보안 암호가 있으므로 요청은 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

새로 고침 토큰이 취소되었습니다.

권한 부여 코드를 이미 사용했거나 해당 코드가 존재하지 않습니다.

앱 클라이언트에는 요청한 범위의 일부 속성에 대한 읽기 액세스 권한이 없습니다. 예를 들어, 앱이 email 범위를 요청하면 앱 클라이언트는 email 속성을 읽을 수 있지만, email_verified 속성은 읽을 수 없습니다.

unauthorized_client

클라이언트가 코드 부여 흐름이나 토큰 새로 고침에 대해 허용되지 않습니다.

unsupported_grant_type

grant_type이 authorization_code 또는 refresh_token 또는 client_credentials 이외의 것인 경우 반환됩니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

권한 부여 엔드포인트

userInfo 엔드포인트