Microsoft Entra ID認証を構成する

このガイドでは、データ API ビルダー用に Microsoft Entra ID (旧称 Azure Active Directory) 認証を構成する手順について説明します。 最終的に、クライアント アプリは Entra を介してユーザーを認証し、データ API ビルダーのトークンを取得し、DAB はマネージド ID を使用して Azure SQL に接続できます。

データ API ビルダーは、JSON Web トークン (JWT) ベアラー検証 (EntraID/AzureAD/Custom) またはプラットフォーム指定の ID ヘッダー (AppService) を使用して受信要求を認証します。 ローカル開発とアクセス許可のテストには、 Simulator プロバイダーを使用します。

認証プロバイダーのガイド

アイデンティティプロバイダーに基づいてガイドを選択してください。

認証フロー

フローには、次の 3 つの異なるフェーズがあります。

前提条件

• Microsoft Entra ID テナントを持つ Azure サブスクリプション
• Data API Builder CLI がインストールされている (インストール ガイド)
• 少なくとも 1 つのエンティティを持つ既存のdab-config.json
• (省略可能) Azure SQL Database を使用したマネージド ID シナリオ

クイック リファレンス

手順 1: Microsoft Entra IDにアプリケーションを登録する

データ API ビルダー API を表すアプリ登録を作成します。 クライアント アプリは、この登録に一致する対象ユーザーを含むトークンを要求します。

1. Microsoft Entra 管理センターにサインインします。

2. Identity>Applications>App registrations に移動します。

3. [新規登録] を選択します。

4. 名前を入力 します (例: Data API Builder API)。

5. シナリオに適 したサポートされているアカウントの種類 を選択します。

   • シングル テナント: 組織内のユーザーのみ
   • マルチテナント: 任意の Microsoft Entra ディレクトリ内のユーザー

6. リダイレクト URI は空白のままにします (この登録はクライアントではなく API 用です)。

7. 登録 を選択します。

8. アプリの [概要 ] ページで、次の値を記録します。

   価値	記載場所	用途
   アプリケーション (クライアント) ID	[概要] ページ	対象ユーザー URI の構築
   ディレクトリ (テナント) ID	[概要] ページ	発行者 URL の構築

アプリケーション ID URI を構成する

1. アプリの登録で、[API の 公開] に移動します。

2. [アプリケーション ID URI] の横にある [追加] を選択します。

3. 既定値 (api://<app-id>) をそのまま使用するか、カスタム URI を入力します。

4. 保存を選びます。

スコープを追加する

クライアント アプリケーション (Azure CLI を含む) が API の委任されたアクセス トークンを要求できるように、スコープが必要です。

1. アプリの登録で、[API の 公開] に移動します。

2. [この API で定義されるスコープ] で、 [スコープの追加] を選択します。

3. 入力します

   • スコープ名: Endpoint.Access
   • 同意できるのはだれですか? : 管理者とユーザー
   • 管理者の同意の表示名: Execute requests against Data API builder
   • 管理者の同意の説明: Allows client app to send requests to Data API builder endpoint.
   • ユーザーの同意の表示名: Execute requests against Data API builder
   • ユーザーの同意の説明: Allows client app to send requests to Data API builder endpoint.
   • 状態: 有効

4. [スコープの追加] を選択します。

アプリ ロールの追加 (省略可能)

AnonymousとAuthenticated以外のカスタム ロールを使用する場合:

1. [アプリ ロール] に移動します。

2. [ アプリ ロールの作成] を選択します。

3. 入力します

   • 表示名: Reader
   • 許可されるメンバーの種類: ユーザー/グループ または 両方
   • 値: reader (この値はトークンの roles 要求に表示されます)
   • 説明: Read-only access to data

4. を選択してを適用します。

5. その他のロール ( writer、 adminなど) に対して繰り返します。

マニフェスト トークンのバージョンを設定する

既定では、アプリ登録マニフェストは accessTokenAcceptedVersion を null に設定し、v1.0 トークンを生成します。 V1 トークンでは、DAB で構成された v2.0 発行者とは異なる発行者形式 (https://sts.windows.net/<tenant-id>/) が使用されるため、トークンの検証が失敗します。

1. アプリの登録で、[マニフェスト] に移動 します。

2. accessTokenAcceptedVersionを見つけて、値を2に変更します。

3. 保存を選びます。

ユーザーをアプリ ロールに割り当てる

アプリ ロールを作成しても、ユーザーに自動的には付与されません。 エンタープライズ アプリケーションを使用してユーザーまたはグループを割り当てる必要があります。

1. Microsoft Entra管理センターで、Identity>Applications>Enterprise アプリケーションに移動します。

2. アプリを検索して選択します (たとえば、 Data API Builder API)。 エンタープライズ アプリケーションは、アプリの登録時に自動的に作成されました。

3. [ ユーザーとグループ] に移動します。

4. [ ユーザー/グループの追加] を選択します。

5. [ ユーザー] で、割り当てるユーザー アカウントを選択し、[選択] を 選択します。

6. [ ロールの選択] で、割り当てるロール ( Readerなど) を選択します。 ロールが表示されない場合は、Microsoft Entraレプリケーションが完了するまで数分待ちます。

7. 割り当てを選びます。

8. 割り当てるロールごとに繰り返します。

手順 2: データ API ビルダーを構成する

API 対象ユーザーに対して Entra テナントによって発行されたトークンを検証するように DAB を構成します。

CLI

# Set the authentication provider
dab configure \
  --runtime.host.authentication.provider EntraID

# Set the expected audience (Application ID URI)
dab configure \
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

# Set the expected issuer (your tenant)
dab configure \
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

REM Set the authentication provider
dab configure ^
  --runtime.host.authentication.provider EntraID

REM Set the expected audience (Application ID URI)
dab configure ^
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

REM Set the expected issuer (your tenant)
dab configure ^
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

結果の構成

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://login.microsoftonline.com/<your-tenant-id>/v2.0"
        }
      }
    }
  }
}

手順 3: エンティティのアクセス許可を構成する

各エンティティにアクセスできるロールを定義します。 要求は、トークンから決定されたロールに対して評価されます。

認証済みユーザーにアクセス権を付与する

dab update Book \
  --permissions "Authenticated:read"

dab update Book ^
  --permissions "Authenticated:read"

カスタム ロールへのアクセスを許可する

dab update Book \
  --permissions "reader:read" \
  --permissions "writer:create,read,update"

dab update Book ^
  --permissions "reader:read" ^
  --permissions "writer:create,read,update"

結果の構成

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "reader",
          "actions": ["read"]
        },
        {
          "role": "writer",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

手順 4: データベース接続を構成する

データ API ビルダーは、認証されたユーザーとは別に、独自の ID を使用してデータベースに接続します。 Azure SQL での運用シナリオでは、マネージド ID を使用します。

オプション A: マネージド ID (Azure に推奨)

システムによって割り当てられた管理ID

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;Encrypt=True;"
  }
}

ユーザーが割り当てた管理ID

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;User Id=<uami-client-id>;Encrypt=True;"
  }
}

オプション B: SQL 認証 (開発)

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  }
}

オプション C: ローカルでの開発 az login

Azure SQL に対するローカル開発の場合は、Azure CLI 資格情報を使用します。

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;"
  }
}

DAB を開始する前に、サインインします。

az login

手順 5: 構成をテストする

クライアント アプリケーションとしてAzure CLIを承認する

Azure CLIが API のトークンを取得するには、そのトークンを承認されたクライアント アプリケーションとして追加する必要があります。

1. アプリの登録で、[API の 公開] に移動します。

2. [ 承認されたクライアント アプリケーション] で、[ クライアント アプリケーションの追加] を選択します。

3. Azure CLI クライアント ID 00001111-aaaa-2222-bbbb-3333cccc4444 を入力します。

4. api://<app-id>/Endpoint.Access スコープを選択します。

5. アプリケーション追加を選択します。

Azure CLIを使用してトークンを取得する

Azure CLIにサインインし、アプリの登録が存在するテナントを設定します。

az login
az account set --tenant <your-tenant-id>

API にスコープを設定したトークンを要求します。

az account get-access-token --scope api://<your-app-id>/Endpoint.Access --query "accessToken" -o tsv

jwt.ms でトークンを調べて、aud、iss、およびroles要求を確認できます。

DAB を開始して要求を送信する

1. データ API ビルダーを起動します。

   dab start
   

2. トークンを使用して API を呼び出します。

   curl -X GET "http://localhost:5000/api/Book" \
     -H "Authorization: Bearer <your-token>"
   

3. カスタム ロールを使用するには、 X-MS-API-ROLE ヘッダーを含めます。

   curl -X GET "http://localhost:5000/api/Book" \
     -H "Authorization: Bearer <your-token>" \
     -H "X-MS-API-ROLE: reader"
   

ロールの選択動作

データ API ビルダーは、次のロジックを使用して要求のロールを決定します。

Troubleshooting

完全な構成例

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=mydb;Authentication=Active Directory Managed Identity;Encrypt=True;"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://dab-api-12345678",
          "issuer": "https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "librarian",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    }
  }
}

関連するコンテンツ

• 認可とロール
• テスト用にシミュレーター認証を構成する
• App Service 認証を構成する
• ランタイム構成リファレンス