日々の開発Tips

【NPM】クラシックトークンが2025年12月9日に完全廃止されたことに伴うパッケージのインストールエラー(403)と対処法

Qualiteg プロダクト開発部

2025年12月11日 — 8 min read

こんにちは！

本日は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が最も推奨される

参考リンク

本稿が同じ問題に遭遇したエンジニアの助けになれば幸いです。

それでは、また次回お会いしましょう！