Federated Credential Management API 개발자 가이드

개인 정보 보호 ID 제휴를 위해 FedCM을 사용하는 방법을 알아보세요.

FedCM (Federated Credential Management)은 사용자가 ID 서비스 또는 사이트와 개인 정보를 공유하지 않고 사이트에 로그인할 수 있는 제휴 ID 서비스 (예: '...으로 로그인')의 개인 정보 보호 접근 방식입니다.

FedCM 사용 사례, 사용자 플로우, API 로드맵에 관한 자세한 내용은 FedCM API 소개를 확인하세요.

FedCM 개발 환경

FedCM을 사용하려면 Chrome의 IdP 및 RP 모두에 보안 컨텍스트 (HTTPS 또는 localhost)가 필요합니다.

Android에서 Chrome 코드 디버그

FedCM 코드를 디버그하려면 서버를 로컬에서 설정하고 실행하세요. 포트 전달을 지원하는 USB 케이블을 사용하여 연결된 Android 기기의 Chrome에서 이 서버에 액세스할 수 있습니다.

Android 기기 원격 디버그의 안내에 따라 데스크톱에서 DevTools를 사용하여 Android에서 Chrome을 디버그할 수 있습니다.

Chrome에서 서드 파티 쿠키 차단

서드 파티 쿠키를 차단하도록 Chrome을 구성하여 단계적 쿠키 사용을 시뮬레이션합니다.
서드 파티 쿠키를 차단하도록 Chrome을 구성하여 단계적 쿠키 중단 시뮬레이션

실제로 시행되기 전에 Chrome에서 서드 파티 쿠키 없이 FedCM이 작동하는 방식을 테스트할 수 있습니다.

서드 파티 쿠키를 차단하려면 시크릿 모드를 사용하거나, 데스크톱 설정(chrome://settings/cookies) 또는 모바일에서 설정 > 사이트 설정> 쿠키로 이동하여 '서드 파티 쿠키 차단'을 선택합니다.

FedCM API 사용

계정 목록, 어설션 발급 및 선택적으로 클라이언트 메타데이터에 대한 잘 알려진 파일, 구성 파일 및 엔드포인트를 생성하여 FedCM과 통합합니다.

여기에서 FedCM은 RP가 IdP로 로그인하는 데 사용할 수 있는 JavaScript API를 노출합니다.

잘 알려진 파일 만들기

추적기가 API를 악용하지 못하도록 하려면 IdP의 eTLD+1의 /.well-known/web-identity에서 잘 알려진 파일을 제공해야 합니다.

예를 들어 IdP 엔드포인트가 https://accounts.idp.example/ 아래에서 제공되는 경우 https://idp.example/.well-known/web-identity에서 잘 알려진 파일과 IdP 구성 파일을 제공해야 합니다. 다음은 잘 알려진 파일 콘텐츠의 예입니다.

{
  "provider_urls": ["https://accounts.idp.example/config.json"]
}

JSON 파일에는 RP가 navigator.credentials.get에 있는 configURL의 경로 부분으로 지정할 수 있는 IdP 구성 파일 URL의 배열과 함께 provider_urls 속성이 포함되어야 합니다. 배열의 URL 문자열 수는 1개로 제한되지만 이는 향후 의견에 따라 변경될 수 있습니다.

IdP 구성 파일 및 엔드포인트 만들기

IdP 구성 파일은 브라우저에 필요한 엔드포인트 목록을 제공합니다. IdP는 이 구성 파일과 필수 엔드포인트 및 URL을 호스팅합니다. 모든 JSON 응답은 application/json 콘텐츠 유형으로 제공되어야 합니다.

구성 파일의 URL은 RP에서 실행된 navigator.credentials.get 호출에 제공된 값에 따라 결정됩니다.

const credential = await navigator.credentials.get({
  identity: {
    context: 'signup',
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

IdP 구성 파일 위치의 전체 URL을 configURL로 지정합니다. RP에서 navigator.credentials.get()가 호출되면 브라우저는 Origin 헤더 또는 Referer 헤더 없이 GET 요청으로 구성 파일을 가져옵니다. 요청에 쿠키가 없으며 리디렉션을 따르지 않습니다. 이렇게 하면 IdP에서 요청한 사람과 연결을 시도하는 RP를 학습하는 것을 효과적으로 방지할 수 있습니다. 예를 들면 다음과 같습니다.

GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

브라우저는 IdP로부터 다음 속성이 포함된 JSON 응답을 예상합니다.

속성 설명
accounts_endpoint(필수) 계정 엔드포인트의 URL입니다.
client_metadata_endpoint(선택사항) 클라이언트 메타데이터 엔드포인트의 URL입니다.
id_assertion_endpoint(필수) ID 어설션 엔드포인트의 URL입니다.
disconnect(선택사항) 연결 해제 엔드포인트의 URL입니다.
login_url(필수) 사용자가 IdP에 로그인할 수 있는 로그인 페이지 URL입니다.
branding(선택사항) 다양한 브랜드 옵션이 포함된 객체입니다.
branding.background_color(선택사항) '다음으로 계속...' 버튼의 배경색을 설정하는 브랜드 옵션입니다. 관련 CSS 문법, 즉 hex-color, hsl(), rgb(), named-color을 사용합니다.
branding.color(선택사항) '다음으로 계속...' 버튼의 텍스트 색상을 설정하는 브랜드 옵션입니다. 관련 CSS 문법, 즉 hex-color, hsl(), rgb(), named-color을 사용합니다.
branding.icons(선택사항) 로그인 대화상자에 표시되는 아이콘 객체를 설정하는 브랜딩 옵션입니다. 아이콘 객체는 다음 두 매개변수가 있는 배열입니다.
  • url (필수): 아이콘 이미지의 URL입니다. SVG 이미지는 지원되지 않습니다.
  • size (선택사항): 애플리케이션에서 정사각형 및 단일 해상도로 가정한 아이콘 크기입니다. 이 숫자는 25 이상이어야 합니다.

RP는 사전 정의된 인증 컨텍스트를 수용하도록 navigator.credentials.get()의 identity.context 값을 통해 FedCM 대화상자 UI의 문자열을 수정할 수 있습니다. 선택적 속성은 "signin" (기본값), "signup", "use", "continue" 중 하나일 수 있습니다.

브랜딩이 FedCM 대화상자에 적용되는 방식
브랜딩이 FedCM 대화상자에 적용되는 방식

다음은 IdP의 응답 본문 예시입니다.

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

브라우저가 구성 파일을 가져오면 후속 요청을 IdP 엔드포인트로 전송합니다.

IdP 엔드포인트
IdP 엔드포인트

계정 엔드포인트

IdP의 계정 엔드포인트는 사용자가 현재 IdP에 로그인한 계정 목록을 반환합니다. IdP가 여러 계정을 지원하는 경우 이 엔드포인트는 로그인한 모든 계정을 반환합니다.

브라우저가 SameSite=None와 함께 쿠키와 함께 GET 요청을 전송하지만 client_id 매개변수, Origin 헤더 또는 Referer 헤더는 포함하지 않습니다. 이렇게 하면 사용자가 로그인하려는 RP를 IdP에서 학습하는 것을 효과적으로 방지할 수 있습니다. 예를 들면 다음과 같습니다.

GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

요청을 받은 서버는 다음과 같아야 합니다.

  1. 요청에 Sec-Fetch-Dest: webidentity HTTP 헤더가 포함되어 있는지 확인합니다.
  2. 세션 쿠키를 이미 로그인한 계정의 ID와 일치시킵니다.
  3. 계정 목록을 포함하여 응답합니다.

브라우저에는 다음 속성이 있는 계정 정보 배열과 함께 accounts 속성이 포함된 JSON 응답이 필요합니다.

속성 설명
id(필수) 사용자의 고유 ID입니다.
name(필수) 사용자의 성과 이름입니다.
email(필수) 사용자의 이메일 주소입니다.
given_name(선택사항) 사용자의 이름입니다.
picture(선택사항) 사용자 아바타 이미지의 URL입니다.
approved_clients(선택사항) 사용자가 등록한 RP 클라이언트 ID의 배열입니다.
login_hints(선택사항) 계정을 지정하기 위해 IdP에서 지원하는 모든 가능한 필터 유형의 배열입니다. RP는 loginHint 속성으로 navigator.credentials.get()를 호출하여 지정된 계정을 선택적으로 표시할 수 있습니다.
domain_hints(선택사항) 계정이 연결된 모든 도메인의 배열입니다. RP는 domainHint 속성과 함께 navigator.credentials.get()를 호출하여 계정을 필터링할 수 있습니다.

응답 본문 예시:

{
  "accounts": [{
    "id": "1234",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "id": "5678",
    "given_name": "Johnny",
    "name": "Johnny",
    "email": "johnny@idp.example",
    "picture": "https://idp.example/profile/456",
    "approved_clients": ["abc", "def", "ghi"],
    "login_hints": ["demo2", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

사용자가 로그인하지 않은 경우 HTTP 401 (승인되지 않음)으로 응답합니다.

반환된 계정 목록은 브라우저에서 사용하며 RP에서 사용할 수 없습니다.

클라이언트 메타데이터 엔드포인트

IdP의 클라이언트 메타데이터 엔드포인트는 RP의 개인정보처리방침 및 서비스 약관과 같은 신뢰 당사자의 메타데이터를 반환합니다. RP는 사전에 개인정보처리방침 및 서비스 약관 링크를 IdP에 제공해야 합니다. 이러한 링크는 사용자가 아직 RP에 IdP로 등록하지 않은 경우 로그인 대화상자에 표시됩니다.

브라우저가 쿠키 없이 client_id navigator.credentials.get를 사용하여 GET 요청을 보냅니다. 예를 들면 다음과 같습니다.

GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity

요청을 받은 서버는 다음과 같아야 합니다.

  1. client_id의 RP를 결정합니다.
  2. 클라이언트 메타데이터로 응답합니다.

클라이언트 메타데이터 엔드포인트의 속성은 다음과 같습니다.

속성 설명
privacy_policy_url(선택사항) RP 개인정보처리방침 URL입니다.
terms_of_service_url(선택사항) RP 서비스 약관 URL입니다.

브라우저는 엔드포인트에서 JSON 응답을 예상합니다.

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

반환된 클라이언트 메타데이터는 브라우저에서 사용되며 RP에서 사용할 수 없습니다.

ID 어설션 엔드포인트

IdP의 ID 어설션 엔드포인트는 로그인한 사용자의 어설션을 반환합니다. 사용자가 navigator.credentials.get() 호출을 사용하여 RP 웹사이트에 로그인하면 브라우저에서 SameSite=None 쿠키와 application/x-www-form-urlencoded 콘텐츠 유형이 포함된 POST 요청을 다음 정보와 함께 이 엔드포인트에 전송합니다.

속성 설명
client_id(필수) RP의 클라이언트 식별자입니다.
account_id(필수) 로그인한 사용자의 고유 ID입니다.
nonce(선택사항) RP에서 제공하는 요청 nonce입니다.
disclosure_text_shown 그 결과 불리언이 아닌 "true" 또는 "false" 문자열이 생성됩니다. 공개 문구가 표시되지 않은 경우 결과는 "false"입니다. 이는 RP의 클라이언트 ID가 계정 엔드포인트의 응답의 approved_clients 속성 목록에 포함되었거나 브라우저에서 이전에 approved_clients가 없는 상태에서 가입 절차를 관찰한 경우에 발생합니다.
is_auto_selected RP에서 자동 재인증이 수행되는 경우 is_auto_selected는 "true"을 나타냅니다. 그렇지 않으면 "false"입니다. 이는 더 많은 보안 관련 기능을 지원하는 데 도움이 됩니다. 예를 들어 일부 사용자는 인증에 명시적인 사용자 중재가 필요한 더 높은 보안 계층을 선호할 수 있습니다. IdP가 이러한 중재 없이 토큰 요청을 받으면 요청을 다르게 처리할 수 있습니다. 예를 들어 RP가 mediation: required로 FedCM API를 다시 호출할 수 있도록 오류 코드를 반환합니다.

HTTP 헤더 예:

POST /assertion.php HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

요청을 받은 서버는 다음과 같아야 합니다.

  1. 교차 출처 리소스 공유 (CORS)로 요청에 응답합니다.
  2. 요청에 Sec-Fetch-Dest: webidentity HTTP 헤더가 포함되어 있는지 확인합니다.
  3. Origin 헤더를 client_id에 의해 결정되는 RP 출처와 일치시킵니다. 일치하지 않으면 거부합니다.
  4. account_id를 이미 로그인한 계정의 ID와 일치시킵니다. 일치하지 않으면 거부합니다.
  5. 토큰으로 응답합니다. 요청이 거부되면 오류 응답으로 응답합니다.

토큰 발급 방법은 IdP에 따라 다르지만, 일반적으로는 RP가 토큰이 진짜인지 확인할 수 있도록 계정 ID, 클라이언트 ID, 발급기관 출처, nonce 등의 정보를 사용하여 서명됩니다.

브라우저는 다음 속성이 포함된 JSON 응답을 예상합니다.

속성 설명
token(필수) 토큰은 인증에 대한 클레임이 포함된 문자열입니다. 
{
  "token": "***********"
}

반환된 토큰은 RP가 인증을 검증할 수 있도록 브라우저에 의해 RP에 전달됩니다.

오류 응답 반환

id_assertion_endpoint는 2개의 선택적 필드가 있는 'error' 응답도 반환할 수 있습니다.

  • code: IdP는 OAuth 2.0 지정 오류 목록(invalid_request, unauthorized_client, access_denied, server_error, temporarily_unavailable)에서 알려진 오류 중 하나를 선택하거나 임의의 문자열을 사용할 수 있습니다. 후자의 경우 Chrome은 일반 오류 메시지와 함께 오류 UI를 렌더링하고 코드를 RP에 전달합니다.
  • url: 오류에 관한 정보를 포함하여 사람이 읽을 수 있는 웹페이지를 식별하여 오류에 관한 추가 정보를 사용자에게 제공합니다. 브라우저가 네이티브 UI에 풍부한 오류 메시지를 제공할 수 없으므로 이 필드는 사용자에게 유용합니다. 예를 들어 다음 단계에 대한 링크, 고객 서비스 연락처 정보 등이 있습니다. 사용자가 오류 세부정보와 해결 방법을 자세히 알아보려는 경우 브라우저 UI에서 제공된 페이지를 방문하여 자세한 내용을 확인할 수 있습니다. URL은 IdP configURL와 동일한 사이트여야 합니다.
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

엔드포인트 연결 해제

IdentityCredential.disconnect()를 호출하면 브라우저에서 SameSite=None 쿠키 및 application/x-www-form-urlencoded 콘텐츠 유형이 포함된 교차 출처 POST 요청을 다음 정보와 함께 이 연결 해제 엔드포인트에 전송합니다.

속성 설명
account_hint IdP 계정에 대한 힌트
client_id RP의 클라이언트 식별자입니다. 
POST /disconnect.php HTTP/1.1
Host: idp.example
Origin: rp.example
Content-Type: application/x-www-form-urlencoded
Cookie: 0x123
Sec-Fetch-Dest: webidentity

account_hint=account456&client_id=rp123

요청을 받은 서버는 다음과 같아야 합니다.

  1. 교차 출처 리소스 공유 (CORS)로 요청에 응답합니다.
  2. 요청에 Sec-Fetch-Dest: webidentity HTTP 헤더가 포함되어 있는지 확인합니다.
  3. Origin 헤더를 client_id에 의해 결정되는 RP 출처와 일치시킵니다. 일치하지 않으면 거부합니다.
  4. account_hint를 이미 로그인한 계정의 ID와 일치시킵니다.
  5. RP에서 사용자 계정을 연결 해제합니다.
  6. 식별된 사용자 계정 정보를 JSON 형식으로 브라우저에 응답합니다.

응답 JSON 페이로드의 예시는 다음과 같습니다.

{
  "account_id": "account456"
}

대신 IdP가 브라우저에서 RP와 연결된 모든 계정의 연결을 해제하도록 하려면 계정 ID와 일치하지 않는 문자열(예: "*")을 전달합니다.

로그인 URL

Login Status API를 사용하면 IdP는 사용자의 로그인 상태를 브라우저에 알려야 합니다. 하지만 세션이 만료될 때와 같이 상태가 동기화되지 않았을 수 있습니다. 이러한 시나리오에서는 브라우저가 idp 구성 파일의 login_url로 지정된 로그인 페이지 URL을 통해 사용자가 IdP에 로그인하도록 동적으로 허용할 수 있습니다.

FedCM 대화상자에 다음 이미지와 같이 로그인을 권장하는 메시지가 표시됩니다.

A
IdP 로그인을 제안하는 FedCM 대화상자

사용자가 계속 버튼을 클릭하면 브라우저에서 IdP 로그인 페이지의 팝업 창이 열립니다.

소유 및
IdP 로그인 버튼을 클릭하면 표시되는 예시 대화상자

이 대화상자는 퍼스트 파티 쿠키가 포함된 일반 브라우저 창입니다. 대화상자 내에서 발생하는 모든 상황은 IdP에 따라 결정되며, RP 페이지에 교차 출처 통신 요청을 하는 데 창 핸들을 사용할 수 없습니다. 사용자가 로그인한 후 IdP는 다음을 수행해야 합니다.

  • Set-Login: logged-in 헤더를 전송하거나 navigator.login.setStatus("logged-in") API를 호출하여 브라우저에 사용자가 로그인되었음을 알립니다.
  • IdentityProvider.close()를 호출하여 대화상자를 닫습니다.
A
사용자가 FedCM을 사용하여 IdP에 로그인한 후 RP에 로그인합니다.

ID 공급업체에서의 사용자 로그인 상태를 브라우저에 알립니다.

Login Status API는 웹사이트(특히 IdP)가 IdP에 있는 사용자의 로그인 상태를 브라우저에 알려주는 메커니즘입니다. 이 API를 사용하면 브라우저에서 IdP에 대한 불필요한 요청을 줄이고 잠재적인 타이밍 공격을 완화할 수 있습니다.

IdP는 사용자가 IdP에 로그인했거나 사용자가 모든 IdP 계정에서 로그아웃될 때 HTTP 헤더를 전송하거나 JavaScript API를 호출하여 사용자의 로그인 상태를 브라우저에 알릴 수 있습니다. 구성 URL로 식별되는 각 IdP의 경우 브라우저는 로그인 상태를 나타내는 3가지 상태 변수를 logged-in, logged-out, unknown 값으로 유지합니다. 기본 상태는 unknown입니다.

사용자가 로그인되었음을 알리려면 최상위 탐색에서 Set-Login: logged-in HTTP 헤더를 전송하거나 IdP 출처에서 동일 사이트 하위 리소스 요청을 전송합니다.

Set-Login: logged-in

또는 최상위 탐색 메뉴의 IdP 출처에서 JavaScript API navigator.login.setStatus("logged-in")를 호출합니다.

navigator.login.setStatus("logged-in")

이러한 호출은 사용자의 로그인 상태를 logged-in로 기록합니다. 사용자의 로그인 상태가 logged-in로 설정되면 FedCM을 호출하는 RP가 IdP의 계정 엔드포인트에 요청을 실행하고 FedCM 대화상자에서 사용자에게 사용 가능한 계정을 표시합니다.

사용자가 모든 계정에서 로그아웃되었음을 알리려면 최상위 탐색에서 Set-Login: logged-out HTTP 헤더를 전송하거나 IdP 출처에서 동일한 사이트 하위 리소스 요청을 전송합니다.

Set-Login: logged-out

또는 최상위 탐색 메뉴의 IdP 출처에서 JavaScript API navigator.login.setStatus("logged-out")를 호출합니다.

navigator.login.setStatus("logged-out")

이러한 호출은 사용자의 로그인 상태를 logged-out로 기록합니다. 사용자의 로그인 상태가 logged-out이면 FedCM 호출은 IdP의 계정 엔드포인트에 요청하지 않고 자동으로 실패합니다.

unknown 상태는 IdP가 Login Status API를 사용하여 신호를 보내기 전에 설정됩니다. Unknown는 보다 원활한 전환을 위해 도입되었습니다. 이 API가 제공될 때 사용자가 이미 IdP에 로그인했을 수 있기 때문입니다. FedCM이 처음 호출될 때 IdP는 브라우저에 이를 알릴 기회가 없을 수도 있습니다. 이 경우 Chrome은 IdP의 계정 엔드포인트에 요청을 전송하고 계정 엔드포인트의 응답에 따라 상태를 업데이트합니다.

  • 엔드포인트가 활성 계정 목록을 반환하면 상태를 logged-in로 업데이트하고 FedCM 대화상자를 열어 해당 계정을 표시합니다.
  • 엔드포인트에서 계정을 반환하지 않으면 상태를 logged-out로 업데이트하고 FedCM 호출을 실패합니다.

사용자가 동적 로그인 흐름을 통해 로그인하도록 허용

IdP에서 사용자의 로그인 상태를 브라우저에 계속 알리지만 세션이 만료될 때와 같이 동기화되지 않은 상태일 수 있습니다. 로그인 상태가 logged-in일 때 브라우저는 사용자 인증 정보가 있는 요청을 계정 엔드포인트로 보내려고 시도하지만 세션을 더 이상 사용할 수 없으므로 서버는 계정을 반환하지 않습니다. 이러한 시나리오에서는 브라우저가 사용자가 팝업 창을 통해 IdP에 로그인하도록 동적으로 허용할 수 있습니다.

ID 공급업체로 신뢰 당사자에 로그인

IdP의 구성과 엔드포인트를 사용할 수 있게 되면 RP는 navigator.credentials.get()를 호출하여 사용자가 IdP로 RP에 로그인할 수 있도록 요청할 수 있습니다.

API를 호출하기 전에 [사용자 브라우저에서 FedCM을 사용할 수 있는지] 확인해야 합니다. FedCM을 사용할 수 있는지 확인하려면 FedCM 구현 주위에 다음 코드를 래핑합니다.

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

사용자가 RP에서 IdP에 로그인할 수 있도록 요청하려면 다음을 따르세요.

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

providers 속성은 다음과 같은 속성을 갖는 IdentityProvider 객체의 배열을 사용합니다.

속성 설명
configURL(필수) IdP 구성 파일의 전체 경로입니다.
clientId(필수) IdP에서 발급한 RP의 클라이언트 식별자입니다.
nonce(선택사항) 이 특정 요청에 대해 응답이 발행되도록 하는 임의의 문자열입니다. 재전송 공격을 방지합니다.
loginHint(선택사항) 계정 엔드포인트에서 제공하는 login_hints 값 중 하나를 지정하면 FedCM 대화상자에 지정된 계정이 선택적으로 표시됩니다.
domainHint(선택사항) 계정 엔드포인트에서 제공하는 domain_hints 값 중 하나를 지정하면 FedCM 대화상자에 지정된 계정이 선택적으로 표시됩니다.

브라우저는 계정 목록 엔드포인트의 응답에 approved_clients가 있는지에 따라 가입 및 로그인 사용 사례를 다르게 처리합니다. 사용자가 이미 RP에 가입한 경우 브라우저에 '계속 진행 중...'이라는 공개 텍스트가 표시되지 않습니다.

가입 상태는 다음 조건이 충족되었는지 여부에 따라 결정됩니다.

  • approved_clients에 RP의 clientId가 포함된 경우
  • 사용자가 이미 RP에 가입했다는 것을 브라우저가 기억하는 경우
사용자가 FedCM을 사용하여 RP에 로그인

RP가 navigator.credentials.get()를 호출하면 다음 활동이 실행됩니다.

  1. 브라우저가 요청을 보내고 여러 문서를 가져옵니다.
    1. 엔드포인트를 선언하는 잘 알려진 파일 및 IdP 구성 파일.
    2. 계정 목록.
    3. 선택사항: 클라이언트 메타데이터 엔드포인트에서 가져온 RP의 개인정보처리방침 및 서비스 약관의 URL.
  2. 사용자가 로그인하는 데 사용할 수 있는 계정 목록과 서비스 약관 및 개인정보처리방침(있는 경우)이 브라우저에 표시됩니다.
  3. 사용자가 로그인할 계정을 선택하면 토큰을 검색하기 위해 ID 어설션 엔드포인트에 대한 요청이 IdP로 전송됩니다.
  4. RP는 토큰의 유효성을 검사하여 사용자를 인증할 수 있습니다.
로그인 API 호출
로그인 API 호출

RP는 FedCM을 지원하지 않는 브라우저를 지원할 것으로 예상되므로 사용자는 FedCM 이외의 기존 로그인 프로세스를 사용할 수 있어야 합니다. 서드 파티 쿠키가 완전히 지원 중단될 때까지는 문제가 되지 않습니다.

RP 서버가 토큰을 검증하면 RP는 사용자를 등록하거나 사용자가 로그인하여 새 세션을 시작하도록 할 수 있습니다.

로그인 힌트 API

사용자가 로그인한 후 신뢰 당사자 (RP)가 사용자에게 재인증을 요청하는 경우가 있습니다. 하지만 사용자는 자신이 어떤 계정을 사용하고 있는지 잘 모를 수 있습니다. RP가 로그인할 계정을 지정할 수 있으면 사용자가 더 쉽게 계정을 선택할 수 있습니다.

RP는 다음 코드 샘플과 같이 계정 목록 엔드포인트에서 가져온 login_hints 값 중 하나로 loginHint 속성으로 navigator.credentials.get()를 호출하여 특정 계정을 선택적으로 표시할 수 있습니다.

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

loginHint와 일치하는 계정이 없으면 FedCM 대화상자에 로그인 프롬프트가 표시됩니다. 이 프롬프트를 통해 사용자는 RP에서 요청한 힌트와 일치하는 IdP 계정에 로그인할 수 있습니다. 사용자가 프롬프트를 탭하면 구성 파일에 지정된 로그인 URL이 포함된 팝업 창이 열립니다. 그러면 링크에 로그인 힌트 및 도메인 힌트 쿼리 매개변수가 추가됩니다.

도메인 힌트 API

RP가 특정 도메인에 연결된 계정만 사이트에 로그인할 수 있다는 것을 이미 알고 있는 경우가 있습니다. 이는 액세스하는 사이트가 회사 도메인으로 제한된 기업 시나리오에서 특히 일반적입니다. 더 나은 사용자 환경을 제공하기 위해 FedCM API는 RP가 RP에 로그인하는 데 사용할 수 있는 계정만 표시하도록 허용합니다. 이렇게 하면 사용자가 회사 도메인 외부의 계정을 사용하여 RP에 로그인하려고 할 때 올바른 유형의 계정이 사용되지 않아 나중에 오류 메시지가 표시되거나 로그인이 작동하지 않는 시나리오가 방지됩니다.

RP는 다음 코드 샘플과 같이 계정 목록 엔드포인트에서 가져온 domain_hints 값 중 하나와 함께 domainHint 속성으로 navigator.credentials.get()를 호출하여 일치하는 계정만 선택적으로 표시할 수 있습니다.

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

domainHint와 일치하는 계정이 없으면 FedCM 대화상자에 로그인 프롬프트가 표시됩니다. 이 프롬프트를 통해 사용자는 RP에서 요청한 힌트와 일치하는 IdP 계정에 로그인할 수 있습니다. 사용자가 프롬프트를 탭하면 구성 파일에 지정된 로그인 URL이 포함된 팝업 창이 열립니다. 그러면 링크에 로그인 힌트 및 도메인 힌트 쿼리 매개변수가 추가됩니다.

domainHint와 일치하는 계정이 없을 때 표시되는 로그인 프롬프트의 예
domainHint와 일치하는 계정이 없을 때 표시되는 로그인 메시지 예시

오류 메시지 표시

간혹 클라이언트가 승인되지 않았거나 서버를 일시적으로 사용할 수 없는 경우와 같이 합법적인 이유로 IdP가 토큰을 발급하지 못할 수 있습니다. IdP가 '오류' 응답을 반환하면 RP는 이를 포착할 수 있으며 Chrome은 IdP에서 제공한 오류 정보가 포함된 브라우저 UI를 사용자에게 표시하여 사용자에게 알립니다.

A
사용자의 로그인 시도가 실패한 후의 오류 메시지가 표시된 FedCM 대화상자 문자열은 오류 유형과 연결됩니다.
try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://idp.example/manifest.json",
          clientId: "1234",
        },
      ],
    }
  });
} catch (e) {
  const code = e.code;
  const url = e.url;
}

초기 동의 후 사용자 자동 재인증

FedCM 자동 재인증(줄여서 'auto-reauthn')을 사용하면 사용자가 FedCM을 사용한 초기 인증 후 돌아올 때 자동으로 재인증할 수 있습니다. 여기서 '초기 인증'은 사용자가 동일한 브라우저 인스턴스에서 처음으로 FedCM 로그인 대화상자의 '다음으로 계속...' 버튼을 탭하여 계정을 만들거나 RP의 웹사이트에 로그인한다는 의미입니다.

명시적인 사용자 환경은 사용자가 추적 (FedCM의 주요 목표 중 하나)을 방지하기 위해 제휴 계정을 만들기 전에 합리적이지만 사용자가 RP와 IdP 간의 통신을 허용하는 권한을 부여한 후에는 사용자가 이전에 확인한 다른 명시적 사용자 확인을 시행해도 개인 정보 보호 또는 보안상의 이점이 없으므로 불필요하게 번거로울 수 있습니다.

자동 재인증을 사용하면 navigator.credentials.get()를 호출할 때 mediation에 지정한 옵션에 따라 브라우저가 동작을 변경합니다.

const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/fedcm.json",
      clientId: "1234",
    }],
  },
  mediation: 'optional', // this is the default
});

// `isAutoSelected` is `true` if auto-reauthn was performed.
const isAutoSelected = cred.isAutoSelected;

mediation는 Credential Management API의 속성이며 PasswordCredential 및 FederatedCredential과 동일한 방식으로 작동하며 PublicKeyCredential에서도 부분적으로 지원됩니다. 이 속성에는 다음 4가지 값을 사용할 수 있습니다.

  • 'optional'(기본값): 가능한 경우 자동 재인증되며, 그렇지 않은 경우 미디에이션이 필요합니다. 로그인 페이지에서 이 옵션을 선택하는 것이 좋습니다.
  • 'required': 작업을 진행하려면 항상 미디에이션이 필요합니다(예: UI에서 '계속' 버튼 클릭). 사용자가 인증이 필요할 때마다 명시적으로 권한을 부여해야 하는 경우 이 옵션을 선택하세요.
  • 'silent': 가능한 경우 자동으로 재인증하며, 그러지 않으면 미디에이션 없이도 자동으로 실패합니다. 전용 로그인 페이지는 아니지만 사용자의 로그인 상태를 유지하려는 페이지(예: 배송 웹사이트의 상품 페이지 또는 뉴스 웹사이트의 기사 페이지)에서 이 옵션을 선택하는 것이 좋습니다.
  • 'conditional': WebAuthn에 사용되며 현재 FedCM에서는 사용할 수 없습니다.

이 호출을 사용하면 다음 조건에서 자동 재인증이 수행됩니다.

  • FedCM을 사용할 수 있습니다. 예를 들어 사용자가 설정에서 전체적으로 또는 RP에 대해 FedCM을 사용 중지하지 않았습니다.
  • 사용자가 FedCM API로 하나의 계정만 사용하여 이 브라우저에서 웹사이트에 로그인했습니다.
  • 사용자가 해당 계정으로 IdP에 로그인했습니다.
  • 최근 10분 내에 자동 재인증이 이루어지지 않았습니다.
  • RP가 이전 로그인 후 navigator.credentials.preventSilentAccess()를 호출하지 않았습니다.

이러한 조건이 충족되면 FedCM navigator.credentials.get()가 호출되는 즉시 사용자 자동 재인증 시도가 시작됩니다.

mediation: optional인 경우 브라우저만 아는 이유로 자동 재인증을 사용할 수 없습니다. RP는 isAutoSelected 속성을 검사하여 자동 재인증이 실행되는지 확인할 수 있습니다.

이는 API 성능을 평가하고 그에 따라 UX를 개선하는 데 도움이 됩니다. 또한 이를 사용할 수 없는 경우 명시적인 사용자 미디에이션(mediation: required를 사용하는 흐름)을 통해 로그인하라는 메시지가 사용자에게 표시될 수 있습니다.

FedCM을 통해 자동으로 재인증하는 사용자입니다.

preventSilentAccess()에서 미디에이션 시행

로그아웃 직후 사용자를 자동으로 다시 인증한다고 해서 사용자 경험이 크게 향상되지는 않습니다. 이러한 이유로 FedCM은 이러한 동작을 방지하기 위해 자동 재인증 후 10분의 대기 기간을 제공합니다. 즉, 사용자가 10분 이내에 다시 로그인하지 않는 한 자동 재인증은 10분마다 최대 한 번 실행됩니다. RP는 navigator.credentials.preventSilentAccess()를 호출하여 사용자가 RP에서 명시적으로 로그아웃(예: 로그아웃 버튼 클릭)할 때 자동 재인증을 사용 중지하도록 브라우저에 명시적으로 요청해야 합니다.

function signout() {
  navigator.credentials.preventSilentAccess();
  location.href = '/signout';
}

사용자는 설정에서 자동 재인증을 선택 해제할 수 있습니다.

사용자는 설정 메뉴에서 자동 재인증을 선택 해제할 수 있습니다.

  • 데스크톱 Chrome에서 chrome://password-manager/settings > 자동 로그인으로 이동합니다.
  • Android Chrome에서 설정 > 비밀번호 관리자를 열고 오른쪽 상단의 톱니바퀴 아이콘을 탭한 다음 자동 로그인을 탭합니다.

전환 버튼을 사용 중지하면 사용자는 자동 재인증 동작을 모두 선택 해제할 수 있습니다. 이 설정은 사용자가 Chrome 인스턴스에서 Google 계정에 로그인되어 있고 동기화가 사용 설정된 경우 기기 간에 저장되고 동기화됩니다.

RP에서 IdP 연결 해제

사용자가 이전에 FedCM을 통해 IdP를 사용하여 RP에 로그인한 경우 관계는 연결된 계정 목록으로 브라우저에 로컬로 저장됩니다. RP는 IdentityCredential.disconnect() 함수를 호출하여 연결 해제를 시작할 수 있습니다. 이 함수는 최상위 RP 프레임에서 호출할 수 있습니다. RP는 configURL, IdP에서 사용하는 clientId, IdP의 연결을 해제할 accountHint을 전달해야 합니다. 연결 해제 엔드포인트가 계정을 식별할 수 있는 한 계정 힌트는 임의의 문자열이 될 수 있습니다(예: 계정 목록 엔드포인트에서 제공한 계정 ID와 일치하지 않는 이메일 주소 또는 사용자 ID).

// Disconnect an IdP account "account456" from the RP "https://idp.com/". This is invoked on the RP domain.
IdentityCredential.disconnect({
  configURL: "https://idp.com/config.json",
  clientId: "rp123",
  accountHint: "account456"
});

IdentityCredential.disconnect()에서 Promise를 반환합니다. 이 프로미스는 다음과 같은 이유로 예외를 발생시킬 수 있습니다.

  • 사용자가 FedCM을 통해 IdP를 사용하여 RP에 로그인하지 않았습니다.
  • API는 FedCM 권한 정책 없이 iframe 내에서 호출됩니다.
  • configURL이 잘못되었거나 연결 해제 엔드포인트가 누락되었습니다.
  • 콘텐츠 보안 정책 (CSP) 검사가 실패합니다.
  • 대기 중인 연결 해제 요청이 있습니다.
  • 사용자가 브라우저 설정에서 FedCM을 사용 중지했습니다.

IdP의 연결 해제 엔드포인트가 응답을 반환하면 브라우저에서 RP와 IdP의 연결이 해제되고 프로미스가 확인됩니다. 연결 해제된 계정의 ID는 연결 해제 엔드포인트의 응답에 지정됩니다.

교차 출처 iframe 내에서 FedCM 호출

FedCM은 상위 프레임이 허용하는 경우 identity-credentials-get 권한 정책을 사용하여 교차 출처 iframe 내에서 호출할 수 있습니다. 그러려면 다음과 같이 allow="identity-credentials-get" 속성을 iframe 태그에 추가합니다.

<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

예시에서 실제 동작을 확인할 수 있습니다.

선택적으로 상위 프레임에서 FedCM을 호출하도록 출처를 제한하려는 경우 허용된 출처 목록과 함께 Permissions-Policy 헤더를 전송합니다.

Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

권한 정책의 작동 방식에 관한 자세한 내용은 권한 정책으로 브라우저 기능 제어를 참고하세요.