Zenn
😁

【Keycloak】OAuth2.0でAPI利用を認可するための設定を紹介

2023/03/05に公開
API
OAuth
認証
Keycloak
認可
tech

はじめに

Webやモバイルのアプリケーションは、セキュリティの観点から、API利用に認可の仕組みを入れる必要があります。
この記事では、認可サーバにKeycloakを採用し、OAuth2.0でAPI認可を行うための設定を紹介します。
※ クライアントアプリケーションとリソースサーバの実装については、ここでは扱いません。

対象読者

APIに認証・認可の仕組みを入れたい方、Keycloakをこれからシステムに取り入れようと考えている方。

Keycloakって何？

Keycloakは、システムに認証・認可の仕組みを組み込むことができるオープンソースのソフトウェアです。
最新版は、21.0.0です。(2023/3/1時点)

システム構成

以下のシステム構成を採用したWebアプリケーションをローカルで動かす前提で説明していきます。

  • クライアント
    • ホスト: localhost
    • ポート: 3000
    • 例: ReactやVueで実装されたSingle Page Applicationなど
  • 認可サーバ
    • ホスト: localhost
    • ポート: 8080
  • リソースサーバ
    • ホスト: localhost
    • ポート: 8001
    • 例: RESTfulなAPIなど

API利用を認可するまでの流れ

Webアプリケーションを開いてから、クライアントを認可して、リソースサーバからデータ取得するまでの流れをシーケンス図にしました。
OAuth2.0でいう認可コードフローで実装した場合の一例です。

Keycloakの基本用語

Keycloakを利用するために、基本用語を抑えておきましょう。

  • Realm(レルム)
    ユーザーやクライアント、ロールを一つのまとまりとして管理する単位のことです。

  • Clients(クライアント)
    Keycloakが認証・認可を行うサービスを登録します。

  • Roles(ロール)
    レルムごとの権限とクライアントごとの権限を設定します。
    ロールによって、認可を振り分けます。

Keycloakの立ち上げ

Keycloakサーバを立ち上げます。
下記のコマンドで、管理者ユーザーも同時に作成しています。

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:21.0.0 start-dev

http://localhost:8080/　にアクセスするとこの画面が表示されます。

Keycloakの設定

サインイン

  1. Administration ConsoleからSign inを行います。

レルムの作成

  1. サイドメニューの「Create Realm」から、レルムを作成します。
    ここでは、レルム名をSampleに設定しています。

クライアントの作成

リソースサーバの設定

  1. 「Create Client」からクライアント作成画面に遷移します。

  2. リソースサーバの設定を行います。

  3. 「Client Authentication」をOnにして、Standard flowにチェックをつけます。
    「Standard flow」がOAuth2.0で推奨される認可コードフローになります。

リソースサーバ側の設定が完了しました。

クライアントアプリケーションの設定

クライアントアプリケーションも登録する必要があるのですが、バックエンドのサービスと設定項目が異なる部分を紹介します。

  1. ブラウザで動くアプリは安全にシークレット情報を保管できないので、「Client authentication」をOFFにします。

  2. valid_redirect_uriにアクセストークンを受け取るURIを指定します。

これで、クライアントはすべて作成完了です。

ユーザーの作成

APIを利用するユーザーの作成を行います。

ロールの作成

Keycloakのクライアントロールを利用して、API利用を認可する権限を分別します。

  1. 先ほど作成した「Test」クライアントのRolesタブで、ロールを作成しておきます。

リソースサーバで、この「TestUserRole」がアクセストークンに含まれていた場合、
/hogeエンドポイントへのリクエストを許可する という実装にしておきます。

ユーザーとロールの紐付け

  1. 先ほど作成した「ユーザーa」のRole Mappingタブを開きます。

  2. Assign Roleから、クライアントロールでフィルターをかけます。

  3. 「TestUserRole」を選択してユーザーにアサインします。

これで設定は完了です。
Keycloakの設定は完了です、APIの認可処理を組み込むことができました。

まとめ

クライアントアプリケーションとリソースサーバの実装は、説明が長くなるので割愛しました。
API利用のための認可サーバの設定は、上記の流れで行うことができます。
Keycloakは設定項目が細かくあるので、実際のプロダクトに利用するときは、カスタマイズしましょう。

参考文献

https://qiita.com/TakahikoKawasaki/items/200951e5b5929f840a1f
https://www.keycloak.org/documentation

Discussion