NOGIKU

開発環境のセットアップ ​

ここでは、開発環境のセットアップ方法を説明します。

Nogiku Auth + Nogiku Access の開発を行う開発者は 3 まで、外部システムの Nogiku SSO を検証したい開発者は 4-1 まで、外部システムが Nogiku Access API を利用した権限管理を実装している場合は 4-3 までセットアップを完了する必要があります。

1. 初回起動 ​

1-1. リポジトリのクローン ​

bash
git clone git@github.com:UTokyo-Festival-Union/nogiku.git
cd nogiku

1-2. Node.js と pnpm のインストール ​

NOTE: このプロジェクトでは mise を使用して Node.js と pnpm をインストールすることを推奨します。

bash
mise install

1-3. 依存関係をインストールします ​

bash
pnpm install

1-4. Docker コンテナの起動 ​

このプロジェクトでは、データストアに PostgreSQL と Redis を使用します。

この２つについては、開発用の Docker ファイルが用意されています。

bash
docker compose up -d

1-5. 環境変数の設定 ​

各 .env.example を .env にコピーし、必要に応じて値を編集します。

bash
pnpm generate:env # 各 .env.example を .env にコピー

既存の .env の値を無視して強制的に .env.example の内容で置き換える場合は pnpm generate:env:force を使います。

1-6. データベースのマイグレーション適用 ​

bash
pnpm -C packages/db-auth db:migrate
pnpm -C packages/db-access db:migrate

1-7. アプリケーションの起動 ​

すべてのアプリをまとめて起動:

bash
pnpm dev

個別に起動する場合:

bash
pnpm -C apps/auth dev
pnpm -C apps/access-engine dev
pnpm -C apps/access-studio dev
pnpm -C apps/doc dev
pnpm -C workers/sync-identity dev

2. Nogiku アカウント作成 & Auth 管理者権限の取得 ​

2-1. サインアップ ​

Nogiku Auth（http://localhost:3500）にアクセスして、「新規登録はこちら」からアカウント作成を行ってください。

新規登録を終えると、6桁のワンタイムコードが記載されたメール本文がターミナルに出力されます。

このコードを遷移先のページにペーストしてメール認証を完了してください。

2-2. サインイン ​

メールアドレスとサインアップ時に設定したパスワードを入力してサインインします。

メールアドレスは、既定で {10桁の共通ID}@g.ecc.u-tokyo.ac.jp が割り振られています。

2-3. 管理者権限の取得 ​

以下のコマンドを実行して、Nogiku Auth のデータベースを開きます。

bash
pnpm -C packages/db-auth exec prisma studio

User テーブルのうち、いまサインアップで作成した行の User.role カラムを "admin" に変更してください。

Nogiku Auth（http://localhost:3500）をリロードして「管理コンソール」が表示されるようになれば成功しています。

3. Nogiku Auth + Access 連携 ​

3-1. OAuth クライアントの作成 ​

OAuth クライアント管理ページ（http://localhost:3500/admin/clients）にアクセスして、「追加」から Nogiku Access のクライアント設定を行います。

アプリ名は「Nogiku Access」、リダイレクト URI は http://localhost:4000/studio/auth/callback/nogiku としてください。

他の設定は既定値のまま変更せず、「保存」して作成を完了してください。

このとき、秘密鍵（client secret）が一度だけ表示されます。値をコピーしてから閉じてください。

3-2. 環境変数の設定 ​

生成された Client ID 及び Client Secret を、apps/access-engine/.env に設定します。

apps/access-engine/.env を開き、以下の環境変数を書き換えてください。

bash
OIDC_CLIENT_ID= # Client ID
OIDC_CLIENT_SECRET= # Client Secret（秘密鍵）

3-3. サインイン ​

Nogiku Access Studio（http://localhost:5173）にアクセスして、サインインできることを確認してください。

サインインに失敗する場合は、上の OAuth クライアントの設定または環境変数に誤りがないか再度チェックしてください。

4. 外部システム連携 ①（Relying Party） ​

4-1. Nogiku SSO セットアップ ​

上記 3-1 及び 3-2 同様に OAuth クライアントを作成し、連携先システムの環境変数に秘密情報を設定してください。

このとき、設定すべきリダイレクト URI と環境変数名はシステムごとに異なるため、注意してください。

Nogiku Auth の SSO 機能のみを利用する外部システムの場合、これにて設定は完了です。

NOTE：Nogiku Access API を利用する外部システム（主に、権限管理を Nogiku Access に任せるもの）では、SSO 時に追加のスコープを要求するため、この先のセットアップを完了するまで SSO に失敗します。このまま先へ進んでください。

4-2. Nogiku Access リソースサーバーの作成 ​

リソースサーバー管理ページ（http://localhost:3500/admin/resource-servers） にアクセスして、「追加」から Nogiku Access リソースサーバー設定を行います。

名前は「Nogiku Access API」、Audience は http://localhost:4000/api としてください。

作成が済んだら、作成されたリソースサーバーのアクションから「スコープを管理」を開き、以下のスコープを作成してください。

  • users.read - Nogiku Access ユーザー情報の読み取り
  • permissions.read - Nogiku Access システム権限情報の読み取り

4-3. OAuth クライアントとの紐づけ ​

OAuth クライアント管理ページ（http://localhost:3500/admin/clients）に戻り、4-1 で作成した OAuth クライアントの設定を編集します。

4-2 で作成したリソースサーバーにチェックを入れ、外部システムが必要とするスコープを追加してください。

このとき、スコープは http://localhost:4000/api/permissions.read のように 「Audience + スコープ名」の形式で指定する必要があります。

5. 外部システム連携 ②（Resource Server） ​

上記 4-2 同様にリソースサーバーを作成してください。

NOTE：Resource Server では、Nogiku Auth の /jwks エンドポイントから取得した jwks を使ってアクセストークンを検証し、payload の iss aud クレームの妥当性を確認してください。