Cloud Run용 최종 사용자 인증 가이드

gcloud 기본값 설정

Cloud Run 서비스의 기본값으로 gcloud를 구성하려면 다음 안내를 따르세요.

1. 기본 프로젝트를 설정합니다.

   gcloud config set project PROJECT_ID

   PROJECT_ID를 이 튜토리얼용으로 만든 프로젝트 이름으로 바꿉니다.

2. 선택한 리전에 맞게 gcloud를 구성합니다.

   gcloud config set run/region REGION

   REGION을 지원되는 Cloud Run 리전 중 원하는 리전으로 바꿉니다.

코드 샘플 검색

사용할 코드 샘플을 검색하려면 다음 안내를 따르세요.

1. 샘플 앱 저장소를 로컬 머신에 클론합니다.

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   또는 zip 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   또는 zip 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

   또는 zip 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.

2. Cloud Run 샘플 코드가 포함된 디렉터리로 변경합니다.

   Node.js

   cd nodejs-docs-samples/run/idp-sql/

   Python

   cd python-docs-samples/run/idp-sql/

   자바

   cd java-docs-samples/run/idp-sql/

아키텍처 시각화

1. 최종 사용자가 Cloud Run 서버에 첫 번째 요청을 보냅니다.

2. 클라이언트가 브라우저에 로드됩니다.

3. 사용자가 Identity Platform의 Google 로그인 대화상자를 통해 로그인 사용자 인증 정보를 제공합니다. 알림에서 로그인한 사용자를 환영합니다.

4. 제어가 다시 서버로 리디렉션됩니다. 최종 사용자가 클라이언트를 사용하여 투표합니다. 그러면 클라이언트가 Identity Platform에서 ID 토큰을 가져와 투표 요청 헤더에 추가합니다.

5. 서버에서 요청을 수신하면 Identity Platform ID 토큰을 확인하여 최종 사용자가 적절하게 인증되었는지 확인합니다. 그런 다음 서버가 자체 사용자 인증 정보를 사용하여 Cloud SQL에 투표를 전송합니다.

코어 코드 이해

이 샘플은 다음에 설명된 것처럼 클라이언트 및 서버로 구현됩니다.

Identity Platform과 통합: 클라이언트 측 코드

이 샘플은 사용자 로그인 및 관리를 위해 Firebase SDK를 사용하여 Identity Platform과 통합됩니다. Identity Platform에 연결하기 위해 클라이언트 측 자바스크립트는 프로젝트의 사용자 인증 정보에 대한 참조를 구성 객체로 저장하며 필요한 Firebase 자바스크립트 SDK를 가져옵니다.

const config = {
  apiKey: 'API_KEY',
  authDomain: 'PROJECT_ID.firebaseapp.com',
};

<!-- Firebase App (the core Firebase SDK) is always required and must be listed first-->
<script src="https://www.gstatic.com/firebasejs/7.18/firebase-app.js"></script>
<!-- Add Firebase Auth service-->
<script src="https://www.gstatic.com/firebasejs/7.18/firebase-auth.js"></script>

Firebase 자바스크립트 SDK는 최종 사용자에게 팝업 창을 통해 Google 계정에 로그인하라는 메시지를 표시하여 로그인 과정을 처리합니다. 그런 다음 다시 서비스로 리디렉션합니다.

function signIn() {
  const provider = new firebase.auth.GoogleAuthProvider();
  provider.addScope('https://www.googleapis.com/auth/userinfo.email');
  firebase
    .auth()
    .signInWithPopup(provider)
    .then(result => {
      // Returns the signed in user along with the provider's credential
      console.log(`${result.user.displayName} logged in.`);
      window.alert(`Welcome ${result.user.displayName}!`);
    })
    .catch(err => {
      console.log(`Error during sign in: ${err.message}`);
      window.alert('Sign in failed. Retry or check your browser logs.');
    });
}

사용자가 성공적으로 로그인하면 클라이언트는 Firebase 메서드를 사용하여 ID 토큰을 만듭니다. 클라이언트는 ID 요청을 서버에 대한 요청의 Authorization 헤더에 추가합니다.

async function vote(team) {
  if (firebase.auth().currentUser) {
    // Retrieve JWT to identify the user to the Identity Platform service.
    // Returns the current token if it has not expired. Otherwise, this will
    // refresh the token and return a new one.
    try {
      const token = await firebase.auth().currentUser.getIdToken();
      const response = await fetch('/', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          Authorization: `Bearer ${token}`,
        },
        body: 'team=' + team, // send application data (vote)
      });
      if (response.ok) {
        const text = await response.text();
        window.alert(text);
        window.location.reload();
      }
    } catch (err) {
      console.log(`Error when submitting vote: ${err}`);
      window.alert('Something went wrong... Please try again!');
    }
  } else {
    window.alert('User not signed in.');
  }
}

Identity Platform과 통합: 서버 측 코드

서버는 Firebase Admin SDK를 사용하여 클라이언트에서 전송된 사용자 ID 토큰을 확인합니다. 제공된 ID 토큰이 올바른 형식이고 만료되지 않았으며 올바르게 로그인된 경우 이 메서드는 디코딩된 ID 토큰을 반환합니다. 서버는 사용자의 Identity Platform uid를 추출합니다.

const firebase = require('firebase-admin');
// Initialize Firebase Admin SDK
firebase.initializeApp();

// Extract and verify Id Token from header
const authenticateJWT = (req, res, next) => {
  const authHeader = req.headers.authorization;
  if (authHeader) {
    const token = authHeader.split(' ')[1];
    // If the provided ID token has the correct format, is not expired, and is
    // properly signed, the method returns the decoded ID token
    firebase
      .auth()
      .verifyIdToken(token)
      .then(decodedToken => {
        const uid = decodedToken.uid;
        req.uid = uid;
        next();
      })
      .catch(err => {
        req.logger.error(`Error with authentication: ${err}`);
        return res.sendStatus(403);
      });
  } else {
    return res.sendStatus(401);
  }
};

def jwt_authenticated(func: Callable[..., int]) -> Callable[..., int]:
    """Use the Firebase Admin SDK to parse Authorization header to verify the
    user ID token.

    The server extracts the Identity Platform uid for that user.
    """

    @wraps(func)
    def decorated_function(*args: a, **kwargs: a) -> a:
        header = request.headers.get("Authorization", None)
        if header:
            token = header.split(" ")[1]
            try:
                decoded_token = firebase_admin.auth.verify_id_token(token)
            except Exception as e:
                logger.exception(e)
                return Response(status=403, response=f"Error with authentication: {e}")
        else:
            return Response(status=401)

        request.uid = decoded_token["uid"]
        return func(*args, **kwargs)

    return decorated_function

/** Extract and verify Id Token from header */
private String authenticateJwt(Map<String, String> headers) {
  String authHeader =
      (headers.get("authorization") != null)
          ? headers.get("authorization")
          : headers.get("Authorization");
  if (authHeader != null) {
    String idToken = authHeader.split(" ")[1];
    // If the provided ID token has the correct format, is not expired, and is
    // properly signed, the method returns the decoded ID token
    try {
      FirebaseToken decodedToken = FirebaseAuth.getInstance().verifyIdToken(idToken);
      String uid = decodedToken.getUid();
      return uid;
    } catch (FirebaseAuthException e) {
      logger.error("Error with authentication: " + e.toString());
      throw new ResponseStatusException(HttpStatus.FORBIDDEN, "", e);
    }
  } else {
    logger.error("Error no authorization header");
    throw new ResponseStatusException(HttpStatus.UNAUTHORIZED);
  }
}

Cloud SQL에 서버 연결

서버에서 /cloudsql/CLOUD_SQL_CONNECTION_NAME 형식을 사용하여 Cloud SQL 인스턴스 Unix 도메인 소켓에 연결합니다.

/**
 * Connect to the Cloud SQL instance through UNIX Sockets
 *
 * @param {object} credConfig The Cloud SQL connection configuration from Secret Manager
 * @returns {object} Knex's PostgreSQL client
 */
const connectWithUnixSockets = async credConfig => {
  const dbSocketPath = process.env.DB_SOCKET_PATH || '/cloudsql';
  // Establish a connection to the database
  return Knex({
    client: 'pg',
    connection: {
      user: credConfig.DB_USER, // e.g. 'my-user'
      password: credConfig.DB_PASSWORD, // e.g. 'my-user-password'
      database: credConfig.DB_NAME, // e.g. 'my-database'
      host: `${dbSocketPath}/${credConfig.CLOUD_SQL_CONNECTION_NAME}`,
    },
    ...config,
  });
};

def init_unix_connection_engine(
    db_config: dict[str, int]
) -> sqlalchemy.engine.base.Engine:
    """Initializes a Unix socket connection pool for a Cloud SQL instance of PostgreSQL.

    Args:
        db_config: a dictionary with connection pool config

    Returns:
        A SQLAlchemy Engine instance.
    """
    creds = credentials.get_cred_config()
    db_user = creds["DB_USER"]
    db_pass = creds["DB_PASSWORD"]
    db_name = creds["DB_NAME"]
    db_socket_dir = creds.get("DB_SOCKET_DIR", "/cloudsql")
    cloud_sql_connection_name = creds["CLOUD_SQL_CONNECTION_NAME"]

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgres+pg8000://<db_user>:<db_pass>@/<db_name>
        #                         ?unix_sock=<socket_path>/<cloud_sql_instance_name>/.s.PGSQL.5432
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,  # e.g. "my-database-user"
            password=db_pass,  # e.g. "my-database-password"
            database=db_name,  # e.g. "my-database-name"
            query={
                "unix_sock": f"{db_socket_dir}/{cloud_sql_connection_name}/.s.PGSQL.5432"
                # e.g. "/cloudsql", "<PROJECT-NAME>:<INSTANCE-REGION>:<INSTANCE-NAME>"
            },
        ),
        **db_config,
    )
    pool.dialect.description_encoding = None
    logger.info("Database engine initialized from unix connection")

    return pool

# Uncomment and add env vars for local development
# spring.datasource.username=${DB_USER}
# spring.datasource.password=${DB_PASSWORD}
# spring.cloud.gcp.sql.database-name=${DB_NAME}
# spring.cloud.gcp.sql.instance-connection-name=${CLOUD_SQL_CONNECTION_NAME}  

private final JdbcTemplate jdbcTemplate;

public VoteController(JdbcTemplate jdbcTemplate) {
  this.jdbcTemplate = jdbcTemplate;
}

보안 관리자로 민감한 구성 처리

Secret Manager는 Cloud SQL 구성과 같은 민감한 정보에 대한 안전한 중앙 집중식 스토리지를 제공합니다. 서버에서는 런타임 시 보안 변수를 통해 Secret Manager의 Cloud SQL 사용자 인증 정보를 삽입합니다. Cloud Run에서 보안 비밀 사용에 대해 자세히 알아보세요.

// CLOUD_SQL_CREDENTIALS_SECRET is the resource ID of the secret, passed in by environment variable.
// Format: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION
const {CLOUD_SQL_CREDENTIALS_SECRET} = process.env;
if (CLOUD_SQL_CREDENTIALS_SECRET) {
  try {
    // Parse the secret that has been added as a JSON string
    // to retrieve database credentials
    return JSON.parse(CLOUD_SQL_CREDENTIALS_SECRET.toString('utf8'));
  } catch (err) {
    throw Error(
      `Unable to parse secret from Secret Manager. Make sure that the secret is JSON formatted: ${err}`
    );
  }
}

def get_cred_config() -> dict[str, str]:
    """Retrieve Cloud SQL credentials stored in Secret Manager
    or default to environment variables.

    Returns:
        A dictionary with Cloud SQL credential values
    """
    secret = os.environ.get("CLOUD_SQL_CREDENTIALS_SECRET")
    if secret:
        return json.loads(secret)

/** Retrieve config from Secret Manager */
public static HashMap<String, Object> getConfig() {
  String secret = System.getenv("CLOUD_SQL_CREDENTIALS_SECRET");
  if (secret == null) {
    throw new IllegalStateException("\"CLOUD_SQL_CREDENTIALS_SECRET\" is required.");
  }
  try {
    HashMap<String, Object> config = new Gson().fromJson(secret, HashMap.class);
    return config;
  } catch (JsonSyntaxException e) {
    logger.error(
        "Unable to parse secret from Secret Manager. Make sure that it is JSON formatted: "
            + e);
    throw new RuntimeException(
        "Unable to parse secret from Secret Manager. Make sure that it is JSON formatted.");
  }
}

Identity Platform 설정

Identity Platform을 사용하려면 Google Cloud Console에서 수동 설정이 필요합니다.

1. Google Cloud Console에서 Identity Platform Marketplace 페이지로 이동합니다.

   Identity Platform Marketplace 페이지로 이동

2. Identity Platform 사용 설정을 클릭합니다.

3. OAuth 동의 화면을 만듭니다.

   1. 새 창에서 API 및 서비스 > 사용자 인증 정보 페이지로 이동합니다.

      API 및 서비스 > 사용자 인증 정보 페이지로 이동

   2. OAuth 동의 화면 페이지를 선택합니다.

   3. 테스트 목적에서 외부를 선택합니다.

   4. 만들기를 클릭합니다.

   5. 앱 정보 대화상자에서

      1. 애플리케이션 이름을 제공합니다.
      2. 표시된 사용자 지원 이메일 중 하나를 선택합니다.
      3. 개발자 연락처에 사용하려는 이메일을 입력합니다.

   6. 저장 후 계속을 클릭합니다.

   7. 범위 대화상자에서 저장 후 계속을 클릭합니다.

   8. 사용자 테스트 대화상자에서 저장 후 계속을 클릭합니다.

   9. 요약 대화상자에서 대시보드로 돌아가기를 클릭합니다.

   10. 게시 상태에서 앱 게시를 클릭합니다.

   11. 확인을 클릭합니다.

4. OAuth 클라이언트 ID와 보안 비밀을 만들고 가져옵니다.

   1. API 및 서비스 > 사용자 인증 정보 페이지로 이동

   2. 페이지 상단에서 사용자 인증 정보 만들기를 클릭하고 OAuth client ID를 선택합니다.

   3. 애플리케이션 유형에서 웹 애플리케이션을 선택하고 이름을 제공합니다.

   4. 만들기를 클릭합니다.

   5. 이 절차의 뒷부분에서 사용할 수 있도록 client_id 및 client_secret을 기록해 둡니다.

5. Google을 공급업체로 구성합니다.

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

      ID 공급업체 페이지로 이동

   2. 공급업체 추가를 클릭합니다.

   3. 목록에서 Google을 선택합니다.

   4. 웹 SDK 구성 설정에 이전 단계의 client_id 및 client_secret 값을 입력합니다.

   5. 애플리케이션 구성에서 설정 세부정보를 클릭합니다.

   6. apiKey 및 authDomain 값을 샘플의 static/config.js에 복사하여 Identity Platform Client SDK를 초기화합니다.

   7. 저장을 클릭합니다.

서비스 배포

아래 단계에 따라 인프라 프로비저닝 및 배포를 완료하거나 'Google Cloud에서 실행'을 클릭하여 Cloud Shell에서 프로세스를 자동화합니다.

1. Console 또는 CLI를 사용하여 postgreSQL 데이터베이스로 Cloud SQL 인스턴스를 만듭니다.

   gcloud sql instances create CLOUD_SQL_INSTANCE_NAME \
       --database-version=POSTGRES_12 \
       --region=CLOUD_SQL_REGION \
       --cpu=2 \
       --memory=7680MB \
       --root-password=DB_PASSWORD

2. Cloud SQL 사용자 인증 정보 값을 postgres-secrets.json에 추가합니다.

   Node.js

   {
     "CLOUD_SQL_CONNECTION_NAME": "PROJECT_ID:REGION:INSTANCE",
     "DB_NAME": "postgres",
     "DB_USER": "postgres",
     "DB_PASSWORD": "PASSWORD_SECRET"
   }
   

   Python

   {
     "CLOUD_SQL_CONNECTION_NAME": "PROJECT_ID:REGION:INSTANCE",
     "DB_NAME": "postgres",
     "DB_USER": "postgres",
     "DB_PASSWORD": "PASSWORD_SECRET"
   }
   

   자바

   {
     "spring.cloud.gcp.sql.instance-connection-name": "PROJECT_ID:REGION:INSTANCE",
     "spring.cloud.gcp.sql.database-name": "postgres",
     "spring.datasource.username": "postgres",
     "spring.datasource.password": "PASSWORD_SECRET"
   }

3. Console 또는 CLI를 사용하여 버전 관리 보안 비밀을 만듭니다.

   gcloud secrets create idp-sql-secrets \
       --replication-policy="automatic" \
       --data-file=postgres-secrets.json

4. Console 또는 CLI를 사용하여 서버의 서비스 계정을 만듭니다.

   gcloud iam service-accounts create idp-sql-identity

5. Console 또는 CLI를 사용하여 Secret Manager 및 Cloud SQL 액세스에 대한 역할을 부여합니다.

   1. 서버와 연결된 서비스 계정에서 생성된 보안 비밀에 액세스하도록 허용합니다.

      gcloud secrets add-iam-policy-binding idp-sql-secrets \
        --member serviceAccount:idp-sql-identity@PROJECT_ID.iam.gserviceaccount.com \
        --role roles/secretmanager.secretAccessor

   2. 서버와 연결된 서비스 계정에서 Cloud SQL에 액세스하도록 허용합니다.

      gcloud projects add-iam-policy-binding PROJECT_ID \
        --member serviceAccount:idp-sql-identity@PROJECT_ID.iam.gserviceaccount.com \
        --role roles/cloudsql.client

6. Artifact Registry를 만듭니다.

   gcloud artifacts repositories create REPOSITORY \
       --repository-format docker \
       --location REGION

   • REPOSITORY는 저장소 이름입니다. 프로젝트의 저장소 위치마다 저장소 이름이 고유해야 합니다.

7. Cloud Build를 사용하여 컨테이너 이미지를 빌드합니다.

   Node.js

   gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/idp-sql

   Python

   gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/idp-sql

   자바

   이 샘플은 Jib를 사용해서 일반적인 Java 도구로 Docker 이미지를 빌드합니다. Jib는 Dockerfile을 사용하거나 Docker를 설치할 필요 없이 컨테이너 빌드를 최적화합니다. Jib로 자바 컨테이너 빌드에 대해 자세히 알아보세요.

   1. gcloud 사용자 인증 정보 도우미를 사용하여 Docker가 Artifact Registry로 내보내도록 승인합니다.

      gcloud auth configure-docker

   2. Jib Maven 플러그인을 사용하여 컨테이너를 빌드하고 Artifact Registry로 내보냅니다.

      mvn compile jib:build -Dimage=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/idp-sql

8. 콘솔 또는 CLI를 사용하여 컨테이너 이미지를 Cloud Run에 배포합니다. 서버는 인증되지 않은 액세스를 허용하도록 배포됩니다. 이는 사용자가 클라이언트를 로드하고 프로세스를 시작할 수 있도록 하기 위함입니다. 서버는 투표 요청에 추가된 ID 토큰을 수동으로 확인하여 최종 사용자를 인증합니다.

   gcloud run deploy idp-sql \
       --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/idp-sql \
       --allow-unauthenticated \
       --service-account idp-sql-identity@PROJECT_ID.iam.gserviceaccount.com \
       --add-cloudsql-instances PROJECT_ID:REGION:CLOUD_SQL_INSTANCE_NAME \
       --update-secrets CLOUD_SQL_CREDENTIALS_SECRET=idp-sql-secrets:latest

   또한 여기서 --service-account ,--add-cloudsql-instances ,--update-secrets 플래그는 서비스 ID, Cloud SQL 인스턴스 연결, 버전을 환경 변수로 사용하는 보안 비밀 이름을 각각 지정합니다.

마무리 단계

Identity Platform을 사용하려면 사용자가 로그인한 후 Cloud Run 서비스 URL을 허용된 리디렉션으로 승인해야 합니다.

1. ID 공급업체 페이지에서 펜 아이콘을 클릭하여 Google 공급업체를 수정합니다.

2. 오른쪽 패널의 승인된 도메인 아래에서 도메인 추가를 클릭하고 Cloud Run 서비스 URL을 입력합니다.

   빌드 또는 배포 후 로그에서 서비스 URL을 찾거나 언제든 다음을 사용하여 찾을 수 있습니다.

   gcloud run services describe idp-sql --format 'value(status.url)'

3. API 및 서비스 > 사용자 인증 정보 페이지로 이동

   1. OAuth 클라이언트 ID 옆에 있는 연필 아이콘을 클릭하여 수정하고 Authorized redirect URIs click the 아래에서 URI 추가 버튼을 클릭합니다.

   2. 필드에 다음 URL을 복사하여 붙여넣고 페이지 하단에서 저장 버튼을 클릭합니다.

   https://PROJECT_ID.firebaseapp.com/__/auth/handler

사용해 보기

전체 서비스를 시도해봅니다.

1. 브라우저에서 위의 배포 단계로 제공된 URL로 이동합니다.

2. Google 계정으로 로그인 버튼을 클릭하고 인증 흐름을 진행합니다.

3. 투표하기

   예를 들면 다음과 같습니다.

   

이러한 서비스를 계속 개발하려면 이들 서비스에 다른 Google Cloud 서비스에 대한 제한적인 Identity and Access Management(IAM) 액세스 권한이 있으며 다른 여러 서비스에 액세스하려면 추가 IAM 역할이 부여되어야 합니다.