ユーザーと権限（Users & Permissions）

Page summary:
Users & Permissions はエンドユーザーアカウント、JWT 認証、API へのロールベースのアクセスを扱います。このページではロールの作成、権限の設定、安全なアクセス用の API トークンについて説明します。

Users & Permissions は、Strapi プロジェクトのエンドユーザーを管理します。エンドユーザーとは、 JSON Web Token（JWT）に基づく認証で API を保護し、グループごとに権限を扱う ACL（アクセス制御リスト）を提供します。

プラン

無料で利用可能

ロールと権限

Roles > Plugins - Users & Permissions で CRUD 権限

有効化

既定で利用可能

環境

開発環境・本番環境の両方で利用可能

管理パネルでの設定

Users & Permissions は、管理パネルの設定とコードの両方から設定します。

ロール

エンドユーザー向けのロールを作成・管理し、どの操作にアクセスできるかを設定できます。

新しいロールを作成する

場所: Users & Permissions プラグイン > Roles

Roles 画面の右上に Add new role があります。Strapi アプリのエンドユーザー向けに新しいロールを作れます。

Add new role をクリックするとロール編集画面へ移動し、名前・詳細・権限を設定します（ロールを編集するも参照）。

Note

新規エンドユーザーに既定で付与するロールは、Users & Permissions プラグイン の Advanced settings で指定します（高度な設定を参照）。

ロールを編集する

場所: Users & Permissions プラグイン > Roles

Roles 画面には、エンドユーザー向けに作成したロールが一覧表示されます。

既定では、どの Strapi アプリにも次の 2 つのロールがあります。

Authenticated — フロントアプリにログインしたエンドユーザーのみコンテンツにアクセスできるようにする。
Public — ログインしていないエンドユーザーでもコンテンツにアクセスできるようにする。

ほかにもロールを追加できます（新しいロールを作成する）。いずれもロール編集画面から編集できます。

編集するロールのをクリックします（新規作成の流れで既に編集画面にいる場合は不要）。
次の表に従って Role details を入力します。

Role details	手順
Name	テキストボックスにロール名を入力します。
Description	テキストボックスに説明を入力します。管理者がロールの権限の範囲を把握できる内容にします。

エンドユーザーロールの Permissions を設定します。
1. 設定する権限カテゴリ名をクリックします（例: Application、Content-Manager、Email など）。
2. ロールに付与するアクションと権限のチェックボックスをオンにします。
Save をクリックします。

Tip

アクションや権限のチェックを入れると、関連する API のルートが画面右側に表示されます。

ロールを削除する

場所: Users & Permissions プラグイン > Roles

既定の 2 ロールは削除できません。それ以外は、まだそのロールがアカウントに付いているエンドユーザーがいなければ削除できます。

対象ロールの右側の削除をクリックします。
確認ダイアログで Confirm をクリックして削除します。

プロバイダー

場所: Users & Permissions プラグイン > Providers

サードパーティのプロバイダーでログインし、Strapi の API 経由でフロントのコンテンツにアクセスできるよう、プロバイダーを有効化して設定します。

既定では複数のプロバイダーが一覧にあり、そのうち Email は Users & Permissions が有効なすべての Strapi アプリで既定で有効です。

有効化・設定するプロバイダーの編集をクリックします。
プロバイダー編集画面で Enable の TRUE をクリックします。
各プロバイダー固有の設定項目を入力します（Users & Permissions のプロバイダーを参照）。
Save をクリックします。

Strapi が既定で用意していないプロバイダーは、アプリのコードから手動で追加できます。次のカードから、設定や独自プロバイダー作成の詳細へ進めます。

プロバイダーの設定

Users & Permissions のプロバイダーの動き、ログインの流れ、よくある設定例を扱います。

カスタムプロバイダーの作成

Users & Permissions 用に独自のプロバイダーを作る方法を説明します。

メールテンプレート

場所: Users & Permissions プラグイン > Email templates

Users & Permissions は、エンドユーザーへ送るメールに次の 2 種類のテンプレートを使います。「Email address confirmation」と「Reset password」です。

アカウントを有効化する前に確認が必要な場合
Strapi アカウントのパスワードをリセットする場合

どちらのテンプレートも変更できます。

編集するメールテンプレートのをクリックします。

メールテンプレートを設定します。

設定名	手順
Shipper name	送信者名を入力します。
Shipper email	送信者のメールアドレスを入力します。
Response email	（任意）エンドユーザーからの返信を受け取るメールアドレスを入力します。
Subject	件名を入力します。変数が使えます（メールのテンプレート変数を参照）。

「Message」テキストボックスで本文を編集します。HTML と変数を使います（メールのテンプレート変数を参照）。
Finish をクリックします。

高度な設定

場所: Users & Permissions プラグイン > Advanced settings

Users & Permissions に関する設定の多くは Advanced Settings で管理します。エンドユーザーの既定ロール、サインアップやメール確認の有効化、パスワードリセット後の遷移先 URL などが含まれます。

次の表に従って必要な項目を設定します。

設定名	手順
Default role for authenticated users	ドロップダウンで、新規エンドユーザーの既定ロールを選びます。
One account per email address	TRUE で、同一メールアドレスのエンドユーザーアカウントを 1 件に制限します。 FALSE で制限を外し、同一メールで複数アカウントを許可します（例: 異なるプロバイダーで `kai.doe@strapi.io` にログインする場合）。
Enable sign-ups	TRUE でエンドユーザーのサインアップを許可します。 FALSE でフロントアプリへのユーザー登録を防ぎます。
Reset password page	フロントアプリのパスワードリセットページの URL を入力します。
Enable email confirmation	TRUE で確認メールによるアカウント確認を有効にします。 FALSE で確認を無効にします。
Redirection url	Strapi アカウント確認後にエンドユーザーをリダイレクトするページの URL を入力します。

Save をクリックします。

コードベースの設定

Users & Permissions の多くは管理パネルで設定しますが、コードで細かく調整できる項目もあります。

JWT の設定

JSON Web Token（JWT）の生成はプラグイン設定ファイルで設定します。

Strapi は JWT の生成に jsonwebtoken を使います。

JWT の管理モード

Users & Permissions では JWT を 2 つのモードで管理できます。

どちらを使うかは、/config/plugins の users-permissions.config の jwtManagement で指定します。legacy-support または refresh のいずれかです。

モード	説明	用途
`legacy-support`	（既定）従来の設定で長寿命の JWT を発行する	既存アプリ、シンプルな認証
`refresh`	短命のアクセストークンとリフレッシュトークンでセッション管理し、安全性を高める	新規アプリ、強めのセキュリティ要件（詳細は管理パネルの設定を参照）

後方互換のため、既定はレガシーモードです。

/config/plugins.js
module.exports = ({ env }) => ({
  'users-permissions': {
    config: {
      jwtManagement: 'legacy-support',
      jwt: {
        expiresIn: '7d', // Traditional JWT expiry
      },
    },
  },
});

メモ

jwtSecret は新しい JWT を作るためのランダム文字列で、多くの場合 JWT_SECRET 環境変数で設定します。
jwt.expiresIn は（レガシーモードのみ）秒数、または時間の長さを表す文字列で指定します。
例: 60、"45m"、"10h"、"2 days"、"7d"、"2y"。数値だけの場合は秒として解釈されます。文字列では単位（分・時間・日・年など）を必ず含めてください。単位がないとミリ秒として扱われます（"120" は "120ms" と同じになります）。

Warning

セキュリティ上、JWT の有効期限を 30 日を超えて長くすることは推奨されません。

refresh モードの設定例は次のとおりです。

JavaScript
TypeScript

/config/plugins.js

module.exports = ({ env }) => ({
  // …
  'users-permissions': {
    config: {
      jwtManagement: 'refresh',
      sessions: {
        accessTokenLifespan: 604800, // 1 week (default)
        maxRefreshTokenLifespan: 2592000, // 30 days
        idleRefreshTokenLifespan: 604800, // 7 days
        httpOnly: false, // Set to true for HTTP-only cookies
        cookie: {
          name: 'strapi_up_refresh',
          sameSite: 'lax',
          path: '/',
          secure: false, // true in production
        },
      },
    },
  },
  // ...
});

/config/plugins.ts

export default ({ env }) => ({
  // …
  'users-permissions': {
    config: {
      jwtManagement: 'refresh',
      sessions: {
        accessTokenLifespan: 604800, // 1 week (default)
        maxRefreshTokenLifespan: 2592000, // 30 days
        idleRefreshTokenLifespan: 604800, // 7 days
        httpOnly: false, // Set to true for HTTP-only cookies
        cookie: {
          name: 'strapi_up_refresh',
          sameSite: 'lax',
          path: '/',
          secure: false, // true in production
        },
      },
    },
  },
  // ...
});

登録まわりの設定

User モデル に登録時に受け付けたい追加フィールドがある場合は、 /config/plugins の config.register に許可フィールドとして列挙しないと API は受け付けません。

次の例では、ユーザー登録時に nickname フィールドを API が受け付けるようにします。

JavaScript
TypeScript

/config/plugins.js
module.exports = ({ env }) => ({
  // ...
  "users-permissions": {
    config: {
      register: {
        allowedFields: ["nickname"],
      },
    },
  },
  // ...
});

/config/plugins.ts
export default ({ env }) => ({
  // ...
  "users-permissions": {
    config: {
      register: {
        allowedFields: ["nickname"],
      },
    },
  },
  // ...
});

レート制限の設定

認証と登録のエンドポイントには、不正利用を防ぐレート制限がかかります。次のパラメーターで挙動を変えられます。さらに詳しいオプションは koa2-ratelimit のドキュメントを参照してください。

/config/plugins で指定できるオプションは次のとおりです。

パラメーター	説明	型	既定値
`ratelimit`	認証・登録エンドポイントのレート制限を調整する設定	object	`{}`
`ratelimit.enabled`	レート制限のオン／オフ	boolean	`true`
`ratelimit.interval`	同一バケットにまとめるリクエストの時間窓	object	`{ min: 5 }`
`ratelimit.max`	時間窓あたりに許可するリクエスト数の上限	integer	`5`
`ratelimit.prefixKey`	レート制限キーの接頭辞	string	`${userIdentifier}:${requestPath}:${ctx.request.ip}`

JavaScript
TypeScript

/config/plugins.js
module.exports = ({ env }) => ({
  // ... other plugins configuration ...
  // Users & Permissions configuration
  'users-permissions': {
    config: {
      ratelimit: {
        enabled: true,
        interval: { min: 5 },
        max: 5,
      },
    },
  },
  // ...
});

/config/plugins.ts
export default ({ env }) => ({
  // ... other plugins configuration ...
  // Users & Permissions configuration
  'users-permissions': {
    config: {
      ratelimit: {
        enabled: true,
        interval: { min: 5 },
        max: 5,
      },
    },
  },
  // ...
});

メールのテンプレート変数

このプラグインには既定で 2 つのテンプレート（パスワードリセットとメールアドレス確認）があります。変数の差し込みには Lodash の `template()` メソッドを使います。

管理パネルの Plugins > Roles & Permissions > Email Templates から編集できます（メールテンプレートも参照）。

利用できる変数は次のとおりです。

Reset password
Email address confirmation

USER (object)
- username
- email
TOKEN はパスワードリセット用に生成されたトークンです。
URL はメール内のリンクをクリックしたあとユーザーが送られる先です。
SERVER_URL はサーバー設定で定義した絶対 URL です。

USER (object)
- username
- email
CODE はメールアドレス確認用に生成されたコードです。
URL はコードを確認する Strapi バックエンドの URL です（既定は /auth/email-confirmation）。
SERVER_URL はサーバー設定で定義した絶対 URL です。

セキュリティの設定

JWT はデジタル署名により検証・信頼できます。署名には secret が必要です。既定では Strapi が生成し、/extensions/users-permissions/config/jwt.js に保存します。

開発中は便利ですが、本番では JWT_SECRET など環境変数で秘密鍵を渡すことを推奨します。

既定では環境変数 JWT_SECRET が secret として使われます。別名の変数を使う場合は設定ファイルを更新します。

JavaScript
TypeScript

/extensions/users-permissions/config/jwt.js

module.exports = {
  jwtSecret: process.env.SOME_ENV_VAR,
};

/extensions/users-permissions/config/jwt.ts

export default {
  jwtSecret: process.env.SOME_ENV_VAR,
};

カスタムコールバック検証

既定では、Strapi の SSO は設定の URL と完全一致するリダイレクト先にしか送りません。

ほかの URL も許可するには、users-permissions プラグイン向けに plugins.js にコールバックの validate 関数を定義します。

/config/plugins.js|ts
  // ... other plugins configuration ...
  // Users & Permissions configuration
  'users-permissions': {
    enabled: true,
    config: {
      callback: {
        validate: (cbUrl, options) => {
          // cbUrl is where Strapi is being asked to redirect the auth info
          // that was received from the provider to

          // in this case, we will only validate that the 
          // if using a base url, you should always include the trailing slash
          // although in real-world usage you should also include the full paths
          if (cbUrl.startsWith('https://myproxy.mysite.com/') || 
              cbUrl.startsWith('https://mysite.com/')) {
            return;
          }

          // Note that you MUST throw an error to fail validation
          // return values are not checked
          throw new Error('Invalid callback url');
        },
      },
    },
  },

使い方

Users & Permissions は、管理パネルでエンドユーザーアカウントを作る場合と、API 経由で使う場合の両方があります。

管理パネルでの利用

利用場所: Content Manager

Users & Permissions では、エンドユーザーとアカウント情報をコンテンツタイプとして管理します。Strapi にインストールするとコレクションタイプが 3 つ自動作成され、そのうち Content Manager から直接扱えるのは User だけです。

フロントで Users & Permissions を使ってエンドユーザーを登録するには、User コレクションタイプに新しいエントリーを足します。

Content Manager で User コレクションタイプを開きます。
右上の Create new entry をクリックします。

既定フィールドを入力します。管理者が Strapi に追加したカスタムフィールドが表示されることもあります。

フィールド	手順
Username	エンドユーザーのユーザー名を入力します。
Email	テキストボックスにメールアドレスを入力します。
Password	（任意）テキストボックスにパスワードを入力します。で表示のオン／オフができます。
Confirmed	（任意）エンドユーザーアカウントを確認済みにするには ON にします。
Blocked	（任意）コンテンツへのアクセスを防ぐにはアカウントをブロックし ON にします。
Role	（任意）新しいエンドユーザーに付与するロールを指定します。空の場合は高度な設定の「Default role」で設定した既定ロールが使われます。

Save をクリックします。

Note

フロントでエンドユーザー自身が登録できるようにしている場合（高度な設定の「Enable sign-ups」）、エントリーは自動で作成され、入力内容でフィールドが埋まります。Strapi の管理者はあとからすべてのフィールドを編集できます。

API での利用

API リクエストのたびに、サーバーは Authorization ヘッダーの有無を確認し、リソースへのアクセス権を検証します。

Note

ロールなしでユーザーを作成した場合、または /api/auth/local/register を使った場合、ユーザーには authenticated ロールが付与されます。

基本的な認証エンドポイント

ユーザー管理と Content API 向けに、次の認証エンドポイントがあります。

メソッド	URL	説明
`POST`	`/api/auth/local`	メール／ユーザー名とパスワードでログイン（`identifier` パラメーターを参照）
`POST`	`/api/auth/local/register`	ユーザー登録
`POST`	`/api/auth/forgot-password`	パスワードリセットの依頼
`POST`	`/api/auth/reset-password`	トークンでパスワードをリセット
`GET`	`/api/auth/email-confirmation`	メールアドレスの確認

セッション管理のエンドポイント

セッション管理（jwtManagement: 'refresh'）が有効なときは、次のエンドポイントも使えます。

メソッド	URL	説明
`POST`	`/api/auth/refresh`	リフレッシュトークンでアクセストークンを更新
`POST`	`/api/auth/logout`	ユーザーセッションを失効（端末単位のログアウトに対応）

認証トークンを更新するリクエストの例です。

リクエスト例: refresh エンドポイント

curl -X POST http://localhost:1337/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "your-refresh-token"
  }'

Example response

{
  "jwt": "your-new-access-token"
}

すべてのセッションからログアウトするリクエスト例です。

リクエスト例: logout エンドポイント

curl -X POST http://localhost:1337/api/auth/logout \
  -H "Authorization: Bearer your-access-token"

`identifier` パラメーター

リクエストに付ける identifier はメールアドレスでもユーザー名でも構いません。例は次のとおりです。

Axios
Postman

import axios from 'axios';

// Request API.
axios
  .post('http://localhost:1337/api/auth/local', {
    identifier: 'user@strapi.io',
    password: 'strapiPassword',
  })
  .then(response => {
    // Handle success.
    console.log('Well done!');
    console.log('User profile', response.data.user);
    console.log('User token', response.data.jwt);
  })
  .catch(error => {
    // Handle error.
    console.log('An error occurred:', error.response);
  });

Postman を使う場合、body を raw にし、データ形式として JSON を選びます。

{
  "identifier": "user@strapi.io",
  "password": "strapiPassword"
}

成功すると jwt キーに ユーザーの JWT が返ります。

レガシーモードのレスポンス:

{
    "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiaWF0IjoxNTc2OTM4MTUwLCJleHAiOjE1Nzk1MzAxNTB9.UgsjjXkAZ-anD257BF7y1hbjuY3ogNceKfTAQtzDEsU",
    "user": {
        "id": 1,
        "username": "user",
        ...
    }
}

セッション管理モードのレスポンス:

{
    "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Short-lived access token
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Long-lived refresh token
    "user": {
        "id": 1,
        "username": "user",
        ...
    }
}

トークンの使い方

取得した jwt は、権限のある API リクエストに使います。ユーザーとして GET などを送るときは、Authorization ヘッダーに JWT を載せます。

トークンがないリクエストは、既定で public ロールの権限として扱われます。各ロールの権限は管理画面で変更します。

認証に失敗すると 401 (unauthorized) が返ります。

token はログインまたは登録時に受け取った data.jwt です。

import axios from 'axios';

const token = 'YOUR_TOKEN_HERE';

// Request API.
axios
  .get('http://localhost:1337/posts', {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  })
  .then(response => {
    // Handle success.
    console.log('Data: ', response.data);
  })
  .catch(error => {
    // Handle error.
    console.log('An error occurred:', error.response);
  });

ユーザー登録

次の例のように、データベースに新しいユーザーを作成できます（既定ロールの扱いは設定に依存します）。

import axios from 'axios';

// Request API.
// Add your own code here to customize or restrict how the public can register new users.
axios
  .post('http://localhost:1337/api/auth/local/register', {
    username: 'Strapi user',
    email: 'user@strapi.io',
    password: 'strapiPassword',
  })
  .then(response => {
    // Handle success.
    console.log('Well done!');
    console.log('User profile', response.data.user);
    console.log('User token', response.data.jwt);
  })
  .catch(error => {
    // Handle error.
    console.log('An error occurred:', error.response);
  });

Strapi コンテキスト内の `user` オブジェクト

認証に成功したリクエストでは user オブジェクトが利用できます。

認証済みの user は ctx.state のプロパティです。

create: async ctx => {
  const { id } = ctx.state.user;

  const depositObj = {
    ...ctx.request.body,
    depositor: id,
  };

  const data = await strapi.services.deposit.add(depositObj);

  // Send 201 `created`
  ctx.created(data);
};

管理パネルでの設定​

ロール​

新しいロールを作成する​

ロールを編集する​

ロールを削除する​

プロバイダー​

プロバイダーの設定

カスタムプロバイダーの作成

メールテンプレート​

高度な設定​

コードベースの設定​

JWT の設定​

JWT の管理モード​

登録まわりの設定​

レート制限の設定​

メールのテンプレート変数​

セキュリティの設定​

カスタムコールバック検証​

使い方​

管理パネルでの利用​

API での利用​

基本的な認証エンドポイント​

セッション管理のエンドポイント​

identifier パラメーター​

トークンの使い方​

ユーザー登録​

Strapi コンテキスト内の user オブジェクト​

管理パネルでの設定

ロール

新しいロールを作成する

ロールを編集する

ロールを削除する

プロバイダー

メールテンプレート

高度な設定

コードベースの設定

JWT の設定

JWT の管理モード

登録まわりの設定

レート制限の設定

メールのテンプレート変数

セキュリティの設定

カスタムコールバック検証

使い方

管理パネルでの利用

API での利用

基本的な認証エンドポイント

セッション管理のエンドポイント

`identifier` パラメーター

トークンの使い方

ユーザー登録

Strapi コンテキスト内の `user` オブジェクト