ツイートシェアはてブ LINE Pocket

Keycloak 認証モジュール

Keycloak 認証モジュールは、ユーザーが Keycloak 資格情報を使用して YouTrack にログインできるようにする事前構成された OAuth2.0 認証モジュールです。

Keycloak 認証を有効にする

既存の Keycloak アカウントを持つユーザーが YouTrack にログインできるようにするには、認証モジュールを有効にします。

この手順は 3 つのステップで行われます。

Keycloak 認証モジュールを作成します。認証モジュールを作成すると、YouTrack は認証サービスで使用するためのリダイレクト URI を生成します。この URI は各ログイン要求の送信元を識別します。
Keycloak でクライアント ID とシークレットを生成します。YouTrack から送信されるすべてのログイン要求には、一意の識別子が含まれています。認証モジュールに保存する ID とシークレットは、各ログイン要求が承認されていることを Keycloak 承認サービスに通知します。
YouTrack で認証モジュールを有効にします。YouTrack が Keycloak 認証サービスでの認証に使用する情報を生成したら、値を YouTrack にコピーして、モジュールを有効にします。

YouTrack で Keycloak 認証モジュールを作成する

まず、Keycloak 認証モジュールを作成します。このアクションを実行すると、YouTrack は承認サービスで使用するリダイレクト URI を生成します。

YouTrack でリダイレクト URI を生成するには:

管理メニューのアクセス管理セクションで、Auth モジュールを選択します。
新規モジュールドロップダウンリストから Keycloak を選択します。
- 新しい Keycloak 認証モジュールダイアログが開きます。

新しい Keycloak 認証モジュールダイアログで、以下の設定に値を入力します。

設定	説明
Keycloak ルート URL	Keycloak サーバーのルート URL を入力します。
Keycloak レルム	YouTrack へのアクセスを許可するユーザーアカウントを管理する Keycloak レルムの名前を入力します。

作成ボタンをクリックしてください。
- Auth モジュールページには、新しい Keycloak 認証モジュールの設定が表示されます。
- YouTrack は、承認サービスで使用するためのリダイレクト URI を生成します。

クライアント ID とシークレットを生成する

次のステップは、Keycloak からクライアント ID とシークレットを取得することです。

管理者アカウントで管理コンソールにログインします。
リストからレルムを選択します。
構成メニューからクライアントを選択します。
作成ボタンをクリックしてください。
- クライアントを追加ダイアログが開きます。
以下の設定に値を入力します。
- クライアント ID の場合、クライアントアプリケーションの識別に役立つ値を入力します。
- クライアントプロトコルの場合は、openid-connect を選択します。
- ルート URL の場合、YouTrack インストールのベース URL を入力します。
保存ボタンをクリックしてください。
- 新しいクライアントアプリケーションの設定を保存するページが開きます。
クライアントアプリの設定タブで、アクセスタイプを機密に変更します。
保存ボタンをクリックしてください。
クライアント ID として保存されている値を使用して、HUb で認証モジュールを有効にします。
資格情報タブを選択し、シークレットとして保存されている値を使用して、YouTrack で認証モジュールを有効にします。

詳細については、Keycloak(英語) のドキュメントを参照してください。

YouTrack で認証モジュールを有効にする

セットアップを完了するには、認証サービスからのクライアント ID とシークレットを Keycloak 認証モジュールに保存します。

Keycloak の設定タブからクライアント ID をコピーし、YouTrack のクライアント ID 入力フィールドに貼り付けます。
Keycloak の資格情報タブからシークレットをコピーし、YouTrack のクライアントシークレット入力フィールドに貼り付けます。
認証モジュールのオプション設定を構成します。詳しくは、追加設定を参照してください。
保存ボタンをクリックして設定を適用します。
モジュールを有効にするボタンをクリックしてください。
- Keycloak 認証モジュールが有効になっています。
- ボタンイメージ設定で保存されているアイコンがログインダイアログウィンドウに追加されます。ユーザーはこのアイコンをクリックして、Keycloak のクレデンシャルを使用して YouTrack にログインできます。

設定

設定ページの最初のセクションには、認証モジュールの一般設定が表示されます。ここには、YouTrack を許可サービスに登録するために使用するリダイレクト URI、および許可サービスで生成されたクライアント ID とクライアントシークレットを保管する入力フィールドもあります。

設定	説明
タイプ	YouTrack のサードパーティー認証が有効になっている認証サービスの種類を表示します。
名前	認証モジュールの名前を格納します。この設定を使用して、このモジュールを Auth モジュールリスト内の他の認証モジュールと区別します。
ボタンイメージ	接続されている認証サービスで、自分のアカウントで YouTrack にログインするためにユーザーがクリックするボタンに使用されるイメージを表示します。JPG、GIF、PNG ファイルをアップロードできます。イメージは自動的に 48 x 48 ピクセルにサイズ変更されます。
リダイレクト URI	認証サービスで YouTrack への接続を登録するために使用される認証済みリダイレクト URI を表示します。
クライアント ID	認可サービスがログイン要求を検証するために使用する識別子を格納します。Web アプリケーションの認証設定を構成して認証済みリダイレクト URI を入力すると、認証サービスでこの値が生成されます。
クライアントシークレット	クライアント ID を検証するために使用されるシークレットまたはパスワードを保管します。この値は、認証サービスでクライアント ID と一緒に生成します。
拡張グラント	拡張許可に使用されるときに認証モジュールを識別するために使用される値を保存します。値が指定されている場合、YouTrack は、承認サービスによって発行されたアクセストークンを、YouTrack へのアクセスを許可するトークンと交換する要求を処理します。アクセストークンを正常に交換するには、認証モジュールがサードパーティの認証サービスで承認され、YouTrack で有効になっている必要があります。 YouTrack REST API を使用してアクセストークンを交換する方法については、拡張グラントを参照してください。

認可サービスのエンドポイント

ページのこのセクションの設定には、Keycloak で使用される OAuth2.0 エンドポイントが格納されています。

事前設定された OAuth 2.0 モジュールの場合、選択された許可サービスによって使用される値は自動的に設定されます。

設定	説明
許可	YouTrack がユーザーエージェントリダイレクトを介してリソース所有者から承認を得るために使用するエンドポイントを格納します。
トークン	YouTrack がアクセス権と認可付与を交換するために使用するエンドポイントを格納します。
ユーザーデータ	認証されたユーザーのプロファイルデータを見つけるために使用されるエンドポイントを格納します。
メール	認証されたユーザーのメールアドレスを見つけるために使用されるエンドポイント。メールアドレスがユーザープロファイルに保存されていない場合にのみ使用してください。
アバター	認証されたユーザーのアバターとして使用されるバイナリファイルを見つけるために使用されるエンドポイント。アバターがユーザープロファイルに直接保存されていない場合にのみ使用してください。

フィールドマッピング

Keycloak によってユーザープロファイル応答オブジェクトが返されると、指定されたフィールドパスの値が YouTrack のユーザープロファイルにコピーされます。次の設定を使用して、認証されたユーザーのプロファイルデータを検索するエンドポイントを定義し、承認サービスに格納されているフィールドを YouTrack のユーザーアカウントにマップします。

事前定義された Keycloak モジュールの場合、ユーザー ID、メール、メール確認状態、フルネーム、グループが自動的に設定されます。ニーズに合わせてこれらの値を変更する必要がある場合は、上書きできます。

ネストされたオブジェクト内のフィールドへのパスを指定するには、スラッシュ文字（/）で区切られた一連のセグメントを入力します。
複数の場所に格納されている値を参照するには、「エルビス演算子」(?:) を複数のパスの区切り文字として使用します。このオプションを使用すると、YouTrack は、指定されたフィールドで最初に検出した空でない値を使用します。

フィールド	説明
ユーザー ID	YouTrack アカウントのユーザー ID プロパティにコピーする値を格納するフィールドにマップします。
ユーザー名	YouTrack アカウントのユーザー名フィールドにコピーする値を格納するフィールドにマップします。このオプションは、YouTrack バージョン 2023.1.65369 以降で使用できます。
フルネーム	YouTrack アカウントのフルネームフィールドにコピーする値を格納するフィールドにマップします。
メール	YouTrack アカウントのメールフィールドにコピーする値を格納するフィールドにマップします。
メール確認状態	YouTrack アカウントの確認済みメールプロパティにコピーする値を格納するフィールドにマップします。
アバター	YouTrack アカウントでアバターとして使用するイメージを格納するフィールドにマップします。
イメージの URL パターン	ID によって参照されるアバターのイメージ URL を生成します。使用 <picture-id> アバターを格納するフィールドを参照するためのプレースホルダー。
グループ	接続された承認サービスでグループメンバーシップの割り当てを格納する属性にマップします。この値を指定すると、許可サービスのグループメンバーシップを YouTrack の対応するグループとマップおよび同期できます。詳細については、グループマッピングを参照してください。

追加設定

次のオプションは、ページの下部にあります。これらの設定により、リクエストスコープを定義し、サービスでの認証方法を選択できます。

事前定義された Keycloak モジュールの場合、スコープは自動的に設定されます。ニーズに合わせてこの値を変更する必要がある場合は、上書きできます。

このセクションの他のオプションを使用すると、YouTrack アカウントの作成とグループメンバーシップを管理し、アイドル状態の接続によって消費される処理リソースの損失を減らすことができます。

オプション	説明
スコープ	アクセス要求の範囲を設定します。スコープのリストをスペースで区切って入力します。
認証	資格情報を許可サービスに渡す方法を決定します。
ユーザー作成	接続された許可サービスに保管されているアカウントでログインしている未登録ユーザー用の YouTrack アカウントの作成を可能にします。YouTrack はユーザーに既存のアカウントがあるかどうかを判断するためにメールアドレスを使用します。
メールの自動確認	認証サービスがこの属性の値を返さない場合に、YouTrack がメールアドレスの検証ステータスを設定する方法を決定します。
自動参加グループ	接続された承認サービスに保存されているアカウントでログインするときに、ユーザーをグループに追加します。1 つまたは複数のグループを選択できます。グループに自動参加する新しいユーザーは、このグループに割り当てられたすべての権限を継承します。少なくとも 1 つのグループにユーザーを追加することをお勧めします。それ以外の場合、新しいユーザーには、現在すべてのユーザーグループに割り当てられているアクセス許可のみが付与されます。
接続タイムアウト	承認サービスへの接続を確立するために待機する期間を設定します。デフォルト設定は 5000 ミリ秒（5 秒）です。
読み取りタイムアウト	承認サービスからユーザープロファイルデータを読み取って取得するのを待機する期間を設定します。デフォルト設定は 5000 ミリ秒（5 秒）です。
監査	YouTrack のイベントの監査ページへのリンク。そこで、この認証モジュールに適用された変更のリストを表示できます。

グループマッピング

グループマッピングタブで、承認サービスの既存のグループを YouTrack のグループにマップできます。

Keycloak のグループを YouTrack のグループにマップする場合は、この認証モジュールの設定のフィールドマッピングセクションに Keycloak グループメンバーシップを格納するグループ属性を指定する必要があります。事前定義された Keycloak モジュールの場合、グループ属性とスコープが自動的に設定されます。

グループマッピングが構成されている場合、YouTrack は、ユーザーがディレクトリサービスで管理されているアカウントでログインするときに、Keycloak グループメンバーシップをチェックします。YouTrack は、YouTrack グループにマップされている Keycloak グループごとに次の操作を実行します。

マップされた Keycloak グループのメンバーであり、マップされた YouTrack グループのメンバーではないユーザーは、YouTrack のグループに追加されます。
マップされた Keycloak グループのメンバーではなく、マップされた YouTrack グループのメンバーであるユーザーは、YouTrack のグループから削除されます。

承認サービスのグループメンバーシップへの変更は、ユーザーが Keycloak アカウントを使用してログインした場合にのみ YouTrack に適用されます。

YouTrack では、複数の Keycloak グループを単一のターゲットグループにマップできます。Keycloak グループを複数の YouTrack グループにマップすることはできません。

Keycloak から YouTrack のグループにグループをマップするには:

Keycloak 認証モジュールを開きます。
グループマッピングタブを選択します。
マッピングの追加ボタンをクリックしてください。
- マッピングの追加ダイアログが開きます。
OAuth グループ名フィールドに Keycloak グループの名前を入力します。
ターゲットグループリストからグループを選択します。
追加ボタンをクリックしてください。
- マッピングがリストに追加されます。

最終更新日: 2024 年 6 月 19 日

YouTrack サーバー 2024.2 ヘルプ