Http Auth 서비스
httpAuth 서비스는 Express HTTP 요청/응답 객체에 자격 증명을 제출하고 받는 일을 다뤄요.
출처: 문서
본문
httpAuth 서비스는 Express HTTP 요청/응답 객체에 자격 증명을 제출하고 받는 일을 다뤄요. 이 서비스는 REST 인터페이스를 가진 플러그인에서 자주 사용돼요.
원시 토큰을 다루고 저수준 자격 증명 처리를 원한다면 auth 서비스도 참고하세요. 소유권 엔터티 참조 같은 인증된 사용자에 대한 더 자세한 정보를 추출하려면 userInfo 서비스를 사용하세요.
서비스 사용
다음 코드 예시에서 auth와 httpAuth 변수는 각각 의존성 주입된 coreServices.auth와 coreServices.httpAuth 서비스 인스턴스라고 가정해요. 백엔드 플러그인의 경우 다음과 같을 수 있어요:
export default createBackendPlugin({ pluginId: 'my-plugin', register(env) { env.registerInit({ deps: { auth: coreServices.auth, httpAuth: coreServices.httpAuth, httpRouter: coreServices.httpRouter, }, async init({ auth, httpAuth, httpRouter }) { // Your code goes here }, }); },});
요청 자격 증명 얻기
들어오는 요청에서 검증된 자격 증명을 추출해야 한다면 이렇게 할 수 있어요:
router.get('/some-request', async (req, res) => { const credentials = await httpAuth.credentials(req, { allow: ['user'] }); // Do something with the credentials here});
두 번째 인자는 선택적이지만, 이 예시에서는 사용자 기반 요청만 허용하고 싶다고 지정했어요. 반환된 자격 증명은 주체가 사용자 타입임이 알려져 있음을 반영하는 더 좁은 TypeScript 타입을 가지게 돼요. 쿠키 기반 접근을 다루는 플러그인을 특별히 만들었다면(드문 경우) 이 두 번째 인자는 allowLimitedAccess: true를 지정할 수도 있어요.
기본적으로 서비스 및 사용자 자격 증명 모두(제한된 접근 제외)를 받아들이지만, 위 예시에서 서비스 자격 증명으로 이 엔드포인트를 호출하려 하면 Unauthorized 오류가 발생해요.
참고
들어오는 자격 증명이 처음부터 유효한지 확인하기 위해 httpAuth.credentials를 호출할 필요는 없어요. 실제로 자격 증명으로 무언가를 수행해야 할 때만 이 메서드를 사용하세요. Backstage 백엔드 프레임워크는 백엔드 코드에 도달하기 전에 들어오는 토큰의 실제 유효성을 보장했을 거예요. 이러한 선행 프레임워크 수준 규칙의 정책은 라우트를 등록할 때 httpRouter 서비스를 사용해 제어돼요.
자격 증명 객체를 더 다루고 싶다면 auth 서비스에 그 도우미 메서드가 있어요.
쿠키 발급
드문 사용 사례로, 플러그인이 제한된 접근 사용자 자격 증명으로 쿠키를 발급하고 싶어할 수 있어요. 이는 주로 브라우저가 TechDocs 플러그인처럼 정적 리소스를 요청할 수 있어야 할 때 관련돼요.
플러그인은 거의 항상 httpAuth 서비스의 쿠키 기능을 직접 다뤄서는 안 돼요. 프레임워크는 전용 well-known 엔드포인트에서 쿠키 생성/삭제 요청 처리를 내장하고 있어요. 일반적으로 제한된 사용자 접근을 받아들이기 위해 해야 하는 일은 라우트를 만들 때 httpRouter 서비스에 특정 라우트에 대해 쿠키 기반 접근을 허용하고 싶다고 알리고, 자격 증명 추출 시 allowLimitedAccess를 true로 설정하는 것뿐이에요.
위 이유로 여기서 httpAuth.issueUserCookie 메서드는 문서화하지 않아요.
서비스 구성
참고
httpAuth 서비스는 사설 저장소에서 구현을 완전히 교체하는 데 적합하지 않아요. 추가 서비스 인증 관련 기능이 필요하다면 주저하지 말고 이슈를 등록하거나 오픈 소스 기능에 기여하세요.
사용자 지정 토큰 추출 로직
어떤 경우에는 들어오는 요청에서 토큰이 추출되는 방식을 사용자 지정하고 싶을 수 있어요. 요청의 다른 위치에서 토큰을 추출하고 싶을지도 몰라요. 이를 지원하기 위해 약간 수정된 httpAuth 서비스를 직접 제공할 수 있어요. DefaultHttpAuthService 클래스는 @backstage/backend-defaults/httpAuth에서 내보내지며, 그 정적 create 메서드를 사용해 사용자 지정 getTokenFromRequest 추출 함수를 전달할 수 있어요.
import { DefaultHttpAuthService } from '@backstage/backend-defaults/httpAuth';import { coreServices, createServiceFactory,} from '@backstage/backend-plugin-api';export const customizedAuthServiceFactory = createServiceFactory({ service: coreServices.httpAuth, deps: { auth: coreServices.auth, discovery: coreServices.discovery, plugin: coreServices.pluginMetadata, }, async factory({ auth, discovery, plugin }) { return DefaultHttpAuthService.create({ auth, discovery, pluginId: plugin.getId(), getTokenFromRequest: req => { let token: string | undefined; const header = req.headers.some_random_header; if (typeof header === 'string') { const parts = header.split(' '); if (parts.length === 2 && parts[0] === 'Bearer') { token = parts[1]; } } return { token }; }, }); },});
이 서비스에는 구성 옵션이 없지만, 라우트에 대해 httpRouter 서비스를 사용해 설정한 정책(있다면)을 따르며, 그 정책을 준수해요.