Okta Authorization Server

Halo に必要な claims、roles、および access policies を備えたカスタム Okta authorization server を設定します。これは、Halo Portal SSO と Halo API Bearer Authentication の両方の前提条件です。

前提条件​

• 管理者アクセス権を持つ Okta organization
• Halo デプロイメントから Okta へのネットワークアクセス

authorization server を作成する​

1. 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"
     

注: audience api://halo はすべての Halo クライアントで共有されます。Portal SSO と API Bearer 認証の両方が、この audience に対してトークンを検証します。これにより、1 つの authorization server で両方のユースケースに対応できます。

Halo API アクセス用のカスタム scope を追加する​

2. 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 をチェックします

注: OIDC scope（例: openid、profile、email）はユーザーコンテキスト専用であり、Client Credentials flow では使用できません。マシン間の API アクセスにはカスタム scope が必要です。

claims を設定する​

3. Halo サービスで必要な claims を設定します。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

ロールを定義する​

注: Halo は 2 つの別個のロールクレームを使用します:

• roles: UI アクセスを制御するために Portal（Portal-Access 経由）で使用されます
• role: エンドポイント認可のために API-Access サービスで使用されます

ロールクレームが設定されていない場合、Portal はデフォルトで読み取り専用ロールになり、API はデフォルトで User ロールになります。各ロールでアクセスできる内容の詳細については、Portal Roles to Action Mapping および API Roles to Action Mapping を参照してください。

4. Halo は 2 つのロール値を認識します: User と Admin（大文字と小文字を区別しません）。Okta には、Authorization servers でロールを定義するネイティブな方法がありません。アクセストークンでユーザー/クライアントのロールを渡すには、ロールクレームを追加する必要があります。

Portal SSO ロール（roles クレーム）​

このクレームは、ユーザーが利用できるページと機能を Portal が判断するために使用されます。Okta 組織内の他のアプリケーションと競合する可能性がある一般的な User または Admin グループではなく、Halo 固有のグループ名を使用することを推奨します。

1. Okta でグループを作成します。Directory -> Groups に移動し、次を作成します:

   • Halo_User
   • Halo_Admin

2. ユーザーを適切なグループに割り当てます。

3. 認可サーバーのClaimsタブに移動し、グループ名をHaloのロール値に変換するrolesクレームを作成します。

   • 名前: roles
   • トークンタイプに含める: Access Token
   • 値のタイプ: Expression
   • Value:

     isMemberOfGroupName("Halo_Admin") ? "Admin" : isMemberOfGroupName("Halo_User") ? "User" : ""
     

   • 含める対象: Any scope

   

注: isMemberOfGroupName() 関数は、ユーザーコンテキストのあるフロー（例: Authorization Code）でのみ機能します。Client Credentials（machine-to-machine）フローには適用されません。

APIロール（role クレーム）​

このクレームは、API-Accessサービスが操作を認可するために使用されます。APIクライアントはClient Credentialsフロー（ユーザーコンテキストなし）を使用するため、グループメンバーシップ式は適用されません。代わりに、client_id をロール値にマッピングします。

4. 認可サーバーの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 トークン認証を設定します

各ガイドには、それぞれのクライアント向けにこの認可サーバー上でアクセス policy を設定する手順が含まれています。