GitHub 인증 공급자(GitHub Authentication Provider)
Backstage core-plugin-api 패키지에는 GitHub 또는 GitHub Enterprise OAuth를 사용해 사용자를 인증할 수 있는 GitHub 인증 공급자가 포함되어 있습니다.
출처: 문서
본문
Backstage core-plugin-api 패키지에는 GitHub 또는 GitHub Enterprise OAuth를 사용해 사용자를 인증할 수 있는 GitHub 인증 공급자가 포함되어 있습니다.
GitHub에서 OAuth App 만들기
GitHub 인증을 추가하려면 GitHub 개발자 설정에서 GitHub App 또는 OAuth App을 만들어야 합니다. Homepage URL은 Backstage의 프론트엔드를 가리켜야 하며, Authorization callback URL은 auth 백엔드를 가리킵니다.
GitHub App을 사용한다면 허용된 scope가 해당 앱의 일부로 구성된다는 점에 유의하세요. 즉 사용하는 플러그인이 요구하는 scope를 검증해야 하며, 그 정보는 플러그인 README를 확인해야 합니다.
로컬 개발 설정:
-
Application name: Backstage(또는 커스텀 앱 이름)
-
Homepage URL:
http://localhost:3000 -
Authorization callback URL:
http://localhost:7007/api/auth/github/handler/frame
GitHub Apps와 GitHub OAuth Apps의 차이
GitHub Apps는 OAuth scope를 앱 설치 수준에서 처리합니다. 즉 프론트엔드의 getAccessToken 호출에 대한 scope 매개변수는 효과가 없습니다. 오픈 소스 플러그인에서 getAccessToken을 호출할 때는 여전히 적절한 scope를 포함해야 하지만, GitHub Apps에 필요한 scope를 플러그인 README에 문서화해야 합니다.
구성
공급자 구성은 루트 auth 구성 아래의 app-config.yaml에 추가할 수 있습니다.
auth: environment: development providers: github: development: clientId: ${AUTH_GITHUB_CLIENT_ID} clientSecret: ${AUTH_GITHUB_CLIENT_SECRET} ## uncomment if using GitHub Enterprise # enterpriseInstanceUrl: ${AUTH_GITHUB_ENTERPRISE_INSTANCE_URL} ## uncomment to set lifespan of user session # sessionDuration: { hours: 24 } # supports `ms` library format (e.g. '24h', '2 days'), ISO duration, "human duration" as used in code signIn:
GitHub 공급자는 다음 구성 키를 가진 구조입니다.
-
clientId: GitHub에서 생성한 클라이언트 ID. 예:b59241722e3c3b4816e2 -
clientSecret: 생성된 클라이언트 ID에 연결된 클라이언트 시크릿. -
enterpriseInstanceUrl(선택): GitHub Enterprise 인스턴스의 기본 URL. 예:https://ghe.<company>.com. GitHub Enterprise에만 필요합니다. -
callbackUrl(선택): GitHub가 OAuth 흐름을 시작할 때 사용할 콜백 URL. 예:https://your-intermediate-service.com/handler. Backstage가 즉시 수신자가 아닐 때만 필요합니다(예: 여러 backstage 인스턴스에 대해 하나의 OAuth 앱). -
sessionDuration(선택): 사용자 세션의 수명. -
signIn: 로그인 프로세스 구성으로, auth 공급자의 사용자를 Backstage 카탈로그의 사용자 엔티티와 매칭하는 데 사용해야 할 리졸버를 포함합니다(일반적으로 단일 리졸버로 충분합니다).
리졸버
이 공급자는 바로 사용할 수 있는 여러 리졸버를 포함합니다.
-
emailMatchingUserEntityProfileEmail: auth 공급자의 이메일 주소를 일치하는spec.profile.email을 가진 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다. -
emailLocalPartMatchingUserEntityName: auth 공급자의 이메일 주소의 로컬 부분을 일치하는name을 가진 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다. -
userIdMatchingUserEntityAnnotation: GitHub 사용자 ID를 일치하는github.com/user-id어노테이션을 가진 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다. -
usernameMatchingUserEntityName(더 이상 사용되지 않음): auth 공급자의 사용자 이름을 일치하는name을 가진 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다.
caution
GitHub 사용자 이름은 변경될 수 있고 다른 사용자가 사용할 수 있게 됩니다. 불변인 GitHub 사용자 ID를 사용하는 userIdMatchingUserEntityAnnotation을 선호하세요.
note
리졸버는 순서대로 시도되지만 NotFoundError를 던질 때만 건너뜁니다.
이 리졸버들이 요구 사항에 맞지 않는다면 커스텀 리졸버를 만들 수 있습니다. 이는 Sign-in Identities and Resolvers 문서의 Building Custom Resolvers 섹션에서 다룹니다.
백엔드 설치
공급자를 백엔드에 추가하려면 먼저 다음 명령을 실행해 패키지를 설치해야 합니다.
Backstage 루트 디렉토리에서
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-github-provider
그런 다음 다음 줄을 추가해야 합니다.
packages/backend/src/index.ts에
backend.add(import('@backstage/plugin-auth-backend'));backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));
공급자를 Backstage 프론트엔드에 추가하기
프론트엔드에 공급자를 추가하려면 githubAuthApi 참조와 SignInPage 컴포넌트를 Adding the provider to the sign-in page에 표시된 대로 추가하세요.