静的アクセストークンによるAPIアクセス制限の方法

KurocoのAPIセキュリティについて

KurocoのAPIセキュリティは下記５つから選択できます。

• 無し
• 静的アクセストークン
• 動的アクセストークン
• Cookie
• 特権付き静的トークン

一時的な開発用APIを作成してテストをする場合や、完全にオープンなデータを利用する場合は「無し」を設定できます。

しかしながら、APIのセキュリティ設定を「無し」にしてしまうと誰でもAPIが利用できるようになり、外部から無差別にAPIリクエストを受け付けることが可能になります。

この状態が想定通りではない場合、静的アクセストークン機能を利用することである程度の制限をかけることができます。
今回は静的アクセストークンを利用してアクセス制限をかける方法を説明します。

注意

静的アクセストークンの文字列は公開サイトのネットワーク通信やJSファイル内の記述を参照することで外部からも閲覧可能な情報となります。その為、セキュアな情報に対する制限をかけたい場合は静的アクセストークンではなく動的アクセストークン・Cookie制限によるログイン認証やAPIに閲覧グループによる制限をかける形で対応をしてください。

静的アクセストークンによるAPIアクセス制限方法

静的アクセストークンによるAPIアクセス制限の方法を説明します。

1. KurocoのAPIのセキュリティを設定する

任意のAPI一覧ページから[セキュリティ]をクリックします。

「セキュリティ」を静的アクセストークンに変更し、[保存する]をクリックします。

2.静的アクセストークンを発行する

API一覧ページから[Swagger UI]をクリックします。

Swagger画面の上部にある 「静的アクセストークン」 の「有効期限」より有効期限を設定し、[生成する]をクリックします。

トークンが発行されます。後ほど利用するのでコピーしておいてください。

以上でKuroco管理画面での操作は完了です。

3. APIアクセスの設定

一例としてNuxt3とNext.jsのコードを記載しています。

備考

本チュートリアルでは以下のバージョンでコードを書いています。

• Nuxt3: v3.14.0
• Next.js: v15.0.3 (Using App Router)

まず、チュートリアルで必要なパッケージをインストールします：

Nuxt3

Nuxt 3では追加のパッケージのインストールは不要です。

Next.js

terminal

npm install axios

4. 環境変数の設定

Nuxt3

.env

NUXT_STATIC_TOKEN=YOUR_STATIC_TOKEN_HERE
NUXT_PUBLIC_API_BASE_URL=https://your-api-endpoint.com

Next.js

.env

STATIC_TOKEN=YOUR_STATIC_TOKEN_HERE
NEXT_PUBLIC_API_URL=https://your-api-endpoint.com

注意

NUXT_PUBLIC_/NEXT_PUBLIC_プレフィックスがつく環境変数は、クライアントサイドで参照可能になります。詳細は下記のリンクをご確認ください。

• Nuxt 3 Documents - runtime-config
• Next.js Documents - environment-variables

5. 設定ファイルの更新

Nuxt3

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      staticToken: process.env.NUXT_STATIC_TOKEN,
      publicApiBaseUrl: process.env.NUXT_PUBLIC_API_BASE_URL
    }
  }
})

Next.js

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  env: {
    STATIC_TOKEN: process.env.STATIC_TOKEN
  }
}

module.exports = nextConfig

6. APIのリクエストヘッダーに静的アクセストークンを設定する

Nuxt3

/plugins/fetch.ts

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig()

  return {
    provide: {
      customFetch: (url: string, options = {}) => {
        return useFetch(url, {
          baseURL: config.public.apiBase as string,
          headers: {
            'x-rcms-api-access-token': config.public.staticToken as string
          },
          ...options
        })
      }
    }
  }
})

備考

Kurocoビギナーズガイドでは plugins の利用方法はカバーしていませんが、この機会に公式ドキュメントでぜひ触れてみてください。

• Nuxt 3 Documents - plugins

Next.js

/lib/axios.ts

import axios from 'axios'

export const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  headers: {
    'x-rcms-api-access-token': process.env.STATIC_TOKEN
  }
})

7. APIの使用例

Nuxt3

/pages/example.vue

<script setup>
// 基本的な使用例
const { $customFetch } = useNuxtApp()
const { data: response } = await $customFetch('/api/endpoint');

// 個別にヘッダーを上書きする例
const { $customFetch } = useNuxtApp()
const { data: customData } = await $customFetch('/api/endpoint', {
  headers: {
    'x-rcms-api-access-token': 'different-token'
  }
}
</script>
<template>
  <div>
    <div v-if="pending">Loading...</div>
    <div v-else>
      <pre>{{ data }}</pre>
    </div>
  </div>
</template>

Next.js

/app/example.tsx

// APIクライアントを使用する場合
import { api } from '@/lib/axios'

export default function Page() {
  const [data, setData] = useState(null)

  useEffect(() => {
    const fetchData = async () => {
      const response = await api.get('/api/endpoint')
      setData(response.data)
    }
    fetchData()
  }, [])

  return <div>{/* データの表示 */}</div>
}

// または組み込みfetchを使用する場合
async function getData() {
  const res = await fetch('https://api-endpoint.com/api/endpoint', {
    headers: {
      'x-rcms-api-access-token': process.env.STATIC_TOKEN
    }
  })
  return res.json()
}

// App RouterのServer Componentで使用する場合
export default async function Page() {
  const data = await getData()
  return <div>{/* データの表示 */}</div>
}

備考

• Nuxt 3: useFetch/$fetchを使用し、自動的にヘッダーに静的トークンが付与される例を紹介しました。
• Next.js: fetchまたはaxiosを使用し、リクエストヘッダーに静的トークンを設定する例を紹介しました。

ヒント

• リクエストヘッダーに、X-RCMS-API-ACCESS-TOKEN をキーとして静的アクセストークンを設定し、リクエストを送信することでデータ取得が可能です。

注意

・プロジェクトにあわせて、実際には .env や .env.local など別ファイルに記述することをお勧めします。 環境変数のファイルは必ず.gitignoreに追加し、機密情報をリポジトリにコミットしないようにしてください。

以上で静的アクセストークンによるAPIアクセス制限の設定が完了です。

特権付き静的トークンによるAPIアクセス制限方法

特権付き静的トークンは、静的アクセストークンと同様のトークン認証ですが、トークン生成時に特定のメンバーを指定します。
指定したメンバーの権限でリクエストが実行されるため、ログインや動的トークン生成のフローを経ることなく、メンバーの権限に基づいたAPIリクエスト制限のあるエンドポイントにアクセスできます。
サーバー間通信で、特定のメンバーの権限でAPIにアクセスする必要がある場合などに利用します。

リクエストヘッダーへのトークンの設定方法やフロントエンドからの利用方法は静的アクセストークンと同じです。ここでは、静的アクセストークンと異なる管理画面での操作を説明します。

1. セキュリティを特権付き静的トークンに設定する

API画面より、セキュリティの[設定]をクリックし、「セキュリティ」を[特権付き静的トークン]に変更して[更新する]をクリックします。

2. 特権付き静的トークンを発行する

API情報画面の[特権付き静的トークン]の[生成する]をクリックし、表示されたダイアログで以下の項目を指定します。

• 有効期限: トークンの有効期限を指定します。
• メモ: 任意のメモを入力できます。
• メンバーID: トークンに紐付けるメンバーのIDを指定します。このメンバーの権限でAPIリクエストが実行されます。

値を入力したら[生成する]をクリックします。トークンが発行されるので、後ほど利用するのでコピーしておいてください。

3. APIアクセスの設定

リクエストヘッダーへの特権付き静的トークンの設定方法は、静的アクセストークンと同じです。
上記「3. APIアクセスの設定」〜「7. APIの使用例」のコードで、環境変数に設定するトークンの値を特権付き静的トークンの値に置き換えることで、そのまま利用できます。
リクエストヘッダーには、静的アクセストークンと同様に X-RCMS-API-ACCESS-TOKEN をキーとしてトークンを設定します。

注意

特権付き静的トークンは、指定したメンバーの権限でリクエストを実行します。そのため、適切な権限を持つメンバーを指定してトークンを生成してください。
また、静的アクセストークンと同様にトークンの文字列が流出するリスクがあるため、トークンの更新を想定したシステム構成にし、機密情報をリポジトリにコミットしないようにしてください。

以上で特権付き静的トークンによるAPIアクセス制限の設定が完了です。

参考

• API Security
• Swagger UIを利用して、APIのセキュリティを確認する

関連ドキュメント

• API セキュリティ
• Swagger UIを利用して、APIのセキュリティを確認する
• ログイン画面を構築する
• エンドポイント設定後の注意点
• 静的アクセストークンの有効期限が切れる前に通知は届きますか？