【NPM】クラシックトークンが2025年12月9日に完全廃止されたことに伴うパッケージのインストールエラー(403)と対処法
こんにちは！
本日は2025年12月9日に行われた npm に関する重要なアップデートについて解説いたします！
2025年12月9日、npmがセキュリティ強化のためclassic tokenを完全に無効化しました。
この影響で、プライベートパッケージを使用しているプロジェクトで突然npm installが失敗するケースが発生しています。（パブリックパッケージの使用には影響はありません）
本記事では、実際に遭遇したエラーと解決方法についてみていきたいと思います。
発生した問題
症状
プライベートパッケージ（@your-org/package-name形式）を含むプロジェクトで
npm install
を実行すると、以下のようなエラーが発生
パターン1: 404エラー
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/@your-org/package-name/...
npm ERR! 404 '@your-org/package-name@x.x.x' is not in the npm registry.
パターン2: 403エラー
既存の.npmrcにトークンを設定していても
npm ERR! code E403
npm ERR! 403 403 Forbidden - GET https://registry.npmjs.org/@your-org/package-name/...
npm ERR! 403 In most cases, you or one of your dependencies are requesting
npm ERR! 403 a package version that is forbidden by your security policy.
原因
原因は、2025年12月9日にClassic tokenが強制的に無効化されたためです（公式発表）
1. Classic tokensの完全無効化
すべての既存のclassic tokenが永久に無効化されましたので、それを利用していたプロジェクトはnpm installなどで失敗することになります。
2. セッションベース認証の導入
また npm loginについても変更がありました。これまではnpm loginを実行すると、長期間有効なトークンが内部的に発行され当面つかうことができましたが、今回のアップデートからは、2時間で期限切れになるセッショントークンが発行されるようになりました。
以下のようになります
- セッションは2時間後に自動的に期限切れ
- 再認証が必要
- UIやCLIのトークンリストには表示されない
- publish操作時は2FA(２段階認証、２要素認証）が強制されます
このようにセキュリティが向上しました。（裏をかえせば、不便になりました）
3. 新しいCLIトークン管理ツール
便利になった点まります。Granular access tokenをコマンドラインから直接管理できる新しいツールが導入されました。これによりWebコンソールを使わなくてもトークン作成が可能となります。
npm token create # トークン作成
npm token list # トークン一覧
npm token revoke # トークン無効化
4. 新パッケージのデフォルト2FA強制
今週(2025/12/9)週から、新しく作成されるパッケージはデフォルトで2FAが有効になります。既存のパッケージは現在の設定が維持されます。
解決方法
さて、ここからは新しいnpmのアクセストークン(Granular Access Token)をローカル開発環境で使う方法を３つご紹介いたします。
プライベートパッケージにアクセスするための方法を3つ紹介します。
| 方法 | セキュリティ | 手軽さ | 推奨度 |
|---|---|---|---|
| 方法1: セッションベース認証 | ◎ 最も安全 | △ 2時間ごとに再認証 | ⭐ 公式推奨 |
| 方法2: 環境変数 | ○ 比較的安全 | ○ 90日ごとに更新 | 実用的 |
| 方法3: .npmrcに直接記載 | △ リスクあり | ◎ 手軽 | 注意が必要 |
方法1: セッションベース認証（公式推奨）
まず１つめは、npm loginをする、セッションベースの認証です。
npm公式が推奨する最も安全な方法です。npm loginを実行すると、2時間有効なセッショントークンが発行されます。
手順
npm login
ブラウザが開き、npmアカウントでの認証を求められます。認証が完了すると、2時間の間プライベートパッケージにアクセスできます。
特徴
- トークンがファイルに保存されないため、漏洩リスクが低い
- セッションはUIやCLIのトークンリストに表示されない
- 2時間後に期限切れになるため、再度
npm loginが必要
こんな人におすすめ
- セキュリティを重視したい
- 頻繁に
npm installを実行しない - 個人開発
方法2: 環境変数を使用
トークンを環境変数に設定し、.npmrcから参照する方法です。トークンをファイルに直接書かないため、次に紹介する方法3より安全です。
Step 2-1: Granular Tokenを作成
まず、新しいGranular Access Tokenを作成します。
Webで作成する場合
①npmjsにアクセスして、設定メニューから Access Tokens を選択
②「Generate New Token」を選択
③以下を設定します
(1)Token name: 任意の名前（例: local-dev）
(2)⚠️ Bypass two-factor authentication: チェックを入れる
(3)Allowed IP Ranges: 必要ならアクセス可能なIPレンジを設定します
(4)Permissions:Read Only/Read and Write を選択します
パッケージを使用するだけなら Read Only で十分ですが、
パッケージのリリースもしたいなら、 Read and Writeです。
とくに、もし、npm publish をするときに、
Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages.
が出てしまったら、 Read and Write なアクセストークンをつくって設定しましょう
(5)Select Packages:このトークンでアクセスできるパッケージを選択します
(6)Expiration Date:このトークンの有効期限を設定します
④設定ができたら「Generate token」をクリックします
⑤表示されたトークン（npm_xxxx...）をコピー
重要: トークンは一度しか表示されませんので、必ずコピーして安全な場所に保存しましょう
CLIで作成する場合（新機能）
CLIで作りたいときは以下のようにします。
npm token create
Step 2-2: 環境変数を設定
さて、アクセストークンができたら、環境変数にセットしましょう。
Mac/Linux（~/.zshrc または ~/.bashrc に追加）：
export NPM_TOKEN=npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
設定を反映
source ~/.zshrc # または source ~/.bashrc
Windows（PowerShellで永続設定）
[Environment]::SetEnvironmentVariable("NPM_TOKEN", "npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "User")
設定後、ターミナルを再起動します。
Step 2-3: .npmrcで環境変数を参照
プロジェクトルートまたはホームディレクトリの.npmrcに以下を追加して、環境変数からトークンを読み込むようにします。
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
この.npmrcはトークンを直接含まないため、Gitにコミットしても安全です。
これで方法２ができました。
特徴
- トークンがコードベースに含まれない
- 環境変数はOS側で管理されるため、比較的安全
- 90日ごとにトークンの更新が必要
方法3: .npmrcにトークンを直接記載
現場レベルでは従来から結構やられちゃってる方法です。
個人開発をする上では手軽ですが、業務やチーム開発ではセキュリティ上の懸念があります
手順
方法2のStep 2-1でGranular Tokenを作成した後、.npmrcに直接トークンを記載します。
ユーザーのホームディレクトリに設定する場合：
# Mac/Linux: ~/.npmrc
# Windows: C:\Users\<ユーザー名>\.npmrc
//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
プロジェクトルートに設定する場合：
# プロジェクトルート/.npmrc
//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠️ セキュリティ上の重大な注意点
この方法にはリスクがあります。特にチーム開発では十分に注意してください。
リスク1: Gitへの誤コミット
プロジェクトルートに.npmrcを置く場合、.gitignoreへの追加を忘れるとトークンがリポジトリに公開されてしまいます。
# 必ず.gitignoreに追加
echo .npmrc >> .gitignore
リスク2: チーム開発での共有
「チームで共有するために.npmrcをGitにコミットしている」というケースがありますが、これは非常に危険なのでやめましょう。
- リポジトリにアクセスできる全員がトークンを見られる
- リポジトリが公開された場合、トークンが漏洩する
- 退職者がトークンを持ち続ける可能性がある
チーム開発では、各メンバーが自分のトークンを環境変数で設定する方法2がおすすめです。
リスク3: 平文保存
そもそもトークンをトークンは暗号化されずにファイルに保存されますので、PCが侵害された場合、トークンが漏洩するリスクがあります。
リスク4: 90日ごとの更新
Granular tokenは最大90日で期限切れになります。更新を忘れると突然ビルドが失敗します。
インストールの実行
どの方法を選んでも、最後に以下を実行します。
既存のnode_modulesをクリーンアップ
# Mac/Linux
rm -rf node_modules
rm package-lock.json
# Windows (コマンドプロンプト)
rmdir /s /q node_modules
del package-lock.json
# Windows (PowerShell)
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
再インストール
npm install
成功すると、プライベートパッケージが正常にインストールされます。
CI/CD環境での設定
GitHub Actions、GitLab CI等のCI/CD環境でも、上記方法２と同様の手法でトークンをつくります
方法1: Granular tokenを使用
- 新しいCLIコマンド（
npm token create）またはWebでトークンを作成 - 「Bypass 2FA」を有効化（非対話型の自動化ワークフロー用）
- 適切な有効期限を設定（書き込みトークンは最大90日）
- CI/CDの環境変数（Secrets）にトークンを設定
例（GitHub Actions）
- name: Create .npmrc
run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc
方法2: OIDC Trusted Publishingを使用（最もセキュア・推奨）
パッケージを公開（publish）する場合、公式が最も推奨する方法です
- トークンの生成・管理が不要
- GitHub Actionsなどと連携
- セキュリティリスクを大幅に軽減
詳細: npm Trusted Publishing documentation
注意: Trusted Publishingはパッケージをインストールする場合には使用できません。publishする場合のみです。
トラブルシューティング
Q1: 「Bypass 2FA」にチェックを入れると警告が出る
There are security risks with this option.
For automation or CI/CD uses, please use Trusted Publishing instead.
A: この警告は正常です。.npmrcにトークンを書いて使用する場合、このオプションが必須となります。
注意点は、前述したとおり、
- トークンを
.gitignoreに追加し、Gitにコミットしない - トークンを他人と共有しない
- 90日ごとにトークンを更新する
です
Q2: 「Access token expired」と表示される
A: Granular tokenは最大90日間で期限切れになります。
解決方法は、あたりまえですが、新しいトークンを作ることです
- 方法2のStep 2-1の手順で新しいトークンを作成
- 環境変数または
.npmrcのトークンを新しいものに置き換え npm installを実行
Q3: npm whoamiは成功するが、パッケージへのアクセスが拒否される
A:これは今回の本筋ではないのですが、問題切り分けのために、解説いたしますね。 以下の原因が考えられます
原因1: 組織のメンバーではない
確認方法：
npm org ls <組織名>
403エラーが出る場合、その組織のメンバーではありません。組織の管理者に招待してもらってください。
原因2: トークン作成時に組織を選択していない
トークン作成時の「Packages and scopes」で、対象の組織を選択していない可能性があります。トークンを作り直してください。
補足: 「Bypass 2FA」オプションについて
トークン作成時の「Bypass two-factor authentication」というオプション名は少し怖く感じます。
↓こんな警告でるので↓
ここで、このオプションの意味と、チェックを入れない場合（2FA付きトークン）の動作について補足します。
2FA付きトークン（Bypass 2FAなし）の動作
このオプションにチェックを入れずにトークンを作成すると、トークンを使った操作のたびに2FAコードの入力が求められます。
npm install @your-org/private-package
# → OTPコードを入力してください: ______
2FA付きトークンの使用シーン
正直なところ、2FA付きトークンの使い道はかなり限定的ではないでしょうか。
| シーン | 2FA付きトークン | 結論 |
|---|---|---|
| CI/CD | 2FA入力できない | ❌ 使えない |
.npmrcに書いてinstall |
毎回2FA入力 | ❌ 非現実的 |
| 手動でpublish | 使えるが... | △ npm loginで十分 |
セッションベース認証（npm login）が導入された今、publish時の2FAはセッション側で強制されます。
わざわざ2FA付きトークンを使う意味はほぼ無いとおもいます。
ということで結論としては、
結論
「Bypass 2FA」は名前こそ怖いけど、実用上はほぼ必須のオプションでしょう。
セキュリティが心配な場合は、トークン自体を使わずに npm login のセッションベース認証（方法1）を使用することをおすすめします。
まとめ
- 2025年12月9日にnpm classic tokenが完全に無効化された（再作成・復旧は不可）
- 新しいGranular Access Tokenを作成する必要がある
npm loginで2時間のセッショントークンを取得する方法が公式推奨- 新しいCLIトークン管理ツール（
npm token create等）が導入された - トークン作成時、「Bypass 2FA」に必ずチェックを入れる
- 書き込み権限のあるトークンの有効期限は最大90日間
- チーム開発で
.npmrcをGitにコミットするのは危険（環境変数方式を推奨） - CI/CDでのpublishにはOIDC Trusted Publishingが最も推奨される
参考リンク
本稿が同じ問題に遭遇したエンジニアの助けになれば幸いです。
それでは、また次回お会いしましょう！
