텔레그램 로그인 위젯 — 내 사이트에 텔레그램으로 로그인

텔레그램으로 로그인이란

내 웹사이트나 앱에 '텔레그램으로 로그인' 버튼을 달면, 방문자는 비밀번호를 새로 만들지 않고 텔레그램 계정으로 로그인합니다. 텔레그램은 지금 이 기능을 OpenID Connect(구글·애플 로그인과 같은 표준) 방식으로 안내합니다. 예전에 쓰던 iframe 자바스크립트 위젯 문서는 따로 보관본으로 옮겨졌습니다.

무엇	내용
준비물	내 서비스를 대표할 봇 하나(@BotFather)
받는 값	Client ID · Client Secret — @BotFather 의 봇 설정 'Login Widget'
등록할 것	로그인을 허락할 내 사이트 주소(도메인)와 돌아올 주소(redirect URI)
붙이는 방법	공식 로그인 라이브러리(웹) · 공식 모바일 SDK · 표준 OpenID Connect 직접 구현

설정 순서

1. @BotFather 에서 봇을 만들거나 고릅니다(봇 만들기). 로그인 창에 이 봇 이름이 내 서비스 이름처럼 보이므로 알아보기 쉬운 이름·사진을 씁니다.
2. 봇 설정의 Login Widget 에서 허락할 주소를 등록합니다. 등록하지 않은 주소에서는 로그인이 열리지 않습니다.
3. 같은 곳에서 Client ID 와 Client Secret 을 받습니다.
4. 웹이면 공식 라이브러리로 버튼을 붙이고, 직접 구현한다면 아래 흐름을 따릅니다.

직접 구현할 때의 흐름

1. 보내기 — 로그인 버튼을 누르면 사용자를 텔레그램 인증 주소(oauth.telegram.org)로 보냅니다. 받을 정보 범위(scope)와 돌아올 주소를 함께 넘깁니다.
2. 돌아오기 — 사용자가 텔레그램에서 허락하면 내 돌아올 주소로 일회용 code 가 붙어 돌아옵니다.
3. 바꾸기 — 내 서버가 이 code 를 Client ID·Secret 과 함께 토큰 주소로 보내 ID 토큰(과 액세스 토큰)을 받습니다. 이 단계는 반드시 서버에서 합니다.
4. 검사하기 — ID 토큰의 서명을 텔레그램이 공개한 키(JWKS)로 확인하고, 발급자·받는 쪽(내 Client ID)·만료 시각이 맞는지 봅니다. 통과해야 그 안의 사용자 정보를 믿습니다.

받을 수 있는 정보 — scope

scope	받는 것
openid	필수 — 텔레그램 사용자 식별
profile	이름·사용자명·프로필 사진 같은 기본 정보
phone	확인된 전화번호 — 사용자가 따로 동의해야 한다
telegram:bot_access	내 봇이 이 사용자에게 메시지를 보낼 수 있게 허락받기

필요한 것만 요청합니다. 전화번호와 메시지 허락은 사용자가 거절할 수 있으니, 받지 못해도 로그인은 되게 만듭니다. 봇이 먼저 말을 걸 수 없는 규칙(봇과 사람 계정)은 사용자가 이 허락을 해 줄 때만 풀립니다.

미니 앱이라면 다른 길

텔레그램 안에서 열리는 미니 앱은 로그인 버튼 없이도 사용자 정보를 받습니다. 대신 서버에서 서명을 검사해야 합니다 — 미니 앱 사용자 확인.