Okta Authorization Server

Halo에 필요한 클레임, 역할 및 액세스 policy를 포함하는 사용자 지정 Okta authorization server를 설정합니다. 이는 Halo Portal SSO와 Halo API Bearer Authentication 모두의 사전 요구 사항입니다.

필수 조건

관리자 액세스 권한이 있는 Okta 조직
Halo 배포 환경에서 Okta로의 네트워크 액세스

authorization server 생성

Navigate to Security -> API and create a new Authorization server.
- 적절한 이름을 지정합니다. 예: Glasswall Halo
- 모든 Halo 클라이언트(Portal 및 API)에서 공유할 공통 audience 값을 입력합니다. 예: api://halo
- 적절한 설명을 입력합니다. 예: Glasswall Halo Authorization server
- 저장한 후 Issuer Metadata URI를 기록해 둡니다. URI 끝에서 /.well-known/oauth-authorization-server를 제거합니다. 예:
```
export ORIGINAL_ISSUER_URI=https://your-org.okta.com/oauth2/aus1234567890abcdef/.well-known/oauth-authorization-server
export OKTA_ISSUER_URI=https://your-org.okta.com/oauth2/aus1234567890abcdef
export VALID_AUDIENCE="api://halo"
```

Screenshot: Create new authorization server Screenshot: Authorization server details with issuer URI

참고: audience api://halo는 모든 Halo 클라이언트에서 공유됩니다. Portal SSO와 API Bearer 인증 모두 이 audience를 기준으로 토큰을 검증합니다. 이를 통해 단일 authorization server가 두 사용 사례를 모두 지원할 수 있습니다.

Halo API 액세스를 위한 사용자 지정 scope 추가

Navigate to the Scopes tab on the authorization server and add a new scope:
- 이름: halo.api
- 표시 문구: Halo API
- 설명: Access to Halo API
- Set as a default scope를 선택합니다

Screenshot: Custom scope configuration

참고: OIDC scope(예: openid, profile, email)는 사용자 컨텍스트 전용이므로 Client Credentials flow와 함께 사용할 수 없습니다. 머신 간 API 액세스에는 사용자 지정 scope가 필요합니다.

claim 설정

Halo 서비스에 필요한 claim을 구성합니다. authorization server의 Claims 탭으로 이동합니다.
- Full name:
  - 이름: name
  - 토큰 유형에 포함: Access Token
  - 값 유형: Expression
  - 값: user.firstName + " " + user.lastName
  - 포함 대상: Any scope
- Family name:
  - 이름: family_name
  - 토큰 유형에 포함: Access Token
  - 값 유형: Expression
  - 값: user.lastName
  - 포함 대상: Any scope
- Given name:
  - 이름: given_name
  - 토큰 유형에 포함: Access Token
  - 값 유형: Expression
  - 값: user.firstName
  - 포함 대상: Any scope
- Email ID:
  - 이름: unique_name
  - 토큰 유형에 포함: Access Token
  - 값 유형: Expression
  - 값: user.email
  - 포함 대상: Any scope

Screenshot: Claims configuration

역할 정의

참고: Halo는 두 개의 별도 역할 클레임을 사용합니다:

roles: UI 액세스를 제어하기 위해 Portal(Portal-Access를 통해)에서 사용

role: 엔드포인트 권한 부여를 위해 API-Access 서비스에서 사용

역할 클레임이 구성되지 않은 경우 Portal은 기본적으로 읽기 전용 역할을 사용하고 API는 기본적으로 User 역할을 사용합니다. 각 역할이 액세스할 수 있는 항목에 대한 자세한 내용은 Portal 역할-작업 매핑 및 API 역할-작업 매핑을 참조하세요.

Halo는 두 가지 역할 값을 인식합니다: User 및 Admin(대소문자 구분 없음). Okta에는 Authorization servers에서 역할을 정의하는 기본 방법이 없습니다. 액세스 토큰에서 사용자/클라이언트 역할을 전달하려면 역할 클레임을 추가해야 합니다.

Portal SSO 역할(`roles` 클레임)

이 클레임은 사용자에게 어떤 페이지와 기능을 사용할 수 있는지 Portal이 결정하는 데 사용됩니다. Okta 조직의 다른 애플리케이션과 충돌할 수 있는 일반적인 User 또는 Admin 그룹 대신 Halo 전용 그룹 이름을 사용하는 것을 권장합니다.

Okta에서 그룹을 생성합니다. Directory -> Groups로 이동하여 다음을 생성합니다:
- Halo_User
- Halo_Admin
사용자를 적절한 그룹에 할당합니다.
권한 부여 서버의 Claims 탭으로 이동하여 그룹 이름을 Halo 역할 값으로 변환하는 roles 클레임을 생성합니다:
- 이름: roles
- 토큰 유형에 포함: Access Token
- 값 유형: Expression
- Value:
```
isMemberOfGroupName("Halo_Admin") ? "Admin" : isMemberOfGroupName("Halo_User") ? "User" : ""
```
- 포함 대상: Any scope

참고: isMemberOfGroupName() 함수는 사용자 컨텍스트 플로우(예: Authorization Code)에서만 작동합니다. Client Credentials(머신 투 머신) 플로우에는 적용되지 않습니다.

API 역할(`role` 클레임)

이 클레임은 API-Access 서비스가 작업을 승인하는 데 사용됩니다. API 클라이언트는 Client Credentials 플로우(사용자 컨텍스트 없음)를 사용하므로 그룹 멤버십 표현식은 적용되지 않습니다. 대신 client_id를 역할 값에 매핑합니다.

권한 부여 서버의 Claims 탭으로 이동하여 role 클레임을 생성합니다:
- 이름: role
- 토큰 유형에 포함: Access Token
- 값 유형: Expression
- Value:
```
(app.clientId == "<your-api-client-id>") ? "Admin" : "User"
```
- 포함 대상: Any scope

참고: <your-api-client-id>를 API Services 애플리케이션의 client_id로 바꾸십시오. 여러 API 클라이언트에 대해서는 추가 조건을 추가합니다. 예:
(app.clientId == "<client-1>") ? "Admin" : (app.clientId == "<client-2>") ? "Admin" : "User"

다음 단계

권한 부여 서버 구성이 완료되면 다음 중 하나 또는 둘 다의 설정을 진행합니다:

Halo Portal SSO - Halo Portal의 ID 공급자로 Okta를 구성합니다
Halo API Bearer Authentication - Halo API에 대한 Bearer 토큰 인증을 구성합니다

각 가이드에는 해당 클라이언트에 대해 이 authorization server에서 액세스 policy를 구성하는 내용이 포함되어 있습니다.

필수 조건​

authorization server 생성​

Halo API 액세스를 위한 사용자 지정 scope 추가​

claim 설정​

역할 정의​

Portal SSO 역할(roles 클레임)​

API 역할(role 클레임)​

다음 단계​