Microsoft Azure 인증 공급자(Microsoft Azure Authentication Provider)
Backstage core-plugin-api 패키지에는 Azure OAuth를 사용해 사용자를 인증할 수 있는 Microsoft 인증 공급자가 포함되어 있습니다.
출처: 문서
본문
Backstage core-plugin-api 패키지에는 Azure OAuth를 사용해 사용자를 인증할 수 있는 Microsoft 인증 공급자가 포함되어 있습니다.
Azure에서 App Registration 구성하기
회사의 보안 수준에 따라 디렉터리 관리자가 이 지침 중 일부 또는 전부를 수행해야 할 수 있습니다.
Azure Portal > App registrations로 이동해 기존 앱 등록을 찾거나 새로 만드세요. Backstage용 기존 App Registration이 있다면 새로 만드는 대신 그것을 사용하세요.
앱 등록의 개요 페이지에서 다음 구성을 가진 새 Web 플랫폼 구성을 추가하세요.
-
Redirect URI:
https://your-backstage.com/api/auth/microsoft/handler/frame(로컬 개발의 경우 일반적으로http://localhost:7007/api/auth/microsoft/handler/frame) -
Front-channel logout Url: 비워 둠
-
Implicit grant and hybrid flows: 모두 선택 해제
API permissions 탭에서 Add Permission을 클릭한 다음, Microsoft Graph API에 대해 다음 Delegated 권한을 추가하세요.
-
email -
offline_access -
openid -
profile -
User.Read -
app-config.yaml파일에 정의된Microsoft GraphAPI의 선택적 커스텀 scope.
회사에서 이러한 권한에 대한 관리자 동의를 요구할 수 있습니다. 회사가 관리자 동의를 요구하지 않더라도, 사용자가 backstage에 처음 접근할 때 개별적으로 동의할 필요가 없으므로 수행하는 것이 좋을 수 있습니다. 관리자 동의를 부여하려면 디렉터리 관리자가 이 페이지에 와서 COMPANY NAME에 대한 Grant admin consent 버튼을 클릭해야 합니다.
기존 앱 등록을 사용하고 있고 backstage에 이미 클라이언트 시크릿이 있다면 그것을 재사용할 수 있습니다. 그렇지 않으면 Certificates & Secrets 페이지로 이동해 Client secrets 탭에서 새 클라이언트 시크릿을 만드세요. 다음 섹션에서 필요하므로 이 값을 기록해 두세요.
아웃바운드 네트워크 접근
환경에 아웃바운드 접근 제한(예: 방화벽 규칙)이 있다면 Backstage 백엔드가 다음 호스트에 접근할 수 있는지 확인하세요.
-
login.microsoftonline.com: 인증 코드와 접근 토큰을 얻고 교환하기 위해 -
graph.microsoft.com: 사용자 프로필 정보를 가져오기 위해(이 소스 코드에서 볼 수 있음). 이 호스트에 도달할 수 없으면 사용자가 로그인을 시도할 때Authentication failed, failed to fetch user profile오류를 볼 수 있습니다.
구성
공급자 구성은 루트 auth 구성 아래의 app-config.yaml에 추가할 수 있습니다.
auth: environment: development providers: microsoft: development: clientId: ${AZURE_CLIENT_ID} clientSecret: ${AZURE_CLIENT_SECRET} tenantId: ${AZURE_TENANT_ID} domainHint: ${AZURE_TENANT_ID} signIn: resolvers: # See https://backstage.io/docs/auth/microsoft/provider#resolvers for more resolvers - resolver: userIdMatchingUserEntityAnnotation
Microsoft 공급자는 세 개의 필수 구성 키를 가진 구조입니다.
-
clientId: App Registration > Overview에서 찾을 수 있는 Application(client) ID -
clientSecret: App Registration > Certificates & secrets에서 찾을 수 있는 Secret -
tenantId: App Registration > Overview에서 찾을 수 있는 Directory(tenant) ID -
domainHint(선택): 일반적으로tenantId와 동일합니다. 앱 등록이 다중 테넌트라면 비워 두세요. 지정하면 여러 테넌트에 계정이 있는 사용자가 다른 테넌트의 계정을 자동으로 필터링해 로그인 마찰을 줄입니다. 자세한 내용은 Home Realm Discovery를 참조하세요. -
additionalScopes(선택): 필수 scope에 더해 요청할 App Registration의 scope 목록. -
skipUserProfile(선택): true이면User.Readscope가 있어도 사용자 프로필 로딩을 건너뜁니다. 이는 Graph가 아닌 리소스(예: Azure Management API)에 대한 토큰을 획득할 때 프로필을 가져오기 위해 그렇지 않으면 이루어지는 별도의 Microsoft Graph 호출도 비활성화합니다. 이는 성능 최적화이며,emailOAuth2 scope가 있을 때 얻는spec.profile.email의 이메일 주소만 필요한 리졸버와 함께 사용할 수 있습니다. -
sessionDuration(선택): 사용자 세션의 수명.
리졸버
이 공급자는 바로 사용할 수 있는 여러 리졸버를 포함합니다.
-
emailMatchingUserEntityProfileEmail: auth 공급자의 이메일 주소를 일치하는spec.profile.email을 가진 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다. -
emailLocalPartMatchingUserEntityName: auth 공급자의 이메일 주소의 로컬 부분을 일치하는name을 가진 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다. -
emailMatchingUserEntityAnnotation: auth 공급자의 이메일 주소를microsoft.com/email어노테이션의 값이 일치하는 User 엔티티와 매칭합니다. 일치하는 항목이 없으면NotFoundError를 던집니다. -
userIdMatchingUserEntityAnnotation: auth 공급자의 사용자 프로필 ID를graph.microsoft.com/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-microsoft-provider
그런 다음 다음 줄을 추가해야 합니다.
packages/backend/src/index.ts에
backend.add(import('@backstage/plugin-auth-backend'));backend.add(import('@backstage/plugin-auth-backend-module-microsoft-provider'));
공급자를 Backstage 프론트엔드에 추가하기
프론트엔드에 공급자를 추가하려면 microsoftAuthApiRef 참조와 SignInPage 컴포넌트를 Adding the provider to the sign-in page에 표시된 대로 추가하세요.