SAML로 사용자 로그인

이 도움말에서는 Identity Platform을 사용하여 보안 보장 마크 업 언어(SAML) 2.0 공급업체로 사용자를 로그인 처리하는 방법을 보여줍니다.

시작하기 전에

1. Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

6. Identity Platform을 사용 설정하고 클라이언트 SDK를 앱에 추가합니다. 자세한 내용은 빠른 시작을 참조하세요.

공급업체 구성

1. Google Cloud 콘솔에서 ID 공급업체 페이지로 이동합니다.
   ID 공급업체 페이지로 이동
   

2. 공급업체 추가를 클릭하고 목록에서 SAML을 선택합니다.

3. 다음 세부정보를 입력합니다.

   1. 공급업체의 이름입니다. 공급업체 ID 또는 커스텀 이름과 동일할 수 있습니다. 커스텀 이름을 입력할 경우 공급업체 ID 옆에 있는 수정을 클릭하여 ID(saml.로 시작해야 함)를 지정합니다.

   2. 공급업체의 엔티티 ID입니다.

   3. 공급업체의 SAML SSO URL입니다.

   4. 공급업체에서 토큰 서명에 사용되는 인증서입니다. 시작 및 종료 문자열을 포함해야 합니다. 예를 들면 다음과 같습니다.

      -----BEGIN CERTIFICATE-----
      MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBSMQswCQYDVQQGEwJ1czEL
      ...
      LEzc1JwEGQQVDYQCwsQMSBDAF0QAB0w9GikhqkgBNADABIgABIwAgOdACCjaCIIM
      -----END CERTIFICATE-----
      

4. 서비스 공급업체에 앱의 엔티티 ID를 입력합니다. 일반적으로 앱의 URL입니다. SAML ID 공급업체에서는 이를 대상이라고 합니다.

5. 승인된 도메인 목록에 앱을 추가합니다. 예를 들어 앱의 로그인 URL이 https://example.com/login이면 example.com을 추가합니다.

6. 필요한 경우 앱의 콜백 URL을 맞춤설정합니다. 일반적으로 SAML ID 공급업체에서 어설션 소비자 서비스(ACS) URL이라고 부릅니다.

   기본 콜백 URL을 사용하면 SAML 응답을 확인하는 복잡성이 줄어 듭니다. 이 흐름을 맞춤설정하는 경우 프로젝트의 Identity Platform 콜백 URL이 SAML ID 공급업체에 구성되어 있는지 확인합니다. 보통 https://[PROJECT-ID].firebaseapp.com/__/auth/handler와 같은 형식입니다. 자세한 내용은 인증 핸들러 맞춤설정을 참조하세요.

7. 저장을 클릭합니다.

제공업체 필수 요소

Identity Platform은 제공업체의 응답으로 <saml:Subject> 및 <saml:NameID> 요소를 예상합니다. 제공업체를 구성할 때 이러한 요소의 값을 정의하지 않으면 SAML 어설션이 실패합니다.

서명 요청

인증 요청에 서명하여 보안을 강화할 수 있습니다.

요청에 서명하려면 먼저 inboundSamlConfigs.patch()을 호출하고 idp_config.sign_request를 true로 설정하여 ID 제공업체에 서명된 요청을 사용 설정합니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• project-id: Google Cloud 프로젝트의 ID
• provider-id: SAML 제공업체 ID

HTTP 메서드 및 URL:

PATCH https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest

JSON 요청 본문:

{
  "idp_config": {
    "sign_request": true
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest" | Select-Object -Expand Content

API 탐색기(브라우저)

요청 본문을 복사하고 메서드 참조 페이지를 엽니다. 페이지 오른쪽에 API 탐색기 패널이 열립니다. 이 도구를 사용하여 요청을 보낼 수 있습니다. 요청 본문을 이 도구에 붙여넣고 다른 필수 필드를 입력한 후 실행을 클릭합니다.

 

REST API를 사용하여 서명된 요청을 사용 설정해야 합니다. Google Cloud 콘솔 또는 Google Cloud CLI를 사용할 수 없습니다.

응답은 SpCertificate의 배열을 포함하는 InboundSamlConfig 객체입니다. 요청의 서명을 검증할 수 있도록 SAML ID 공급업체로 X509 인증서 값을 구성합니다.

사용자 로그인

사용자가 로그인하면 클라이언트 SDK는 인증 핸드셰이크를 처리한 다음 페이로드에 SAML 속성이 포함된 ID 토큰을 반환합니다. 사용자를 로그인 처리해서 SAML 공급업체에서 속성을 가져오려면 다음 안내를 따르세요.

1. 이전 섹션에서 구성한 공급업체 ID로 SAMLAuthProvider 인스턴스를 만듭니다. 공급업체 ID는 saml.로 시작해야 합니다.

   웹 버전 9

   트리 쉐이킹 작업이 가능한 모듈식 웹 API에 대해 자세히 알아보고 네임스페이스화된 API에서 업그레이드하세요.

   import { SAMLAuthProvider } from "firebase/auth";
   
   const provider = new SAMLAuthProvider("saml.myProvider");
   auth_saml_provider_create.js

   웹 버전 8

   const provider = new firebase.auth.SAMLAuthProvider('saml.myProvider');
   saml.js

2. 로그인 과정을 시작합니다. 팝업 또는 리디렉션을 사용하도록 선택할 수 있습니다.

   팝업

   웹 버전 9

   트리 쉐이킹 작업이 가능한 모듈식 웹 API에 대해 자세히 알아보고 네임스페이스화된 API에서 업그레이드하세요.

   import { getAuth, signInWithPopup, SAMLAuthProvider } from "firebase/auth";
   
   const auth = getAuth();
   signInWithPopup(auth, provider)
     .then((result) => {
       // User is signed in.
       // Provider data available from the result.user.getIdToken()
       // or from result.user.providerData
     }).catch((error) => {
       // Handle Errors here.
       const errorCode = error.code;
       const errorMessage = error.message;
       // The email of the user's account used.
       const email = error.customData.email;
       // The AuthCredential type that was used.
       const credential = SAMLAuthProvider.credentialFromError(error);
       // Handle / display error.
       // ...
     });
   auth_saml_signin_popup.js

   웹 버전 8

   firebase.auth().signInWithPopup(provider)
     .then((result) => {
       // User is signed in.
       // Identity provider data available in result.additionalUserInfo.profile,
       // or from the user's ID token obtained from result.user.getIdToken()
       // as an object in the firebase.sign_in_attributes custom claim
       // This is also available from result.user.getIdTokenResult()
       // idTokenResult.claims.firebase.sign_in_attributes.
     })
     .catch((error) => {
       // Handle / display error.
       // ...
     });
   saml.js

   리디렉션

   로그인 페이지로 리디렉션하려면 signInWithRedirect()를 호출합니다.

   웹 버전 9

   트리 쉐이킹 작업이 가능한 모듈식 웹 API에 대해 자세히 알아보고 네임스페이스화된 API에서 업그레이드하세요.

   import { getAuth, signInWithRedirect } from "firebase/auth";
   
   const auth = getAuth();
   signInWithRedirect(auth, provider);
   auth_saml_signin_redirect.js

   웹 버전 8

   firebase.auth().signInWithRedirect(provider);
   saml.js

   그런 다음 getRedirectResult()를 호출하여 사용자가 앱으로 돌아올 때 결과를 가져옵니다.

   웹 버전 9

   트리 쉐이킹 작업이 가능한 모듈식 웹 API에 대해 자세히 알아보고 네임스페이스화된 API에서 업그레이드하세요.

   import { getAuth, getRedirectResult, SAMLAuthProvider } from "firebase/auth";
   
   const auth = getAuth();
   getRedirectResult(auth)
     .then((result) => {
       // User is signed in.
       // Provider data available from the result.user.getIdToken()
       // or from result.user.providerData
     })
     .catch((error) => {
       // Handle Errors here.
       const errorCode = error.code;
       const errorMessage = error.message;
       // The email of the user's account used.
       const email = error.customData.email;
       // The AuthCredential type that was used.
       const credential = SAMLAuthProvider.credentialFromError(error);
       // Handle / display error.
       // ...
     });
   auth_saml_signin_redirect_result.js

   웹 버전 8

   firebase.auth().getRedirectResult()
     .then((result) => {
       // User is signed in.
       // Provider data available in result.additionalUserInfo.profile,
       // or from the user's ID token obtained from result.user.getIdToken()
       // as an object in the firebase.sign_in_attributes custom claim
       // This is also available from result.user.getIdTokenResult()
       // idTokenResult.claims.firebase.sign_in_attributes.
     }).catch((error) => {
       // Handle / display error.
       // ...
     });
   saml.js

3. firebase.sign_in_attributes 클레임을 사용하여 ID 토큰에서 SAML 공급자와 연결된 사용자 속성을 검색합니다. ID 토큰을 서버로 전송할 때 Admin SDK를 사용하여 ID 토큰을 확인하세요.

   ID 토큰에는 ID 공급업체로부터 SAML 어설션의 NameID 속성에 제공된 경우에만 사용자의 이메일 주소가 포함됩니다.

   <Subject>
     <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[e-mail]</NameID>
   </Subject>
   

   이는 Firebase에서 발급된 ID 토큰 및 UserInfo 객체에 채워집니다.

현재는 클라이언트의 SDK에서 서비스 공급업체가 시작하는 SAML 흐름만 지원됩니다.

사용자 계정 연결

사용자가 이미 다른 방식(예: 이메일/비밀번호)을 사용하여 앱에 로그인한 경우 linkWithPopup() 또는 linkWithRedirect()를 사용하여 SAML 제공업체에 기존 계정을 연결할 수 있습니다. 예를 들어 Google 계정에 연결할 수 있습니다.

웹 버전 9

트리 쉐이킹 작업이 가능한 모듈식 웹 API에 대해 자세히 알아보고 네임스페이스화된 API에서 업그레이드하세요.

import { getAuth, linkWithPopup, GoogleAuthProvider } from "firebase/auth";
const provider = new GoogleAuthProvider();

const auth = getAuth();
linkWithPopup(auth.currentUser, provider).then((result) => {
  // Accounts successfully linked.
  const credential = GoogleAuthProvider.credentialFromResult(result);
  const user = result.user;
  // ...
}).catch((error) => {
  // Handle Errors here.
  // ...
});
auth_link_with_popup.js

웹 버전 8

auth.currentUser.linkWithPopup(provider).then((result) => {
  // Accounts successfully linked.
  var credential = result.credential;
  var user = result.user;
  // ...
}).catch((error) => {
  // Handle Errors here.
  // ...
});
link-multiple-accounts.js

다음 단계

• OIDC로 사용자 로그인
• 로그인 시 커스텀 도메인 표시
• 프로그래매틱 방식으로 OIDC 및 SAML 공급업체 관리