신뢰 당사자 측에서 FedCM을 사용하여 ID 솔루션 구현

신뢰 당사자 (RP)는 사이트에서 FedCM을 사용 설정하려면 다음 단계를 완료해야 합니다.

• RP 사이트에서 FedCM 엔드포인트가 허용되는지 확인합니다.
• FedCM JavaScript API를 사용하여 사용자 인증을 시작합니다.
• ID 공급업체에 메타데이터 (예: 개인정보처리방침 및 서비스 약관 URL)를 제공합니다.
• [선택사항] UX 모드를 선택하거나, 로그인 또는 도메인 힌트를 제공하거나, 맞춤 매개변수를 전달하거나, 특정 사용자 정보를 요청하거나, 맞춤 오류 메시지를 제공하거나, 사용자를 다시 인증하는 방법을 선택하여 사용자 환경을 맞춤설정합니다.

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

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

  if ('IdentityCredential' in window) {
    // If the feature is available, take action
  } else {
    // FedCM is not supported, use a different identity solution
  }

사용자가 FedCM을 사용하여 RP의 IdP에 로그인할 수 있도록 하려면 RP에서 navigator.credentials.get()를 호출하면 됩니다. 예를 들면 다음과 같습니다.

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

컨텍스트 속성

선택적 context 속성을 사용하면 RP가 사전 정의된 인증 컨텍스트를 수용하도록 FedCM 대화상자 UI의 문자열 (예: 'rp.example에 로그인…', 'idp.example 사용…')을 수정할 수 있습니다. context 속성은 다음 값을 가질 수 있습니다.

• signin(기본)
• signup
• use

예를 들어 context를 use로 설정하면 다음 메시지가 표시됩니다.

브라우저는 계정 목록 엔드포인트의 응답에 approved_clients가 있는지 여부에 따라 가입 및 로그인 사용 사례를 다르게 처리합니다. 사용자가 이미 RP에 가입한 경우 브라우저에 '계속하려면...'이라는 공개 문구가 표시되지 않습니다.
providers 속성은 다음 속성을 갖는 IdentityProvider 객체 배열을 취합니다.

제공업체 속성

providers 속성은 다음 속성을 갖는 IdentityProvider 객체 배열을 취합니다.

활성 모드

FedCM은 다양한 UX 모드 구성을 지원합니다. 수동 모드는 기본 모드이며 개발자가 구성할 필요가 없습니다.

활성 모드에서 FedCM을 사용하려면 다음 단계를 따르세요.

1. 사용자의 브라우저에서 기능 사용 가능 여부를 확인합니다.
2. 버튼 클릭과 같은 일시적인 사용자 동작으로 API를 호출합니다.
3. mode 매개변수를 API 호출에 전달합니다.

  let supportsFedCmMode = false;
  try {
    navigator.credentials.get({
      identity: Object.defineProperty(
        // Check if this Chrome version supports the Mode API.
        {}, 'mode', {
          get: function () { supportsFedCmMode = true; }
        }
      )
    });
  } catch(e) {}

  if (supportsFedCmMode) {
    // The button mode is supported. Call the API with mode property:
    return await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/config.json',
          clientId: '123',
        }],
        // The 'mode' value defines the UX mode of FedCM.
        // - 'active': Must be initiated by user interaction (e.g., clicking a button).
        // - 'passive': Can be initiated without direct user interaction.
        mode: 'active'
      }
    });
  }

활성 모드의 맞춤 아이콘

활성 모드를 사용하면 IdP가 클라이언트 메타데이터 엔드포인트 응답에 RP의 공식 로고 아이콘을 직접 포함할 수 있습니다. RP는 브랜딩 데이터를 사전에 제공해야 합니다.

교차 출처 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")

권한 정책으로 브라우저 기능 제어에서 권한 정책의 작동 방식을 자세히 알아보세요.

Login Hint API

RP는 로그인 힌트를 사용하여 사용자가 로그인해야 하는 계정을 추천할 수 있습니다. 이는 이전에 사용한 계정이 무엇인지 모르는 사용자를 재인증하는 데 유용할 수 있습니다.

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

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: '123',
        // Accounts endpoint can specify a 'login_hints' array for an account.
        // When RP specifies a 'exampleHint' value, only those accounts will be
        // shown to the user whose 'login_hints' array contains the 'exampleHint'
        // value
        loginHint : 'exampleHint'
      }]
    }
  });

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

Domain Hint API

RP는 특정 도메인과 연결된 계정만 선택적으로 표시할 수 있습니다. 이는 기업 도메인으로 제한된 RP에 유용할 수 있습니다.

특정 도메인 계정만 표시하려면 RP는 다음 코드 샘플과 같이 계정 목록 엔드포인트에서 가져온 domain_hints 값 중 하나를 사용하여 domainHint 속성으로 navigator.credentials.get()를 호출해야 합니다.

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: 'abc',
        // Accounts endpoint can specify a 'domain_hints' array for an account.
        // When RP specifies a '@domain.example' value, only those accounts will be
        // shown to the user whose 'domain_hints' array contains the
        // '@domain.example' value
        domainHint : '@domain.example'
      }]
    }
  });

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

맞춤 매개변수

맞춤 매개변수 기능을 사용하면 RP가 ID 어설션 엔드포인트에 키-값 매개변수를 추가로 제공할 수 있습니다. RP는 Parameters API를 사용하여 IdP에 추가 매개변수를 전달하여 기본 로그인 외의 리소스에 대한 권한을 요청할 수 있습니다. 다음과 같은 시나리오에서는 추가 매개변수를 전달하는 것이 유용할 수 있습니다.

• RP는 결제 주소 또는 캘린더 액세스와 같이 IdP에 있는 추가 권한을 동적으로 요청해야 합니다. 사용자는 계속 기능을 사용하여 실행되는 IdP 제어 UX 흐름을 통해 이러한 권한을 승인할 수 있으며, 그러면 IdP에서 이 정보를 공유합니다.

API를 사용하기 위해 RP는 navigator.credentials.get() 호출에서 객체로 params 속성에 매개변수를 추가합니다.

  let {token} = await navigator.credentials.get({
    identity: {
      providers: [{
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',
        // Key/value pairs that need to be passed from the
        // RP to the IdP but that don't really play any role with
        // the browser.
        params: {
          IDP_SPECIFIC_PARAM: '1',
          foo: 'BAR'
        }
      },
    }
  });

브라우저는 이를 자동으로 IdP에 대한 POST 요청으로 변환하며, 이때 매개변수는 단일 URL 인코딩 JSON 직렬화 객체로 표시됩니다.

  // The assertion endpoint is drawn from the config file
  POST /fedcm_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
  account_id=123&client_id=client1234&params=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.

RP에 추가 권한이 필요한 경우 IdP에서 리디렉션 링크를 제공할 수 있습니다. 예를 들어 node.js에서:

  if (rpRequestsPermissions) {
    // Response with a URL if the RP requests additional permissions
    return res.json({
      continue_on: '/example-redirect',
    });
  }

필드

RP는 IdP가 공유해야 하는 사용자 정보 (이름, 이메일 주소, 프로필 사진의 조합)를 지정할 수 있습니다. 요청된 정보는 FedCM 대화상자의 공개 UI에 포함됩니다. 사용자가 로그인을 선택하면 idp.example에서 요청된 정보를 rp.example와 공유한다는 알림 메시지가 표시됩니다.

필드 기능을 사용하려면 RP가 navigator.credentials.get() 호출에 fields 배열을 추가해야 합니다. 이 필드에는 name, email, picture의 모든 순열이 포함될 수 있습니다. 향후 더 많은 값을 포함하도록 확장될 수 있습니다. fields가 포함된 요청은 다음과 같습니다.

  let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        // RP requests the IdP to share only user email and profile picture
        fields: [ 'email', 'picture'],
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',

      },
    }
  });

브라우저는 이를 자동으로 ID 어설션 엔드포인트에 대한 HTTP 요청으로 변환하며, 여기에는 RP가 지정한 fields 매개변수와 브라우저가 disclosure_shown_for 매개변수로 사용자에게 공개한 필드가 포함됩니다. 이전 버전과의 호환성을 위해 브라우저는 공개 텍스트가 표시되고 요청된 필드에 세 필드 모두('name', 'email', 'picture')가 포함된 경우에도 disclosure_text_shown=true를 전송합니다.

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

  // The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
  account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture

fields가 빈 배열인 경우 사용자 에이전트는 공개 UI를 건너뜁니다.

이는 계정 엔드포인트의 응답에 approved_clients의 RP와 일치하는 클라이언트 ID가 포함되지 않은 경우에도 마찬가지입니다.

이 경우 ID 어설션 엔드포인트로 전송된 disclosure_text_shown가 HTTP 본문에서 false입니다.

  POST /id_assertion_endpoint HTTP/1.1
  Host: 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=234234&disclosure_text_shown=false

오류 메시지 표시

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

  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 자동 재인증(줄여서 '자동 재인증')을 사용하면 사용자가 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는 인증 관리 API의 속성이며 PasswordCredential 및 FederatedCredential과 동일한 방식으로 작동하며 PublicKeyCredential에서도 부분적으로 지원됩니다. 이 속성은 다음 네 가지 값을 허용합니다.

• '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가 포함된 흐름인 명시적 사용자 미디에이션으로 로그인하라는 메시지가 표시될 수 있습니다.

preventSilentAccess()로 미디에이션 시행

사용자가 로그아웃한 직후에 자동으로 재인증하면 사용자 경험이 좋지 않습니다. 이러한 동작을 방지하기 위해 FedCM에는 자동 재인증 후 10분의 대기 시간이 있습니다. 즉, 사용자가 10분 이내에 다시 로그인하지 않는 한 자동 재인증은 10분마다 최대 한 번씩 발생합니다. RP는 사용자가 로그아웃 버튼을 클릭하는 등 명시적으로 RP에서 로그아웃할 때 브라우저에 자동 재인증을 사용 중지하도록 명시적으로 요청하기 위해 navigator.credentials.preventSilentAccess()를 호출해야 합니다.

  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는 연결 해제 엔드포인트의 응답에 지정됩니다.

Next steps