本記事は、SAML や OpenOID Connect (OIDC) を理解したけど、結局 SSO ってどうやって実装するの？という方のための入門記事です。
| 関連記事：サーバー | ||||
|---|---|---|---|---|
Docker で Keycloak をインストール
今回は Docker を利用して Keycloak の使い方を説明します。
Docker って何？という方や、インストール方法、使い方については以下の記事で解説しています。
Keycloak の使い方
- http://localhost:8080/admin にアクセスします。
- admin ユーザーでログインします。パスワードは「admin」です。
(Docker run のオプションが -e KEYCLOAK_ADMIN_PASSWORD=admin の場合)
リモートホストでコンテナを起動した場合
レルムの作成
Keycloak のレルムとは、ユーザーや認証するアプリケーションの情報などを１つにまとめたテナント (グループ) です。
例えば、顧客ごとにレルムを分けることで管理を分離できます。
- ナビゲーションメニューの「Master」にマウスオーバーすると「Add realm」が表示されるので選択
- 「Name」に「myrealm」と入力
- 「Create」を押下
ユーザーの作成
- ナビゲーションメニューの「Users」を選択
- 右側にある「Add user」を選択
- 作成するユーザー情報を入力
- Username:
「myuser」 - First Name: 名前を入力
- Last Name: 苗字を入力
- Username:
- 「Save」を選択
認証情報 (Credentials) を設定
- 「ユーザー」ページの上部タブにある「Credentials」を選択
- パスワードを入力し「Set Password」を選択
- (オプション) Temporary を OFF にすると、初回ログイン時にパスワードを再設定しなくて済みます
作成したユーザーでログイン
- http://localhost:8080/realms/myrealm/account にアクセス
- 右上の「Sign In」を選択
- 先ほど設定した myuser でログイン
ログインに成功すると、右上に苗字と名前が表示されます。
(サンプルどおりに入力した場合は Foo Bar)
クライアント (アプリ) を設定
- 左側のナビゲーションバーから「Clients」を選択
- 右側の「Create」を選択しクライアント (アプリ) を作成
- 以下のように情報を入力
- Client ID:
myclient(アプリ名) - Client Protocol:
openid-connect(利用するプロトコル) - Root URL:
https://www.keycloak.org/app/(Keycloak が用意したテスト用アプリ)
- Client ID:
アプリに SSO でログイン
今回はサンプルアプリ (https://www.keycloak.org/app/) を利用します。
- https://www.keycloak.org/app/ にアクセス
- 「Save」を選択
- 「Sign in」を選択
- 先ほど myuser でログインした情報を利用して自動で SSO を行います
- SSO に成功すると「Hello, Foo Bar」と表示されます
- 「Sign out」を選択
- サンプルアプリからログアウトします
- http://localhost:8080/realms/myrealm/account/#/personal-info もログアウトします
(ログアウトしない場合はスーパーリロードしてください)
- 「Sign in」を選択
- 今度はログイン画面が表示 (myuser はログアウトしているので、SSO できない)
- myuser でログインすると４と同じ画面が表示されます。
よって、以下のいずれかにログインすると、SSO によってもう片方ではログインが不要になることが確認できます。
HTTPS/TLS の設定
本番環境で利用する場合は、HTTPS を介して keycloak のエンドポイントを公開します。
本作業は以下の手順で行います。
- Let's Encrypt (Certbot) の HTTP-01 チャレンジのために、Web サーバーとして nginx を稼働
- Let's Encrypt (Certbot) の HTTP-01 チャレンジ で SSL/TLS 証明書を発行
- Keycloak で SSL/TLS 証明書を利用して、HTTPS でエンドポイントを公開
Let's Encrypt については、以下の記事で説明しています。
また、本作業には docker-compose を利用します。docker-compose については、以下の記事で説明しています。
Keycloak + HTTPS の設定
ドメイン名は、ご自身のドメインに置き換えてください。
version: '3'
services:
keycloak:
image: quay.io/keycloak/keycloak:17.0.1
container_name: keycloak
ports:
- "8443:8443"
volumes:
- cert:/etc/letsencrypt
environment:
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: admin
KC_HOSTNAME: $DOMAIN
KC_HTTPS_CERTIFICATE_FILE: /etc/letsencrypt/live/$DOMAIN/fullchain.pem
KC_HTTPS_CERTIFICATE_KEY_FILE: /etc/letsencrypt/live/$DOMAIN/privkey.pem
entrypoint: ["/opt/keycloak/bin/kc.sh", "start"]
user: "0:0" #cert ボリュームに root 権限が必要なため
depends_on:
- certbot
certbot:
image: certbot/certbot:v1.7.0
container_name: certbot
volumes:
- cert:/etc/letsencrypt
- html:/usr/share/nginx/html/
entrypoint: ["certbot", "certonly", "-d $DOMAIN", "-m hoge@foo.bar", "--agree-tos","--webroot", "-w","/usr/share/nginx/html/"]
depends_on:
- nginx
nginx:
image: nginx:alpine
restart: always
container_name: nginx
volumes:
- cert:/etc/letsencrypt
- html:/usr/share/nginx/html/
ports:
- "80:80"
volumes:
html:
cert:hoge@foo.bar はご自身のメールアドレスに置き換えます。
下から２番目のログで「Profile prod activated.」が表示されていれば成功です。
ブラウザから https://$DOMAIN:8443/admin/ にアクセスし、以下の画面が表示されれば成功です。
(※ $DOMAIN は、ご自身のドメインに置き換えてください。)
Keycloak の設定方法は、localhost の時と同じです。(ココ参照)
データベースを設定
Keycloak のデータ保管にデータベースを利用します。
データベースのベンダーを指定するには、ビルド時のオプションが必要です。
The database vendor.
Possible values are: dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgresEnv:
https://www.keycloak.org/server/db#_relevant_optionsKC_DBBuild option
そのため、Dockerfile を利用してビルドしたイメージを作成し、docker-compose で各コンテナを起動します。
FROM quay.io/keycloak/keycloak:latest ENV KC_DB=postgres RUN /opt/keycloak/bin/kc.sh build
version: '3'
services:
keycloak:
#image: quay.io/keycloak/keycloak:17.0.1
build:
context: ./
dockerfile: keycloak_Dockerfile
container_name: keycloak
ports:
- "8443:8443"
volumes:
- cert:/etc/letsencrypt
environment:
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: $PASSWORD
KC_HOSTNAME: $DOMAIN
KC_HTTPS_CERTIFICATE_FILE: /etc/letsencrypt/live/$DOMAIN/fullchain.pem
KC_HTTPS_CERTIFICATE_KEY_FILE: /etc/letsencrypt/live/$DOMAIN/privkey.pem
KC_DB_USERNAME: keycloak
KC_DB_PASSWORD: $PASSWORD
#KC_DB_SCHEMA: public
KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
entrypoint: ["/opt/keycloak/bin/kc.sh", "start"]
user: "0:0" #cert ボリュームに root 権限が必要なため
depends_on:
- certbot
- postgres
certbot:
image: certbot/certbot:v1.7.0
container_name: certbot
volumes:
- cert:/etc/letsencrypt
- html:/usr/share/nginx/html/
entrypoint: ["certbot", "certonly", "-d $DOMAIN", "-m hoge@foo.bar", "--agree-tos","--webroot", "-w","/usr/share/nginx/html/"]
depends_on:
- nginx
nginx:
image: nginx:alpine
restart: always
container_name: nginx
volumes:
- cert:/etc/letsencrypt
- html:/usr/share/nginx/html/
ports:
- "80:80"
postgres:
image: postgres:13.0-alpine
container_name: postgres
restart: always
environment:
POSTGRES_DB: keycloak
POSTGRES_USER: keycloak
POSTGRES_PASSWORD: $PASSWORD
volumes:
- ./postgres_data:/var/lib/postgresql/data
volumes:
html:
cert: ドメイン名と好きなパスワードを設定してください。
ブラウザから https://$DOMAIN:8443/admin/ にアクセスし、以下の画面が表示されれば成功です。
(※ $DOMAIN は、ご自身のドメインに置き換えてください。)
SSO の IdP として利用
Keycloak を SSO の IdP として利用する方法を紹介します。
今回は、SSO を実現するプロトコルとして、次の２通り説明します。
SAML
SAML で ID フェデレーションを設定し、SSO を実現します。
SP に IdP を登録
サービスプロバイダー (SP) に、Keycloak を SAML ID プロバイダー (IdP) として登録するため、SAML メタデータドキュメントを取得します。
- [Realm Settings] を選択
- [SAML 2.0 Identity Provider Metadata] を[リンク先を別名で保存]
取得した IdP 側の SAML メタデータドキュメントを、サービスプロバイダ (SP) でインポートします。
(例:https://docs.aws.amazon.com/ja_jp/IAM/latest/UserGuide/id_roles_providers_create_saml.html)
IdP に SP をクライアントとして登録
SAML ID プロバイダー (IdP) に SP をクライアントとして登録します。
事前に SP 側の SAML メタデータドキュメントを用意しておきます。
(例: https://signin.aws.amazon.com/static/saml-metadata.xml の [リンク先を別名で保存] )
- [Clients] を選択
- [Create] を選択
- [Select file] を選択
- SAML メタデータドキュメントを Import
- [Save] を選択
IdP で SAML アサーションを設定
Mappers を利用して、SAML アサーションをマッピングします。
- [Clients] を選択
- [Mappers] タブを選択
- [User Attribute] は ユーザーの属性キーを利用して属性値を設定
- [SAML Attribute Name] は Attribute element の Name 属性を設定
※ [username] 属性値の属性キーは、認証した [ユーザー名] です。
SAML レスポンスに含まれる SAML アサーションは以下のようになります。(SAML レスポンスの解析方法はこちら)
<Attribute Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName"> <AttributeValue>ユーザー名</AttributeValue> </Attribute>
属性キーと属性値の設定
自分で任意の属性キーと属性値を設定することも可能です。
- メニューの [Users] を選択
- 管理するユーザーを選択
- [Attributes] タブを選択
- [key] フィールドに属性キーを入力
- [value] フィールド属性値を入力
- [Add] を選択
- [Save] を選択
[User Attribute] に上記で設定した属性キーを利用できます
今回は RoleAttribute をこちらに従って設定しました。
SSO を開始
[IDP Initiated SSO URL Name] で設定した URL にアクセスし、SSO を開始します。
https://<Keycloak のドメイン>:8443/realms/myrealm/protocol/saml/clients/amazon-aws?RelayState=<ログイン後にリダイレクトするエンコードした URL>
OpenID Connect (OIDC)
ここでは、クライアントの [Access Type] に confidential を利用します。
[Access Type] の [confidential] と [public] の違いは以下のドキュメントをご覧ください。
IdP のクライアントに SP を登録
IdP である Keycloak のクライアントに SP を登録します。
(SP の例： https://aws.amazon.com/jp/blogs/news/built-in-authentication-in-alb/)
- [Clients] を選択
- [Create] を選択
OIDC メタデータを import
もしくは以下の手順で手動入力
- [Client ID] を入力
- [Root URL] にログイン後にリダイレクトする URL を入力
クライアントの [Access Type] を confidential に設定
- タブの [Credentials] を選択
- [Secret] をメモ
SP に IdP を登録
- [Realm Settings] を選択
- [OpenID Endpoint Configuration] を選択
SP 側で [OpenID Endpoint Configuration] をインポート or 内容を見て手動で入力します。
[Client ID] と [Secret] は先ほど設定したものです。
関連記事
| 関連記事：サーバー | ||||
|---|---|---|---|---|
参考ページ
