initiate+validate 및 initiate+wait 패턴에 대한 시작 API 계약

온라인에서 편집하기

initiate 자원은 사용되는 요소가 "initiate+validate" 또는 "initiate+wait" 통합 패턴을 지원하는 경우 런타임 MFA 인증 확인 중에 내부 Verify 구성요소에서 실행됩니다.

예를 들어, smsotp 또는 푸시입니다. Verify에서는 MFA 시작 성공 또는 실패를 표시하는 status와 후속 "validate" 또는 "wait for result" 요청에 포함된 트랜잭션 ID가 응답에 포함될 것으로 예상합니다. 다음 예시에서는 가 실시간 웹훅의 리소스로 initiateVerify 전송하는 요청의 예시를 보여줍니다. 웹훅 구성에 따라 이 동일한 페이로드를 대상 MFA 제공자에 직접 전송하거나 대상 제공자가 승인 가능한 API 클라이언트 요청으로 변환할 수 있습니다.
POST '/initiate' \
'Content-Type: application/json' \
'Accept: application/json' \

{
  "capability":  "<<factor capability name, e.g. totp>>",
  "id": "<<factor or device identifier from external provider>>",
  "attributes":
    {
      "username": "<<external MFA username>>"
    }
}
참고: 이 예시에서 /initiateHTTP 경로는 웹훅 구성에 따라 달라집니다.

시작 요청 세부사항

요소 설명
HTTP 요청 POST
HTTP 헤더 - Content-Type 요청 페이로드의 컨텐츠 유형은 항상 application/json입니다.
HTTP 헤더 - Accept 응답 페이로드에 대해 예상되는 컨텐츠 유형은 항상 application/json입니다.
페이로드 유효성을 검증할 토큰 또는 전달 값을 나타내는 JSON 오브젝트입니다. 또한 페이로드는 사용자 및 사용자와 연관된 MFA 등록을 식별합니다.
id

필수. 사용자의 등록된 MFA 요소 기능의 고유 ID입니다.
capability

필수. 값은 유효한 문자열입니다. 웹훅과 연관된 MFA 제공자에 대해 구성된 기능 중 하나와 일치해야 합니다.
attributes

필수. 요청 특정 추가 속성입니다.
attributes.username 필수. MFA 시작이 요청된 외부 제공자 시스템의 사용자 이름입니다.
다음 코드 샘플은 initiate 응답 페이로드의 예제입니다.
{
    "attributes": {
        "<<any name>>": "<<any value>>"
    },
    "status": "SUCCESS",
    "transactionId": "<<provider transaction identifier>>"
}

시작 응답 세부사항

요소 설명
페이로드 유형 MFA 시작 시도 상태를 나타내는 JSON 오브젝트입니다.
HTTP 상태 코드 HTTP 상태를 참조하십시오.
status 필수. 유효성 검증 완료 상태입니다. 유효한 값은 SUCCESS, PENDING, TIMEOUT, CANCELED 및 FAILED입니다.
참고: 다음 상태를 반환하는 경우SUCCESS초보자용 호출을 시도하면 최종 사용자에게 오류가 발생합니다. SUCCESS는 Initiate 호출에 대해 유효한 상태가 아닙니다

MFA 제공자가 OTP 재시도를 지원하는 경우, '상태'는 '보류 중'으로 반환되어야 합니다.
transactionId

필수. 트랜잭션 또는 기타 MFA 제공자 인증 확인 상태 핸들입니다. 제공자가 후속 "유효성 검증" 또는 "결과 폴링" 호출과 상관시키는 데 사용합니다.
attributes

선택사항. MFA 인증 확인을 트리거한 공용 Verify 클라이언트에 리턴되는 추가 속성입니다. 임의의 속성 및 값이 있을 수 있습니다.