Role Template vs Role Collection 차이 #shorts #SAP #BTP

📖 이 글에서 정리하는 것

BTP 콕핏을 열 때마다 Role, Role Collection, Role Template이 뒤섞여 보인다면, 이 글 하나로 권한 구조를 한번에 정리할 수 있습니다. 가상의 물류 기업 "한빛로지스"가 서브계정 권한을 세팅하는 과정을 따라가며, 콕핏 클릭이 아닌 구조 이해를 목표로 합니다.

• Role Template → Role → Role Collection → 사용자로 이어지는 4단계 체인을 그림 없이도 설명할 수 있다
• Global Account / Directory / Subaccount 각 레벨에서 어떤 권한이 관리되는지 구분할 수 있다
• Trust Configuration(SAP ID Service vs Custom IdP)의 차이와 그룹 매핑을 이해한다
• btp CLI와 cf CLI로 권한 할당을 자동화할 수 있다

📚 시작 전에 갖추면 좋은 배경

BTP 트라이얼 또는 엔터프라이즈 계정에 로그인해 본 경험, 그리고 콕핏에서 서브계정 화면을 한 번이라도 열어본 정도면 충분합니다. Cloud Foundry에 앱을 배포해 봤다면 3단계 예제가 더 와닿겠지만 필수는 아닙니다. 터미널에서 CLI 명령을 실행해 본 경험이 있으면 좋습니다.

🔧 환경과 준비물

이 글의 예시는 2026년 기준 SAP BTP 멀티 환경 서브계정(Cloud Foundry 런타임 포함)을 전제로 합니다. 트라이얼 계정에서도 대부분 따라 할 수 있으며, Directory 기능과 Custom IdP 연동은 일반적으로 엔터프라이즈(유료) 글로벌 계정에서 온전히 활용됩니다.

• SAP BTP 콕핏 — Subaccount의 Security 메뉴 접근 권한 필요
• btp CLI 2.x — btp login으로 글로벌 계정 접속 확인
• cf CLI v8 — Cloud Foundry org/space 권한 실습용
• 실습 계정에는 Subaccount Administrator 롤 컬렉션이 할당되어 있어야 합니다

시나리오 조직은 다음과 같이 창작했습니다. 물류 스타트업 한빛로지스는 글로벌 계정 아래 hanbit-dev, hanbit-qa, hanbit-prod 세 서브계정을 운영하고, 운임 정산 앱 cargo-billing을 배포합니다.

💡 권한 구조, 출입증 비유로 한번에

BTP 권한이 헷갈리는 이유는 이름이 비슷한 개념 세 가지가 층층이 쌓여 있기 때문입니다. 회사 건물 출입증에 비유하면 명확해집니다.

• Role Template(역할 템플릿) = 출입증 양식. 앱 개발자가 "이 앱에는 조회자, 관리자라는 권한 등급이 존재한다"라고 선언한 설계도입니다. 앱(정확히는 XSUAA 앱 인스턴스)을 서브계정에 배포하면 함께 등록됩니다.
• Role(역할) = 양식으로 실제 발급한 출입증. 템플릿에 속성 값(attribute)을 채워 서브계정에 만들어진 구체적 인스턴스입니다. 템플릿에 속성이 없으면 배포 시 동일 이름의 Role이 자동 생성되는 경우가 일반적입니다.
• Role Collection(역할 컬렉션) = 출입증 여러 장을 담은 목걸이 카드홀더. 사용자에게는 개별 Role이 아니라 항상 Role Collection 단위로만 권한이 부여됩니다. 이것이 가장 중요한 규칙입니다.

즉 체인은 다음 한 줄입니다.

Role Template(앱이 선언) → Role(서브계정에 생성) → Role Collection(롤을 묶음) → 사용자 또는 IdP 그룹(컬렉션 할당)

레벨 관점도 정리해 봅니다. Global Account에서는 글로벌 계정 관리자 권한과 Directory 구성을, Directory에서는 하위 서브계정 묶음에 대한 관리 권한(권한 부여 기능을 켠 Directory에 한함)을, Subaccount에서는 실제 비즈니스 앱의 Role Collection과 Trust Configuration을 관리합니다. 권한이 자동으로 아래로 "상속"된다기보다, Directory 관리자 권한이 하위 서브계정 관리 작업을 허용하는 방식에 가깝습니다. 앱 권한(Role Collection)은 어디까지나 각 서브계정 안에서만 유효합니다. dev에서 만든 컬렉션이 prod에 자동으로 생기지 않는 이유가 바로 이것입니다.

마지막 조각은 Trust Configuration입니다. 서브계정은 "누가 사용자인지"를 신뢰할 IdP를 정합니다. 기본값은 SAP ID Service(개인 SAP 계정 기반)이고, 실무에서는 SAP Cloud Identity Services(IAS) 같은 Custom IdP를 연결해 회사 계정으로 로그인시키는 방식이 널리 권장됩니다. Custom IdP를 쓰면 사용자 개개인이 아니라 IdP 그룹에 Role Collection을 매핑할 수 있어 운영 부담이 크게 줄어듭니다.

💻 실전 예제: 한빛로지스 권한 세팅 3단계

1단계 — 기본: Role Collection 만들고 사용자에게 할당하기

cargo-billing 앱의 보안 설정(xs-security.json)에서 Role Template 두 개를 선언했다고 합시다. 이 파일이 배포되면 서브계정에 템플릿과 롤이 등록됩니다.

{
  "xsappname": "cargo-billing",
  "tenant-mode": "dedicated",
  "scopes": [
    { "name": "$XSAPPNAME.InvoiceRead",  "description": "정산 조회" },
    { "name": "$XSAPPNAME.InvoiceWrite", "description": "정산 승인/수정" }
  ],
  "role-templates": [
    { "name": "BillingViewer",  "scope-references": ["$XSAPPNAME.InvoiceRead"] },
    { "name": "BillingManager", "scope-references": ["$XSAPPNAME.InvoiceRead", "$XSAPPNAME.InvoiceWrite"] }
  ]
}

이제 btp CLI로 hanbit-dev 서브계정에 컬렉션을 만들고 롤을 담은 뒤 사용자에게 할당합니다.

# 서브계정 타겟 지정
btp target --subaccount <hanbit-dev-서브계정-ID>

# 롤 컬렉션 생성
btp create security/role-collection "HB_Billing_Read" \
  --description "운임 정산 조회 전용"

# 컬렉션에 롤 추가 (of-app 값은 btp list security/app 으로 확인)
btp add security/role --to-role-collection "HB_Billing_Read" \
  --name-of-role "BillingViewer" \
  --role-template "BillingViewer" \
  --of-app "cargo-billing!t2001"

# 사용자에게 컬렉션 할당
btp assign security/role-collection "HB_Billing_Read" \
  --to-user minsu.park@hanbitlogis.example \
  --create-user-if-missing

사용자가 다시 로그인하면 토큰에 InvoiceRead 스코프가 포함되고, 앱은 이 스코프로 접근을 판단합니다.

2단계 — 실무: Custom IdP 그룹 매핑과 점검 루틴

사용자가 30명만 되어도 개별 할당은 관리 재앙이 됩니다. 한빛로지스는 IAS 테넌트를 Custom IdP로 연결하고, 재무팀 그룹 HB-FIN-TEAM을 컬렉션에 매핑합니다. 콕핏에서는 Security → Trust Configuration에서 IdP를 확인하고, Role Collection 상세 화면의 그룹 매핑으로도 설정할 수 있지만 CLI가 재현성이 좋습니다.

# 신뢰 구성 확인: origin key(예: hanbitias-platform)를 여기서 확인
btp list security/trust

# IdP 그룹 -> 롤 컬렉션 매핑
btp assign security/role-collection "HB_Billing_Read" \
  --to-group "HB-FIN-TEAM" \
  --of-idp "hanbitias-platform"

이후 재무팀 입퇴사자는 IAS 그룹에서만 관리하면 BTP 권한이 따라옵니다. 실무에서는 설정 후 반드시 검증 루틴을 돌리는 것이 좋습니다.

# 특정 사용자의 실제 할당 상태 조회 (원인 추적의 시작점)
btp list security/user --of-idp "hanbitias-platform"
btp get security/user minsu.park@hanbitlogis.example --of-idp "hanbitias-platform"

자주 발생하는 에러도 짚어 둡니다. 그룹 매핑 후에도 권한이 없다고 나오면 대부분 (1) 사용자가 SAP ID Service 로그인 화면으로 잘못 들어갔거나(origin 불일치), (2) IdP 어서션에 그룹 속성이 Groups라는 이름으로 전달되지 않는 경우입니다. IAS 쪽 어서션 속성 구성에서 그룹 클레임 이름을 확인하세요.

3단계 — 프로덕션: 최소 권한, 환경 분리, CF 권한까지

hanbit-prod에서는 보안 원칙이 달라집니다. 첫째, 최소 권한: prod에는 HB_Billing_Admin 같은 쓰기 권한 컬렉션을 소수 인원 그룹에만 매핑합니다. 둘째, 플랫폼 권한과 비즈니스 권한 분리: 개발자가 앱을 배포하려면 BTP Role Collection이 아니라 Cloud Foundry의 org/space 롤이 필요합니다. 이 둘은 완전히 별개의 권한 체계입니다.

# CF 배포 권한: BTP 롤 컬렉션과 무관하게 별도로 부여해야 함
cf api https://api.cf.ap12.hana.ondemand.com
cf login --sso

cf set-org-role   jiyoon.seo@hanbitlogis.example HANBIT-PROD OrgAuditor
cf set-space-role jiyoon.seo@hanbitlogis.example HANBIT-PROD billing SpaceDeveloper

셋째, 구성의 코드화: prod의 컬렉션 생성·매핑을 사람이 콕핏에서 클릭하지 않고 스크립트로 관리하면 dev/qa/prod 간 불일치를 막을 수 있습니다.

# 환경별 반복 실행 가능한 세팅 스크립트의 핵심부 (idempotent 하게 작성)
for SA in $HB_QA_ID $HB_PROD_ID; do
  btp target --subaccount $SA
  btp create security/role-collection "HB_Billing_Admin" \
    --description "정산 승인 권한 (제한 그룹 전용)" || true
  btp assign security/role-collection "HB_Billing_Admin" \
    --to-group "HB-FIN-LEAD" --of-idp "hanbitias-platform"
done

넷째, 정기 감사: 분기마다 btp list security/role-collection 결과와 그룹 매핑을 덤프해 저장소에 커밋해 두면 권한 변경 이력을 추적할 수 있습니다. prod 서브계정의 Subaccount Administrator는 2~3명 이내로 유지하는 것이 일반적으로 권장됩니다.

⚠️ 헷갈리는 포인트 정리와 FAQ

• Q1. Role Template과 Role Collection, 뭐가 다른가요? 방향이 다릅니다. Template은 앱 개발자가 코드(xs-security.json)로 선언하는 것이고, Collection은 서브계정 관리자가 운영 관점에서 롤을 묶는 것입니다. Template은 배포 산출물, Collection은 운영 설정이라고 기억하면 다시 헷갈리지 않습니다.
• Q2. 역할은 어느 레벨에서 만들어야 하나요? 앱 권한(Role/Role Collection)은 반드시 해당 앱이 배포된 서브계정에서 만듭니다. Global Account 레벨의 컬렉션은 글로벌 계정 관리 권한용이고, Directory는 하위 서브계정 관리 위임용입니다. dev에서 잘 되던 권한이 prod에서 없다면, prod 서브계정에 컬렉션을 다시 만들지 않았을 가능성이 가장 큽니다.
• Q3. Role Collection을 할당했는데 CF에 배포가 안 됩니다. 정상입니다. CF org/space 롤(OrgManager, SpaceDeveloper 등)은 BTP Role Collection과 별도 체계입니다. cf set-space-role로 따로 부여해야 합니다. 반대로 SpaceDeveloper라고 해서 앱 화면의 데이터가 보이는 것도 아닙니다.
• Q4. 권한을 줬는데도 403이 계속 납니다. 토큰은 로그인 시점에 발급됩니다. 로그아웃 후 재로그인(또는 토큰 만료 대기)해야 새 스코프가 반영됩니다. 그래도 안 되면 사용자의 origin(SAP ID Service vs Custom IdP)이 컬렉션을 할당한 IdP와 일치하는지 확인하세요. 같은 이메일이라도 origin이 다르면 다른 사용자로 취급됩니다.

🚀 이어서 보면 좋은 주제

권한 구조가 잡혔다면 다음 순서로 확장하는 것을 권합니다. (1) SAP Cloud Identity Services의 인증 정책과 MFA 적용, (2) XSUAA 속성(attribute) 기반 인스턴스 권한으로 데이터 수준 제어 구현, (3) Terraform Provider for SAP BTP로 서브계정·컬렉션·매핑 전체를 IaC로 관리, (4) CAP/RAP 앱에서 스코프를 서비스 코드와 연결하는 방법. 특히 Terraform 방식은 3단계 스크립트를 한 단계 발전시킨 형태로, 환경 복제와 감사에 강력합니다.

🗂 정리하며

결국 BTP 권한 관리에서 사고가 나는 지점은 대부분 두 곳입니다. 하나는 Role Collection을 서브계정마다 다시 만들어야 한다는 사실을 잊는 것, 다른 하나는 BTP 권한과 Cloud Foundry org/space 권한을 같은 것으로 착각하는 것입니다. 한빛로지스 예제처럼 Role Template은 코드로, Role Collection과 그룹 매핑은 서브계정별로 명시적으로 관리한다는 원칙만 지키면 콕핏 화면을 아무리 옮겨 다녀도 헷갈릴 일이 없습니다.