はじめに

こんにちは、パブリックセクターのお客様向けにプロトタイピングの支援をしている、SA の鈴木です。
早速ですが、みなさま、デジタル庁が提供している、デジタル認証アプリはご存知でしょうか？「デジタル認証アプリ」は、マイナンバーカードを使った本人確認を、安全に・簡単にするためのアプリです。

令和6年（2024年）4月時点で、マイナンバーカードの保有率は70%を越えており、マイナンバーカードの利用シーンが広がっています。「デジタル認証アプリ」は、マイナンバーカードを使った認証や署名を、安全に・簡単にするための、デジタル庁が提供するアプリです。
行政機関や民間事業者は、デジタル庁が提供するデジタル認証アプリと連携する API（デジタル認証アプリサービス API）を活用することで、マイナンバーカードを使った本人確認・認証や電子申請書類への署名機能を簡単に組み込むことができます。
引用元：デジタル認証アプリ – https://services.digital.go.jp/auth-and-sign/business/

デジタル認証アプリと連携する、デジタル認証アプリサービス API を利用すると、EC サイト・ネットバンキングの利用開始時に発生する本人確認や、イベント等での酒類購入時の年齢確認、地域に住んでいる方の住所確認、といったことをマイナンバーカードを用いて行うことができます。
これまでこのような本人確認は、申請書類と共に免許証や健康保険証のコピーを同封し、それら書類を申請先で確認、問題なければ申請が受理される、といった流れで進み、申請が受理されるまで、数日から1週間近くかかっていました。これは郵送による長いリードタイム、手作業による確認作業、とコストが高いものでした。しかし、デジタル認証アプリを利用することで、オンラインで本人確認を済ませることができ、より短時間での申請や、申請確認作業の効率化が可能になります。

本記事のゴール

本記事では、サービスサイトが示す、次の「認証 API 利用の流れ」を、Cognito と連携し、実現したいと思います。
本人確認が必要なサービスを企画・開発されている方々向けに、デジタル認証アプリサービス API と、AWS の Customer Identity and Access Management (CIAM) のサービスである Amazon Cognito の連携の一例としてぜひご確認いただければと思います。

認証 API 利用の流れ（引用元：【民間事業者向け情報】マイナンバーカードで本人の確認を簡単に – https://services.digital.go.jp/auth-and-sign/business/）

Cognito は ソーシャルなIdentity Provider (IdP) や、Open ID Connect (OIDC) 、Security Assertion Markup Language (SAML) といったサードパーティの IdP を経由した認証が可能です。そのため、Cognito を利用し、OIDC に対応しているデジタル認証アプリサービス API とも連携することが理論上可能です。しかし、デジタル認証アプリサービス API で求められている実装のガイドラインを満たすには、private key jwt 認証を利用する必要があります。2025年2月現在、Cognito は、private key jwt 認証に非対応です。そのため、今回は client secret の代わりに、private key jwt 認証を Cognito で利用できるようにしたサンプル実装である、cognito-external-idp-proxy をカスタマイズして利用します。本サンプルは、ブログも公開されていますので、まずこちらをご一読いただくことをお勧めします。
目を通していただいた、という前提の上で、先に進めたいと思います。次に示す構成図が cognito-external-idp-proxy を利用した場合の全体構成となります。

また、この構成のシーケンス図は以下のようになります。

※上記は、デジタル庁 開発者サイトのシーケンス図：認証と cognito-external-idp-proxy のドキュメントを元に作成しました。

デジタル認証アプリサービス API の利用にあたって

デジタル認証アプリサービス API は、利用にあたり事前に申請が必要です。詳しくは、デジタル庁が公開しているサービスサイトをご一読いただき、申請してください。申請の際には、申請する企業の情報などが必要になり、特に、システム面で事前に注意すべき項目としては、次に示すものがあります。

• private key jwt 認証用の秘密鍵と公開鍵のペア
  • cognito-external-idp-proxy の README に作成手順が記載されています。
  • ここで作成した公開鍵をデジタル認証アプリサービス API の利用申請時に提出します。ペアとなる秘密鍵は大事に保管してください。
• コールバック URL
  • cognito-external-idp-proxy をデプロイ後に提供される、コールバック関数と接続されている API Gateway のエンドポイントを申請時に提出することになります。
  • カスタムドメインを利用しない場合、ドメイン名はデプロイ後に決定されます。先んじてデプロイを進めておきましょう。
• テストカード/テストカード代替機能の準備
  • J-LIS に別途申請する必要があります。貸与または購入から選択できます。
  • 今回はテストカードを J-LIS から貸与していただき、検証を行いましたが、テストカード代替機能を用いた検証も可能になったようです。テストカードの管理が煩雑な場合や急ぎ検証したい場合は、この機能の利用も検討ください。
    • https://developers.digital.go.jp/documents/auth-and-sign/testcard_alternative/

デジタル認証アプリサービス API の実装ガイドラインとサンプルの比較

デジタル認証アプリサービス API を利用するために必要な実装は、実装のガイドライン（本記事では、2025年3月27日時点を参照） にまとめられています。これを整理し、cognito-external-idp-proxy の実装状況と比較すると、次のような表にまとめることができます。（横長になってしまい、読みづらいですがご容赦ください）

それでは、次から、各要件ごとに、どのようにカスタマイズすべきか、みていきましょう。

準備：利用するライブラリの変更

サンプルで利用している python-jwt ライブラリは、ヘッダ部の kid の検証や iat クレームの検証が実装されていないため、PyJWT に変更します。変更したことによって、private key jwt 認証の処理に関する部分を修正する必要があります。今回は PyJWT を利用しましたが、読者の方々が実装される際は、ご自身の環境に合わせてライブラリをお選びください。また、ライブラリを変更する場合は、Layer の更新手順に従い、 Layer を忘れずに更新してください。

ID トークンの検証（JWT ヘッダ部の検証）

ID トークンの検証は、 ID トークンを取得する処理が記述されている、token Lambda 関数を更新します。
PyJWT では、ID トークン署名検証用公開鍵を取得するための関数が用意されており、取得した ID トークンに含まれる kid の ID に最適な公開鍵を取得します。kid の ID に一致する公開鍵を取得する、ということは、JWT ヘッダ部の検証の要件である、「ID トークンヘッダ部の kid が検証準備で取得した公開鍵の kid と一致することを検証してください。」 を満たすことがわかります。実際のコードは、cognito-external-idp-proxy/lambda/token/token_flow.py の 186 行目の直後に、以下のように追記します。

print("+++ VERIFYING ID TOKEN +++")
id_token = json.loads(data)["id_token"] 

print("+++ GET JWKS +++")
jwks_client = jwt.PyJWKClient(config["jwks_uri"])
signing_key = jwks_client.get_signing_key_from_jwt(id_token)

ID トークンの検証（JWT ヘッダ部の検証とペイロード部の検証）

ここでは、ヘッダ部の検証の要件である、「署名のアルゴリズム である alg と、検証準備で取得した公開鍵のアルゴリズムがともに「ES256」になっていることを検証してください。」と、
ペイロード部の検証の要件である、「iat クレーム」、「at_hash クレーム」の検証を実装します。
まず、iat クレームについてです。
PyJWT は、ID トークンのデコード関数で iat クレームの検証をデフォルトで行います。ただし、要件に「所要時間は、RP アプリで決める必要があります。」とあるように、所要時間をパラメータとして渡す必要があります。トークンが発行されてから検証を行うまでの所要時間を定義すれば良いので、今回は 60 秒程度とします。ここはそれぞれの環境で適した時間を設定ください。
実際のコードは、以下のようになります。JWT ヘッダ部の kid の検証で取得した公開鍵 (signing_key) も一緒に渡します。このコードでは、念の為、iss クレームと aud クレームも検証するように、必要なパラメータを渡しています。
cognito-external-idp-proxy/lambda/token/token_flow.py の signing_key = jwks_client.get_signing_key_from_jwt(id_token) の直後に以下を記述します。

try:
    decoded_id_token = jwt.decode(
        id_token, 
        signing_key, # kid の検証時に取得した公開鍵
        leeway=60, # 所要時間に 60 秒を設定
        issuer=config["idp_issuer_url"], # iss クレームの検証
        audience=config["client_id"], # aud クレームの検証
        algorithms=["ES256"])

続いて、at_hash クレームの検証を実装します。
at_hash クレームは、要件にある通り、「アクセストークンを、ID トークンヘッダ部の algorithm クレーム（alg）と同じハッシュアルゴリズムを用いてハッシュ化し、ハッシュ化した結果の左半分のビット群を Base64URL にてエンコードした値」です。
繰り返しになりますが、まず、（①）トークンエンドポイントから取得したデータから、アクセストークンを取得・検証し、（②）sha256 でハッシュ化します。続いて、（③）ハッシュ化した値の左半分のビット群を Base64URL でエンコードし、at_hash を生成します。最後に、（④）生成した at_hash とデコードした ID トークンに含まれる at_hash を比較し、同じ値であることを確認します。
cognito-external-idp-proxy/lambda/token/token_flow.py の 上記デコード処理の直後に以下を記述します。

    access_token = json.loads(data)["access_token"] # ①アクセストークンの取得
    jwt.decode(
                access_token,
                signing_key,
                algorithms=["ES256"]) # アクセストークンの検証
    hashed_access_token = hashlib.sha256(access_token.encode()).digest() # ②
    calculated_at_hash = base64.urlsafe_b64encode(hashed_access_token[:len(hashed_access_token)//2]).decode('utf-8').rstrip('=') # ③
    # ④
    if decoded_id_token['at_hash'] != calculated_at_hash:
        print("at_hash mismatch")
        return { "statusCode": 400 }

リプレイ攻撃への対策

要件では、リプレイ攻撃への対策として nonce の利用が求められています。
今回は、authorize Lambda 関数でリクエストごとに nonce を生成し、認可リクエストに設定し、DynamoDB の state テーブルと code テーブルで nonce を一定期間保持し、token Lambda 関数で検証します。
まず、authorize Lambda 関数で nonce を生成する処理の実装です。ここでは、Secrets Manager のクライアントを用いて、ランダムパスワードを生成し、その乱数を nonce のフォーマットに合うように変換します。
以下のコードを cognito-external-idp-proxy/lambda/authorize/authorize_flow.py の 77 行目あたりに追加します。

nonce_random = SM_CLIENT.get_random_password(
    PasswordLength=64,
    ExcludePunctuation=True,
    IncludeSpace=False
)
nonce_random = nonce_random["RandomPassword"]
nonce = hashlib.sha256(nonce_random.encode("utf-8")).digest()
nonce = base64.urlsafe_b64encode(nonce).decode('utf-8')
nonce = nonce.replace('=', '')

RP で生成した nonce を state テーブルで管理するため、state や code_verifier を格納する処理で合わせて state テーブルに格納するように、cognito-external-idp-proxy/lambda/authorize/authorize_flow.py の 82 行目のコードを書き換えます。

DYNAMODB_CLIENT.put_item(
    TableName = config["state_table"],
    Item = {
        "state": {
            "S": str(hashed_state)
        },
        "code_verifier": {
            "S": code_verifier
        },
        "ttl": {
            "N": str(state_ttl)
        },
         # Add
        "nonce": {
             "S": nonce
        }
    }
 )

そして、デジタル認証アプリサービス API の認可エンドポイントのパラメータとして設定します。
ここでは、cognito-external-idp-proxy の実装には存在しないパラメータである、acr_values も合わせて設定します。（参照：認可エンドポイントのリクエストパラメータ、https://developers.digital.go.jp/documents/auth-and-sign/authserver/）
cognito-external-idp-proxy/lambda/authorize/authorize_flow.py の 100 行目あたりに以下のコードを追加します。

params["nonce"] = nonce
params["acr_values"] = "aal3 crl"

デジタル認証アプリサービス API からのレスポンスに、nonce は含まれていても、state は含まれていません。このままでは state テーブルから、RP が生成した nonce を取得できず、レスポンスに含まれる nonce を検証できません。そこで、callback Lambda 関数で、state テーブルの nonce を、code テーブルに格納し、token Lambda 関数で、code をキーに、nonce を取得するため、cognito-external-idp-proxy/lambda/callback/callback_flow.py の 81 行目の code テーブルへの追加処理を以下のように変更します。

DYNAMODB_CLIENT.put_item(
    TableName = config["auth_code_table"],
    Item = {
        "auth_code": {
            "S": config["auth_code"]
        },
        "code_verifier": {
            "S": code_verifier
        },
        # Add
        "nonce": {
            "S": state_result["Item"]["nonce"]["S"]
        },
        "ttl": {
            "N": str(code_ttl)
        }
    }
)

これで RP が生成した nonce を token Lambda 関数で取得する準備が整いました。
最後に、cognito-external-idp-proxy/lambda/token/token_flow.py の 122 行目の直後に、以下のコードを追加し、code テーブルから取得した nonce を変数に格納します。

nonce = code_result["Item"]["nonce"]["S"]

デコードした ID トークンの検証後（ if decoded_id_token['at_hash'] != calculated_at_hash: での検証後）に、以下のコードを追加し、変数に格納した nonce の値（ RP で生成したもの）と ID トークンに含まれる nonce の値（デジタル認証アプリサービスのレスポンス）が等しいかを検証します。

    if decoded_id_token["nonce"] != nonce:
        print("Nonce mismatch")
        return { "statusCode": 400 }
# トークンの検証時に例外が発生したら、認証失敗とするための例外処理
except Exception as e:
    return { "statusCode": 400 }

アクセストークン置き換え攻撃への対策

この要件は、ID トークンのペイロード検証時に、 at_hash クレームの検証を行なっているため、対策済みとなります。

SPA やバックエンドで必要な実装

これまでの実装で、デジタル認証アプリサービス API を通じて、認証を行うことができるようになりました。実際のサービスでは、この認証後に発行される Cognito のトークンを用いて、サービスの API に対する認可処理を行い、さまざまな処理を実行することになります。
今回のデモでは、Cognito のユーザ属性から生年月日を確認し、20歳以上かどうか判断するという一連の流れを、React と Amazon API Gateway と COGNITO_USER_POOLS タイプのオーソライザー（オーソライザー）を利用して実装したいと思います。React からは Cognito のアクセストークンを送信し、オーソライザーでアクセストークンに含まれるスコープ（custom/read:age)を検証し、API の利用可否を判断（認可）します。
このアクセストークンに含まれるスコープは、独自で Cognito に設定した、デモ用に作成した API のためのスコープです。具体な実装は、この後の「CDK の実装例」で示しています。

SPA の実装

今回は、Cognito のコンソールで紹介されているサンプル実装を利用します。利用するライブラリは、oidc-client-ts ライブラリと react-oidc-context ライブラリです。SPA における OIDC の利用で論点になるのは、トークンのハンドリング方法ですが、これは各サービスのポリシーに合わせ、BFF や、Custom Storage などの採用をご検討ください。
本実装はあくまでサンプルです。InMemoryWebStorage を利用することでページリロード時のユーザ体験が損なわれてしまう点や、環境変数やバックエンドとの接続設定や、API 呼び出しの処理など、皆様がご利用される際には、本番環境向けに、適切に実装してください。

実装例 – main.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import { AuthProvider } from "react-oidc-context";
import "./index.css";
import { InMemoryWebStorage, WebStorageStateStore } from "oidc-client-ts";

const cognitoAuthConfig = {
  authority: "https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_XXXXXXXXXX",
  client_id: "xxxxxxxxxxxxxxxxxx",
  redirect_uri: "http://localhost:5173", // デモアプリのため、localhostで実装しています。
  response_type: "code",
  scope: "custom/read:age openid",
  automaticSilentRenew: true,
  silentRedirectUri: "http://localhost:5173", // デモアプリのため、localhostで実装しています。
  onSigninCallback: () => {
    window.history.replaceState({}, document.title, window.location.pathname);
  },
  userStore: new WebStorageStateStore({ store: new InMemoryWebStorage() }),
};

const root = ReactDOM.createRoot(document.getElementById("root")!);

root.render(
  <React.StrictMode>
    <AuthProvider {...cognitoAuthConfig}>
      <App />
    </AuthProvider>
  </React.StrictMode>
);

実装例 – App.tsx

今回は、RFC6750 に従い、アクセストークンを指定し、オーソライザーでスコープによるアクセス制御を実現します。
参考：リソースサーバーを使用したスコープ、M2M、および API

import { useCallback, useEffect, useState } from "react";
import { useAuth } from "react-oidc-context";
import AppIcon from "../public/App-Icon_White.svg";

function App() {
  const auth = useAuth();
  const [isLoading, setIsLoading] = useState(true);
  const [isOver20, setIsOver20] = useState(false);

  const signOutRedirect = () => {
    const clientId = "xxxxxxxxxxxxxxxxxxxxxxxx";
    const logoutUri = "http://localhost:5173";
    const cognitoDomain = "https://xxxxxxxxxx.auth.ap-northeast-1.amazoncognito.com";
    window.location.href = `${cognitoDomain}/logout?client_id=${clientId}&logout_uri=${encodeURIComponent(logoutUri)}`;
  };

  const ageCheck = useCallback(async() => {
    try {
      const res = await fetch("https://xxxxxxxxxx.execute-api.ap-northeast-1.amazonaws.com/prod/api/age-check", {
        method: "GET",
        headers: {
          "Content-Type": "application/json",
          "Authorization": `Bearer ${auth.user?.access_token}`, // アクセストークンを指定する
        },
      });
      if (res.ok) {
        const data = await res.json();
        setIsOver20(Boolean(data.isOver20));
        setIsLoading(false);
      }
    } catch(error) {
      console.error("Error was happend:", error);
    }
  }, [auth.user?.access_token])

  useEffect(() => {
    if (auth.isAuthenticated) {
      ageCheck();
    }
  }, [auth.isAuthenticated, ageCheck])

  if (auth.isLoading) {
    return <div>Loading...</div>;
  }

  if (auth.error) {
    return <div>Encountering error... {auth.error.message}</div>;
  }

  return (
    <div className="flex flex-col items-center justify-center h-screen">
      <h1 className="text-2xl mb-20">デジタル認証アプリ デモ on AWS</h1>
      <>
      {auth.isAuthenticated ? (
        <>
          <pre> {auth.user?.profile.name} さんは、 {isLoading ? "読み込み中..." : isOver20 ? "20歳以上です。" : "20歳未満です。"} </pre>
          <button 
            className="mt-4 flex justify-center items-center bg-digital-agency-blue-default text-white px-4 py-2 rounded-md hover:bg-digital-agency-blue-hover active:bg-digital-agency-blue-active focus:outline-none focus:ring-2 focus:ring-[#0017C1] focus:ring-opacity-50"
            onClick={() => signOutRedirect()}>
            ログアウト
          </button>
        </>
      ) : (
        <>
          <div className="text-center">本人確認のため、デジタル庁が提供するデジタル認証アプリを利用します。</div>
          <button 
            className="mt-4 flex justify-center items-center bg-digital-agency-blue-default text-white px-4 py-2 rounded-md hover:bg-digital-agency-blue-hover active:bg-digital-agency-blue-active focus:outline-none focus:ring-2 focus:ring-[#0017C1] focus:ring-opacity-50"
            onClick={() => auth.signinRedirect()}>
            <img src={AppIcon} alt="App Icon" className="mr-4 w-6 h-6 fill-white" />
            マイナンバーカードでログイン
          </button>
        </>
      )}
      </>
      <footer className="absolute right-0 left-0 bottom-0 bg-gray-100 w-full">
          <div className="flex justify-center space-x-4">
            <pre>サービスについて</pre>
            <pre>利用規約</pre>
            <pre>ポリシー</pre>
          </div>
      </footer>
    </div>
  );
}

export default App

アプリのデザインについて

デジタル認証アプリを利用するアプリケーションには、デザインガイドラインも示されています。フロントエンドアプリケーションは、こちらに従うようにしてください。
https://developers.digital.go.jp/documents/auth-and-sign/design-guideline/

バックエンドの実装

前述の通り、API Gateway と オーソライザー、Lambda で API とその認可処理を実装します。今回実装したサンプルのバックエンドでは、トークンベースでアクセス制御、つまりトークン所有者による代理アクセスとして、バックエンドが保持するユーザー情報を特定、照合することで、データにアクセスしているユーザーが、本当にそのデータのユーザーであるかを検証しています。

CDK の実装例

バックエンド用のコンストラクトを次のように作成します。このコンストラクトを PjwtWithPkceStack から呼び出してください。
construct の実装例（ファイルは、cognito-external-idp-proxy/cdk/construct/backend.py のように追加します）は次のようになります。

from aws_cdk import (
    aws_apigateway as _apigw,
    aws_lambda as _lambda,
    aws_cognito as _cognito,
    aws_iam as _iam,
    Duration,
)
from constructs import Construct
from cdk_nag import NagSuppressions

class Backend(Construct):
    def __init__(self, scope: Construct, id: str, user_pool: _cognito.UserPool, oauth_scopes: list[str], **kwargs):
        super().__init__(scope, id)

        # Create API Gateway with CORS
        self.api = _apigw.RestApi(
            self,
            "BackendApi",
            rest_api_name="Backend API",
            description="API Gateway with COGNITO_USER_POOLS type authorizer and custom scopes",
            default_cors_preflight_options=_apigw.CorsOptions(
                allow_origins=["http://localhost:5173"],
                allow_methods=["GET", "OPTIONS"],
                allow_headers=["Content-Type", "X-Amz-Date", "Authorization", "X-Api-Key",
                             "X-Amz-Security-Token", "X-Amz-User-Agent"],
                max_age=Duration.days(1)
            )
        )

        # Create an authorizer of the type of COGNITO_USER_POOLS
        auth = _apigw.CognitoUserPoolsAuthorizer(
            self,
            "CognitoUserPoolsAuthorizer",
            cognito_user_pools=[user_pool]
        )

        # Create age_check Lambda function
        age_check_lambda = _lambda.Function(
            self,
            "AgeCheckFunction",
            runtime=_lambda.Runtime.PYTHON_3_10,
            handler="age_check.handler",
            code=_lambda.Code.from_asset("./lambda/age_check"),
            timeout=Duration.seconds(30),
            environment={
                "USER_POOL_ID": user_pool.user_pool_id
            }
        )
        age_check_lambda.add_to_role_policy(
            _iam.PolicyStatement(
                effect=_iam.Effect.ALLOW,
                actions=["cognito-idp:AdminGetUser"],
                resources=[user_pool.user_pool_arn]
            )
        )

        # Create API resources and methods
        api_resource = self.api.root.add_resource("api")
        age_check_resource = api_resource.add_resource("age-check")

        # Add method with authorization
        age_check_get_method = age_check_resource.add_method(
            "GET",
            _apigw.LambdaIntegration(age_check_lambda),
            authorizer=auth,
            authorization_type=_apigw.AuthorizationType.COGNITO,
            authorization_scopes=["custom/read:age"]  # Custom scope for age check
        )

        # Grant Lambda permissions to be invoked by API Gateway
        age_check_lambda.add_permission(
            "ApiGatewayInvoke",
            principal=_iam.ServicePrincipal("apigateway.amazonaws.com"),
            source_arn=age_check_get_method.method_arn
        )

        # Create custom resource scope
        age_check_scope = _cognito.ResourceServerScope(
            scope_name="read:age",
            scope_description="Permission to access age check endpoint"
        )

        # Create resource server for custom scopes
        resource_server = user_pool.add_resource_server(
            "ResourceServer",
            identifier="custom",
            scopes=[age_check_scope]
        )

        # Add custom scope to OAuth scopes
        oauth_scopes.append(_cognito.OAuthScope.resource_server(resource_server, age_check_scope)) 

        """
        SUPPRESSION RULES FOR CDK_NAG
        """

        NagSuppressions.add_resource_suppressions(
            self.api, [
                { "id": "AwsSolutions-APIG2", "reason": "This is demo api. There is no request parameters for this API."}
            ]
        )

        NagSuppressions.add_resource_suppressions(
            self.api.deployment_stage, [
                { "id": "AwsSolutions-APIG1", "reason": "This is demo api. Logging of APIGW is not necessary. Instead, Lambda turned on logging."},
                { "id": "AwsSolutions-APIG3", "reason": "This is demo api. This is protected by COGNITO_USER_POOLS authorizer. It's enough for dev env. If you go to production, you have to attach WAF."},
                { "id": "AwsSolutions-APIG6", "reason": "This is demo api. Logging of APIGW is not necessary. Instead, Lambda turned on logging."}
            ]
        )

        NagSuppressions.add_resource_suppressions(
            age_check_lambda.role, [
                { "id": "AwsSolutions-IAM4", "reason": "Managed policies were used by CDK automatically. Managed policies make CDK simple."}
            ]
        )

        NagSuppressions.add_resource_suppressions(
            age_check_lambda, [
                { "id": "AwsSolutions-L1", "reason": "Runtime version followed cognito-external-idp-proxy's runtime version."}
            ]
        )

Lambda の実装例

import boto3
import json
from datetime import datetime
import os

headers = {
    'Access-Control-Allow-Origin': 'http://localhost:5173',
    'Access-Control-Allow-Headers': 'Content-Type',
    'Access-Control-Allow-Methods': 'OPTIONS,GET'
}

def get_birthdate(username):
    """
    Get custom:birth attribute by cognito AdminGetUser api
    """
    try:
        cognito = boto3.client('cognito-idp')
        response = cognito.admin_get_user(
            UserPoolId = os.environ.get('USER_POOL_ID'),
            Username = username 
        )
        # Get value when match UserAttributes Name is custom:birth
        birthdate:str = next((attr['Value'] for attr in response['UserAttributes'] if attr['Name'] == 'custom:birth'), None)
        return birthdate
    except Exception as e:
        raise ValueError(f"Error getting birthdate: {str(e)}")


def calculate_age(birthdate_str):
    """
    Calculate age from birthdate string in YYYYMMDD format
    """
    try:
        birthdate = datetime.strptime(birthdate_str, '%Y%m%d')
        today = datetime.now()
        age = today.year - birthdate.year - ((today.month, today.day) < (birthdate.month, birthdate.day))
        return age
    except ValueError as e:
        raise ValueError(f"Invalid birthdate format. Expected YYYY-MM-DD, got: {birthdate_str}")

def handler(event, context):
    """
    Lambda function to check age from claims in the JWT token and verify if user is over 20
    """
    try:
        print("+++ event +++")
        print(event)
        # Get the claims from the authorizer context
        claims = event['requestContext']['authorizer']['claims']
        
        # Check if sub claim exists
        if 'username' not in claims:
            return {
                'statusCode': 400,
                'headers': headers,
                'body': json.dumps({
                    'message': 'sub claim not found in token'
                })
            }
        
        # Calculate age and check if over 20
        birthdate = get_birthdate(claims['username'])
        if birthdate is None:
            return {
                'statusCode': 400,
                'headers': headers,
                'body': json.dumps({
                    'message': 'This user is not found in userpool.'
                })
            }
        age = calculate_age(birthdate)
        is_over_20 = age >= 20
        
        return {
            'statusCode': 200,
            'headers': headers,
            'body': json.dumps({
                'isOver20': is_over_20,
            })
        }

    except Exception as e:
        return {
            'statusCode': 500,
            'headers': headers,
            'body': json.dumps({
                'message': f'Error processing request: {str(e)}'
            })
        }

属性マッピングの修正

認証後にデジタル認証アプリサービス API から取得できる券面情報（基本4情報）をマッピングしたい場合、name, gender, addressは Cognito の標準の属性が利用できますが、birthdate は 10 桁の YYYY-mm-dd フォーマットである必要があるため、この API で提供されるデータ形式と異なり、エラーとなってしまいます。そこで、UserPool 作成時に、カスタム属性として custom:birthdate を追加し、ログイン時にこのカスタム属性に券面情報の生年月日を連携します。これを行うには、以下のように CDK のソースコードを修正します。

UserPool へのカスタム属性の追加

生年月日をマッピングしたい場合だけ、追加してください。cognito-external-idp-proxy/cdk/pjwt_with_pkce_stack.py の 346行目を以下のように更新してください。

# Cognito User Pool base configuration
cognito_user_pool = _cognito.UserPool(self, "UserPool",
    custom_attributes={"birth": _cognito.StringAttribute(mutable=True, max_len=8, min_len=8)}
)

カスタム属性のマッピング

また、基本 4 情報を全てマッピングする場合は、以下のように修正してください。（不要な属性はマッピング対象から除外してください。）cognito-external-idp-proxy/cdk/pjwt_with_pkce_stack.py の 350行目を以下のように更新してください。

cognito_user_pool_idp_oidc = _cognito.UserPoolIdentityProviderOidc(
    self, "IdentityProvider",
    client_id = self.node.try_get_context("idp_client_id"),
    client_secret = self.node.try_get_context("idp_client_secret"),
    issuer_url = idp_issuer_url,
    user_pool = cognito_user_pool,
    attribute_request_method = _cognito.OidcAttributeRequestMethod.GET,
    attribute_mapping = _cognito.AttributeMapping(
       address = _cognito.ProviderAttribute.other("address"),
        fullname = _cognito.ProviderAttribute.other('name'),
        gender = _cognito.ProviderAttribute.other("gender"),
        custom = {
            "custom:birth": _cognito.ProviderAttribute.other("birthdate"),
        }
    ),
    endpoints = _cognito.OidcEndpoints(
        authorization = apigw_proxy_route_auth_uri,
        jwks_uri = idp_issuer_url + self.node.try_get_context("idp_keys_path"),
        token = apigw_proxy_route_token_uri,
        user_info = idp_issuer_url + self.node.try_get_context("idp_attributes_path")
    ),
    name = self.node.try_get_context("idp_name"),
    scopes = self.node.try_get_context("idp_scopes").split()
)

Tips
Cognito はカスタム属性をキーに検索できないため、カスタム属性をキーに検索したい要件があれば、外部のデータストア（Amazon DynamoDB など）に券面情報を保存することをご検討ください。

デプロイ方法

ここまで実装お疲れ様でした。この後はデプロイを行い、動作を確認していきます。
cognito-external-idp-proxy のカスタマイズが完了し、デジタル認証アプリのサンドボックス環境の準備が整っていることを確認し、以下のようにパラメータを設定の上、cognito-external-idp-proxy の README の手順に沿ってデプロイします。

{
  "api_version": "v1",
  "api_authn_route": "/oauth2/authorize",
  "api_callback_route": "/callback",
  "api_token_route": "/oauth2/token",
  "idp_attributes_path": "/protocol/openid-connect/userinfo",
  "idp_auth_path": "/protocol/openid-connect/auth",
  "idp_keys_path": "/protocol/openid-connect/certs",
  "idp_token_path": "/api/realms/main/protocol/openid-connect/token",
  "idp_client_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "idp_client_secret": "secret",
  "idp_issuer_url": "https://sb-auth-and-sign.go.jp/api/realms/main",
  "idp_name": "digital-auth-and-sign",
  "idp_scopes": "openid name address birthdate gender",
  "pkce": true,
  "stack_name": "CognitoExternalIdpProxyStack",
  "userpool_allowed_callback_url": "http://localhost:5173"
}

無事デプロイが終われば、J-LIS より貸与された、または購入したテストカードを利用し、動作確認を行います。

動作確認

それでは、デジタル認証アプリでのログインと券面情報（ユーザの情報、基本４情報）が取れるか、取得したアクセストークンを用いて年齢確認 API にリクエストを送り、20 歳以上かどうか判定するデモを、動画でご覧ください。

SPA に表示されている、「マイナンバーカードでログイン」をクリックすると、デジタル認証アプリが提供するサービスページに遷移し、デジタル認証アプリのログインシーケンスが始まります。
QR コードが表示されますので、これをスマートフォンで読み取ると、スマートフォンにインストールされたデジタル認証アプリが起動し、マイナンバーカードによるログインを求められます。
ログインが成功すると、先ほどまでデジタル認証アプリのサービスページが表示されていたタブは、リダイレクトし SPA のログイン後画面に遷移します。券面情報は、Cognito の属性マッピングにより、Cognito へ連携されているため、Cognito の API から取得でき、SPA 上に表示することができます。

Cognito へ属性マッピングされた券面情報は、引き続き、自社のサービスで利用することができます。今回は、アクセストークンの sub クレームから取得したユーザー ID をキーに、Cognito に登録された生年月日を GetAdminUser API で取得し、ログインしたユーザーが 20 歳以上か判定する処理を実装しました。
このようにデジタル認証アプリサービス API を利用し、自社のサービスをより高度に・高価値にしていくことができることでしょう。

終わりに

いかがでしたでしょうか。本記事では、デジタル認証アプリサービス API を利用し、Cognito と連携するための実装方法を紹介しました。
皆様が実装を行う際には、利用予定のユーザの認証リクエストの予測数から、AWS 側の API のクォータ（本サンプルでは、Cognito の GetAdminUser API や、Secrets Manager の GetRandomPassword API を利用します）を確認し、問題なくサービス提供できるよう設計ください。
本人認証や本人確認は、サービスを提供する上でなくてはならないものであり、一連の体験は、お客様の満足度向上に大きく寄与する部分です。JPKI を利用した認証により、サービスの利便性を向上させることはこのデジタル社会では不可欠ですので、ぜひご活用いただければと思います。

著者