UCIDM API

UCIDM は ID 連携のための Web API を提供します。

• 環境変数の設定
  • API サーバー
    • primaryID
  • ミドルウェア
  • メールサーバー
    • SMTP プロトコルの OAuth 2.0 認証
  • パスワードリセットメール
    • パスワードリセット向けメールのテンプレートファイル
    • 一時トークンを送付するメールテンプレートのサンプル
    • パスワードリセット完了を連絡するメールテンプレートのサンプル
  • OAuth 認証
  • LDAP サーバー
  • SAML 認証
    • SAML 認証の捕捉

さまざまな機能を提供します。

• ユーザ操作
• グループ操作
• 外部連携先設定操作
• 履歴情報一覧
• ジョブ進捗概要取得
• ジョブ詳細情報取得
• LDAP サーバー管理

UCIDM API はコンテナとして稼働させます。次のように compose.yml に設定します。

  api:
    depends_on:
      mongo:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
    container_name: api
    hostname: api
    image: docker.io/osstech/ucidm-api:latest
    logging: *default-logging
    volumes:
      - type: bind
        source: ./server-data
        target: /ucidm
        bind:
          create_host_path: false
      - type: bind
        source: ./server-data/files
        target: /files
        bind:
          create_host_path: true
      #- type: bind
      #  source: ./path/to/example.crt
      #  target: /saml/ucidm_samlsp.crt
      #  read_only: true
      #  bind:
      #    create_host_path: false
      #- type: bind
      #  source: ./path/to/example.key
      #  target: /saml/ucidm_samlsp.key
      #  read_only: true
      #  bind:
      #    create_host_path: false
    entrypoint:
      - ./bin/entrypoint.sh
      - -port
      - ${API_PORT}
      - -jsonl
    environment:
      TZ: "${TZ}"
      AMQP_URL: "${AMQP_URL}"
      MONGO_USER: "${MONGO_USER}"
      MONGO_PASSWORD: "${MONGO_PASSWORD}"
      MONGO_HOSTS: "${MONGO_HOSTS}"
      MONGO_REPLICA_SET: "${MONGO_REPLICA_SET}"
      JWT_SECRET_KEY: "${JWT_SECRET_KEY}"
      JWT_ACCESS_EXPIRATION_TIME: "${JWT_ACCESS_EXPIRATION_TIME}"
      JWT_REFRESH_EXPIRATION_TIME: "${JWT_REFRESH_EXPIRATION_TIME}"
      XFF_TRUST_IP_RANGES: "${XFF_TRUST_IP_RANGES}"
      ID_FEDERATION_CLIENT_HOST: "${ID_FEDERATION_CLIENT_HOST}"
      SMTP_HOST: "${SMTP_HOST}"
      SMTP_PORT: "${SMTP_PORT}"
      SMTP_AUTH_USERNAME: "${SMTP_AUTH_USERNAME}"
      SMTP_AUTH_PASSWORD: "${SMTP_AUTH_PASSWORD}"
      SMTP_USE_TLS: "${SMTP_USE_TLS}"
      PASSWORD_RESET_MAIL_SENDER: "${PASSWORD_RESET_MAIL_SENDER}"
      PASSWORD_RESET_REQUEST_MAIL_TEMPLATE_FILE: "${PASSWORD_RESET_REQUEST_MAIL_TEMPLATE_FILE}"
      PASSWORD_RESET_SUCCESS_MAIL_TEMPLATE_FILE: "${PASSWORD_RESET_SUCCESS_MAIL_TEMPLATE_FILE}"
      PASSWORD_RESET_LDAP_MAIL_ATTRIBUTE: "${PASSWORD_RESET_LDAP_MAIL_ATTRIBUTE}"
      # USER_PRIMARY_ID_TEMPLATE: "${USER_PRIMARY_ID_TEMPLATE}"
      # GROUP_PRIMARY_ID_TEMPLATE: "${GROUP_PRIMARY_ID_TEMPLATE}"
      LDAP_SCHEME: "${AGENT_LDAP_SCHEME}"
      LDAP_HOSTS: "${AGENT_LDAP_HOSTS}"
      LDAP_PORT: "${AGENT_LDAP_PORT}"
      LDAP_SECURE_SKIP: "${AGENT_LDAP_SECURE_SKIP}"
      # SSL_CERT_FILE: "${SSL_CERT_FILE}"
      LDAP_BIND_DN: "${AGENT_LDAP_BIND_DN}"
      LDAP_BIND_PASSWORD: "${AGENT_LDAP_BIND_PASSWORD}"
      LDAP_SEARCH_BASE: "${AGENT_LDAP_SEARCH_BASE}"
      LDAP_USER_SEARCH_BASE: "${AGENT_LDAP_USER_SEARCH_BASE}"
      LDAP_USER_SEARCH_FILTER: "${AGENT_LDAP_USER_SEARCH_FILTER}"
      LDAP_GROUP_SEARCH_BASE: "${AGENT_LDAP_GROUP_SEARCH_BASE}"
      LDAP_GROUP_SEARCH_FILTER: "${AGENT_LDAP_GROUP_SEARCH_FILTER}"
      LDAP_GROUP_MEMBER_ATTRIBUTE: "${AGENT_LDAP_GROUP_MEMBER_ATTRIBUTE}"
      # SAML_SP_ENTITY_ID: "${SAML_SP_ENTITY_ID}"
      # SAML_SP_ROOT_URL: "${SAML_SP_ROOT_URL}"
      # SAML_SP_IDP_METADATA_URL: "${SAML_SP_IDP_METADATA_URL}"
      # SAML_SP_TLS_SKIP_VERIFY_FETCH_IDP_METADATA: "${SAML_SP_TLS_SKIP_VERIFY_FETCH_IDP_METADATA}"
      # SAML_SP_COOKIE_EXP_TIME: "${SAML_SP_COOKIE_EXP_TIME}"
    ports:
      - 127.0.0.1:${API_PORT}:${API_PORT}
    restart: "always"

ここで参照する環境変数は .env に設定します。

環境変数の設定

API サーバー

• ID_FEDERATION_CLIENT_HOST (外部連携モジュールのコンテナ) はバージョン情報を取得するときの宛先を設定します

  • 複数の外部連携モジュールのコンテナを利用していたとしても、どれか1つのコンテナのポート番号を指定します
  • ここで取得されるバージョン情報は 1 時間キャッシュされます。外部連携モジュールのコンテナを更新したとき、最大 1 時間はバージョン情報が更新されない可能性があります

• API サーバーは X-Forwarded-For (以下 XFF) ヘッダーを参照してリクエスト元 IP アドレスを履歴に記録します

  • 信頼できるネットワークはカンマ区切りで複数指定できます
    • 設定例) 192.168.0.1/24,172.16.0.0/12,2001:db8::/64
  • 指定しないときはコンテナネットワークのゲートウェイ (172.18.0.1) がリクエスト元 IP アドレスとなります

• JWT_ACCESS_EXPIRATION_TIME/JWT_REFRESH_EXPIRATION_TIME の有効期限は次の記法で設定します

  • 5 秒に設定する場合 “5s” を環境変数に設定します
  • 5 分に設定する場合 “5m” を環境変数に設定します
  • 5 時間に設定する場合 “5h” を環境変数に設定します
  • 日数は時間に変換して設定します。5 日の場合 “120h” を環境変数に設定します

primaryID

UCIDM では、各ユーザー/グループを一意に識別するための ID として primaryID を使用します。

primaryID はデフォルトでは DN 文字列の RDN0 の値が割り当てられます。

例) cn=test1,ou=people,dc=example,dc=com という DN であれば test1 が primaryID になる

ここで primaryID は必ず一意となるように設定する必要があります。仮に DN 文字列の RDN0 の値のみだと競合してしまうような場合は USER_PRIMARY_ID_TEMPLATE と GROUP_PRIMARY_ID_TEMPLATE のテンプレート文字列を使って一意になるような値を割り当ててください。

例) “%{cn}-%{uid}” と設定した場合、属性の cn=test1, uid=101 ならば test1-101 が primaryID になる

primaryID は、Microsoft Entra ID、Google Workspace、AD、SCIM の外部サービスへの連携において主要なキー情報として連携されます。仕様上の制約 もご確認ください。

ミドルウェア

メールサーバー

SMTP プロトコルの OAuth 2.0 認証

Google Workspace では SMTP サーバーと OAuth 2.0 認証 を行うことが推奨されています。次のツールを使ってクライアントシークレットと認証コードからリフレッシュトークンを取得できます。リフレッシュトークンがないと、アクセストークンの有効期限が切れたときに再取得できません。ツールを実行すると、クライアントシークレットと認証コードが求められるので入力します（入力時、文字は表示されません）。

./bin/oauth -clientID <OAuth 2.0 認証で使用するクライアントID> -redirectURL <OAuth 2.0 認証で設定したリダイレクトURL> -authURL <OAuth 2.0 認証の認証エンドポイント> -tokenURL <OAuth 2.0 認証のトークンエンドポイント> -scope <OAuth 2.0 認証で設定したスコープ>

出力

access token: xxxxa0AfB_byAY5...
refresh token: yyyy0elQbS2Fscsi5...

パスワードリセットメール

パスワードリセット向けメールのテンプレートファイル

アカウントのパスワードを忘れたときにメールを送信してパスワードリセットできます。メールのテンプレートファイルを使ってパスワードリセットメールをカスタマイズできます。

メールのテンプレートファイルでは、次のフィールドに対してテンプレート変数を使ってカスタマイズします。

以下の変数をテンプレートファイルに記述することで、値が入ったメール送信が可能になります。

テンプレートファイルのサンプル設定は次になります。メールヘッダーと本文の間には空行を入れてください。

一時トークンを送付するメールテンプレートのサンプル

From: 送信者名 <{{.SenderMailAddress}}>
To: {{.UserName}} <{{.UserMailAddress}}>
Reply-To: 返信しないで <no-reply@osstech.co.jp>
Subject: パスワードリセット

パスワードをリセットするための一時トークンを送ります。
このトークンを使って管理画面からパスワードリセットしてください。

一時トークン: {{.TemporaryToken}}

一定時間経過するとパスワードリセットができなくなります。

パスワードリセット完了を連絡するメールテンプレートのサンプル

From: 送信者名 <{{.SenderMailAddress}}>
To: {{.UserName}} <{{.UserMailAddress}}>
Subject: パスワードリセット成功

新しいパスワードに更新されました。

OAuth 認証

LDAP サーバー

• LDAP サーバーで管理している LDAP ユーザーエントリーのパスワード変更に関して API サーバーでは平文パスワードのハッシュ化は行いません。LDAP サーバーの設定で ppolicy_hash_cleartext を使ってハッシュ化してください
• LDAP_CREDENTIALS_SEARCH_BASE に所属する ou=Credentials から FIDO2 エントリーを検索します
  • LDAP_CREDENTIALS_SEARCH_BASE を設定しない場合、LDAP_SEARCH_BASE の値を使います
• 登録／更新リクエストのログ出力から userPassword と unicodePwd は必ず除外されます

SAML 認証

UCIDM の SAML 認証にて使用する証明書ファイルおよび鍵ファイルについては、compose.yml ファイルの api の volumes 設定において、それぞれ /saml/ucidm_samlsp.crt と /saml/ucidm_samlsp.key のファイルに紐付けを行う必要があります。これらのファイルはコンテナで動作するアプリケーションにて参照されます。

SAML 認証の捕捉

SAML_SP_ENTITY_ID の値を設定することで、SAML 認証が有効になります。

SAML_SP_ROOT_URL の値を使って SAML 関連のエンドポイントが定義され、メタデータに反映されます。この値はユーザープロファイルのアクセスホスト名：ポート番号を使って、以下のように設定してください。

• ＜プロトコル＞://＜ユーザープロファイル画面の HOST ＞:＜ PORT ＞/ui/user/api/

SAML_SP_CERTIFICATE_FILE および SAML_SP_KEY_FILE にて SAML SP の証明書およびキーファイルのパスを設定します。

SAML IdP のメタデータを IdP からメタデータをダウンロードし、そのメタデータを配置したパスを SAML_SP_IDP_METADATA_FILE にて設定してください。

API 起動時に SAML IdP のメタデータを指定した URL から 取得したい場合、SAML_SP_IDP_METADATA_URL にその URL を設定します。（IdP にて自己証明書を使っている場合は、SAML_SP_TLS_SKIP_VERIFY_FETCH_IDP_METADATA を true に設定する必要があります。）

SAML 認証時、認証されたユーザーに ldap 以外の認証タイプ、デフォルトで ldap-user 以外のロールを指定する場合は、SAML_SP_AUTH_TYPE および SAML_SP_ROLE_NAME の値を設定します。

SAML 認証 も合わせてご確認ください。