authn-api

Okta Authentication API

Okta Authentication API는 사용자 인증을 처리하는 REST API예요. 사용자를 인증하고, 다중 요소 인증(MFA) 등록과 확인을 수행하고, 잊어버린 비밀번호를 복구하거나 잠긴 계정을 해제하는 일을 담당해요. 기존 애플리케이션 위에 identity 레이어를 얹는 독립 API로 쓸 수도 있고, Okta Sessions API와 연동해서 Okta 세션 쿠키를 얻고 Okta 내부의 앱에 접근하는 데 쓸 수도 있어요.

이 API는 자체 로그인 화면을 처음부터 만들어 보고 싶은 개발자를 대상으로 해요. Okta가 기본으로 제공하는 로그인 경험을 대체하는 나만의 로그인 경험을 구축할 수 있죠. 다음 시나리오를 다룹니다.

Primary authentication: 사용자의 아이디와 비밀번호 자격 증명을 검증해요.
MFA(Multifactor authentication): 비밀번호 인증의 보안을 강화하기 위해 다른 Factor의 추가 검증을 요구해요. 예를 들어 비밀번호 외에 일회용 임시 패스코드나 SMS 패스코드를 요구할 수 있어요. 관리자가 활성화한 MFA Factor로 사용자 등록(enrollment)을 지원하고, 글로벌 세션 정책에 기반한 MFA 챌린지를 지원해요.
Recovery: 비밀번호를 잊어버린 사용자가 비밀번호를 안전하게 재설정하거나, 실패한 로그인 시도가 너무 많아 잠긴 계정을 해제할 수 있게 해요.

참고: 이 API의 동작은 앱의 종류와 조직(org)의 보안 정책, 예를 들어 글로벌 세션 정책·MFA 등록 정책·비밀번호 정책에 따라 달라져요. 이 문서는 Classic Engine API에 해당하므로 Identity Engine으로 업그레이드하기 전에 인증 통합과 커스터마이징을 확인해야 해요.

출처: 문서

인증 트랜잭션 (Authentication transaction)

Authentication API는 상태가 있는(stateful) API예요. 정의된 상태와 전환이 있는 유한 상태 머신(finite state machine)을 구현하죠. 최초의 인증 또는 복구 요청마다 고유한 state token이 발급돼요. 이 토큰은 트랜잭션이 완료되거나 취소될 때까지 모든 후속 요청에 함께 전달해야 해요.

API는 JSON HAL 형식을 사용해서 현재 트랜잭션 상태의 next, prev 링크를 노출해요. 상태 머신을 전이할 때는 이 링크를 따라가면 됩니다.

트랜잭션 상태 (Transaction state)

인증 또는 복구 트랜잭션은 다음 상태 중 하나를 가져요.

LOCKED_OUT: 사용자 계정이 잠겼어요. 셀프 서비스 해제 또는 관리자 해제가 필요해요. unlock 링크로 POST 하세요.
MFA_CHALLENGE: 사용자가 Factor별 챌린지를 확인해야 해요. verify 링크로 POST 하세요.
MFA_ENROLL_ACTIVATE: 사용자가 등록을 마치려면 Factor를 활성화해야 해요. next 링크로 POST 하세요.
MFA_ENROLL: 사용자가 추가 검증에 쓸 Factor를 선택·등록해야 해요. Factor별 enroll 링크로 POST 하세요.
MFA_REQUIRED: 사용자가 이전에 등록한 Factor로 추가 검증을 제공해야 해요. Factor별 verify 링크로 POST 하세요.
PASSWORD_EXPIRED: 비밀번호는 검증됐지만 만료됐어요. next 링크로 POST 해서 만료된 비밀번호를 변경하세요.
PASSWORD_RESET: 사용자가 복구 질문에 답했고 새 비밀번호를 설정해야 해요. next 링크로 POST 하세요.
PASSWORD_WARN: 비밀번호는 검증됐지만 곧 만료돼서 변경해야 해요. next 링크로 POST 하세요.
RECOVERY_CHALLENGE: 사용자가 Factor별 복구 챌린지를 확인해야 해요. verify 링크로 POST 하세요.
RECOVERY: 사용자가 비밀번호를 재설정하거나 계정을 해제하는 복구 토큰을 요청했어요. next 링크로 POST 해서 복구 질문에 답하세요.
SUCCESS: 트랜잭션이 성공적으로 완료됐어요.

상태를 전이할 때는 특정 상태 전이나 URL을 미리 가정하면 안 돼요. 항상 응답의 status를 확인하고, 응답에 게시된 링크 관계(_links)를 동적으로 따라가야 해요. 유효한 state token으로 next 링크에 POST 하면 다음 상태로 진행돼요.

토큰 (Tokens)

인증 또는 복구 트랜잭션의 상태에 따라 다른 종류의 토큰이 발급돼요.

State token: 인증 또는 복구 트랜잭션의 현재 상태를 인코딩하는 임시 토큰이에요. 인증을 수행하는 웹 앱과 Okta API 사이에서만 쓰기 위한 것이므로, 사용자에게 이메일 등으로 배포하면 안 돼요. 수명은 요청마다 연장되는 슬라이딩 스케일 만료 알고리즘을 사용해요. 만료된 state token을 쓰면 모든 작업이 401 Unauthorized를 반환해요.
Recovery token: 복구 트랜잭션이 RECOVERY 상태로 전환될 때 recoveryToken으로 발급되는 일회용 토큰이에요. state token으로 교환해서 사용자 비밀번호를 복구하거나 계정을 해제할 수 있어요. 이 토큰은 이메일을 통해 사용자에게 out-of-band로 배포돼요.
Session token: 인증 트랜잭션이 SUCCESS 상태로 완료될 때 sessionToken으로 발급되는 일회용 토큰이에요. Sessions API로 세션과 교환하거나 세션 쿠키로 변환할 수 있어요. 수명은 5분이에요.

Primary authentication (사용 예시)

모든 인증 트랜잭션은 사용자의 기본 비밀번호 자격 증명을 검증하는 primary authentication으로 시작해요. 비밀번호 정책, MFA 정책, 사인온 정책이 이 단계에서 평가돼요. 요청에는 username과 password, 또는 token 파라미터 중 하나를 제공해야 해요.

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-d '{
  "username": "[email protected]",
  "password": "correcthorsebatterystaple",
  "options": {
    "multiOptionalFactorEnroll": false,
    "warnBeforePasswordExpired": false
  }
}' "https://${yourOktaDomain}/api/v1/authn"

비밀번호가 유효하고 추가 검증이 요구되지 않는 사용자라면 트랜잭션이 성공적으로 완료돼요. SUCCESS 상태와 함께 sessionToken이 반환돼요.

{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "[email protected]",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

MFA: Enroll · Verify · Factor

MFA는 MFA_ENROLL·MFA_ENROLL_ACTIVATE·MFA_REQUIRED·MFA_CHALLENGE 상태에서 동작해요. 흐름은 Enroll(Factor 등록) → Activate(활성화) → Verify(검증) 순서로 진행돼요.

Enroll Factor: 사용자가 비밀번호 외의 추가 Factor를 선택해 등록해요. Okta Verify(TOTP·Push), SMS, Call, Email, 구글 Authenticator, RSA SecurID, Symantec VIP, YubiKey, Duo, U2F, WebAuthn, Custom HOTP를 지원해요.
Activate Factor: 등록한 Factor를 활성화해서 실제로 사용할 수 있게 해요(예: TOTP의 검증 코드 확인).
Verify Factor: MFA_REQUIRED 또는 MFA_CHALLENGE 상태에서 등록된 Factor를 검증해요. 검증이 성공하면 SUCCESS 상태와 sessionToken이 반환돼요.

예를 들어 상태가 MFA_CHALLENGE일 때 SMS 챌린지를 보내고, 아래처럼 /api/v1/authn/factors/${factorId}/verify 엔드포인트에 state token을 POST 해서 검증할 수 있어요.

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb"
}' "https://${yourOktaDomain}/api/v1/authn/factors/sms193zUBEROPBNZKPPE/verify"

검증이 성공하면 트랜잭션이 SUCCESS로 전환되고 sessionToken이 발급돼요.

{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00ZD3Z7ixppspFljXV2t_Z6GfrYzqG7cDJ8reWo2hy",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "[email protected]",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

사인온(또는 앱 사인온) 정책이 장치 기억을 허용하면, end user가 현재 장치를 Okta가 기억하도록 선택할 수 있어요. 이 선택은 verify 엔드포인트에 rememberDevice 요청 파라미터로 전달해요(기본값은 false).

Recovery operations

비밀번호를 잊어버렸거나 계정이 잠긴 사용자를 위한 복구 작업이에요.

Forgot password: 이메일·SMS·Call Factor로 복구 토큰을 발급해요. trusted application이라면 recoveryToken을 직접 얻기도 해요.
Unlock account: 잠긴 계정을 복구 Factor(이메일·SMS)로 해제해요.
Verify recovery Factor: 복구 챌린지(SMS·Call)를 검증하고, 필요하면 챌린지를 재전송해요.
Verify recovery token: out-of-band로 받은 recoveryToken을 stateToken으로 교환해요.
Answer recovery question: 복구 질문에 답해서 success 또는 PASSWORD_RESET 상태로 전환해요.
Reset password: 사용자의 비밀번호를 재설정해요.

상태 관리 작업 (State management)

진행 중인 트랜잭션의 상태를 관리하는 작업이에요.

Get transaction state: 유효한 state token으로 현재 트랜잭션 상태를 조회해요.
Previous transaction state: 이전 트랜잭션 상태로 되돌아가요.
Skip transaction state: 현재 상태를 건너뛰어요(예: 선택적인 MFA 등록).
Cancel transaction: 트랜잭션을 취소하고 해제해요.

더 알아보기 (Learn more)

공식 문서