다중 인증(MFA) 구성

이 페이지에서는 이메일로 인증 코드를 전송하여 사용자의 신원을 확인할 수 있는 다중 인증(MFA)을 구성하는 방법을 설명합니다. 이 기능을 사용하면 사용자가 자신의 계정과 연결된 이메일 주소를 소유하고 있는지 확인할 수 있습니다. MFA는 사용자 인증 정보 반복 입력 공격 및 계정 탈취(ATO)로부터 사용자를 보호하는 데 도움이 될 수 있습니다.

MFA는 점수 기반 키에 사용할 수 있으며 체크박스 키에는 사용할 수 없습니다.

MFA의 구성 프로세스 이해

reCAPTCHA의 MFA 기능은 일반적인 reCAPTCHA 워크플로 위에 구현됩니다.

대략적으로 MFA 워크플로는 다음과 같습니다.

웹사이트에서 중요한 워크플로를 계측합니다.
execute() 호출에서 반환하는 토큰과 MFA 매개변수를 사용하여 MFA requestToken을 가져와 평가를 만듭니다.
사용하려는 채널(지원되는 이메일만)에 따라 requestToken을 사용하여 MFA 챌린지를 트리거합니다.
웹사이트에서 최종 사용자가 입력한 PIN을 확인합니다.
확인 요청에 반환된 토큰을 사용하여 새 평가를 만듭니다.

시작하기 전에

reCAPTCHA 환경을 준비합니다.
프로젝트에 결제 계정을 추가할 때 시작되는 보안 검토 후 MFA에 액세스할 수 있습니다. 이 기능에 사이트를 온보딩하려면 결제 계정을 추가하세요.
MFA의 이메일 확인 기능을 사용 설정하려면 다음 안내를 따르세요.

참고: 이메일 전송의 안정성을 개선하기 위해 다양한 조치를 취하고 있지만 최종 사용자가 메시지를 수신하지 못하도록 하는 여러 요인이 있습니다. MFA와 통합 시 이 요소를 고려해야 합니다. 예를 들어 최종 사용자가 고객지원에 문의하여 계정을 확인할 수 있는 기능을 제공하는 것을 고려해야 합니다.
1. Google Cloud 콘솔에서 reCAPTCHA 페이지로 이동합니다.
  
  reCAPTCHA로 이동
2. 리소스 선택기에 프로젝트 이름이 표시되는지 확인합니다.
  
  프로젝트 이름이 표시되지 않으면 리소스 선택기를 클릭한 다음 프로젝트를 선택합니다.
3. 설정 클릭합니다.
4. 다중 인증 창에서 구성을 클릭합니다.
5. MFA 구성 대화상자에서 다음을 수행합니다.
  1. 이메일 인증을 사용 설정하려면 이메일 사용 설정 전환 버튼을 클릭합니다.
  2. 발신자 이름 상자에 이름을 입력합니다.
  3. 발신자 이메일 상자에 이메일 주소를 입력합니다.
6. 저장을 클릭합니다.
참고: 기본적으로 전송되는 이메일은 매우 일반적이고 브랜드화되지 않습니다. 이 이메일을 브랜딩하거나 맞춤설정하려면 전담 기술 전문가에게 문의하세요.
점수 기반 키를 사용하여 웹사이트에 reCAPTCHA를 설정합니다.

웹사이트의 중요 워크플로 계측

위험 평가를 위해 execute() 함수를 사용하여 reCAPTCHA에 필요한 정보를 전달합니다. execute() 함수는 토큰 생성 시 확인된 프라미스를 반환합니다.

다음 샘플 코드에서와 같이 twofactor 매개변수를 execute() 함수에 추가합니다.

  grecaptcha.enterprise.execute(KEY_ID, {
    action: 'login',
    twofactor: true
  }).then(token => {
    // Handle the generated token.
  });

KEY_ID를 웹사이트용으로 만든 점수 기반 키로 바꿉니다.

평가 작성

execute() 함수에서 생성된 토큰을 사용하여 reCAPTCHA 클라이언트 라이브러리 또는 백엔드의 REST API를 사용하여 평가를 만듭니다.

이 문서에서는 REST API를 사용하여 MFA 평가를 만드는 방법을 보여줍니다. 클라이언트 라이브러리를 사용하여 평가를 만드는 방법은 웹사이트 평가 만들기를 참조하세요.

평가를 만들기 전에 다음을 수행합니다.

reCAPTCHA에 대한 인증을 설정합니다.

reCAPTCHA가 설정된 환경에 따라 선택하는 인증 방법이 달라집니다. 다음 표는 인증을 설정하는 데 적합한 인증 방법과 지원되는 인터페이스를 선택하는 데 도움이 됩니다.

환경	인터페이스	인증 방법
Google Cloud	REST 클라이언트 라이브러리	연결된 서비스 계정을 사용합니다.
온프레미스 또는 다른 클라우드 제공업체	REST	API 키 또는워크로드 아이덴티티 제휴를 사용합니다. API 키를 사용하려면 API 키 제한사항을 적용하여 API 키를 보호하는 것이 좋습니다.
클라이언트 라이브러리	다음 중 하나를 사용합니다. Python 또는 Java의 경우 API 키 또는 워크로드 아이덴티티 제휴를 사용합니다. API 키를 사용하려면 API 키 제한사항을 적용하여 API 키를 보호하는 것이 좋습니다. 다른 언어의 경우 워크로드 아이덴티티 제휴를 사용하세요.

환경

인터페이스

인증 방법

Google Cloud

REST
클라이언트 라이브러리

연결된 서비스 계정을 사용합니다.

온프레미스 또는 다른 클라우드 제공업체

REST

API 키 또는워크로드 아이덴티티 제휴를 사용합니다.

API 키를 사용하려면 API 키 제한사항을 적용하여 API 키를 보호하는 것이 좋습니다.

클라이언트 라이브러리

다음 중 하나를 사용합니다.

Python 또는 Java의 경우 API 키 또는 워크로드 아이덴티티 제휴를 사용합니다.
API 키를 사용하려면 API 키 제한사항을 적용하여 API 키를 보호하는 것이 좋습니다.
다른 언어의 경우 워크로드 아이덴티티 제휴를 사용하세요.

사용자가 자주 변경하지 않는 안정적인 계정 식별자 accountId를 선택하고 projects.assessments.create 메서드의 평가에 제공합니다. 이 안정적인 계정 식별자는 동일한 사용자와 관련된 모든 이벤트에서 같은 값이어야 합니다. 계정 식별자로 다음을 제공할 수 있습니다.
사용자 식별자

모든 계정을 안정적인 사용자 이름, 이메일 주소 또는 전화번호와 고유하게 연결할 수 있는 경우 accountId로 사용할 수 있습니다. 이러한 교차 사이트 식별자(사이트 간에 재사용할 수 있는 식별자)를 제공하면 reCAPTCHA가 이 정보를 사용하여 악용 계정 식별자를 신고하고 이러한 식별자와 관련된 교차 사이트 악용 패턴에 대한 지식을 사용하여 교차 사이트 모델을 기반으로 사용자 계정 보호를 강화할 수 있습니다.

또는 각 계정과 고유하게 연결된 내부 사용자 ID가 있으면 이를 accountId로 제공할 수 있습니다.
해싱 또는 암호화됨

각 계정에 고유하게 연결된 내부 사용자 ID가 없는 경우 안정적인 식별자를 사이트별 불확실한 계정 식별자로 전환할 수 있습니다. 이 식별자는 reCAPTCHA 계정 방어 도구가 사용자 활동 패턴을 이해하고 비정상적인 동작을 감지하는 데 필요하지만 다른 사이트 간에 공유되지는 않습니다.

reCAPTCHA에 전송하기 전에 안정적인 계정 식별자를 선택하고 암호화 또는 해싱을 사용하여 불확실하게 만듭니다.
- 암호화(권장): 안정적인 암호문을 생성하는 확정적 암호화 메서드를 사용하여 계정 식별자를 암호화합니다. 자세한 안내는 확정적으로 데이터 암호화를 참조하세요. 해싱 대신 대칭적 암호화를 선택할 경우 사용자 식별자와 해당 불확실한 사용자 식별자 간에 매핑을 유지할 필요가 없습니다. reCAPTCHA에서 반환하는 불확실한 식별자를 복호화하여 사용자 식별자로 변환합니다.
- 해싱: SHA256-HMAC 메서드를 사용하여 원하는 커스텀 솔트로 계정 식별자를 해싱하는 것이 좋습니다. 해시는 단방향이므로, 원래 계정으로 다시 반환할 수 있는 해시된 계정 식별자를 매핑할 수 있도록 생성된 해시와 사용자 식별자 간에 매핑을 유지해야 합니다.

projects.assessments.create 메서드의 평가에서 확인할 accountId 매개변수와 엔드포인트(예: 이메일 주소)를 추가합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
TOKEN: grecaptcha.enterprise.execute() 호출에서 반환된 토큰입니다.
KEY_ID: 웹사이트에 설치한 점수 기반 키입니다.
ACCOUNT_ID: 웹사이트에 고유한 사용자 계정의 식별자입니다.
EMAIL_ID: 확인 요청을 트리거해야 하는 이메일 주소입니다.

HTTP 메서드 및 URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments

JSON 요청 본문:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userInfo": {
       "accountId": "ACCOUNT_ID"
    }
  }
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "EMAIL_ID",
    }]
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments"

PowerShell

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.


{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "",
    }],
    "latestVerificationResult": "RESULT_UNSPECIFIED"
  }
}

평가에는 토큰을 발행한 기기에서 지정된 엔드포인트에 대한 최근의 성공적인 확인 날짜 및 시간이 포함됩니다(있는 경우). 또한 암호화된 문자열이 포함된 엔드포인트당 requestToken 필드 하나도 포함됩니다. 엔드포인트에 MFA 챌린지를 트리거하려면 암호화된 문자열을 웹페이지에 다시 보내야 합니다. 요청 토큰은 15분 동안 유효합니다.

권장 조치

프로젝트에 reCAPTCHA 계정 방어 도구를 사용 설정한 경우 평가 응답에는 MFA와 관련된 정보 외에도 계정 방어 도구와 관련된 정보가 포함됩니다. recommended_action 필드에서는 MFA 챌린지를 트리거하기 전에 취할 수 있는 조치를 보여줍니다.

다음 예시는 MFA 건너뛰기를 권장 작업으로 표시하는 샘플 평가를 보여줍니다.

{
  [...],
  "accountDefenderAssessment": {
    labels: ["PROFILE_MATCH"],
    "recommended_action": "SKIP_2FA"
  }
}

recommended_action 필드에는 다음 값이 포함될 수 있습니다.

값	설명
`RECOMMENDED_ACTION_UNSPECIFIED`	계정 방어 도구가 이 요청을 판단할 수 없음을 나타냅니다.
`SKIP_2FA`	계정 방어 도구가 이 평가에서 MFA를 건너뛰는 것이 안전하다고 간주함을 나타냅니다. 일반적으로 사용자가 최근 이 기기에서 사이트에 인증했음을 의미합니다.
`REQUEST_2FA`	사용자에 대한 MFA 챌린지를 트리거함을 나타냅니다. 자세한 내용은 계정 방어 도구 평가 응답을 참조하세요.

웹사이트에서 MFA 챌린지 트리거

평가에 포함된 정보를 기반으로 사용자에게 챌린지를 트리거하려면 평가에서 확인하려는 엔드포인트의 MFA requestToken을 다시 웹페이지로 보냅니다.

challengeAccount() 호출을 통해 MFA 챌린지를 트리거합니다. challengeAccount() 함수는 챌린지가 완료되면 해결되거나 오류 또는 제한 시간 초과 시 거부되는 프라미스를 리턴합니다. 완료되면 업데이트된 정보가 포함된 새 토큰이 생성된 후 평가를 위해 전송됩니다.

MFA 챌린지를 트리거하려면 다음을 수행합니다.

MFA 통합을 테스트합니다.

다음 값을 제공하여 challengeAccount()를 호출하여 MFA 챌린지를 트리거합니다.
- KEY_ID: 웹사이트에 설치한 점수 기반 키입니다.
- REQUEST_TOKEN_FROM_ASSESSMENT: 평가 응답의 requestToken 필드 값입니다.
- CONTAINER_HTML_COMPONENT_ID: 확인 챌린지를 렌더링해야 하는 HTML 구성요소의 ID입니다. 이 매개변수를 지정하지 않으면 챌린지는 페이지 상단의 오버레이에 렌더링됩니다.
다음 예시에서는 challengeAccount()를 호출하여 MFA 챌린지를 트리거하는 방법을 보여줍니다.
```
grecaptcha.enterprise.challengeAccount(KEY_ID, {
  'account-token': REQUEST_TOKEN_FROM_ASSESSMENT,
  'container': CONTAINER_HTML_COMPONENT_ID
}).then(newToken => {
  // Handle the new token.
});
```
challengeAccount() 요청이 성공하면 수신된 PIN을 입력할 수 있는 HTML 구성요소가 표시됩니다. 올바른 PIN을 입력하면 newToken 변수가 백엔드에서 생성된 평가를 통해 확인할 결과 토큰이 포함된 연결 함수로 전달됩니다.

참고: 이 기본 챌린지 UI에는 프로덕션 환경에 적합한 오류 처리 또는 기타 맞춤설정 기능이 없습니다. 따라서 통합 단계 이후에는 이 프로토타입을 사용하지 않는 것이 좋습니다.

다음 매개변수를 사용하여 확인 핸들을 만들고 챌린지를 시작합니다.

// Initialize verification handle.
const verificationHandle = grecaptcha.enterprise.eap.initTwoFactorVerificationHandle(
  KEY_ID,
  REQUEST_TOKEN_FROM_ASSESSMENT
);

// Call the challenge API.
verificationHandle.challengeAccount().then(
  (challengeResponse) => {
    if (challengeResponse.isSuccess()) {
      // Handle success: This means displaying an input for the end user to
      // enter the PIN that they received and then call the `verifyAccount(pin)`
      // method.
    } else {
      // Handle API failure
    }
  });

웹페이지에서 MFA 코드 확인

최종 사용자로부터 PIN을 가져온 후에는 PIN이 올바른지 여부를 확인해야 합니다.

PIN을 확인하려면 최종 사용자가 입력한 PIN으로 verificationHandle.verifyAccount()를 호출합니다.

verificationHandle.verifyAccount(pin).then(
  (verifyResponse) => {
    if (verifyResponse.isSuccess()) {
      // Handle success: Send the result of `verifyResponse.getVerdictToken()`
      // to the backend in order to determine if the code was valid.
    } else {
      // Handle API failure
    }
  },
  (error) => {
    // Handle other errors
  }
);

새 평가 만들기

accountId 및 endpoints로 새 평가를 만듭니다. 자세한 내용은 MFA 평가 만들기를 참조하세요.

클라이언트에서 워크플로가 완료되면 트리거한 인증 결과를 가져올 때 사용할 수 있는 새 토큰을 받게 됩니다. 평가에는 성공한 최근의 성공 인증과 관련된 최신 타임스탬프와 성공 결과 상태가 포함되어야 합니다.

다음 예시는 웹사이트에서 가져온 새 토큰을 사용하여 새 평가를 요청하면 받는 샘플 평가를 보여줍니다.

{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "2020-03-23 08:27:12 PST",
    }],
    "latestVerificationResult": "SUCCESS_USER_VERIFIED"
  }
}

latestVerificationResult 필드는 다음 표에 나열된 것과 다른 상태를 표시할 수 있습니다.

인증 결과 상태	설명
SUCCESS_USER_VERIFIED	사용자가 성공적으로 인증되었습니다.
ERROR_USER_NOT_VERIFIED	사용자가 인증 챌린지에 답하지 못했습니다.
ERROR_SITE_ONBOARDING_INCOMPLETE	사이트가 이 기능을 사용할 수 있도록 올바르게 온보딩되지 않았습니다.
ERROR_RECIPIENT_NOT_ALLOWED	이 수신자에게는 테스트 중 이메일 전송이 승인되지 않았습니다.
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED	이 수신자는 짧은 기간 내에 이미 인증 코드를 너무 많이 받았습니다.
ERROR_CUSTOMER_QUOTA_EXHAUSTED	사용 가능한 MFA 할당량을 초과했습니다.
ERROR_CRITICAL_INTERNAL	시스템 내부 오류로 인해 인증을 완료할 수 없습니다.
RESULT_UNSPECIFIED	최근 인증에 대한 정보가 없습니다(인증 내역 없음).

다음 단계

reCAPTCHA 계정 방어 도구를 사용하여 계정 관련 허위 행위 감지 및 방지