권한 부여 엔드포인트 - Amazon Cognito
GET /oauth2/authorize긍정적인 응답이 있는 요청의 예부정 응답 예제

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

권한 부여 엔드포인트

/oauth2/authorize 엔드포인트는 두 개의 리디렉션 대상을 지원하는 리디렉션 엔드포인트입니다. URL에 identity_provider 또는 idp_identifier 파라미터를 포함하면 사용자를 해당 ID 제공업체(IdP)의 로그인 페이지로 자동 리디렉션합니다. 그렇지 않으면 요청에 포함된 것과 동일한 URL 파라미터를 사용하여 Login 엔드포인트로 리디렉션됩니다.

권한 부여 엔드포인트는 호스팅 UI 또는 IdP 로그인 페이지로 리디렉션합니다. 이 엔드포인트에서 사용자 세션의 대상은 사용자가 브라우저에서 직접 상호 작용해야 하는 웹 페이지입니다.

권한 부여 엔드포인트를 사용하려면 사용자 풀에 다음 사용자 풀 세부 정보에 대한 정보를 제공하는 매개변수를 사용하여 /oauth2/authorize에서 사용자 브라우저를 호출하세요.

  • 로그인할 앱 클라이언트입니다.

  • 최종 콜백 URL입니다.

  • 사용자의 액세스 토큰에서 요청할 OAuth 2.0 범위입니다.

  • 필요에 따라 로그인하는 데 사용할 서드 파티 IdP입니다.

Amazon Cognito가 수신 클레임을 검증하는 데 사용하는 state 및 nonce 파라미터를 제공할 수도 있습니다.

GET /oauth2/authorize

/oauth2/authorize 엔드포인트는 HTTPS GET만 지원합니다. 대체로 앱은 사용자의 브라우저에서 이 요청을 시작합니다. HTTPS를 통해서만 /oauth2/authorize 엔드포인트에 요청할 수 있습니다.

권한 부여 엔드포인트에서 OpenID Connect(OIDC) 표준의 권한 부여 엔드포인트 정의에 대해 자세히 알아볼 수 있습니다.

요청 파라미터

response_type

(필수) 응답 유형. code 또는 token이어야 합니다.

code의 response_type이 있는 성공적인 요청은 권한 부여 코드 부여를 반환합니다. 권한 부여 코드 부여는 Amazon Cognito가 리디렉션 URL에 추가하는 code 파라미터입니다. 앱에서는 액세스, ID 및 새로 고침 토큰을 위해 Token 엔드포인트와 코드를 교환할 수 있습니다. 보안 모범 사례로 사용자를 위한 새로 고침 토큰을 받으려면 앱에서 권한 부여 코드 부여를 사용하세요.

token의 response_type이 있는 성공적인 요청은 암시적 권한 부여를 반환합니다. 암시적 권한 부여는 Amazon Cognito가 리디렉션 URL에 추가하는 ID 및 액세스 토큰입니다. 암시적 권한 부여는 토큰과 잠재적인 식별 정보를 사용자에게 노출하기 때문에 덜 안전합니다. 앱 클라이언트 구성에서 암시적 권한 부여에 대한 지원을 비활성화할 수 있습니다.

client_id

(필수) 앱 클라이언트 ID.

client_id 값은 요청한 사용자 풀에 있는 앱 클라이언트의 ID여야 합니다. 앱 클라이언트는 Amazon Cognito 로컬 사용자 또는 하나 이상의 서드 파티 IdP 로그인을 지원해야 합니다.

redirect_uri

(필수) Amazon Cognito가 사용자에게 권한을 부여한 후 인증 서버가 브라우저를 리디렉션하는 URL입니다.

리디렉션 URI(Uniform Resource Identifier)의 속성은 다음과 같아야 합니다.

  • 절대 URI이어야 합니다.

  • 클라이언트를 사용하여 URI를 미리 등록했어야 합니다.

  • 여기에는 조각 구성 요소가 없어야 합니다.

OAuth 2.0 - Redirection Endpoint 섹션을 참조하세요.

Amazon Cognito를 사용하려면 리디렉션 URI에서 테스트 목적으로 콜백 URL로 설정할 수 있는 HTTPS를 사용해야 합니다(http://localhost 제외).

또한 Amazon Cognito는 myapp://example과 같은 앱 콜백 URL을 지원합니다.

state

(선택 사항, 권장) 앱이 요청에 상태 파라미터를 추가하면 /oauth2/authorize 엔드포인트가 사용자를 리디렉션할 때 Amazon Cognito가 해당 값을 앱에 반환합니다.

이 값을 요청에 추가하여 CSRF 공격으로부터 보호할 수 있습니다.

state 파라미터의 값을 URL 인코딩 JSON 문자열로 설정할 수 없습니다. 이 형식과 일치하는 문자열을 state 파라미터로 전달하려면 문자열을 base64로 인코딩한 다음 앱에서 디코딩하십시오.

identity_provider

(선택사항) 호스팅된 UI를 우회하고 사용자를 공급자 로그인 페이지로 리디렉션하려면 이 매개변수를 추가합니다. identity_provider 파라미터의 값은 사용자 프로필에 나타나는 대로 자격 증명 공급자(IdP)의 이름입니다.

  • 소셜 공급자의 경우 identity_provider 값, 및 를 사용할 수 있습니다. Facebook Google LoginWithAmazon SignInWithApple

  • Amazon Cognito 사용자 풀의 경우 값을 사용하십시오. COGNITO

  • SAML 2.0 및 OpenID Connect (OIDC) ID 공급자 (IdPs) 의 경우 사용자 풀의 IdP에 할당한 이름을 사용합니다.

idp_identifier

(선택 사항) identity_provider 이름의 대체 이름을 사용하여 공급자로 리디렉션하려면 이 매개 변수를 추가합니다. Amazon Cognito 콘솔의 로그인 경험 탭에서 SAML 2.0 및 IdPs OIDC에 대한 식별자를 입력할 수 있습니다.

scope

(선택 사항) 시스템 예약 범위 또는 클라이언트와 연결된 사용자 지정 범위를 조합할 수 있습니다. 범위는 공백으로 구분해야 합니다. 시스템에 예약된 범위로는 openid, email, phone, profile 및 aws.cognito.signin.user.admin이 있습니다. 사용된 범위는 클라이언트와 연결되어 있어야 합니다. 그렇지 않으면 런타임 시 무시됩니다.

클라이언트가 범위를 요청하지 않은 경우 인증 서버에서는 클라이언트와 연결된 모든 범위를 사용합니다.

openid 범위가 요청될 경우에만 ID 토큰이 반환됩니다. aws.cognito.signin.user.admin 범위가 요청된 경우에만 Amazon Cognito 사용자 풀에 대해 액세스 토큰을 사용할 수 있습니다. phone 범위도 요청된 경우에만 email, profile 및 openid 범위를 요청할 수 있습니다. 이러한 범위는 ID 토큰 내부로 들어가는 클레임을 지정합니다.

code_challenge_method

(선택 사항) 챌린지를 생성하는 데 사용한 해싱 프로토콜. PKCE RFC는 S256 및 일반의 두 가지 메서드를 정의하지만 Amazon Cognito 인증 서버는 S256만 지원합니다.

code_challenge

(선택 사항) 에서 생성한 챌린지입니다. code_verifier

code_challenge_method 파라미터를 지정하는 경우에만 필수입니다.

nonce

(선택 사항) 요청에 추가할 수 있는 임의의 값입니다. 제공한 임시 값은 Amazon Cognito가 발행하는 ID 토큰에 포함되어 있습니다. 재생 공격을 방지하기 위해 앱은 ID 토큰의 nonce 클레임을 검사하고 생성한 것과 비교할 수 있습니다. nonce 클레임에 대한 자세한 내용은 OpenID Connect 표준의 ID 토큰 유효성 검사를 참조하세요.

긍정적인 응답이 있는 요청의 예

다음 예는 /oauth2/authorize 엔드포인트에 대한 HTTP 요청의 형식을 보여줍니다.

인증 코드 권한 부여

다음은 인증 코드 부여에 대한 요청의 예입니다.

예 — GET 요청

다음 요청은 사용자가 redirect_uri 목적지의 앱에 전달하는 인증 코드를 검색하는 세션을 시작합니다. 이 세션에서는 사용자 속성에 대한 범위와 Amazon Cognito 셀프 서비스 API 작업에 대한 액세스 범위를 요청합니다.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin
예 — 응답

Amazon Cognito 인증 서버는 권한 부여 코드 및 상태를 통해 앱으로 다시 리디렉션합니다. 인증 코드는 5분 동안 유효합니다.

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

PKCE를 통한 인증 코드 권한 부여

다음은 PKCE의 인증 코드 부여 요청 예시입니다.

예 — GET 요청

다음 요청은 이전 요청에 code_challenge 매개변수를 추가합니다. 코드를 토큰으로 교환하려면 /oauth2/token 엔드포인트에 대한 요청에 code_verifier 파라미터를 포함해야 합니다.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin&
code_challenge_method=S256&
code_challenge=a1b2c3d4...
예 — 응답

인증 서버는 인증 코드 및 상태를 사용하여 애플리케이션으로 다시 리디렉션합니다. 코드와 상태는 프래그먼트가 아닌 쿼리 문자열 파라미터에 반환되어야 합니다.

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

openid 범위가 없는 토큰 부여

다음은 암시적 승인을 생성하고 JWT를 사용자 세션에 직접 반환하는 요청의 예입니다.

예 — GET 요청

다음은 권한 부여 서버의 암시적 권한 부여에 대한 요청입니다. Amazon Cognito의 액세스 토큰은 셀프 서비스 API 작업을 승인합니다.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=token&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin
예시 — 응답

Amazon Cognito 권한 부여 서버는 액세스 토큰을 통해 앱으로 다시 리디렉션합니다. openid 범위가 요청되지 않았기 때문에 Amazon Cognito에서 ID 토큰을 반환하지 않습니다. 또한 Amazon Cognito는 이 흐름에서 새로 고침 토큰을 반환하지 않습니다. Amazon Cognito는 쿼리 문자열이 아닌 프래그먼트에서 액세스 토큰과 상태를 반환합니다.

HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=STATE

openid 범위가 있는 토큰 부여

다음은 암시적 권한을 생성하고 JWT를 사용자 세션에 직접 반환하는 예제 요청입니다.

예 — GET 요청

다음은 권한 부여 서버의 암시적 권한 부여에 대한 요청입니다. Amazon Cognito의 액세스 토큰은 사용자 속성 및 셀프 서비스 API 작업에 대한 액세스를 승인합니다.

GET
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? 
response_type=token& 
client_id=1example23456789& 
redirect_uri=https://www.example.com& 
state=abcdefg&
scope=aws.cognito.signin.user.admin+openid+profile
예 — 응답

권한 부여 서버는 액세스 토큰과 ID 토큰을 사용하여 앱으로 다시 리디렉션합니다 (openid범위가 포함되었기 때문).

HTTP/1.1 302 Found
Location: https://www.example.com#id_token=eyJra67890EXAMPLE&access_token=eyJra12345EXAMPLE&token_type=bearer&expires_in=3600&state=abcdefg

부정 응답 예제

Amazon Cognito는 요청을 거부할 수 있습니다. 부정적인 요청에는 요청 파라미터를 수정하는 데 사용할 수 있는 HTTP 오류 코드와 설명이 함께 제공됩니다. 다음은 부정적인 응답의 예입니다.

  • client_id및 redirect_uri 가 유효하지만 요청 매개 변수의 형식이 올바르지 않은 경우 인증 서버는 오류를 클라이언트의 서버로 redirect_uri 리디렉션하고 URL 매개 변수에 오류 메시지를 추가합니다. 다음은 잘못된 형식의 예입니다.

    • 요청에는 response_type 매개변수가 포함되어 있지 않습니다.

    • 권한 부여 요청에서 code_challenge 매개변수는 제공했지만 code_challenge_method 매개변수는 제공하지 않았습니다.

    • code_challenge_method파라미터의 값은 그렇지 않습니다S256.

    다음은 잘못된 형식의 예제 요청에 대한 응답입니다.

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request

  • 클라이언트가 요청했지만 이러한 요청에 code 대한 권한이 없는 경우 Amazon Cognito 권한 부여 서버는 다음과 같이 클라이언트의 redirect_uri 서버로 돌아갑니다unauthorized_client. token response_type 

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=unauthorized_client

  • 클라이언트가 알 수 없거나, 형식이 잘못되었거나, 유효하지 않은 범위를 요청한 경우 Amazon Cognito 권한 부여 서버에서 다음과 같이 invalid_scope를 클라이언트의 redirect_uri에 반환합니다.

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_scope

  • 서버에 예상치 못한 오류가 발생하는 경우 인증 서버는 클라이언트의 redirect_uri 서버로 server_error 돌아갑니다. HTTP 500 오류가 클라이언트에 전송되지 않기 때문에 오류가 사용자 브라우저에 표시되지 않습니다. 권한 부여 서버가 다음 오류를 반환합니다.

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=server_error

  • Amazon Cognito가 제3자와의 페더레이션을 통해 인증하는 경우 Amazon IdPs Cognito에서 다음과 같은 연결 문제가 발생할 수 있습니다.

    • IdP에게 토큰을 요청하는 동안 연결 제한 시간이 발생하면 인증 서버가 다음과 같이 오류를 클라이언트의 redirect_uri로 리디렉션합니다.

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Timeout+occurred+in+calling+IdP+token+endpoint

    • ID 토큰 검증을 위해 jwks_uri 엔드포인트를 호출하는 동안 연결 제한 시간이 초과되면 인증 서버가 오류와 함께 다음과 같이 클라이언트의 서버로 리디렉션합니다. redirect_uri 

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=error_description=Timeout+in+calling+jwks+uri

  • 타사와 페더레이션하여 인증하는 경우 공급자가 오류 응답을 IdPs 반환할 수 있습니다. 이는 구성 오류나 다음과 같은 기타 이유 때문일 수 있습니다.

    • 다른 공급자로부터 오류 응답이 수신되면 인증 서버가 다음과 같이 오류를 클라이언트의 redirect_uri로 리디렉션합니다.

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=[IdP name]+Error+-+[status code]+error getting token

    • Google로부터 오류 응답이 수신되면 인증 서버가 다음과 같이 오류를 클라이언트의 redirect_uri로 리디렉션합니다.

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Google+Error+-+[status code]+[Google-provided error code]

  • Amazon Cognito에서 외부 IdP에 연결할 때 통신 예외가 발생하면 인증 서버가 오류와 함께 다음 메시지 중 하나를 사용하여 클라이언트의 redirect_uri 서버로 리디렉션합니다.

    • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Connection+reset
    • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Read+timed+out