Apache APISIX での認証に Keycloak を統合する方法

2021年12月21日投稿者: Xinxin Zhu & Yilin Zeng

この記事は公開から1年以上経過しています。ブログ記事の内容は古くなっている可能性があります。

この記事では、詳細な手順を通して、Apache APISIX で OpenID Connect プロトコルと Keycloak を使用して ID 認証を行う方法を紹介します。

Keycloak は、最新のアプリケーションとサービス向けのオープンソースのアイデンティティおよびアクセス管理ソリューションです。Keycloak はシングルサインオンをサポートしており、サービスは OpenID Connect、OAuth 2.0 などのプロトコルを介して Keycloak と連携できます。Keycloak は、Github、Google、Facebook などのさまざまな認証サービスとの統合もサポートしています。

さらに、Keycloak はユーザーフェデレーションもサポートしており、LDAP および Kerberos を介してユーザーをインポートできます。Keycloak の詳細については、公式ドキュメントを参照してください。

Apache APISIX は、動的でリアルタイム、高性能な API ゲートウェイであり、豊富なトラフィック管理を提供します。このプロジェクトは、ロードバランシング、動的アップストリーム、カナリアリリース、サーキットブレーキング、認証、可観測性、および多くの便利なプラグインを提供します。さらに、ゲートウェイはホットアップデートとともに動的なプラグイン変更をサポートしています。Apache APISIX 用の OpenID Connect プラグインを使用すると、ユーザーは従来の認証モードを OpenID Connect を介した集中型 ID 認証モードに置き換えることができます。

使用方法

Apache APISIX のインストール

依存関係のインストール

Apache APISIX のランタイム環境には、NGINX と etcd への依存関係が必要です。

Apache APISIX をインストールする前に、使用しているオペレーティングシステムに従って依存関係をインストールしてください。CentOS7、Fedora 31 および 32、Ubuntu 16.04 および 18.04、Debian 9 および 10、macOS 用の依存関係インストール手順を提供しています。詳細については、依存関係のインストールを参照してください。

RPM パッケージ経由でのインストール (CentOS 7)

このインストール方法は CentOS 7 に適しています。Apache APISIX をインストールするには、次のコマンドを実行してください。

sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm

Docker 経由でのインストール

Docker を使用した Apache APISIX のインストールを参照してください。

Helm Chart 経由でのインストール

Helm Chart を使用した Apache APISIX のインストールを参照してください。

依存関係の初期化

NGINX 設定ファイルと etcd を初期化するには、次のコマンドを実行します。

make init

Apache APISIX の起動

Apache APISIX を起動するには、次のコマンドを実行します。

apisix start

Keycloak の起動

ここでは、docker を使用して Keycloak を起動します。

docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=password -e DB_VENDOR=h2  -d jboss/keycloak:9.0.2

実行後、Keycloak が正常に起動したことを確認する必要があります。

docker ps

Keycloak の設定

Keycloak が起動したら、ブラウザを使用して "http://127.0.0.1:8080/auth/admin/" にアクセスし、admin/password アカウントのパスワードを入力して管理者コンソールにログインします。

レルムの作成

まず、apisix_test_realm という名前のレルムを作成する必要があります。Keycloak では、レルムはプロジェクトの管理専用のワークスペースであり、異なるレルムのリソースは互いに分離されています。

Keycloak のレルムは、2 つのカテゴリに分類されます。1 つは master realm で、Keycloak の初回起動時に作成され、管理者アカウントの管理と他のレルムの作成に使用されます。2 つ目は other realm で、master realm の管理者によって作成され、このレルムのユーザーとアプリケーションの作成、管理、および使用に使用できます。詳細については、Keycloak のレルムとユーザーのセクションを参照してください。

クライアントの作成

次のステップは、OpenID Connect Client を作成することです。Keycloak では、クライアントとは、Keycloak への認証を開始することを許可されたクライアントを意味します。

この例のシナリオでは、Apache APISIX は Keycloak への認証リクエストを開始する役割を担うクライアントに相当するため、apisix という名前のクライアントを作成します。クライアントの詳細については、Keycloak OIDC クライアントを参照してください。

クライアントの設定

クライアントを作成したら、クライアントの Apache APISIX アクセスタイプを設定する必要があります。

Keycloak には、3 種類のアクセスタイプがあります。

Confidential (コンフィデンシャル): ブラウザログインを実行する必要があるアプリケーションに使用され、クライアントは client secret を介して access token を取得します。主にサーバーによってレンダリングされる Web システムで使用されます。
Public (パブリック): ブラウザログインを実行する必要があるアプリケーションに使用され、主に vue や react を使用して実装されたフロントエンドプロジェクトで使用されます。
Bearer-only (ベアラのみ): ブラウザログインを実行する必要がなく、bearer token でのアクセスのみを許可するアプリケーションに使用され、主に RESTful API シナリオで使用されます。

クライアント設定の詳細については、Keycloak OIDC クライアントの詳細設定を参照してください。

Apache APISIX をサーバー側のクライアントとして使用しているため、「Confidential」アクセスタイプまたは「Bearer-only」アクセスタイプのいずれかを選択できます。以下のデモンストレーションでは、「Confidential」アクセスタイプを例として使用します。

ユーザーの作成

Keycloak は、Google や Facebook などの他のサードパーティユーザーシステムとの連携、または LDAP を使用したユーザーのインポートまたは手動作成をサポートしています。ここでは、「手動でユーザーを作成する」を使用してデモンストレーションを行います。

次に、「Credentials (資格情報)」ページでユーザーのパスワードを設定します。

ルートの作成

Keycloak を設定したら、ルートを作成し、Openid-Connect プラグインを有効にする必要があります。このプラグインの設定の詳細については、Apache APISIX OpenID-Connect プラグインを参照してください。

client_id と client_secret の取得

上記の設定で。

client_id は、以前にクライアントを作成したときに使用した名前、つまり apisix です。
client_secret は、Clients-apisix-Credentials から取得する必要があります。例: d5c42c50-3e71-4bbbe-aa9e-31083ab29da4。

ディスカバリー設定の取得

「Realm Settings (レルム設定)」-「General (一般)」-「Endpoints (エンドポイント)」に移動し、「OpenID Endpoint Configuration (OpenID エンドポイント設定)」リンクを選択し、リンクが指すアドレス (例: `http://127.0.0.1:8080/auth/realms/apisix_test_realm/.well-known/openid-configuration`) をコピーします。

ルートを作成してプラグインを有効にする

次のコマンドを使用して Apache APISIX 管理インターフェースにアクセスし、ルートを作成し、アップストリームを httpbin.org に設定し、認証用のプラグイン OpenID Connect を有効にします。

注: クライアントの作成時にアクセスタイプとして bearer-only を選択した場合は、ルートを設定するときに bearer_only を true に設定する必要があります。これにより、Apache APISIX へのアクセスが Keycloak ログイン画面にジャンプしなくなります。

curl  -XPOST 127.0.0.1:9080/apisix/admin/routes -H "X-Api-Key: edd1c9f034335f136f87ad84b625c8f1" -d '{
    "uri":"/*",
    "plugins":{
        "openid-connect":{
            "client_id":"apisix",
            "client_secret":"d5c42c50-3e71-4bbe-aa9e-31083ab29da4",
            "discovery":"http://127.0.0.1:8080/auth/realms/apisix_test_realm/.well-known/openid-configuration",
            "scope":"openid profile",
            "bearer_only":false,
            "realm":"apisix_test_realm",
            "introspection_endpoint_auth_method":"client_secret_post",
            "redirect_uri":"http://127.0.0.1:9080/"
        }
    },
    "upstream":{
        "type":"roundrobin",
        "nodes":{
            "httpbin.org:80":1
        }
    }
}'

アクセステスト

上記の設定が完了したら、Apache APISIX で関連するアクセステストを実行する準備が整いました。

Apache APISIX へのアクセス

ブラウザを使用して http://127.0.0.1:9080/image/png にアクセスします。

OpenID-Connect プラグインが有効になっており、bearer-only が false に設定されているため、このパスに初めてアクセスすると、Apache APISIX は Keycloak の apisix_test_realm で設定されたログイン画面にリダイレクトし、ユーザーログインリクエストを行います。

Keycloak 設定中に作成したユーザー peter を入力して、ユーザーログインを完了します。

アクセス成功

ログインに成功すると、ブラウザはリンクを http://127.0.0.1:9080/image/png に再度リダイレクトし、画像コンテンツへのアクセスに成功します。コンテンツは、アップストリーム http://httpbin.org/image/png のコンテンツと同じです。

ログアウト

テスト後、ブラウザを使用して http:/127.0.0.1:9080/logout にアクセスしてアカウントからログアウトします。

注: ログアウトパスは、OpenID-Connect プラグイン設定の logout_path で指定できます。デフォルトは logout です。

まとめ

この記事では、Apache APISIX で認証に OpenID-Connect プロトコルと Keycloak を使用する手順を示しました。Keycloak と統合することにより、Apache APISIX はユーザーとアプリケーションサービスを認証および認可するように構成でき、関連する開発作業を大幅に削減できます。

Apache APISIX での認証の実装の詳細については、Apache APISIX ブログを参照してください。