GitLab 인증 공급자(GitLab Authentication Provider)
Backstage core-plugin-api 패키지에는 GitLab OAuth를 사용해 사용자를 인증할 수 있는 GitLab 인증 공급자가 포함되어 있습니다.
출처: 문서
본문
Backstage core-plugin-api 패키지에는 GitLab OAuth를 사용해 사용자를 인증할 수 있는 GitLab 인증 공급자가 포함되어 있습니다.
GitLab에서 OAuth App 만들기
GitLab 인증을 지원하려면 GitLab 설정에서 Application을 만들어야 합니다. Redirect URI는 Backstage 백엔드 auth 핸들러를 가리켜야 합니다.
-
Application Name을
backstage-dev또는 그와 비슷하게 설정하세요. -
Authorization Callback URL은 Backstage에 설정된 redirect URI와 일치해야 합니다.
-
로컬 개발의 경우 이것을
http://localhost:7007/api/auth/gitlab/handler/frame으로 설정하세요. -
비로컬 배포의 경우 이것을
http://{APP_FQDN}:{APP_BACKEND_PORT}/api/auth/gitlab/handler/frame으로 설정하세요. -
목록에서 다음 scope를 선택하세요.
-
apiapi에 대한 전체 읽기-쓰기 접근을 부여합니다. 사용자가 자신의 권한으로 병합 요청을 만들 수 있어야 하는 경우에만 필요합니다. -
read_apiAPI에 대한 읽기 접근을 부여하며, 모든 그룹과 프로젝트, 컨테이너 레지스트리, 패키지 레지스트리를 포함합니다. -
read_user/userAPI 엔드포인트를 통해 인증된 사용자 프로필에 대한 읽기 전용 접근을 부여합니다. 여기에는 사용자 이름, 공개 이메일, 전체 이름이 포함됩니다./users아래의 읽기 전용 API 엔드포인트에도 접근을 부여합니다. -
read_repositoryGit-over-HTTP(API가 아닌)를 사용해 비공개 프로젝트의 저장소에 읽기 전용 접근을 부여합니다. -
write_repositoryGit-over-HTTP(API가 아닌)를 사용해 비공개 프로젝트의 저장소에 읽기-쓰기 접근을 부여합니다. -
openidOpenID Connect를 사용해 GitLab으로 인증할 권한을 부여합니다. 사용자의 프로필과 그룹 멤버십에 대한 읽기 전용 접근도 제공합니다. -
profileOpenID Connect를 사용해 사용자 프로필 데이터에 대한 읽기 전용 접근을 부여합니다. -
emailOpenID Connect를 사용해 사용자의 기본 이메일 주소에 대한 읽기 전용 접근을 부여합니다.
구성
공급자 구성은 루트 auth 구성 아래의 app-config.yaml에 추가할 수 있습니다.
auth: environment: development providers: gitlab: development: clientId: ${AUTH_GITLAB_CLIENT_ID} clientSecret: ${AUTH_GITLAB_CLIENT_SECRET} ## uncomment if using self-hosted GitLab # audience: https://gitlab.company.com ## uncomment if using a custom redirect URI # callbackUrl: https://${BASE_URL}/api/auth/gitlab/handler/frame ## uncomment to set lifespan of user session # sessionDuration: { hours: 24 } # supports `ms` library fo
GitLab 공급자는 세 개의 구성 키를 가진 구조입니다.
-
clientId: GitLab에서 생성한 Application ID. 예:4928c033ab3d592845c044a653bc20583baf84f2e67b954c6fdb32a532ab76c9 -
clientSecret: Application 시크릿 -
audience(선택): 자체 호스팅 GitLab 인스턴스의 기본 URL. 예:https://gitlab.company.com -
callbackUrl(선택): GitLab OAuth App을 만들 때 등록한 Redirect URI와 일치하는 URL. 예:https://$backstage.acme.corp/api/auth/gitlab/handler/frame참고: GitLab OAuth의 특성 때문에 URL의 'frame' 뒤에 후행/가 없는지 확인하세요. -
sessionDuration(선택): 사용자 세션의 수명.
리졸버
이 공급자는 바로 사용할 수 있는 여러 리졸버를 포함합니다.
-
emailMatchingUserEntityProfileEmail: auth 공급자의 이메일 주소를 일치하는spec.profile.email을 가진 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다. -
emailLocalPartMatchingUserEntityName: auth 공급자의 이메일 주소의 로컬 부분을 일치하는name을 가진 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다. -
usernameMatchingUserEntityName: auth 공급자의 사용자 이름을 일치하는name을 가진 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다. -
userIdMatchingUserEntityAnnotation: GitLab 사용자 ID를 일치하는gitlab.com/user-id어노테이션(자체 호스팅 GitLab 인스턴스의 경우{integration-host}/user-id)을 가진 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다.
note
리졸버는 순서대로 시도되지만 NotFoundError를 던질 때만 건너뜁니다.
이 리졸버들이 요구 사항에 맞지 않는다면 커스텀 리졸버를 만들 수 있습니다. 이는 Sign-in Identities and Resolvers 문서의 Building Custom Resolvers 섹션에서 다룹니다.
백엔드 설치
공급자를 백엔드에 추가하려면 먼저 다음 명령을 실행해 패키지를 설치해야 합니다.
Backstage 루트 디렉토리에서
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-gitlab-provider
그런 다음 다음 줄을 추가해야 합니다.
packages/backend/src/index.ts에
backend.add(import('@backstage/plugin-auth-backend'));backend.add(import('@backstage/plugin-auth-backend-module-gitlab-provider'));
공급자를 Backstage 프론트엔드에 추가하기
프론트엔드에 공급자를 추가하려면 gitlabAuthApi 참조와 SignInPage 컴포넌트를 Adding the provider to the sign-in page에 표시된 대로 추가하세요.