SSO 연락처 인터페이스
이 문서는 연락처를 이메일 주소 또는 제3자 사용자 ID로 로그인시키는 방법을 설명합니다. 이 기능은 하위 계정 SSO 인터페이스와 동일한 appId와 Secret Key를 사용하지만, URL, 서명 필드, 랜딩 페이지는 다릅니다. 하위 계정은 하위 계정 SSO 인터페이스로 생성하고 역할을 설정하세요.
개요
연락처 이메일 또는 제3자 사용자 ID를 전송합니다. SurveyMars가 서명을 확인한 후 해당 연락처를 로그인시킵니다.
- 연락처가 하위 계정인 경우 SurveyMars는 returnUrl을 엽니다. returnUrl이 없으면 설문 목록을 엽니다.
- 연락처가 하위 계정이 아닌 경우 SurveyMars는 returnUrl을 무시하고 연락처 홈 페이지를 엽니다.
사용 사례
- 귀하의 시스템에 이미 연락처 이메일 또는 제3자 사용자 ID가 있으며, SurveyMars에 비밀번호 없이 접속하고 싶을 때.
- 하위 계정 연락처가 returnUrl로 이동합니다. 다른 연락처는 returnUrl을 건너뛰고 연락처 홈 페이지로 이동합니다.
시작하기 전에
1. 메인 계정으로 로그인한 뒤 내 계정에서 appId를 복사합니다.
2. 지원팀에 Secret Key 활성화를 요청하세요. 이 키는 서버에서만 사용해야 합니다. URL이나 프런트엔드 코드에 넣지 마세요.
3. 서버에서 SHA256 서명을 생성한 다음 GET으로 로그인 링크를 엽니다.
요청
메서드: GET
| Parameter | Required | Description |
| appId | Yes | 메인 계정 ID입니다. 하위 계정 SSO 인터페이스와 동일한 appId를 사용하세요. |
| Conditional | 연락처 이메일입니다. email 또는 thirdUserId, 혹은 둘 다 제공하세요. 메인 계정에서 비어 있는 연락처 이메일을 허용하지 않은 경우 email이 필요합니다. | |
| thirdUserId | Conditional | 제3자 사용자 ID입니다. email 또는 thirdUserId, 혹은 둘 다 제공하세요. 둘 다 전송되면 검증에는 email만 사용됩니다. thirdUserId는 서명에는 그대로 포함됩니다. |
| language | No | 프롬프트 메시지의 언어입니다. 서명에는 포함되지 않습니다. |
| returnUrl | No | 하위 계정이 로그인한 후 열 페이지입니다. SurveyMars는 하위 계정 연락처에 대해서만 이를 따르고, 그 외에는 무시합니다. 서명에는 포함되지 않습니다. |
| ts | Yes | 1970-01-01 00:00:00 UTC 이후의 초입니다. 60초 동안 유효합니다. URL의 ts는 서명에 사용된 ts와 일치해야 합니다. 사용자가 링크를 열기 직전에 생성하세요. |
| sign | Yes | 서명입니다. sign은 연결된 평문인 appId + email + thirdUserId + ts + Secret Key의 소문자 16진수 SHA256입니다. 순서는 정확히 일치해야 합니다. Secret Key는 서버에서만 연결되며 브라우저 주소 표시줄에 나타나면 안 됩니다. 아래의 서명 생성 방법을 참고하세요. |
서명 생성
서명 규칙
1. 구분자 없이 고정된 순서로 서명 필드를 연결합니다: appId + email + thirdUserId + ts + Secret Key. email 또는 thirdUserId가 생략되면 해당 위치에는 빈 문자열을 사용하세요. 필드를 제거하거나 자리 표시자로 대체하지 마세요. Secret Key는 서버에서만 연결되며 브라우저 주소 표시줄에 나타나면 안 됩니다.
2. 해당 문자열을 SHA256로 해시한 뒤 소문자 16진수 값을 sign으로 사용합니다.
3. language와 returnUrl은 서명에 포함되지 않습니다. 1단계의 필드와 순서만 사용하세요.
4. ts는 1970-01-01 00:00:00 UTC 이후의 초 단위 숫자입니다. 60초 동안 유효합니다. 사용자가 링크를 열기 직전에 ts와 sign을 생성하고, URL에는 동일한 ts를 사용하세요. URL 인코딩으로 인해 서명에 사용된 원래 값이 변경되어서는 안 됩니다.
5. 연결된 문자열을 확인하려면 LZL online SHA256과 같은 SHA256 도구에 붙여넣으세요. 실제 운영 환경에서는 서버에서 sign을 생성하세요. Secret Key를 브라우저에 노출하지 마세요.
6. 하위 계정 SSO 서명을 재사용하지 마세요. 해당 문자열은 appId, email, userName, roleId, ts를 사용합니다. 이 인터페이스는 userName이나 roleId를 사용하지 않습니다.
예시：
http://surveymars.com/app/login/contact/verify?appId=TTeEB8&[email protected]&ts=1790760357&language=2&returnUrl=https://surveymars.com/app/usercenter&sign=26c0c7d9da5e38c61d4aeecb223336d7a259cad0b75c8ff912855421fd832a4e
이메일과 제3자 사용자 ID
1. email과 thirdUserId 중 최소 하나를 전송하세요.
2. 둘 다 전송하면 검증에는 email이 사용되고 thirdUserId는 무시됩니다. 서명에는 원래의 thirdUserId를 유지하고, URL에도 유지할 수 있습니다.
3. 메인 계정에서 비어 있는 연락처 이메일을 허용하지 않은 경우 email이 필요합니다.
4. 이 설정이 꺼져 있으면 지원팀에 "Allow empty contact email"을 켜 달라고 문의하세요. 활성화되면 이메일 없이도 연락처를 추가할 수 있습니다.
연락처가 이동하는 위치
1. 하위 계정 연락처: SurveyMars가 returnUrl을 엽니다. returnUrl이 생략되면 설문 목록을 엽니다.
2. 다른 연락처: SurveyMars가 returnUrl을 무시하고 연락처 홈 페이지를 엽니다.
중요 참고 사항
- Secret Key는 서버에 보관하세요. 브라우저 주소 표시줄에 넣지 마세요.
- 이 인터페이스는 연락처를 로그인시킵니다. 하위 계정을 생성하거나 하위 계정 역할을 설정하지 않습니다.
- 이메일의 @와 같은 문자는 URL 인코딩하세요. 서명은 인코딩된 값이 아니라 원래 값으로 생성해야 합니다.
자주 묻는 질문
이것은 하위 계정 SSO와 어떻게 다른가요?
하위 계정 SSO는 /app/login/sso/verify를 사용해 하위 계정을 생성하거나 로그인합니다. 연락처 로그인은 이메일 또는 제3자 사용자 ID와 함께 /app/login/contact/verify를 사용합니다. 서명 필드가 다릅니다. sign을 재사용하지 마세요.
thirdUserId만 전송할 수 있나요?
네, 메인 계정이 비어 있는 연락처 이메일을 허용하는 경우 가능합니다. 그렇지 않으면 email이 필요합니다. 서명에서 생략된 필드에는 빈 문자열을 사용하세요.
email과 thirdUserId를 둘 다 전송했는데 왜 email로 로그인되나요?
둘 다 존재할 때 검증은 thirdUserId를 무시하고 email로 연락처를 매칭합니다. thirdUserId는 여전히 서명에 포함됩니다.
하위 계정이 아닌 연락처는 왜 returnUrl을 건너뛰나요?
returnUrl은 연락처가 하위 계정일 때만 적용됩니다. 그렇지 않으면 SurveyMars가 이를 무시하고 연락처 홈 페이지를 엽니다.
서명 검증이 왜 실패하나요?
Secret Key를 확인하세요. appId, email, thirdUserId, ts, 그리고 Secret Key를 그 순서대로 연결해야 합니다. 생략된 email 또는 thirdUserId에는 빈 문자열을 사용하세요. ts가 아직 60초 이내인지, URL 인코딩으로 원래 값이 바뀌지 않았는지 확인하세요. language나 returnUrl은 포함하지 마세요.
ts가 왜 그렇게 빨리 만료되나요?
운영 환경에서는 ts가 서버 시간 기준 60초 이내여야 합니다. 사용자가 링크를 열기 직전에 ts와 sign을 생성하세요.
