UCIDM API

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

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

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

外部連携モジュールから名前付きパイプを介してバージョン情報を受け取ります。設定の詳細については コンテナ間のデータ連携 を参照してください。この情報は 1 時間キャッシュされます。外部連携モジュールのコンテナを更新したとき、最大 1 時間はバージョン情報が更新されない可能性があります。

  api:
    depends_on:
      mongo:
        condition: service_started
      rabbitmq:
        condition: service_healthy
    container_name: api
    hostname: api
    image: docker.io/osstech/ucidm-api:latest
    logging: *default-logging
    volumes:
      - ./server-data:/ucidm
      - ./volumes/id-federation-client-pipe:${ID_FEDERATION_CLIENT_PIPE}
    entrypoint:
      - ./bin/entrypoint.sh
      - -port
      - ${API_PORT}
      - -jsonl
    environment:
      AMQP_URL: "${AMQP_URL}"
      MONGO_USER: "${MONGO_USER}"
      MONGO_PASSWORD: "${MONGO_PASSWORD}"
      MONGO_HOSTS: "${MONGO_HOSTS}"
      MONGO_REPLICA_SET: "${MONGO_REPLICA_SET}"
      BASIC_AUTH_PASSWORD: "${BASIC_AUTH_PASSWORD}"
      JWT_SECRET_KEY: "${JWT_SECRET_KEY}"
      JWT_ACCESS_EXPIRATION_TIME: "${JWT_ACCESS_EXPIRATION_TIME}"
      JWT_REFRESH_EXPIRATION_TIME: "${JWT_REFRESH_EXPIRATION_TIME}"
      MAX_PRODUCER_SESSIONS: "${MAX_PRODUCER_SESSIONS}"
      ID_FEDERATION_CLIENT_PIPE: "${ID_FEDERATION_CLIENT_PIPE}"
      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}"
      # 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}"
      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_USER_ENABLED_ATTRIBUTE: "${AGENT_LDAP_USER_ENABLED_ATTRIBUTE}"
      LDAP_GROUP_SEARCH_BASE: "${AGENT_LDAP_GROUP_SEARCH_BASE}"
      LDAP_GROUP_SEARCH_FILTER: "${AGENT_LDAP_GROUP_SEARCH_FILTER}"
      # SAML_SP_ENTITY_ID: "${SAML_SP_ENTITY_ID}"
      # SAML_SP_ROOT_URL: "${SAML_SP_ROOT_URL}"
      # SAML_SP_CERTIFICATE_FILE: "${SAML_SP_CERTIFICATE_FILE}"
      # SAML_SP_KEY_FILE: "${SAML_SP_KEY_FILE}"
      # 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}"
    ports:
      - ${API_PORT}:${API_PORT}
    restart: "always"

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

環境変数の設定

環境変数設定の補足

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 の外部サービスへの連携において主要なキー情報として連携されます。仕様上の制約 もご確認ください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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...

SAML 認証

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

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

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

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

SAML IdP のメタデータが URL にて取得可能な場合、SAML_SP_IDP_METADATA_URL にその URL を設定します。（IdP にて自己証明書を使っている場合は、SAML_SP_TLS_SKIP_VERIFY_FETCH_IDP_METADATA を true に設定する必要があります。）

SAML IdP のメタデータが URL にて取得可能でない場合、IdP からメタデータをダウンロードし、そのメタデータを配置したパスを SAML_SP_IDP_METADATA_FILE にて設定してください。

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

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