softasap.sa-kong
sa-kong
Kongは、スケーラブルでオープンソースのAPIレイヤー（APIゲートウェイとも呼ばれます）です。Kongは任意のRESTful APIの前で実行され、プラグインを通じて拡張されます。プラグインは、コアプラットフォームを超える追加機能やサービスを提供します。
KongはもともとMashapeで構築され、APIマーケットプレイスのために15,000以上のAPIとマイクロサービスを保護、管理、拡張するために使用されていました。このマーケットプレイスは、20万人以上の開発者向けに毎月数十億のリクエストを生成しています。現在、Kongは小規模および大規模な組織で重要なデプロイメントに使用されています。
スケーラブル: Kongは簡単に水平スケーリングが可能で、もっと多くのマシンを追加するだけで、ほぼどんな負荷も処理でき、遅延を低く保つことができます。
モジュラー: Kongは新しいプラグインを追加することで拡張でき、これらはRESTful Admin APIを通じて簡単に設定できます。
あらゆるインフラストラクチャで実行可能: Kongはどこでも動作します。Kongをクラウドやオンプレミス環境にデプロイでき、単一または複数のデータセンターセットアップや公開、プライベート、招待制のAPIでも使用できます。
おそらく、KongがNginxの上に構築され、その安定性と効率性を活用していることを聞いたことがあるでしょう。しかし、これがどのように可能なのか、もう少し詳しく説明します。
正確に言えば、KongはNginxで動作するLuaアプリケーションで、lua-nginx-moduleによって実現されています。このモジュールでNginxをコンパイルする代わりに、Kongはすでにlua-nginx-moduleを含むOpenRestyとともに配布されます。OpenRestyはNginxのフォークではなく、その能力を拡張するモジュールのバンドルです。
これにより、Luaスクリプト（「プラグイン」と呼ばれます）がランタイムで有効化され、実行されるプラガブルアーキテクチャの基盤が築かれます。このため、Kongはマイクロサービスアーキテクチャの模範と考えることができます。コア部分では、データベース抽象化、ルーティング、プラグイン管理を実装しています。プラグインは別のコードベースに存在し、リクエストライフサイクルのどこにでも注入でき、わずかなコードで実現できます。
注意: Kongのコミュニティ版にはUIがありません。オープンソースのWEB UIを検討することもできます。例えば、https://github.com/PGBI/kong-dashboard や https://github.com/pantsel/konga/ などがあります。
私たちの経験から、https://github.com/PGBI/kong-dashboard はより堅実な開発とリリースプロセスを使用していますが、kongaはより創造的に見えます。
# Kong Dashboardのインストール
npm install -g kong-dashboard
# Kong Dashboardの起動
kong-dashboard start --kong-url http://kong:8001
# カスタムポートでKong Dashboardの起動
kong-dashboard start \
--kong-url http://kong:8001 \
--port [port]
roles:
- {
role: "sa-kong"
}
高度な設定:
roles:
- {
role: "sa-kong",
kong_version: 2.0.1,
kong_activated_plugins: "bundled,oidc",
kong_luarocks_plugins:
- kong-oidc
kong_admin_http: "0.0.0.0:8001",
kong_admin_https: "127.0.0.1:8444",
kong_proxy_http: "0.0.0.0:8000",
kong_proxy_https: "0.0.0.0:8443",
kong_pg_host: "127.0.0.1",
kong_pg_port: 5432,
kong_pg_user: kong,
kong_pg_password: kong,
kong_pg_database: kong
}
将来の利用のための未整理のメモ
興味があるかもしれないサードパーティプラグイン
kong-oidc
https://github.com/nokia/kong-oidc
kong-oidcは、OpenID Connect Relying Party（RP）機能を実装するKongのプラグインです。
OpenID Connect Discoveryと基本クライアントプロファイルを使用して、OpenID Connectプロバイダーに対してユーザーを認証します。
lua-resty-openidcを活用して、認証されたユーザーのセッションを管理し、セッション状態をクライアント側のブラウザクッキーに保存するか、サーバー側のストレージメカニズム（共有メモリ、メムキャッシュ、Redisなど）を使用する選択肢を提供します。
解決されたDiscoveryドキュメントと検証されたアクセストークンのサーバー全体のキャッシングもサポートしています。
一般的には、OIDCをサポートする認可サーバーと、登録されたクライアントが必要です。ここでは、Keycloak/Gluuまたは、第三者提供のソリューション（例: Googleのhttps://developers.google.com/identity/protocols/OpenIDConnect;この場合、Googleアカウントでログインします）を使用できます。
クライアントID/シークレットとOIDC Discovery URLを入手した後（詳細はhttps://auth0.com/docs/tutorials/openid-connect-discoveryを参照）、プラグインを有効にできます。
curlの例は次のようになります:
curl -XPOST -d 'name=oidc' -d 'config.client_id=<client_id>' -d 'config.client_secret=<client_secret>' -d 'config.discovery=<OIDC_Discovery_url>' http://kong:8001/plugins
その後、Kongに登録されたAPIにアクセスする前に、認可サーバーにリダイレクトされてログインすることになります。これにより、Kong内のすべてのAPIにSSOソリューションが提供されます。
これにより、KongはOIDC Relying Partyとなり、Kongの背後にある任意のAPIはOIDC認証保護の恩恵を受けることができます。
実際には、Authorization Code grant（https://auth0.com/docs/api-auth/grant/authorization-code）を使用します。認証されていないユーザーがこのプラグインが有効になっているKongのAPIにアクセスしようとすると、ログインページにリダイレクトされます（認可サーバーの場所は設定のdiscoveryフィールドで設定されます）。成功したログイン後、認可サーバーはアクセストークンを提供し、Kongにリダイレクトされます。Kongはアクセストークンを使用して、アクセストークン、IDトークン、およびリフレッシュトークンを取得します。
トークンは暗号化されたセッションクッキーに保存されます。暗号化キーは、ユーザーエージェント、リモートIPアドレスなどの数変数と、プラグインを有効にするときに定義できるsession_secretの組み合わせです（詳細はhttps://github.com/nokia/kong-oidc/blob/master/kong/plugins/oidc/schema.luaを参照）。このフィールドはオプションですが、高度に推奨されており、ランダムである必要があります。
Kongプラグインは、すでにクッキーが設定されている場合、それを解読してトークンを検証します。アクセストークンのリフレッシュはこのプラグインによって処理されます。
これは、アップストリームサーバーへのリクエストにいくつかの情報を追加します。X-Userinfoヘッダーをセットし、ユーザー情報エンドポイントからの出力を含めます（https://connect2id.com/products/server/docs/api/userinfo）。
一般的にOIDCフローと論理は、lua-resty-openidcパッケージによって実装されています。
これはステートレスであり、Kongのデータストアは使用されません。別のブラウザや別のマシンでこのクッキーを使用すると、機能しません。
トークンを無効にするには、ルートURL /logout（http://
元のトークンはアップストリームサーバーに送信されませんが、X-UserinfoヘッダーにはIDトークンからのクレームが含まれます（ASの署名なし）。
プロセスはステートレスであり、Kongのデータストアは使用されません。このため、別のブラウザや異なるマシンでクッキーを使用すると、機能しません。
トークンを無効にするには、ルートURL /logout（http://
元のトークンはアップストリームサーバーに送信されませんが、X-UserinfoヘッダーにはIDトークンからのクレームが含まれています（ASの署名なし）。
サイドノート - Docker化されたKongでプラグインを使用する予定であれば、以下が必要です。
FROM kong:1.4.0-alpine
LABEL description="Alpine + Kong 1.4.0 + kong-oidc plugin"
RUN apk update && apk add git unzip luarocks
RUN luarocks install kong-oidc
イメージ内でプラグインは環境変数 KONG_PLUGINS を使用して有効化できます。
KONG_PLUGINS=oidc
Kubernetesデプロイメントからの例
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: ingress-kong
annotations:
plugins.konghq.com: oidc
spec:
rules:
- http:
paths:
- path: /graphql
backend:
serviceName: corphub-graphql-service
servicePort: 8082
---
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: kong-oidc
labels:
global: "true"
config:
client_id: kong
client_secret: XXX
discovery: http://keycloak:8180/auth/realms/master/.well-known/openid-configuration
plugin: oidc
Kong Middleman
https://github.com/pantsel/kong-middleman-plugin
オリジナルのプロキシの前に追加のHTTP POSTリクエストを可能にするKongプラグインです。
kong-external-oauth
https://github.com/mogui/kong-external-oauth
APIを保護するために外部のOauth 2.0プロバイダーを使用できるKongプラグインです。
$ luarocks install external-oauth
Kongが新しいプラグインを探す必要があることを認識させるためには、構成ファイルのcustom_pluginsプロパティに追加する必要があります。
custom_plugins:
- external-oauth
以下のリクエストでプラグインを追加できます。
$ curl -X POST http://kong:8001/apis/{api}/plugins \
--data "name=external-oauth" \
--data "config.authorize_url=https://oauth.something.net/openid-connect/authorize" \
--data "config.scope=openid+profile+email" \
--data "config.token_url=https://oauth.something.net/openid-connect/token" \
--data "config.client_id=SOME_CLIENT_ID" \
--data "config.client_secret=SOME_SECRET_KEY" \
--data "config.user_url=https://oauth.something.net/openid-connect/userinfo" \
--data "config.user_keys=email,name,sub" \
--data "config.hosted_domain=mycompany.com" \
--data "config.email_key=email"
| フォームパラメータ | デフォルト | 説明 |
|---|---|---|
name |
プラグイン名 external-oauth |
|
config.authorize_url |
OAUTHプロバイダーの認可URL（認証されていないときにリダイレクトされるURL） | |
config.scope |
認可リクエストのOAUTHスコープ | |
config.token_url |
アクセストークン取得のためのOAUTHプロバイダーのURL | |
config.client_id |
OAUTHクライアントID | |
config.client_secret |
OAUTHクライアントシークレット | |
config.user_url |
ユーザー情報を取得し、アクセストークンの有効性を確認するためのOAUTHプロバイダーのURL | |
config.user_keys オプション |
username,email |
user_urlエンドポイントから返されるJSONから抽出するキーで、これらはアップストリームサーバーのヘッダーに X-OAUTH-XXXとして追加されます。 |
config.hosted_domain |
ログインするためにユーザーが属する必要があるドメイン。空の場合は無視されます。 | |
config.email_key |
ユーザー情報エンドポイントから取得するホスティドドメインでチェックするキー | |
config.user_info_periodic_check |
60 | トークンチェック間の秒数 |
user_keys に加え、プロバイダーのアクセストークンを含む X-OAUTH-TOKEN ヘッダーも追加されます。
Postgresバックエンド
pg_hba.confの修正後の見た目は次のようになります。
local all postgres peer
# TYPE DATABASE USER ADDRESS METHOD
# "local"はUnixドメインソケット接続のみに適用されます。
local all all md5
# local all all peer
# IPv4ローカル接続：
host all all 127.0.0.1/32 password
host all all 127.0.0.1/32 md5
# IPv6ローカル接続：
host all all ::1/128 md5
# レプリケーション権限を持つユーザーによるローカルホストからのレプリケーション接続を許可します。
#local replication postgres peer
#host replication postgres 127.0.0.1/32 md5
#host replication postgres ::1/128 md5
サードパーティの参考資料
ダッシュボード
Konga https://github.com/pantsel/konga (Kong > 1)
Kong-Dashboard https://github.com/PGBI/kong-dashboard (Kong > 0.9)
宣言型設定ツール
kongfig https://github.com/mybuilder/kongfig (Kong < 1)
Deck https://github.com/hbagdi/deck (Kong >= 1)
Ansible Galaxyワークフローでの使用
以下のコマンドを使用してsa-kongロールをインストールした場合：
ansible-galaxy install softasap.sa-kong
ロールはlibrary/sa-kongフォルダに利用可能になりますので、パスを適宜調整してください。
- {
role: "softasap.sa-kong"
}
著作権とライセンス
コードはBSD 3条項とMITライセンスの下で二重ライセンスされています。どちらかお好きな方を選んでください。
お問い合わせ：
ロールの更新についてはFBを購読してください。
Gitterのディスカッションチャンネルに参加するにはGitterを訪れてください。
他のロールを発見するには、http://www.softasap.com/roles/registry_generated.htmlを訪れてください。