OIDC と AD FS による認証

このページでは、Active Directory フェデレーション サービス(AD FS)で OpenID Connect(OIDC)を使用して、GKE On-Prem ユーザー クラスタの認証を構成する方法を説明します。AD FS はバージョン 2016 以降の OIDC のみをサポートしています。

認証フローの概要については、認証をご覧ください。AD FS 以外の OpenID プロバイダの使用方法については、OpenID Connect による認証をご覧ください。

概要

GKE On-Prem は、ユーザー クラスタの Kubernetes API サーバーとやり取りする認証メカニズムの 1 つとして OpenID Connect(OIDC)をサポートしています。OIDC を使用すると、組織内の標準的な手順に従って Kubernetes クラスタへのアクセスを管理して、従業員のアカウントの作成、有効化、無効化を行うことが可能です。

従業員が OIDC 認証フローを使用するには、次の 2 つの方法があります。

  • 従業員は、kubectl を使用して、OIDC フローを開始できます。このフローを自動化するためには、GKE On-Prem で、kubectl プラグインである Kubectl 用の Anthos プラグインを指定します。
  • 従業員は、Google Cloud Console を使用して、OIDC 認証フローを開始できます。

この演習では、kubectl と Google Cloud コンソールの両方のオプションを構成します。一連の AD FS 管理ウィザードを使用して、AD FS サーバーと AD 従業員データベースを構成します。

始める前に

このトピックでは、OAuth 2.0OpenID Connect について理解していることを前提にしています。このトピックでは、OpenID のスコープクレームについて理解していることを前提としています。

このトピックは、次のインフラストラクチャを所有する企業に適用されます。

  • 企業が従業員データベースとして Active Directory(AD)を使用している。
  • 企業が Active Directory フェデレーション サービス(AD FS)サーバーを運用している。
  • AD FS サーバーが OpenID プロバイダとして使用されている。

ペルソナ

このトピックでは、次の 3 つのペルソナについて説明します。

  • 組織管理者: OpenID プロバイダを選択し、クライアント アプリケーションをプロバイダに登録します。

  • クラスタ管理者: 1 つ以上のユーザー クラスタを作成し、クラスタを使用する開発者用の認証構成ファイルを作成します。

  • デベロッパー: 1 つ以上のクラスタでワークロードを実行し、OIDC を使用して認証します。

Kubectl 用 Anthos プラグイン用のリダイレクト URL の作成

このセクションは、組織管理者を対象としています。

AD FS サーバーとの関係を確立する際に、AD FS サーバーが Kubectl 用 Anthos プラグインに ID トークンを返すために使用できるリダイレクト URL を指定する必要があります。Kubectl 用の Anthos プラグインは、各デベロッパーのローカルマシンで実行され、任意のポートでリッスンします。この目的に適した 1024 より大きいポート番号を選択します。リダイレクト URL は次のようになります。

http://localhost:[PORT]/callback

ここで、[PORT] はポート番号です。

AD FS サーバーを構成するときは、リダイレクト URL の 1 つとして http://localhost:[PORT]/callback を指定します。

Google Cloud コンソール用のリダイレクト URL の構成

このセクションは、組織管理者を対象としています。

Kubectl 用 Anthos プラグインのリダイレクト URL のほかに、Google Cloud コンソール用のリダイレクト URL も必要です。Google Cloud コンソールのリダイレクト URL は次のとおりです。

https://console.cloud.google.com/kubernetes/oidc

AD FS サーバーを構成するときは、リダイレクト URL の 1 つとして https://console.cloud.google.com/kubernetes/oidc を指定します。

AD FS の構成

次のセクションでは、GKE On-Prem 用に AD FS を構成する方法について説明します。

リダイレクト URL の設定

このセクションは、組織管理者を対象としています。

  1. AD FS 管理ペインを開きます。

  2. [Application Groups] > [Actions] > [Add an Application Group] の順に選択します。

  3. [Server Application] を選択します。名前と説明を入力します。[Next] をクリックします。

  4. リダイレクト URL を 2 つ入力します。クライアント ID が付与されます。これは、AD FS サーバーが Kubectl 用と Google Cloud コンソール用の Anthos プラグインを識別する方法です。後で使用するために、クライアント ID を保存します。

  5. [Generate a shared secret] を選択します。Kubectl 用と Google Cloud コンソール用の Anthos プラグインは、この Secret を使用して AD FS サーバーに対する認証を行います。後で使用するために Secret を保存します。

セキュリティ グループの構成(省略可)

このセクションは、組織管理者を対象としています。

  1. AD FS Management で、[Relying party trusts] > [Add a new relying party trust] の順に選択します。

  2. [Claims aware] を選択し、[Start] をクリックします。

  3. [Enter data about relying party manually] を選択します。

  4. 表示名を入力します。

  5. 次の 2 つの手順はスキップします。

  6. [Relying party trust identifier] を入力します。例: token-groups-claim

  7. Access control policy には、[Permit everyone] を選択します。これは、全従業員が、Kubectl 用と Google Cloud コンソール用の Anthos プラグインと、セキュリティ グループ情報を共有することを意味します。

  8. [完了] をクリックします。

LDAP 属性のクレーム名へのマッピング

このセクションは、組織管理者を対象としています。

  1. AD FS Management で、[Relying party trusts] > [Edit claim issuance policy] の順に選択します。

  2. [Send LDAP Attributes as Claims] をオンにしてから [Next] をクリックします。

  3. [Claim rule name] に「groups」と入力します。

  4. [Attribute store] で [Active Directory] を選択します。

  5. テーブルの [LDAP Attribute] で、以下を選択します。

    • AD FS バージョン 5.0 以降: Token-Groups Qualified by Domain name
    • バージョン 5.0 より前の AD FS: Token Groups - Qualified Names
  6. [Outgoing Claim Type] には、以下を選択します。

    • AD FS バージョン 5.0 以降: Group
    • バージョン 5.0 より前の AD FS: groups
  7. [Finish] をクリックし、[Apply] をクリックします。

AD FS による Kubectl 用と Google Cloud コンソール用の Anthos プラグインの登録

このセクションは、組織管理者を対象としています。

管理者モードで PowerShell ウィンドウを開き、次のコマンドを入力します。

Grant-AD FSApplicationPermission `
    -ClientRoleIdentifier "[CLIENT_ID]" `
    -ServerRoleIdentifier [SERVER_ROLE_IDENTIFIER] `
    -ScopeName "allatclaims", "openid"

ここで

  • [CLIENT_ID] は、前の手順で取得したクライアント ID です。

  • [SERVER_ROLE_IDENTIFIER] は、前に入力したクレーム ID です。提案された ID は token-groups-claim でした。

GKE On-Prem 構成ファイルに oidc 仕様を入力する

このセクションは、クラスタ管理者を対象としています。

ユーザー クラスタを作成する前に、gkectl create-config を使用して GKE On-Prem 構成ファイルを生成します。構成には次の oidc 仕様が含まれます。プロバイダに固有の値で、oidc を入力します。

oidc:
  issuerurl:
  kubectlredirecturl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: 必須。OpenID プロバイダの URL(例: https://example.com/adfs)。Kubectl 用と Google Cloud コンソール用の Anthos プラグインなどのクライアント アプリケーションは、この URL に認可リクエストを送信します。Kubernetes API サーバーは、この URL を使用してトークン検証用の公開鍵を検出します。HTTPS を使用する必要があります。
  • kubectlredirecturl: 必須。Kubectl 用 Anthos プラグインに構成済みのリダイレクト URL。
  • clientid: 必須。OpenID プロバイダへの認証リクエストを行うクライアント アプリケーションの ID。Kubectl 用と Google Cloud コンソール用の両方の Anthos プラグインが、この ID を使用します。
  • clientsecret: 省略可。クライアント アプリケーション用の Secret。Kubectl 用と Google Cloud コンソール用の両方の Anthos プラグインが、この Secret を使用します。
  • username: 省略可。ユーザー名として使用する JWT クレーム。デフォルトは sub で、これはエンドユーザーの一意の識別子である必要があります。OpenID プロバイダによっては、emailname などの他のクレームを選択できます。ただし、他のプラグインとの競合を避けるため、email 以外のクレームには発行者の URL が先頭に付加されます。
  • usernameprefix: 省略可。既存の名前と競合しないように、ユーザー名のクレームの先頭に付加される接頭辞。このフィールドを指定せず、usernameemail 以外の値の場合、接頭辞はデフォルトの issuerurl# になります。値 - を使用すると、すべての接頭辞を無効にできます。
  • group: 省略可。プロバイダがセキュリティ グループを返すために使用する JWT クレーム。
  • groupprefix: 省略可。既存の名前と競合しないように、グループ クレームの先頭に付加される接頭辞。たとえば、グループ foobar と接頭辞 gid- が指定されている場合、gid-foobar となります。デフォルトでは、この値は空で、接頭辞はありません。
  • scopes: 省略可。OpenID プロバイダにカンマ区切りのリストとして送信する追加のスコープ。
    • Microsoft Azure による認証の場合は、offline_access を渡します。

  • extraparams: 省略可。OpenID プロバイダにカンマ区切りのリストとして送信する追加の Key-Value パラメータ。
  • usehttpproxy: 省略可。ユーザー認証用のオンプレミス OIDC プロバイダへの Google Cloud Console でのアクセスを許可するために、クラスタにリバース プロキシをデプロイするかどうかを指定します。値は文字列("true" または "false")で指定する必要があります。ID プロバイダが公共のインターネット経由でアクセスできず、Google Cloud Console を使用して認証する場合、このフィールドは "true" に設定する必要があります。
  • capath: 省略可。ID プロバイダのウェブ証明書を発行した認証局(CA)の証明書へのパス。この値は必須ではない場合があります。たとえば、ID プロバイダの証明書がよく知られている公開 CA によって発行された場合は、ここに値を指定する必要はありません。ただし、usehttpproxy が "true" の場合は、よく知られている公開 CA であってもこの値を指定する必要があります。

例: ユーザーとグループの承認

多くのプロバイダは、ユーザー識別プロパティ(メールやユーザー ID など)をトークンにエンコードします。ただし、これらのプロパティには認証ポリシーに関する潜在的なリスクがあります。

  • ユーザー ID を使用すると、ポリシーの読み取りと監査が困難になることがあります。
  • メールでは、可用性リスク(ユーザーがメインのメールを変更した場合)とセキュリティ リスク(メールを再割り当てできる場合)の両方が発生する可能性があります。

そのため、グループ ポリシーを使用することをおすすめします。グループ ID は永続的で監査が容易なためです。

プロバイダが、次のフィールドを含む ID トークンを作成したとします。

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}

このトークン形式では、構成ファイルの oidc 仕様を次のように指定します。

issueruri: 'https://server.example.com'
username: 'sub'
usernameprefix: 'uid-'
group: 'groupList'
groupprefix: 'gid-'
extraparams: 'resource=token-groups-claim'
...

ユーザー クラスタを作成すると、Kubernetes のロールベースのアクセス制御(RBAC)を使用して、認証済みユーザーに特権アクセスを付与できます。たとえば、クラスタの Secret への読み取り専用アクセス権を付与する ClusterRole を作成し、認証されたグループにロールをバインドする ClusterRoleBinding リソースを作成できます。

ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: secret-reader
rules:
- apiGroups: [""]
  # The resource type for which access is granted
  resources: ["secrets"]
  # The permissions granted by the ClusterRole
  verbs: ["get", "watch", "list"]

ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-secrets-admins
subjects:
  # Allows anyone in the "us-east1-cluster-admins" group to
  # read Secrets in any namespace within this cluster.
- kind: Group
  name: gid-us-east1-cluster-admins # Name is case sensitive
  apiGroup: rbac.authorization.k8s.io
  # Allows this specific user to read Secrets in any
  # namespace within this cluster
- kind: User
  name: uid-u98523-4509823
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

最初の認証構成ファイルの作成

このセクションは、クラスタ管理者を対象としています。

ユーザー クラスタの作成後、クラスタの認証構成ファイルを作成します。

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG]

ここで、[USER_CLUSTER_KUBECONFIG] はユーザー クラスタの kubeconfig ファイルのパスです。ユーザー クラスタを作成したときに、gkectl create cluster によってクラスタ用の kubeconfig ファイルが生成されています。

上記のコマンドでは、現在のディレクトリに kubectl-anthos-config.yaml という名前のファイルを作成します。

追加のクラスタを認証構成ファイルに追加する

このセクションは、クラスタ管理者を対象としています。

複数のクラスタの認証構成を 1 つのファイルに格納できます。次に、そのクラスタすべてにアクセスする必要のあるデベロッパーにそのファイルを 1 つずつ配布します。

既存の認証構成ファイルから始めます。次のコマンドを使用して、そのファイルを追加のクラスタの構成と結合します。

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG] \
    --merge-from [IN_AUTH_CONFIG_FILE] --output [OUT_AUTH_CONFIG_FILE]

ここで

  • [USER_CLUSTER_KUBECONFIG] は、追加クラスタの kubeconfig ファイルです。

  • [IN_AUTH_CONFIG_FILE] は、既存の認証構成ファイルのパスです。

  • [OUT_AUTH_CONFIG_FILE] は、マージされた構成を保持するファイルを保存するパスです。これは [IN_AUTH_CONFIG_FILE] と同じでかまいません。

認証構成ファイルの配布

このセクションは、クラスタ管理者を対象としています。

デベロッパーに配布する認証構成ファイルの名前は、kubectl-anthos-config.yaml にする必要があります。認証構成ファイルはさまざまな方法で配布できます。

  • 各デベロッパーに手動でファイルを提供します。

  • デベロッパーがダウンロードできるように、1 つの URL でファイルを管理します。

  • 各デベロッパーのマシンにファイルを push します。

配布方法に関係なく、認証構成ファイルは各デベロッパーのマシンの次の場所に配置する必要があります。

Linux

$HOME/.config/google/anthos/kubectl-anthos-config.yaml

macOS

$HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

Windows

%APPDATA%\google\anthos\kubectl-anthos-config.yaml

認証構成ファイルの配置

このセクションはデベロッパーを対象としています。

認証構成ファイルには、認証できるすべてのクラスタの詳細が含まれています。このファイルの内容は変更しないでください。

クラスタ管理者が認証構成ファイルを提供している場合は、適切なディレクトリにファイルを配置します。クラスタ管理がすでにマシンに構成を適用している場合は、このセクションを省略できます。

認証構成ファイルをデフォルトの場所にコピーします。

Linux

mkdir -p  $HOME/.config/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/.config/google/anthos/kubectl-anthos-config.yaml

ここで、[AUTH_CONFIG_FILE] は認証構成ファイルの名前です。

macOS

mkdir -p  $HOME/Library/Preferences/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

ここで、[AUTH_CONFIG_FILE] は認証構成ファイルの名前です。

Windows

md "%APPDATA%\google\anthos"
copy [AUTH_CONFIG_FILE] "%APPDATA%\google\anthos\kubectl-anthos-config.yaml"

ここで、[AUTH_CONFIG_FILE] は認証構成ファイルの名前です。

Kubectl 用 Anthos プラグインの取得

このセクションは、クラスタ管理者を対象としています。

Kubectl 用 Anthos プラグインは、次の管理者ワークステーションに含まれています。

Linux

/usr/bin/kubectl_anthos/v1.0beta/linux_amd64/kubectl-anthos

macOS

/usr/bin/kubectl_anthos/v1.0beta/darwin_amd64/kubectl-anthos

Windows

/usr/bin/kubectl_anthos/v1.0beta/windows_amd64/kubectl-anthos

デベロッパーにプラグインを配布するか、デベロッパーにプラグインを直接ダウンロードしてもらうことができます。

Kubectl 用 Anthos プラグインのダウンロード

このセクションは、クラスタ管理者とデベロッパーを対象としています。

各デベロッパーは、各自のパソコンに Kubectl 用の Anthos プラグインをインストールする必要があります。デベロッパーがプラグインを個別にダウンロードすることも、クラスタ管理者がプラグインをダウンロードしてデベロッパーに配布することもできます。

デベロッパー向けの注意事項: 使用するプラグインのバージョンをクラスタ管理者に問い合わせてください。

Kubectl 用 Anthos プラグインをダウンロードします。

Linux

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/linux_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

macOS

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/darwin_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

Windows

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/windows_amd64/kubectl-anthos ./
rename kubectl-anthos kubectl-anthos.exe.

Kubectl 用 Anthos プラグインのインストール

このセクションはデベロッパーを対象としています。

クラスタ管理者から Kubectl 用 Anthos プラグインが提供される場合があります。または、クラスタ管理者から、自分でプラグインをダウンロードするように指示されることもあります。

Kubectl 用 Anthos プラグインをインストールするには、実行可能ファイルを PATH 上の任意の場所に移動します。実行可能ファイルの名前は kubectl-anthos とする必要があります。詳細は、kubectl プラグインのインストールをご覧ください。

Kubectl 用の Anthos プラグインがインストールされていることを確認します。

kubectl plugin list
kubectl anthos version

利用可能クラスタの一覧表示

このセクションはデベロッパーを対象としています。

認証構成ファイルがデフォルトのパスにある場合は、次のコマンドを入力して、認証できるクラスタを一覧表示します。

kubectl anthos listclusters

認証構成ファイルがデフォルトのパスにない場合は、次のコマンドを入力して、クラスタを一覧表示します。

kubectl anthos listclusters --loginconfig [AUTH_CONFIG_FILE]

ここで、[AUTH_CONFIG_FILE] は認証構成ファイルへのパスです。

Kubectl 用 Anthos プラグインを使用した認証

このセクションはデベロッパーを対象としています。

ユーザー クラスタにログインします。

kubectl anthos login --cluster [CLUSTER_NAME] --user [USER_NAME] \
    --loginconfig [AUTH_CONFIG_FILE] --kubeconfig [USER_CLUSTER_KUBECONFIG]

ここで

  • [CLUSTER_NAME] はユーザー クラスタの名前です。この名前は、kubectl anthos listclusters コマンドで提供されるリストから選択する必要があります。

  • [USER_NAME] は、kubeconfig ファイルに保存されている認証情報のユーザー名を指定するオプションのパラメータです。デフォルト値は [CLUSTER_NAME]-anthos-default-user です。

  • [AUTH_CONFIG_FILE] は、認証構成ファイルのパスです。認証構成ファイルがデフォルトの場所にある場合は、このパラメータを省略できます。

  • [USER_CLUSTER_KUBECONFIG] はユーザー クラスタの kubeconfig ファイルのパスです。kubeconfig ファイルが存在しない場合、コマンドで認証構成ファイルから新しい kubeconfig ファイルが生成され、kubeconfig ファイルにクラスタの詳細とトークンが追加されます。

kubectl anthos login で、認証情報を入力できるブラウザを起動します。

現在指定されている kubeconfig ファイルには、kubectl でユーザー クラスタ上の Kubernetes API サーバーに認証するために使用される ID トークンが含まれています。

kubectl anthos login コマンドには、オプションの --dry-run フラグがあります。--dry-run フラグを指定すると、kubeconfig ファイルにトークンを追加する kubectl コマンドが出力されますが、実際には kubeconfig ファイルにトークンは保存されません。

kubectl コマンドを入力して、認証が成功したことを確認します。次に例を示します。

kubectl get nodes --kubeconfig [USER_CLUSTER_KUBECONFIG]

Google Cloud Console での OIDC の使用

このセクションは開発者を対象としています。

  1. クラスタが OIDC 用に構成されていることを確認します。

  2. クラスタが、自動でクラスタ作成中に、または手動で Google Cloud で登録されていることを確認します。

  3. Google Cloud コンソールの [Kubernetes クラスタ] ページにアクセスします。

    [Kubernetes クラスタ] ページに移動

  4. クラスタのリストで、GKE On-Prem クラスタを見つけ、[ログイン] をクリックします。

  5. [クラスタ用に構成された ID プロバイダで認証] を選択し、[ログイン] をクリックします。

    ID プロバイダにリダイレクトされます。ここで、ログイン、または Google Cloud コンソールがアカウントにアクセスすることへの同意が必要となる場合があります。その後、Google Cloud コンソールの [Kubernetes クラスタ] ページに再度リダイレクトされます。

まとめ

企業では、OpenID プロバイダとして機能する AD FS サーバーを実行しています。OpenID プロバイダは、2 つのクライアント アプリケーション(Kubectl 用の Anthos プラグインと Google Cloud コンソール用の Anthos プラグイン)を認識します。OpenID プロバイダは、クライアント アプリケーションが openidallatclaims スコープをリクエストできることを認識しています。

バージョン 5.0 より前の AD FS では、AD データベースの Token-Groups Qualified Names LDAP 属性が OpenID プロバイダの groups クレームにマッピングされます。5.0 以降では、この属性は Token-Groups Qualified by Domain name です。プロバイダは、従業員 ID、発行者 ID、openid クレーム、groups クレームを含むトークンを返します。groups(5.0 では Group)クレームでは、従業員が属するセキュリティ グループが一覧表示されます。

カスタム構成

デフォルトでは、Kubectl 用 Anthos プラグインでは、認証構成ファイルが特定の場所にあることが想定されています。認証構成ファイルをデフォルトの場所に配置しない場合は、--login-config フラグを使用して手動で認証構成ファイルのパスをプラグイン コマンドに渡すことができます。たとえば、Kubectl 用 Anthos プラグインを使用した認証をご覧ください。

GKE On-Prem における OIDC のトラブルシューティング

無効な構成

Google Cloud コンソールでクラスタから OIDC 構成を読み取れない場合、[ログイン] ボタンは無効になります。

無効なプロバイダ構成

ID プロバイダの構成が無効な場合は、[ログイン] をクリックした後に、ID プロバイダからのエラー画面が表示されます。プロバイダ固有の手順に従って、プロバイダまたはクラスタを正しく構成します。

無効な権限

認証フローを完了してもクラスタの詳細が表示されない場合は、OIDC で使用したアカウントに適切な RBAC 権限が付与されていることを確認してください。これは、Google Cloud コンソールへのアクセスに使用するアカウントとは異なる場合があるので注意してください。

Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct

このエラーは、認可サーバーから同意を求められたものの、必要な認証パラメータが指定されていない場合に発生します。prompt=consent パラメータを GKE On-Prem 構成ファイルの oidc: extraparams フィールドに指定し、--extra-params prompt=consent フラグを使用してクライアント認証ファイルを再生成します。

次のステップ