사용자 가이드
Cognito App Client를 발급받고, 발급 정보로 로그인 인증을 구현하는 방법을 안내합니다.
1. 앱 발급 절차
- 대시보드의 앱 클라이언트 프로비저닝 폼을 작성합니다(앱 이름 3~128자, 앱 타입, 콜백 URL 1개 이상, 로그아웃 URL·설명은 선택).
- 앱 클라이언트 생성을 누르면 발급 정보와 복사 가능한
.env블록이 표시됩니다.
Client Secret은 발급 화면에서만 확인할 수 있습니다(재발급 기능 없음). 성공 화면의 .env 블록을 지금 복사해 안전하게 보관하세요.
📝 콜백/로그아웃 URL은 발급 이후에도 포털의 관리 → 내 앱 → 수정에서 추가·삭제·변경할 수 있습니다. (Client ID·Client Secret·앱 타입은 변경되지 않습니다.)
2. 콜백 / 로그아웃 URL 규칙
아래 패턴만 허용됩니다. 다른 값은 「사내 IP만 허용됩니다」 오류가 납니다.
| 허용 | 예시 | 비허용 |
|---|---|---|
| https://*.piolink.com 또는 *.piolink.kr | https://app.piolink.com/callback | http 도메인(http://app.piolink.com), 외부 도메인(google.com) |
| https://*.webfront.kr | https://hqa.webfront.kr/callback | webfront.com 등 기타 도메인 |
| http://localhost[:포트]/... | http://localhost:3000/callback | localhost가 아닌 http 주소 |
| https://192.168.x.x[:포트]/... | https://192.168.1.50/callback | http IP, https://10.0.0.1/... |
※ `webfront.com`은 허용되지 않습니다.
Cognito는 등록된 URL로만 인증 코드를 보내므로, 앱의 redirect_uri와 정확히 일치해야 합니다.
콜백은 발급 후에도 관리 → 내 앱 → 수정에서 추가·삭제·변경할 수 있습니다(최소 1개 유지). 앱 주소가 바뀌면 새로 발급받지 말고 여기서 갱신하세요.
콜백은 2개를 함께 등록하는 것을 권장합니다. 로컬 테스트용 http://localhost:3000/api/auth/callback/cognito 와 배포용 https://[앱].piolink.com/api/auth/callback/cognito.
3. 앱 타입 선택
| 앱 타입 | Client Secret | 언제 선택? |
|---|---|---|
| 기밀 클라이언트 (Confidential) | 발급됨 | 백엔드 서버가 있는 웹 앱 |
| 퍼블릭 클라이언트 (Public) | 미발급 | 순수 프론트(SPA)/모바일 — PKCE 필수 |
| M2M | 발급됨 | 서버 간 통신 |
대부분의 경우 기본 옵션(기밀 클라이언트)을 그대로 선택하면 됩니다. 서버가 있는 웹/백엔드 앱(Next.js, Spring Boot, Django, Express 등)은 전부 Confidential이 맞습니다.
고정 정책(변경 불가): flow code · scope openid email profile · IdP COGNITO
4. 발급 결과로 인증 구현하기
생성 직후 표시되는 .env 블록을 AI 코딩 에이전트에 그대로 붙여넣어 로그인을 구현할 수 있습니다.
당신은 시니어 웹 개발자다. 아래 AWS Cognito App client 정보를 그대로 이용하여 인증(로그인/로그아웃/세션 보호) 기능을 구현해줘. COGNITO_USER_POOL_ID=ap-northeast-2_XXXXXXXXX COGNITO_CLIENT_ID=xxxxxxxxxxxxx COGNITO_CLIENT_SECRET=.... AWS_REGION=ap-northeast-2 COGNITO_ISSUER=https://cognito-idp.ap-northeast-2.amazonaws.com/ap-northeast-2_XXXXXXXXX COGNITO_DOMAIN=awssso.piolink.com COGNITO_CALLBACK_URL_1=http://localhost:3000/api/auth/callback/cognito 조건: 프레임워크(예: Next.js/Spring/Express), 콜백은 COGNITO_CALLBACK_URL_1과 정확히 일치, scope은 openid email profile만 사용(offline_access 금지), Secret은 커밋/프론트에 두지 말 것.
프레임워크별 전체 예제는 아래 「상세 보기」 링크(관리 페이지와 동일한 이 페이지의 하단 섹션)를 참고하세요.
5. 발급한 앱 관리 (관리 → 내 앱)
- 검색: 앱 이름 / Client ID / 설명 부분일치.
- 잠금 🔒: 실수 삭제 방지. 잠긴 앱은 삭제 불가(수정·잠금해제는 가능).
- 수정 ✏️: 콜백/로그아웃 URL·설명 변경 → AWS 즉시 반영 + 갱신 .env 표시. 발급 후에도 언제든 콜백을 추가·삭제·변경할 수 있습니다(Client ID·Secret·앱 타입은 불변).
- 삭제 🗑️: AWS·목록에서 영구 삭제. 타인 앱/잠긴 앱은 삭제 불가.
6. 자주 묻는 문제
| 문제 | 조치 |
|---|---|
| 로그인 후 로그인 화면으로 돌아옴 | 쿠키를 지우고 재시도. 계속되면 관리자 문의 |
| 「사내 IP만 허용됩니다」 오류 | 콜백/로그아웃이 §2 규칙을 벗어남 |
| 삭제 버튼 비활성 | 앱이 잠금 상태 → 잠금 해제 후 삭제 |
| Client Secret 분실 | 재발급 불가 → 앱 삭제 후 재발급 |
| 토큰이 1시간 뒤 만료 | refresh_token을 저장해 갱신(수명 30일). offline_access는 불필요 |
7. 인증 구현용 AI 에이전트 프롬프트 (프레임워크별)
아래 예제는 Confidential(백엔드 웹 앱, 기본) 기준입니다. Public(SPA/모바일)로 발급했다면 「PKCE 사용, Client Secret 없음」을 반드시 명시하세요.
당신은 시니어 웹 개발자다. 아래 .env 정보로 Next.js(App Router) 앱에 사내 Cognito OIDC 로그인을 구현해라. 패키지는 next-auth(Auth.js v5)를 쓰고 app/api/auth/[...nextauth] route handler + Cognito provider 구성. .env 값: <생성 화면의 .env 블록을 그대로 붙여넣기> - clientId/clientSecret/issuer 설정, 세션은 JWT. - 콜백 redirect_uri를 .env의 COGNITO_CALLBACK_URL_1과 정확히 일치시킬 것. - scope: openid email profile만. offline_access 금지. - 서버 컴포넌트에서 세션을 읽어 로그인 안 된 사용자는 로그인 페이지로 보낼 것. - 구현 후 npm run build로 검증.
당신은 시니어 Java/Spring 개발자다. Spring Boot 3 앱에 사내 Cognito OIDC 로그인을 spring-boot-starter-oauth2-client로 구현해라. 설정값: issuer-uri / client-id / client-secret / redirect-uri(http://localhost:8080/login/oauth2/code/cognito) - issuer-uri로 OIDC discovery 사용, registrationId="cognito". - scope: openid,email,profile (offline_access 금지). - 로그인 성공 시 session에 email/sub 노출, 인증 페이지는 Cognito Hosted UI로. - mvn -q compile로 검증.
당신은 시니어 Node.js 개발자다. Express 앱에 openid-client로 Cognito OIDC 로그인을 구현해라. .env: issuer / client_id / client_secret / redirect_uri=http://localhost:3000/auth/callback - issuer discovery, /auth/login → Cognito 리다이렉트, /auth/callback에서 code 교환, 세션(express-session)에 sub·email 저장, /auth/logout. - scope: openid email profile. offline_access 금지. redirect_uri 일치.
이 가이드는 로그인 없이 누구나 열람할 수 있습니다. 상세 운영(관리자) 내용은 관리자에게 문의하세요.