メインコンテンツまでスキップ
API リファレンス

ユーザーを認証する

MIZUHIKI アイデンティティ SDK は、日本における法令準拠の電子本人確認（eKYC）を、シンプルかつ便利な方法で完了するための機能を提供します。ユーザーを認証フローに誘導するための組み込み UI をご利用いただけます。

事前にSDK インストールガイドの手順を完了していることをご確認ください。

1. SDK の初期化​

MIZUHIKI チームから取得したプロジェクト ID を渡して、SDK インスタンス（モックまたは本番）を作成します。このインスタンスを通じて、すべての MIZUHIKI ID 機能にアクセスできます。

必須： YOUR_PROJECT_ID を、ベータアクセス設定時に MIZUHIKI チームから提供された実際のプロジェクト ID に置き換えてください。

import MizuhikiIdentityCore
import MizuhikiIdentityMock
import MizuhikiIdentity

// Define your app environment with MIZUHIKI Identity SDK client
class AppEnvironment: ObservableObject {
    // Replace with your actual project ID from the MIZUHIKI team
    private let mizuhikiProjectId = "YOUR_PROJECT_ID"
    
    lazy var mizuhiki: IdentityClient = {
        #if DEBUG
        // Use mock environment for development and testing
        return MizuhikiIdentityMock.makeClient(projectId: mizuhikiProjectId)
        #else
        // Use production environment for release builds
        return MizuhikiIdentity.makeClient(projectId: mizuhikiProjectId)
        #endif
    }()
    
    // Shared instance for app-wide usage
    static let shared = AppEnvironment()
}

// Usage in SwiftUI
struct ContentView: View {
    @StateObject private var appEnv = AppEnvironment.shared
    
    var body: some View {
        VStack {
            Text("MIZUHIKI Identity SDK Ready")
            // Use appEnv.mizuhiki for all MIZUHIKI Identity SDK operations
        }
        .environmentObject(appEnv)
    }
}

重要事項：

  • 🔑 プロジェクト ID： MIZUHIKI アイデンティティ SDK の認証情報に記載された ID と一致している必要があります
  • 🏗️ 環境： 開発時はモック、リリース時は本番環境を使用してください
  • 💾 インスタンス管理： アプリセッションごとにクライアントインスタンスを 1 つ作成してください
  • 🔄 ライフサイクル： 接続管理はクライアントが自動的に行います

2. 組み込み MIZUHIKI UI を使用して KYC を完了する​

MIZUHIKI アイデンティティ SDK には、ユーザーを KYC プロセスに誘導するための組み込み UI フローが含まれています。

KYC プロセスには以下の画面が含まれます：

  1. プロセスの説明を表示するイントロダクション画面
  2. 暗証番号入力画面
  3. マイナンバーカードのスキャン手順画面
  4. NFC スキャン中の画面
  5. 完了画面

MIZUHIKI APIを使用して独自のUIを利用したい場合は、お知らせください。

ユーザー情報のフォーマット​

注記

KYC 完了後、SDK はユーザーの個人情報（氏名、生年月日、住所、性別）を JWE オブジェクトとして暗号化して返します。 この JWE をバックエンドに送信し、復号・処理を行ってください。モバイルアプリ内でユーザー情報（PII）を復号しないでください。

パラメーター型必須説明例
addressStringはい居住地住所徳島県板野町犬伏9番8
dateOfBirthStringはい西暦での生年月日2000-12-25
fullNameStringはい氏名山中 逸穂
genderEnum (female | male | other)はい性別male
import MizuhikiIdentityCore
import MizuhikiIdentityUI

struct ContentView: View {
    @Environment(\.appEnv) private var appEnv

    var body: some View {
        VStack {
            Button(action: kyc) {
                Text("KYC")
                    .padding(8)
                    .fontWeight(.semibold)
                    .frame(maxWidth: .infinity)
            }
        }
    }

    @State private var signedUpUser: MizuhikiIdentityCore.User?
    private func onSignUp() {
        MizuhikiIdentityUIBridge.present(config: .init(client: appEnv.mizuhiki)) { event in
            switch event {
            case .didStart:
                break
            case .didFinish(let result):
                self.signedUpUser = result.user
                // submit the encrypted JWE to your backend for decryption and storage, see details in the next step
                submitEncryptedPii(jwe: result.kycDetails)
            case .didCancel:
                break
            }
        }
    }
}

3. 暗号化されたユーザー情報（JWE）をバックエンドに転送する​

KYC 完了後、アプリは JWE 形式で暗号化されたユーザーの個人情報を受け取ります。 HTTPS 経由でバックエンド API に直接渡してください。

// Example payload you send to your backend after successful KYC
struct KycResultPayload: Encodable {
    let encryptedPiiJwe: String
}

func submitEncryptedPii(_ jwe: String) async throws {
    let payload = KycResultPayload(encryptedPiiJwe: jwe)
    // POST payload to your backend over HTTPS
}

4. バックエンドで JWE を復号する​

セットアップ時に生成した秘密鍵を使用して JWE を復号し、ユーザー情報ペイロードを解析します。

Node.js example (jose)
import { compactDecrypt, CompactJWEHeaderParameters } from "jose";
import { createPrivateKey } from "node:crypto";

type KycPiiGender = "female" | "male" | "other";

interface KycPii {
   // in ""徳島県板野町犬伏9番8" format
   address: string;

   // in "2000-12-25" basic ISO format
   dateOfBirth: string;

   // in "山中 逸穂" format
   fullName: string;
   gender: KycPiiGender;
}

interface DecryptedKycPii {
   pii: KycPii;
   protectedHeader: CompactJWEHeaderParameters;
}

export async function decryptMizuhikiPii(jwe: string): Promise<DecryptedKycPii> {
  const privateKeyPem = process.env.MIZUHIKI_PII_PRIVATE_KEY_PEM;
  if (!privateKeyPem) {
    throw new Error("Missing MIZUHIKI_PII_PRIVATE_KEY_PEM");
  }

  const privateKey = createPrivateKey(privateKeyPem);
  const { plaintext, protectedHeader } = await compactDecrypt(jwe, privateKey);

  const json = new TextDecoder().decode(plaintext);
  const pii = JSON.parse(json) as KycPii;

  return { pii, protectedHeader };
}

バックエンドの処理要件：

  • JWE は TLS（HTTPS）経由でのみ受け付けてください。
  • 信頼できるサーバーインフラ上でのみ復号してください。
  • 生の JWE や復号された PII をログに記録しないでください。
  • 復号されたデータへのアクセスには最小権限の原則を適用してください。
KYC introduction screenMyNumber card passwordMyNumber card scanning instructionsMyNumber card scanningVerification success

MIZUHIKI ID アプリによる本人確認フロー

次のステップ​

KYC 完了後、ユーザーのアドレスに MIZUHIKI Verified（本人認証済み）ソウルバウンドトークンをミントする準備が整いました。

次へ： SBT ミントガイド →

トラブルシューティング​

よくある問題と解決策​

NFC 関連の問題​

問題：NFC 権限が拒否された

  • 症状： マイナンバーカードのスキャン時にアプリがクラッシュする
  • iOS の解決策：
    1. Xcode プロジェクト設定で NFC 機能が追加されていることを確認してください
    2. Info.plist に NFCReaderUsageDescription が含まれていることを確認してください
    3. デバイスが NFC に対応していることを確認してください（NFC 読み取りは iPhone 7 以降）
  • Android の解決策：
    1. AndroidManifest.xml に <uses-permission android:name="android.permission.NFC" /> を追加してください
    2. デバイスに NFC ハードウェアが搭載されており、設定で有効になっていることを確認してください

問題：カードが検出されない

  • 症状： NFC スキャンでカードが検出されない
  • 解決策：
    1. カードをウォレット・ケースから取り出してください（干渉を避けるため）
    2. カードをデバイスの NFC エリアに少なくとも 5 秒間静止させてかざしてください
    3. 位置を変えて試してください（NFC アンテナの位置はデバイスにより異なります）
    4. カードが破損または消磁されていないことを確認してください

認証関連の問題​

問題：プロジェクト ID が無効

  • 症状： SDK 使用中に認証エラーが発生する（"message": "permission denied: invalid x-project-id"）
  • 解決策： プロジェクト ID が MIZUHIKI チームから提供されたものと完全に一致していることを確認してください（大文字・小文字を区別します）

問題：モック環境でカードが拒否される

  • 症状： モック環境で有効な FeliCa カードが拒否される
  • 解決策：
    1. モック SDK バージョン（mizuhiki-adapter-mock）を使用していることを確認してください
    2. すべてのモックカードに暗証番号 ABC123 を使用してください
    3. カードが FeliCa または ISO/IEC 14443-4 Type-A 対応であることを確認してください

問題：本番環境での暗証番号ロック

  • 症状： 入力ミスによりマイナンバーカードが使用不能になった
  • 解決策：
    1. カードと身分証明書を持参してコンビニエンスストア（セブン-イレブン、ファミリーマート）に行ってください
    2. カードリーダー端末で暗証番号リセット手順を使用してロックを解除してください
    3. または：市区町村の窓口で手動解除の手続きを行ってください

統合関連の問題​

問題：パッケージレジストリでのビルドエラー

  • 症状： MIZUHIKI アイデンティティ SDK の依存関係を解決できない
  • iOS の解決策： 
    # Re-authenticate with package registry
    swift package-registry login https://swift.cloudsmith.io/mizuhiki/compliance/ --token YOUR_TOKEN --no-confirm

    # Clear Xcode derived data
    rm -rf ~/Library/Developer/Xcode/DerivedData
  • Android の解決策： 
    # Verify environment variable is set
    echo $MIZUHIKI_TOKEN

    # Clean and rebuild project
    ./gradlew clean
    ./gradlew build

問題：UI ブリッジが応答しない

  • 症状： KYC UI が表示されない、またはコールバックが呼び出されない
  • iOS の解決策：
    1. UI の呼び出しがメインスレッドで行われていることを確認してください
    2. MizuhikiUI フレームワークがインポートされていることを確認してください
    3. クライアントインスタンスが正しく初期化されているか確認してください
  • Android の解決策：
    1. context が有効な Activity context であることを確認してください
    2. UI パーミッションが付与されているか確認してください
    3. UI 表示前にクライアントが作成されていることを確認してください

サポートが必要な場合​

上記で解決できない問題が発生した場合：

  1. SDK バージョンを確認： 最新の SDK バージョンを使用していることを確認してください
  2. サポートへ連絡： 以下の情報を添えて [email protected] にメールしてください：
    • SDK バージョンとプラットフォーム（iOS/Android）
    • 環境（モック/本番）
    • 完全なエラーメッセージとスタックトレース
    • 最小限の再現コードの例