ionic-enterprise-sdk-migration

Ionic Enterprise SDK の移行

Ionic Enterprise プラグインを、ログインセッションと保存データを維持しながら、Capgo のオープンソースプラグインに1つずつ置き換えます。

背景：Ionic は2025年2月に、Enterprise SDK を含む商用製品の販売を終了し、メンテナンスも段階的に縮小しています。ライセンスまたはサポート期間が終了する前に移行を計画してください。

使用するタイミング

次の場合に使用します：

• package.json に @ionic-enterprise/auth、@ionic-enterprise/identity-vault、または @ionic-enterprise/secure-storage が含まれている場合。
• コードで AuthConnect、ProviderOptions、Vault、BrowserVault、VaultType、DeviceSecurityType、または Secure Storage の SQLite／KeyValueStorage をインポートしている場合。
• 再ログインを強制せずに Auth Connect、Identity Vault、または Secure Storage を置き換える方法をユーザーが尋ねた場合。

次の場合は使用しないでください：

• Appflow Live Updates／ビルド → ionic-appflow-migration。
• コミュニティ製またはその他の SQLite プラグイン → sqlite-to-fast-sql。
• 生体認証の UX または一般的なセキュリティレビュー → capacitor-security。

ライブプロジェクトのスナップショット

検出された Ionic Enterprise パッケージと置き換えパッケージ： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@ionic-enterprise/')||name.startsWith('@capgo/')||name==='@capacitor/preferences'||name==='@capacitor/core')out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

置き換え対応表

Ionic Enterprise	置き換え先	対応範囲	対応範囲外（アプリで再構築）
Auth Connect	@capgo/capacitor-social-login（OIDC／OAuth2 IdP には provider: 'oauth2'、google、apple、facebook など）	認可コード＋PKCE、トークンの更新（refreshToken）、ログアウト、ネイティブの Apple／Google サインイン	トークンの保存ポリシー（Native Biometric または暗号化 SQL でトークンを保存）
Identity Vault	@capgo/capacitor-native-biometric	Keychain／Keystore への認証情報の保存／読み取り／削除。accessControl: BIOMETRY_CURRENT_SET または BIOMETRY_ANY により、生体認証を必須とする読み取りが可能。iOS でパスコードにフォールバックする verifyIdentity。biometryChange リスナー	非アクティブ時のロックタイムアウト、バックグラウンド時のプライバシー画面（@capacitor/privacy-screen）、カスタムパスコードのボルト、メモリー内のボルト
Secure Storage（SQLite）	@capgo/capacitor-fast-sql（encrypted: true ＋ encryptionKey）	暗号化 SQLite（SQLCipher）、トランザクション、バッチ、KeyValueStore	キー管理：DB キーは JS 定数ではなく Native Biometric に保存してください
Secure Storage（キーと値）	@capgo/capacitor-data-storage-sqlite または Fast SQL の KeyValueStore	シンプルな暗号化キーと値の保存

機密情報ではない設定は @capacitor/preferences に保存できます。トークンやシークレットは絶対に保存しないでください。

手順

ステップ 1：検出と計画

rg -n "@ionic-enterprise/" -g '!node_modules' .

各 Enterprise パッケージ、すべての呼び出し箇所、保存されている内容（キー、DB 名、ボルト設定：type、deviceSecurityType、lockAfterBackgrounded、unlockVaultOnLoad）を一覧にします。複数のプラグインがある場合は、リリースごとに1つずつ移行します。編集前に計画を報告してください。

ステップ 2：データの引き継ぎを計画する（2リリースのルール）

古いプラグインのデータを読み取れるのは、古いプラグインがインストールされている間だけです。トークン、ボルトの値、暗号化 DB の場合：

1. リリース N：Capgo の置き換え先を Enterprise プラグインと併せてインストールします。初回起動時に古いストアから読み取り、新しいストアに書き込み、migrated フラグを設定してから、古いストアをクリアします。
2. リリース N+1（大半のユーザーがリリース N を起動した後）：Enterprise プラグインを削除します。

ユーザーが全員の再ログインを強制することを了承した場合は、1回のリリースで問題ありません。その点を明示的に確認してください。

ステップ 3：Auth Connect -> Social Login

npm install @capgo/capacitor-social-login
npx cap sync

• 同じクライアント ID、スコープ、リダイレクト URI を維持します。新しいネイティブリダイレクト（カスタムスキームまたはユニバーサルリンク）を追加する場合は、リリース前に IdP に登録してください。
• 各 Auth Connect プロバイダー（Azure、Auth0、Okta、Cognito、汎用 OIDC）を、SocialLogin.initialize({ oauth2: { <providerId>: { ... } } }) の oauth2 エントリーに対応付けます。clientId/appId、issuerUrl または authorizationBaseUrl + accessTokenEndpoint、redirectUrl、スコープを設定してください。正確なフィールドについては、インストールされているバージョンのプラグインの OAuth2 ドキュメントを確認してください。
• AuthConnect.login/logout/refreshSession/isAccessTokenExpired を、SocialLogin.login({ provider: 'oauth2', options: { providerId } })、logout、refreshToken、および返されたトークンに対する独自の有効期限チェックに置き換えます。
• テスト用テナントで、変更前後の認可リクエスト（スコープ、prompt、オーディエンス）とトークンレスポンスを比較してください。

ステップ 4：Identity Vault -> Native Biometric

npm install @capgo/capacitor-native-biometric
npx cap sync

import { NativeBiometric, AccessControl } from '@capgo/capacitor-native-biometric';

await NativeBiometric.setCredentials({
  server: 'com.company.app.session',
  username: userId,
  password: refreshToken,
  accessControl: AccessControl.BIOMETRY_CURRENT_SET,
});

const { password: token } = await NativeBiometric.getSecureCredentials({
  server: 'com.company.app.session',
  reason: 'Unlock your account',
});

• lockAfterBackgrounded -> App の resume 時に、経過時間がタイムアウトを超えている場合はロック画面を表示し、再度 getSecureCredentials を呼び出します。
• DeviceSecurityType.Both / パスコードへのフォールバック -> verifyIdentity は iOS でデバイスのパスコードへのフォールバックをサポートします。保護された認証情報の読み取りは、引き続き生体認証のみです。
• BIOMETRY_CURRENT_SET は生体認証情報が変更されるとアイテムを無効化します（Identity Vault の厳格モードと同様です）。BIOMETRY_ANY は登録情報の変更後も有効です。
• アプリスイッチャーでのプライバシー画面 -> @capacitor/privacy-screen。
• iOS：Info.plist に NSFaceIDUsageDescription を追加します。

ステップ 5：Secure Storage -> Fast SQL または Data Storage SQLite

npm install @capgo/capacitor-fast-sql
npx cap sync

import { FastSQL, KeyValueStore } from '@capgo/capacitor-fast-sql';

const db = await FastSQL.connect({ database: 'app', encrypted: true, encryptionKey });
const kv = await KeyValueStore.open({ database: 'kv', encrypted: true, encryptionKey });

• 同じスキーマを維持し、クエリを移植します（executeSql -> db.query / db.run / db.executeBatch / db.transaction）。
• 暗号化には SQLCipher が必要です。Android では android/app/build.gradle に implementation 'net.zetetic:sqlcipher-android:<version>' を追加します。iOS では CocoaPods のサブスペック CapgoCapacitorFastSql/SQLCipher を使用します。これがない場合、iOS で encrypted: true を指定すると Encryption is not available in this build が発生します。
• Fast SQL は localhost HTTP サーバーを実行します。NSAppTransportSecurity -> NSAllowsLocalNetworking（iOS）と、localhost 用のクリアテキスト通信を許可する network_security_config.xml（Android）を追加してください。完全な設定については sqlite-to-fast-sql を参照してください。
• encryptionKey は Native Biometric（ステップ 4）で保管するか、サーバー側で導出してください。ハードコードしないでください。

ステップ 6：クリーンアップ

npm uninstall @ionic-enterprise/auth @ionic-enterprise/identity-vault @ionic-enterprise/secure-storage
rg -n "@ionic-enterprise" -g '!node_modules' .
npx cap sync

エンタープライズパッケージが残っていないことを確認してから、.npmrc から Ionic Enterprise のレジストリ／トークン行を削除してください（削除しないと CI のインストールに失敗します）。

検証

• アップグレードテスト：現在のストアビルドをインストールしてログインし、データを保存します。その上から新しいビルドをインストールし、ユーザーのログイン状態が維持され、データが存在することを確認します。
• 新規インストール：実機の iOS および Android デバイスで、ログイン、トークンの更新、ログアウト、生体認証によるロック解除が機能することを確認します（シミュレーターでは生体認証を完全にはテストできません）。
• デバイスの生体認証情報を変更すると、BIOMETRY_CURRENT_SET のアイテムが読み取り不可になり、アプリはログインにフォールバックします。
• 最終リリース後に rg -n "@ionic-enterprise" -g '!node_modules' . を実行すると、何も返されません。
• CI で Ionic Enterprise のレジストリ認証情報なしに npm ci が成功します。

エラー処理

問題	対処方法
CI で @ionic-enterprise/* に対して npm error 401 Unauthorized / 404 が発生する	エンタープライズレジストリのトークンが期限切れです。削除を完了するか、リリース N+1 までトークンを維持してください
更新後にユーザーがログアウトされる	データが引き継がれていません。まずデュアルプラグインのリリース N を出荷してください
切り替え後に redirect_uri_mismatch / IdP エラーが発生する	新しいリダイレクト URL を IdP に登録してください。スコープは同一に維持してください
Encryption is not available in this build	SQLCipher の依存関係／サブスペックを追加して、再ビルドしてください
Fast SQL 呼び出しがネットワークエラーで失敗する	localhost 用の ATS ローカルネットワーク設定／Android のクリアテキスト設定が不足しています
登録情報の変更後に生体認証の読み取りに失敗する	BIOMETRY_CURRENT_SET では想定どおりの動作です。再認証して、再度保存してください