以下の内容はhttps://rheb.hatenablog.com/entry/rhdh-practice-03より取得しました。

【Developer Hub 実践｜第3回】GitLabを使用した認証を実装しよう

OpenShift Red Hat Developer Hub Developer Hub 実践 Backstage

【2026年2月追記】最新の情報を元に内容をアップデートしました！

こんにちは、Red HatでOpenShift関連のプリセールスをしている北村です。

前回の記事ではGitHubと連携してDeveloper Hubの認証を実装しました。

しかし中には、GitHubではなく社内のオンプレミス環境に構築したGitLabを利用している方もいるかと思います。

なので今回はGitLab OAuthを利用したDeveloper Hub認証の実現方法をまとめてみます。

GitLabを利用した認証に関する問題

GitLabでの認証では、GitHubのように直接Developer Hubと連携するとこはできません。

これはRed Hatのサポート状況に関するものです。Developer Hubで利用可能な認証はv1.8時点で "GitHub"、"Red Hat Build of Keycloak(RHBK)"、"Microsoft Azure" の3種類となっています。

それを踏まえ、今回はDeveloper HubでサポートされているRHBKを経由して認証を実装します。GitLabをRHBKのIdentity Providerとして登録します。ちなみにRHBKはOpenShiftのSubscriptionに含まれており、ROSA環境でも追加費用なく導入可能です。（詳細はこちら）

つまりイメージはこんな感じ↓

Developer Hub GitLab 認証 実装手順

今回の手順はコミュニティ版のGitLabを前提としています。おそらくエンタープライズ版でも同様の手順で実現できます。

GitLab Application設定

まずはGitLab側の設定から始めます。

GitHubのようにGroupを作成後、Applicationを登録します。今回はrhdh-gitlab-groupというGroupにしました。

GroupのページからSettings→Applications→Add new applicationを選択して、以下の内容を入力します。Redirect URIは後ほど書き換えるのでダミーで適当な値を入れておきます。

Name 任意の値
Redirect URI https://dummy.hoge
Confidential false
Scopes read_user
openid

作成完了の画面でApplication IDとSecretを取得しておきます。

RHBK設定

次にRHBK側の設定を進めます。

まずはRHBKをOpenShiftにインストールしていきます。

今回はrhdh NamespaceにRHBK Operatorをインストールします。インストール時はデフォルトの設定でOKです。2026年2月時点での更新チャネルはstable-v26.2、バージョンはv26.2.12-opr.1でした。

次にKeycloakが使うDBをデプロイします。今回は開発用の一時的な PostgreSQL Podを作成します。

postgres.yaml

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgresql-db
  namespace: rhdh
spec:
  serviceName: postgresql-db-service
  selector:
    matchLabels:
      app: postgresql-db
  replicas: 1
  template:
    metadata:
      labels:
        app: postgresql-db
    spec:
      containers:
        - name: postgresql-db
          image: postgres:15
          volumeMounts:
            - mountPath: /data
              name: postgres-storage
          env:
            - name: POSTGRES_USER
              valueFrom:
                secretKeyRef:
                  name: keycloak-db-secret
                  key: username
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: keycloak-db-secret
                  key: password
            - name: PGDATA
              value: /data/pgdata
            - name: POSTGRES_DB
              value: keycloak
      volumes:
        - name: postgres-storage
          persistentVolumeClaim:
            claimName: postgres-storage
---
apiVersion: v1
kind: Service
metadata:
  name: postgres-db
  namespace: rhdh
spec:
  selector:
    app: postgresql-db
  type: ClusterIP
  ports:
  - port: 5432
    targetPort: 5432
---
apiVersion: v1
kind: Secret
metadata:
  name: keycloak-db-secret
  namespace: rhdh
stringData:
  password: testpassword
  username: testuser
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-storage
  namespace: rhdh
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

DB作成できたらkeycloakをデプロイしていきます。以下のyamlを作成してデプロイしましょう。

keycloak.yaml

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  labels:
    app: sso
  name: keycloak
  namespace: rhdh
spec:
  instances: 1
  http:
    httpEnabled: true
  hostname:
    strict: false
  proxy:
    headers: xforwarded
  ingress:
      className: openshift-default

しばらくするとrouteが作成されるので、keycloak-initial-adminというSecretに記載のユーザーとパスワードでログインします。

次にrealmとgitlabのIdentity Providerを登録します。今回はRHBK Operatorを使っているので、KeycloakRealmImport というCRを使って一気に登録を行います。reamlとclientの名前はrhdhとしました。

keycloakrealmimport.yaml

apiVersion: k8s.keycloak.org/v2alpha1
kind: KeycloakRealmImport
metadata:
  name: realm-import
  namespace: rhdh
spec:
  keycloakCRName: keycloak
  realm:
    realm: rhdh
    displayName: "GitLab Realm for RHDH"
    enabled: true
    ssoSessionIdleTimeout: 28800
    ssoSessionMaxLifespan: 86400
    rememberMe: true
    clients:
      - clientId: rhdh
        name: rhdh
        enabled: true
        publicClient: false
        redirectUris:
          - "https://<Developer HubのURL>/*"
        webOrigins:
          - "https://<Developer HubのURL>"
        clientAuthenticatorType: client-secret
        secret: "<任意の値>"      # node -p 'require("crypto").randomBytes(24).toString("base64")' などで生成
    identityProviders:
      - enabled: true
        alias: "gitlab"
        displayName: "GitLab"
        providerId: "oidc"
        config:
          clientId: "<GitLab ApplicationのClient ID>"
          clientSecret: "<GitLab ApplicationのClient Secret>"
          authorizationUrl: "https://<GitLabのURL>/oauth/authorize"
          tokenUrl: "https://<GitLabのURL>/oauth/token"

適宜自分の環境に合わせてパラメータを編集してデプロイします。

KeycloakRealmImportがデプロイされるとJobが起動し、Keycloak Podが再起動します。再度ログインすると以下のようにRealm、Client、Identity Providerが作成されています。

このGitLabのIdentity ProviderにあるRedirect URIの値をコピーしておきましょう。

GitLab Applicationの変更

GitLab Applicationにダミーで登録したRedirect URIを、コピーしてきた値に変更します。

これで認証周りの実装は完了しました。

次にDeveloper HubがGitLabからUserやGroup情報を読み込むために必要なアクセストークンを払い出します。 GroupのページからSettings→Access tokens→Add new tokenを選択して、以下の内容を入力します。

Token name 任意の値
Token description 任意記入
Expiration date 任意記入
Select a role Developer
Select scopes api
read_repository
write_repository

作成するとYour new project access tokenにアクセストークンが払い出されるので、これをコピーしておきます。

Developer Hubの設定変更

Developer Hubからこのファイルを読み込むための設定をします。

最初はdynamic-plugins-rhdh.yamlにGitLab pluginのインストール設定を記入します。

dynamic-plugins-rhdh.yaml

kind: ConfigMap
apiVersion: v1
metadata:
  name: dynamic-plugins-rhdh
  namespace: rhdh
  annotations:
    rhdh.redhat.com/backstage-name: developer-hub
data:
  dynamic-plugins.yaml: |
    includes:
      - 'dynamic-plugins.default.yaml'
    plugins:
    # GitHub Plugins
      - package: ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic
        disabled: false

    # GitLab Plugins ←GitLab用のPluginを追記
      - package: ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-dynamic  # GitLab APIからデータを取得するための「専用の裏口（Proxy/API）」を提供
        disabled: false

      - package: ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-org-dynamic # GitLabの「グループ」や「ユーザー」の構造を、RHDHのUser/Groupエンティティとして同期
        disabled: false

次に app-config-rhdh.yaml を編集します。以下のように、auth , integrations , signInPage , catalog の設定を追記・編集します。

  • auth : Developer Hubの認証に関する設定
  • integrations : GitHubなどの外部システムとの統合（連携）に関する設定
  • signInPage : ログインするときに表示されるサインインページを指定する設定
  • catalog : Developer HubにさまざまなEntity(Catalog)を登録するための設定

app-config-rhdh.yaml

kind: ConfigMap
apiVersion: v1
metadata:
  name: app-config-rhdh
  namespace: rhdh
  annotations:
    rhdh.redhat.com/backstage-name: developer-hub
data:
  app-config-rhdh.yaml: |
    app:
    ...omit...
    backend:
    ...omit...
    auth:
      providers:
        gitlab: # GitLabの情報を追記
          production:
            clientId: ${AUTH_GITLAB_CLIENT_ID}
            clientSecret: ${AUTH_GITLAB_CLIENT_SECRET}
            signIn:
              resolvers:
                - resolver: usernameMatchingUserEntityName
        oidc: # OIDC(Keycloak)の情報を追記
          production:
            clientId: ${KEYCLOAK_CLIENT_ID}
            clientSecret: ${KEYCLOAK_CLIENT_SECRET}
            metadataUrl: https://${KEYCLOAK_BASE_URL}/realms/${KEYCLOAK_REALM}
            prompt: auto
            signIn:
              resolvers:
                - resolver: preferredUsernameMatchingUserEntityName
    signInPage: oidc # SigninページをOIDC(Keycloak)に設定
    integrations:
      github:
      ...omit... 
      gitlab: # GitLabの情報を追記
        - host: ${GITLAB_HOST}
          apiBaseUrl: https://${GITLAB_HOST}/api/v4
          token: ${GITLAB_TOKEN}

    catalog:
      rules:
      - allow:
        - User
        - Group
      providers:
        gitlab: # GitLabの情報を追記
          gitlabProvider:
            host: ${GITLAB_HOST}
            orgEnabled: true
            allowInherited: true
            group: ${GITLAB_GROUP}
            rules:
              - allow:
                - Group
                - User
                - Location
            schedule:
              frequency: PT60S
              initialDelay: PT30S
              timeout: PT120S

導入したGitLab Pluginとcatalog.providers.gitlabの設定によって、Developer Hubが定期的に該当のGroupのユーザー情報を取得します。

最後にsecrets-rhdh.yamlも修正して必要な値を追加しておきましょう。

apiVersion: v1
kind: Secret
metadata:
  name: secrets-rhdh
  namespace: rhdh
stringData:
  ...omit...
  # GitLab Settings
  GITLAB_GROUP: "<GitLabのGroup名>"
  GITLAB_HOST: "<GitLabのURL(https://は不要)>"
  GITLAB_TOKEN: "<取得したGitLab アクセストークン>"
  AUTH_GITLAB_CLIENT_ID: "<作成したGitLab ApplicationのApplication ID>"
  AUTH_GITLAB_CLIENT_SECRET: "<作成したGitLab ApplicationのSecret>"

  # Keycloak Settings
  KEYCLOAK_BASE_URL: "<KeycloakのURL(http://は不要)>"
  KEYCLOAK_CLIENT_ID: "rhdh"
  KEYCLOAK_CLIENT_SECRET: "<KeycloakRealmImportに設定したsecretの値>"
  KEYCLOAK_LOGIN_REALM: "rhdh"
  KEYCLOAK_REALM: "rhdh"

これらをデプロイします。

oc apply -f app-config-rhdh.yaml -f secrets-rhdh.yaml -f dynamic-plugins-rhdh.yaml

Podの再起動後、ログインしてみると、無事にHOME画面が表示されます。

OIDCのSign Inを選択すると、Keycloakのログイン画面が表示されるので、下の方のGitLabマークを選択します。

するとGitLabのページに飛ぶので、Authorize rhdhを選択するとKeycloakの画面に戻ります。ここでFirst nameやLast nameを追記します。ここで設定したFirst nameやLast nameはDeveloper Hubにも反映されます。なお、Usernameの項目は変更NGです。

Submitを選択すると、無事にDeveloper Hubにログインできます。

Settingsに移動すると、先ほど設定したFirst nameやLast nameが反映されていたり、Backstage Identityを見ると、作成したGroup/User Entityに紐づいていることも確認できます。

おわりに

今回はGitLabと連携してDeveloper Hubの認証を実装する方法を解説しました。

次回の記事以降でいよいよDeveloper Hubの中身に触れていきます。乞うご期待！



以上の内容はhttps://rheb.hatenablog.com/entry/rhdh-practice-03より取得しました。
このページはhttp://font.textar.tv/のウェブフォントを使用してます
不具合報告/要望等はこちらへお願いします。
モバイルやる夫Viewer Ver0.14