인증(Authentication)

원문 보기 위키 갱신 2026.10.07

이 문서는 이전 프런트엔드 시스템을 기준으로 작성됐어요.

출처: 문서

본문

info

이 문서는 이전 프런트엔드 시스템을 위해 작성됐어요. 새 프런트엔드 시스템을 사용 중이라면 별도의 문서를 읽는 것이 좋아요.

대상 독자: 관리자 또는 개발자(Admins or Developers)

요약(Summary)

GitHub을 사용해 Backstage 앱에 인증을 설정하는 방법을 안내할게요. 이 가이드를 끝내면 작동하는 인증과, 로그인하는 사용자와 대응시킬 Backstage 앱 안의 사용자를 모두 갖게 돼요.

Backstage와 함께 사용할 수 있는 인증 제공자는 여러 가지가 있어요. 자신들의 지침을 따라 인증을 추가해도 좋아요.

note

기본 Backstage 앱에는 게스트 Sign In Resolver가 함께 제공돼요. 이 resolver는 모든 사용자가 하나의 "guest" 아이덴티티를 공유하게 만들고, 빠르게 실행하기 위한 최소 요구사항으로만 의도된 것이에요. Sign In Resolver가 로그인한 사용자를 위한 Backstage 사용자 아이덴티티(User Identity)를 만드는 데 어떤 역할을 하는지 자세히 읽어볼 수 있어요.

인증 설정하기

이 튜토리얼에서는 무료 서비스라서 대부분이 익숙할 GitHub을 선택하고, OAuth 앱을 사용할게요. 자세한 옵션은 GitHub auth provider 문서를 참고하세요.

https://github.com/settings/applications/new로 이동해 OAuth App을 만드세요. "Homepage URL"은 Backstage의 프런트엔드를 가리켜야 해요. 이 튜토리얼에서는 http://localhost:3000이 되죠. "Authorization callback URL"은 auth 백엔드를 가리키는데, 아마 http://localhost:7007/api/auth/github/handler/frame이 될 거예요.

Client ID와 Client Secret을 기록해 두세요("Generate a new client secret" 버튼을 클릭하면 이 값을 얻을 수 있어요). app-config.yaml을 열고 이 파일에 clientId와 clientSecret으로 추가하세요. 다음과 같이 되어야 해요.

app-config.yaml

auth:
  # see https://backstage.io/docs/auth/ to learn about auth providers
  environment: development
  providers:
    # See https://backstage.io/docs/auth/guest/provider
    guest: {}
    github:
      development:
        clientId: YOUR CLIENT ID
        clientSecret: YOUR CLIENT SECRET

프런트엔드에 로그인 옵션 추가하기

다음 단계는 로그인 페이지를 바꾸는 것이에요. 이를 위해 실제로 코드를 좀 작성해야 해요.

packages/app/src/App.tsx를 열고 마지막 import 줄 아래에 다음을 추가해요.

packages/app/src/App.tsx

import { githubAuthApiRef } from '@backstage/core-plugin-api';

이 파일에서 const app = createApp({를 찾아 다음을 교체해요.

packages/app/src/App.tsx

components: {
  SignInPage: props => <SignInPage {...props} auto providers={['guest']} />,
},

다음으로:

packages/app/src/App.tsx

components: {
  SignInPage: props => (
    <SignInPage
      {...props}
      auto
      provider={{
        id: 'github-auth-provider',
        title: 'GitHub',
        message: 'Sign in using GitHub',
        apiRef: githubAuthApiRef,
      }}
    />
  ),
},

다음으로 구성에 sign-in resolver를 추가해야 해요. 방법은 다음과 같아요.

app-config.yaml

auth:
  # see https://backstage.io/docs/auth/ to learn about auth providers
  environment: development
  providers:
    # See https://backstage.io/docs/auth/guest/provider
    guest: {}
    github:
      development:
        clientId: YOUR CLIENT ID
        clientSecret: YOUR CLIENT SECRET
        signIn:
          resolvers:
            # Matches the immutable GitHub user ID with the Backstage user entity.
            # See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers.
            - resolver: userIdMatchingUserEntityAnnotation

이 구성은 auth 제공자가 제공하는 변경 불가능한(immutable) GitHub 사용자 ID를 Catalog의 User에 있는 github.com/user-id annotation과 대응시켜요. 일치하는 사용자를 찾지 못하면 "Failed to sign-in, unable to resolve user identity" 메시지를 받게 돼요. 이 부분은 다음 몇 섹션에서 다룰게요.

이 주제에 대해 더 배우고 싶다면 Sign-in Resolvers 문서를 참고하세요.

백엔드에 auth provider 추가하기

백엔드에 auth provider를 추가하려면 먼저 이 명령을 실행해 패키지를 설치해야 해요.

Backstage 루트 디렉터리에서:

yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-github-provider

그다음 이 줄을 추가해야 해요.

in packages/backend/src/index.ts

backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));

터미널에서 Ctrl+C로 Backstage를 멈추고 yarn start로 다시 시작하세요. 로그인 프롬프트가 반겨줄 거예요! 이 시점에 로그인을 시도하면 "Failed to sign-in, unable to resolve user identity" 메시지를 받게 될 텐데, 다음에서 그걸 고치니 계속 읽어 보세요.

note

때로는 프런트엔드가 백엔드보다 먼저 시작되어 로그인 페이지에 오류가 생길 수 있어요. 백엔드가 시작할 때까지 기다린 다음 Backstage를 새로고침해 계속하세요.

사용자 추가하기

Catalog에 사용자(User)와 그룹(Group)을 추가하는 권장 방법은 GitHub용 같은 기존 Org Entity Provider 중 하나를 사용하는 것이에요. 그것들이 동작하지 않는다면 조직의 필요에 맞는 것을 만들어야 할 수도 있어요.

이 가이드에서는 새 Backstage 인스턴스를 만들 때 포함되는 org.yaml 파일에 사용자를 추가하는 방법을 간단히 안내할게요. 해 봅시다.

먼저 텍스트 편집기로 /examples/org.yaml 파일을 여세요.
맨 아래에 다음 YAML을 추가할게요.

---
apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: YOUR GITHUB USERNAME
  annotations:
    github.com/user-id: YOUR GITHUB USER ID
spec:
  memberOf: [guests]

YOUR GITHUB USERNAME을 여러분의 GitHub 사용자 이름으로, YOUR GITHUB USER ID를 GitHub 사용자 프로필의 node_id로 바꾸세요.

터미널에서 한 번 더 Ctrl+C로 Backstage를 멈추고 yarn start로 다시 시작해 보세요. 이제 Backstage에 로그인하고 Catalog에서 항목들을 볼 수 있을 거예요.

Backstage에서 인증에 대해 더 배우고 싶다면 읽을 수 있는 문서가 있어요.

Backstage에서의 인증(Authentication in Backstage)
GitHub에서 조직 데이터 사용하기

GitHub 통합 설정하기

GitHub 통합은 GitHub 또는 GitHub Enterprise에서 카탈로그 엔티티를 로드하는 것을 지원해요. 엔티티는 정적 카탈로그 구성에 추가하거나, catalog-import 플러그인으로 등록하거나, GitHub 조직에서 발견할 수 있어요. 사용자와 그룹도 조직에서 로드할 수 있어요. GitHub Apps를 사용하는 것이 통합을 설정하는 가장 좋은 방법일 수 있지만, 이 튜토리얼에서는 Personal Access Token을 사용할게요.

GitHub 토큰 생성 페이지를 열어 Personal Access Token을 만드세요. 이름을 사용해 이 토큰을 식별하고 notes 필드에 넣으세요. 만료 일수를 선택하세요. 숫자를 고르기 어렵다면 7일을 추천해요. 행운의 숫자니까요.

스코프는 원하는 대로 설정하세요. 이 튜토리얼에서는 repo와 workflow를 선택하는 것이 필요해요. 이 가이드의 스캐폴딩 작업이 새로 만든 프로젝트에 GitHub actions 워크플로우를 구성하기 때문이에요.

이 튜토리얼에서는 토큰을 app-config.local.yaml에 작성할게요. 이 파일이 없을 수도 있는데, 없으면 프로젝트 루트의 app-config.yaml 옆에 만들면 돼요. 이 파일은 실수로 커밋되지 않도록 .gitignore에도 제외되어야 해요. 이 파일에 대한 자세한 내용은 정적 구성(Static Configuration) 문서에서 찾을 수 있어요.

app-config.local.yaml에 다음을 추가하세요.

app-config.local.yaml

integrations:
  github:
    - host: github.com
      token: «redacted:ghp_…» # this should be the token from GitHub

그럼 됐어요. 이 정보는 다른 플러그인이 활용할 거예요.

이 시크릿을 관리하는 더 프로덕션적인 방법을 찾고 있다면, 토큰을 GITHUB_TOKEN이라는 환경 변수에 저장하고 다음과 같이 할 수 있어요.

app-config.local.yaml

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN} # this will use the environment variable GITHUB_TOKEN

note

통합에 대한 구성을 업데이트했다면 백엔드가 이러한 변경을 적용하려면 재시작이 필요할 가능성이 높아요. 이렇게 하려면 터미널에서 실행 중인 인스턴스를 Control-C로 멈춘 다음 yarn start로 다시 시작하세요. 백엔드가 재시작되면 연산을 다시 시도하세요.

더 배우고 싶다면 유용한 링크가 몇 가지 있어요.

다른 사용 가능한 통합들
Personal Access Token 대신 GitHub Apps 사용하기

인증(Authentication)

본문

요약(Summary)

인증 설정하기

프런트엔드에 로그인 옵션 추가하기

Sign-in resolver(s) 추가하기

백엔드에 auth provider 추가하기

사용자 추가하기

GitHub 통합 설정하기

더 알아보기 (Learn more)