Auth 모듈
The auth module (@backstage/cli-module-auth)은 CLI를 Backstage 인스턴스와 인증하기 위한 명령을 제공합니다.
출처: 문서
본문
The auth module (@backstage/cli-module-auth)은 CLI를 Backstage 인스턴스와 인증하기 위한 명령을 제공합니다. 액세스 토큰을 얻기 위해 PKCE가 있는 OAuth 2.0을 사용하며, 이 토큰은 actions 같은 다른 CLI 명령에서 사용됩니다.
전제 조건 (Prerequisites)
연결 대상 Backstage 인스턴스에 CLI 인증 지원이 활성화되어 있어야 합니다. CLI는 인스턴스의 well-known 엔드포인트인 /api/auth/.well-known/oauth-client/cli.json에서 OAuth 클라이언트 메타데이터를 가져와 이를 확인합니다.
인스턴스 이름 (Instance names)
각 인증된 Backstage 인스턴스는 사용자가 선택한 이름으로 저장됩니다. 이 이름은 다른 명령에서 인스턴스를 가리키는 데 사용되는 짧은 레이블입니다 (예: --instance production). 로그인 시 이름을 제공하지 않으면 CLI는 백엔드 URL의 호스트 이름에서 이름을 파생합니다 (예: backstage.example.com).
auth login
CLI를 Backstage 인스턴스에 로그인합니다. 브라우저를 열어 인증하는 OAuth 인가 흐름을 시작한 다음 결과 자격 증명을 로컬에 저장합니다.
Usage: backstage-cli auth login [options]Log in the CLI to a Backstage instanceOptions: --backendUrl <url> Backend base URL --noBrowser Do not open browser automatically --instance <name> A short name for this instance, used to refer to it in other auth commands. Defaults to the backend URL hostname.
플래그 없이 실행하면 명령이 대화형으로 프롬프트합니다. 로컬 app-config.yaml 파일을 스캔해 백엔드 URL을 발견하고, 하나를 선택하거나 URL을 수동으로 입력하게 하며, URL 호스트에서 인스턴스 이름을 파생합니다.
--noBrowser가 설정되면 인가 URL이 터미널에 출력되어 수동으로 열 수 있습니다.
예시 (Examples)
대화형 로그인:
yarn backstage-cli auth login
특정 백엔드 URL에 로그인:
yarn backstage-cli auth login --backendUrl https://backstage.example.com
로그인하고 나중에 참조할 인스턴스 이름 지정:
yarn backstage-cli auth login --backendUrl https://backstage.example.com --instance production
브라우저를 자동으로 열지 않고 로그인:
yarn backstage-cli auth login --backendUrl https://backstage.example.com --noBrowser
auth logout
Backstage 인스턴스에서 로그아웃하고 저장된 자격 증명을 지웁니다. 명령은 서버에서 리프레시 토큰을 취소하고(최선 노력) 로컬 저장소에서 토큰과 인스턴스 메타데이터를 모두 제거합니다.
Usage: backstage-cli auth logout [options]Log out the CLI and clear stored credentialsOptions: --instance <name> Name of the instance to log out
--instance가 제공되지 않으면 대화형 프롬프트가 인증된 인스턴스 목록에서 선택하게 합니다.
예시 (Examples)
특정 인스턴스에서 로그아웃:
yarn backstage-cli auth logout --instance production
대화형 로그아웃:
yarn backstage-cli auth logout
auth show
현재 사용자 신원과 소유권 엔터티 참조를 포함해 인증된 인스턴스의 세부 정보를 표시합니다.
Usage: backstage-cli auth show [options]Show details of an authenticated instanceOptions: --instance <name> Name of the instance to show
명령은 인스턴스의 /api/auth/v1/userinfo 엔드포인트에서 사용자 정보를 가져오고 필요하면 액세스 토큰을 새로 고칩니다.
예시 (Examples)
기본 인스턴스의 세부 정보 표시:
yarn backstage-cli auth show
이름이 지정된 인스턴스의 세부 정보 표시:
yarn backstage-cli auth show --instance production
auth list
인증된 모든 인스턴스를 나열합니다. 선택된 기본 인스턴스는 별표(*)로 표시됩니다.
Usage: backstage-cli auth listList authenticated instances
예시 (Examples)
yarn backstage-cli auth list
출력 예시:
* production - https://backstage.example.com staging - https://backstage-staging.example.com
auth print-token
액세스 토큰을 stdout으로 출력합니다. 토큰이 만료되었거나 곧 만료되면 출력 전에 자동으로 새로 고칩니다. 스크립팅과 파이프라인에 유용합니다.
Usage: backstage-cli auth print-token [options]Print an access token to stdout (auto-refresh if needed)Options: --instance <name> Name of the instance to use
예시 (Examples)
기본 인스턴스의 액세스 토큰 출력:
yarn backstage-cli auth print-token
curl 명령에서 토큰 사용:
curl -H "Authorization: Bearer *** backstage-cli auth print-token)" \ https://backstage.example.com/api/catalog/entities
이름이 지정된 인스턴스의 토큰 출력:
yarn backstage-cli auth print-token --instance staging
auth select
기본 인스턴스를 선택합니다. 다른 auth 명령은 --instance 플래그가 제공되지 않을 때 기본 인스턴스를 사용합니다.
Usage: backstage-cli auth select [options]Select the default instanceOptions: --instance <name> Name of the instance to select
--instance가 제공되지 않으면 대화형 프롬프트가 인증된 인스턴스 목록에서 선택하게 합니다.
예시 (Examples)
특정 인스턴스를 기본값으로 선택:
yarn backstage-cli auth select --instance production
대화형 선택:
yarn backstage-cli auth select
인스턴스 저장 (Instance storage)
인증 상태는 두 곳에 저장됩니다.
- 인스턴스 메타데이터는
~/.config/backstage-cli/auth-instances.yaml(또는 XDG 구성 디렉터리를 사용하는 플랫폼 적절한 동등물)의 YAML 파일에 저장됩니다. 이 파일에는 인스턴스 이름, 백엔드 URL, 토큰 만료 타임스탬프, 선택된 인스턴스가 포함됩니다. - 토큰(액세스 토큰과 리프레시 토큰)은 YAML 파일과 분리된 시스템 비밀 저장소에 저장됩니다.