🔑

Keycloak (>=18) でScript Mapperを使う

2022/12/18に公開

Keycloak 18以降でupload-scriptが廃止されたため、OICD Mapper等のためのスクリプトを管理画面から直接追加・編集できなくなってしまいました。サーバーのビルド時にスクリプトをデプロイできるものの、ドキュメントの説明はあまり詳しくないので、ここではMattermostのauthdataをUserIDから生成するOICD Mapperを例に、Keycloakに追加する方法を残しておきます。

環境

Keycloak（quay.io/keycloak/keycloak:20.0.2）
Docker

デプロイ手順

こちら^[1]で紹介されているマッパーをデプロイする。

ファイル構成

custommappers/
├── META-INF
│   └── keycloak-scripts.json
└── authdata.js

マッパースクリプト

ファイル名は適当でよい

authdata.js

exports = parseInt(user.getId().split("-").join("").substr(0,12),16).toString();

Tokenの何らかのClaimに入れる値をexportsという変数に代入する。何を参照できるかはこれ^[2]とかを参照。

メタデータ

META-INFというディレクトリを作ってそこにkeycloak-scripts.jsonを書く。

keycloak-scripts.json

{
  "mappers": [
    {
      "name": "Mattermost authdata mapper",
      "fileName": "authdata.js",
      "description": "Make integer from user ID"
    }
  ]
}

この例ではマッパーは1つだが、複数のスクリプトを1つにまとめることも可能。

jarを作る

jarといってもzipで圧縮するだけでいい。

$ cd custommappers
$ zip -r ../custom.jar *

ビルド

ビルド時にkeycloak/providers/に作ったjarファイルを置く。Running Keycloak in a containerを参考に書くとだいたい次のような感じ

FROM quay.io/keycloak/keycloak:20.0.2 as builder

COPY custom.jar /opt/keycloak/providers/

ENV ...
ENV KC_LOG_LEVEL=debug

WORKDIR /opt/keycloak
RUN /opt/keycloak/bin/kc.sh build


FROM quay.io/keycloak/keycloak:20.0.2
COPY --from=builder /opt/keycloak/ /opt/keycloak/

# change these values to point to a running postgres instance
ENV ...
ENV KC_LOG_LEVEL=info

ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
CMD ["start", "--optimized"]

jarファイルが存在していればログに次のように出力される。

DEBUG [io.quarkus.deployment.index.ApplicationArchiveBuildStep] (build-29) Indexing dependency: /opt/keycloak/lib/../providers/custom.jar

使う

Clients -> Client details -> Dedicated scopes から Add mapper -> By configurationを選ぶ。
Mapperの一覧にkeycloak-scripts.jsonで記述した名前と説明のカスタムマッパーが入っているので選んで使う。

なお、以前のバージョンでupload-scriptを使ったマッパーが登録されていて、そのデータを残したままアップグレードした場合、マッパーの一覧には表示されなくとも内部的には残っているため、次のようなエラーが出る可能性がある。

この場合は、データを移行する前に予めマッパーを消したり、exportしたデータを編集したりデータベースを直接叩いたりしてマッパーを消さないといけない。

脚注