keenauth test login으로 테스트 사용자 로그인하기

keenauth test login은 development 환경의 테스트 사용자를 로그인시키고 토큰을 출력하므로, 로그인 페이지를 클릭하지 않고도 API를 호출하거나 백엔드를 테스트할 수 있습니다. 브라우저와 같은 방식으로 실제 호스티드 로그인을 거치며, 고정된 개발용 코드 424242를 사용합니다(프로덕션이 아닌 환경의 테스트 사용자 및 메시지 참조).

이 명령에는 API 키나 keenauth login 세션이 필요하지 않습니다. 로그인하는 대상은 본인이 아니라 테스트 사용자입니다.

시작하기 전에

테스트 사용자. 이메일 주소의 로컬 부분에 +test 태그가 있어야 합니다(예: ada+test@example.com 또는 ada+test_1@example.com). 먼저 사용자를 생성하십시오(예: keenauth users create --email ada+test@example.com). 명령은 이 형식이 아닌 주소를 요청 전에 거부하고 종료 코드 2로 끝납니다.
공개 애플리케이션. --client-id로 환경의 네이티브 또는 단일 페이지 애플리케이션 ID를 전달하십시오. 해당 애플리케이션은 이메일 코드 로그인(비밀번호 없는 email_otp)을 허용해야 합니다.
리디렉션 URI. 기본적으로 명령은 http://127.0.0.1:<임의 포트>/callback을 사용합니다. 애플리케이션에 http://127.0.0.1/callback을 등록하십시오. 루프백 리디렉션 URI는 모든 포트를 허용합니다(RFC 8252). 해당 주소에서는 아무것도 수신하지 않으며, 리디렉션은 명령이 직접 읽습니다. 등록된 다른 리디렉션 URI를 사용하려면 --redirect-uri를 전달하십시오.
환경의 발급자. --issuer로 전달하거나 KEENAUTH_ISSUER를 설정하십시오(예: https://acme-dev.keenauth.app).

사용법

export KEENAUTH_ISSUER=https://acme-dev.keenauth.app
keenauth test login --user ada+test@example.com --client-id app_01j9z3k4m5n6p7q8r9s0t1v2w3

플래그	설명
`--user`	테스트 사용자의 이메일 주소(필수).
`--client-id`	환경의 공개 애플리케이션 ID(필수).
`--issuer`	환경의 발급자 URL. 기본값: `KEENAUTH_ISSUER` 환경 변수.
`--scope`	요청할 스코프(공백으로 구분). 기본값: `openid profile email`. 리프레시 토큰을 받으려면 `offline_access`를 추가하십시오.
`--resource`	액세스 토큰의 대상 API 리소스 지시자(RFC 8707).
`--redirect-uri`	애플리케이션에 등록된 리디렉션 URI.
`--output`, `-o`	`json`, `yaml` 또는 `table`. 플래그를 생략하면 터미널에서는 표, 그 외에는 JSON으로 출력합니다.

출력에는 token_type, access_token, id_token(openid를 요청한 경우), refresh_token(offline_access를 요청한 경우에만), expires_in, scope가 포함됩니다. 토큰은 비밀번호처럼 취급하십시오. 만료될 때까지 테스트 사용자로 동작합니다. 명령은 토큰을 표준 출력에만 쓰며, 코드는 어디에도 출력하지 않습니다.

ACCESS_TOKEN=$(keenauth test login --user ada+test@example.com --client-id app_01j9z3k4m5n6p7q8r9s0t1v2w3 -o json | jq -r .access_token)
curl -H "Authorization: Bearer $ACCESS_TOKEN" http://localhost:3000/api/orders

명령이 하는 일

환경의 디스커버리 문서를 읽고, PKCE(S256), state, nonce를 포함한 인증 요청을 엽니다.
호스티드 로그인에서 주소를 입력하고, 이메일 코드를 요청한 뒤 424242를 제출합니다. 환경이 이어서 두 번째 인증 요소로 이메일 코드를 요구하면 그 코드를 요청받아 424242를 다시 제출합니다.
리디렉션 URI로 돌아오는 리디렉션을 따라가 state와 iss를 확인하고, 토큰 엔드포인트에서 인증 코드를 교환합니다.
ID 토큰이 요청의 nonce와 함께 애플리케이션용 발급자가 발급한 것인지 확인한 뒤 토큰을 출력합니다.

로그인에 다른 단계가 필요하면 명령은 오류와 함께 중단됩니다. 예를 들어 비밀번호, 패스키, 인증 앱, 주소 도메인의 Single Sign-On, 동의 페이지, 조직 선택 등이 해당합니다.

환경

고정 코드는 development 환경에서만 허용됩니다. 명령은 개발 환경에서만 사용하십시오.

staging에서는 테스트 주소로 아무것도 전송되지 않지만, 고정 코드는 거부됩니다(401 invalid_credentials).
production에서는 +test 주소도 일반 주소입니다. 이메일 코드가 실제로 전송되며, 고정 코드는 거부됩니다.

서버가 단계를 거부하면 CLI는 문제 응답을 변경 없이 출력합니다(error, code, status, detail, request_id). 예를 들어 code: test_feature_not_in_production처럼 표시됩니다.

종료 코드

코드	의미
`0`	테스트 사용자가 로그인했으며 토큰이 출력되었습니다.
`1`	로그인에 실패했습니다. OAuth 오류, `state`, `iss` 또는 `nonce` 불일치, 또는 명령이 완료할 수 없는 단계가 있습니다.
`2`	사용 오류입니다. 주소에 `+test` 태그가 없거나, 필수 플래그나 발급자가 없거나, 값이 잘못되었습니다. 요청은 전송되지 않았습니다.
`3`	서버가 `401` 또는 `403`으로 응답했습니다(예: `invalid_credentials`, `test_feature_not_in_production`).