FHIR サービスの ID プロバイダー構成のトラブルシューティング

[アーティクル]
02/25/2024

Azure Health Data Services の FHIR® サービスの API バージョン 2023-12-01 では、Microsoft Entra ID に加えて 2 つの ID プロバイダーがサポートされています。スコープ指定されたアクセスをユーザーに提供するには、authenticationConfiguration オブジェクトの smartIdentityProviders セクションを設定して 2 つの ID プロバイダーを構成します。

エラーメッセージ

FHIR サービス SMART ID プロバイダーが失敗した場合に発生するエラーメッセージと、問題を解決するために実行する推奨されるアクションを次に示します。

エラー	原因	固定
SMART ID プロバイダーの数は最大で 2 つまでです。	ID プロバイダーの設定数が 2 を超える数になっています。	ID プロバイダーの数を、2 以下に減らしてください。
1 つ以上の SMART ID プロバイダーオーソリティの値が、null、空白である、または無効になっています。	ID プロバイダー構成の `authority` 要素が完全修飾 URL となる必要があります。	すべての `authority` 値が完全修飾 URL となっていることを確認してください。
すべての SMART ID プロバイダーオーソリティが一意である必要があります。	2 つの ID プロバイダー構成の `authority` 要素は同一です。	すべての `authority` 値が一意な完全修飾 URL となっていることを確認してください。
SMART ID プロバイダーアプリケーションの数は最大で 2 つまでです。	ID プロバイダー構成内の ID プロバイダーアプリケーションの数が 2 を超えています。	ID プロバイダーのアプリケーションの数を ID プロバイダーごとに 1 つまたは 2 つに減らします。
1 つ以上の SMART アプリケーションが null です。	1 つ以上の ID プロバイダーの `applications` の要素が null である、または、アプリケーションが含まれていません。	すべての ID プロバイダー構成内に 1 つ以上のアプリケーションが構成されていることを確認してください。
1 つ以上の SMART アプリケーション`allowedDataActions` に、重複した要素が含まれています。	`allowedDataActions` 1 つ以上のアプリケーション構成内の配列に、重複する値が含まれています。	`allowedDataActions` 配列内の重複する値を削除します。
1 つ以上の SMART アプリケーションの `allowedDataActions` 値が無効です。	`allowedDataActions` 配列内での許容値は `Read` のみです。	すべての不適合な値を、`allowedDataActions` 配列から削除してください。
SMART アプリケーションの 1 つ以上の `allowedDataActions` 値が null または空です。	1 つ以上のアプリケーション構成の `allowedDataActions` 配列が null または空です。	`allowedDataActions` 配列内での許容値は `Read` のみです。
1 つ以上の SMART アプリケーションの `audience` 値が、null、空白である、または無効になっています。	1 つ以上のアプリケーション構成内の `audience` 文字列、null、空白である、または誤りがある形式になっています。	`audience` 文字列が null にも空白にもなっておらず、値が文字列型となっていることを確認してください。
すべての SMART ID プロバイダーアプリケーションクライアント ID が、一意となっている必要があります。	`clientId` 1 つ以上のアプリケーション構成の値が別の`clientId` の値と同じ値になっています。	すべての `clientId` 値が一意であるようにしてください (ID プロバイダーの構成で確認してください)。
1 つ以上の SMART アプリケーションクライアント ID の値が、null、空白である、または無効になっています。	1 つ以上のアプリケーション構成内の `clientId` 文字列、null、空白である、または誤りがある形式になっています。	`clientId` 文字列が null にも空白にもなっておらず、値が文字列型となっていることを確認してください。

FHIR API 要求のエラー

SMART ID プロバイダーによって発行されたトークンを使用して FHIR サービスに要求を行うと、次の 2 つの一般的なエラーコードが発生する可能性があります (401 Unauthorized または 403 Forbidden)。トラブルシューティングを開始する場合は smartIdentityProviders 要素の構成をチェックしてください (特に、FHIR サービスが新しい場合)。

次の手順に従って smartIdentityProviders 要素の正しい構成を確認してください。

smartIdentityProviders 要素が正しく構成されていることを確認します。
authority 文字列が適切であることを確認してください。 authority 文字列が、アクセストークンを発行した ID プロバイダーのトークンオーソリティとなっていることを確認してください。
authority 文字列が、検証トークンオーソリティであることを確認します。 OpenID Connect 構成のために、要求を実行します。 aubrowser navigatesthority 文字列の末尾に /.well-known/openid-configuration をアペンドして、続いて、それをブラウザー内に貼り付けます。値が適切である場合は、ブラウザーが openid-connect configuration に移動します. 移動しない場合は、文字列に問題があります。

例:
```
https://<YOUR_IDENTITY_PROVIDER_AUTHORITY>/authority/v2.0/.well-known/openid-configuration
```
clientId 文字列が適切であることを確認してください。 clientId 文字列が、ID プロバイダー内で定義されているリソースアプリケーションのクライアント ID (またはアプリケーション ID) と一致していることを確認してください。
要求メソッドが GET であることを確認してください。 allowedDataActions の値は Read のみをサポートするため、サポートされる要求の種類は GET のみです。
JSON Web トークン (JWT) 要求を確認してください。アクセストークンが使用可能な場合は、jwt.ms などのオンラインツールを使用してデコードしてください。トークンがデコードされると、要求の正確性を検査することができます。
iss (発行元要求) を確認します。 iss 要求が、ID プロバイダーの OpenId 構成内の issuer の値と正確に一致していることを確認してください。

smartIdentityProvider ID プロバイダー設定からの値 authorityを取得して、それを /.well-known/openid-configuration を使用してブラウザー内にアペンドします。値が適切である場合は、ブラウザーが OpenID Connect 構成に移動します。

例:
```
https://<YOUR_IDENTITY_PROVIDER_AUTHORITY>/authority/v2.0/.well-known/openid-configuration
```
azp または appid (承認されたパーティーまたは appid クレーム) を確認します。 azp または appid 要求が、smartIdentityProvider ID プロバイダー構成で提供された clientId 値と完全に一致していることを確認してください。
aud (オーディエンス要求)を確認します。 aud 要求が、smartIdentityProvider ID プロバイダーの構成内で指定された audience の値と完全に一致している必要があります。
scp (範囲の要求) を確認します。 scp 要求は必須となっています。それがなかった場合、要求は失敗します。 scp 要求の形式は、SMART on FHIR v1 スコープに準拠している必要があります。重要な注意事項: FHIR サービスでは、現在、読み取りスコープのみがサポートされていることに注意してください。 SMART on FHIR v1 スコープの許容されるバリエーションは、スラッシュ (/) を,ピリオド (.) と all 付きのアスタリスク (*) に置き換えます。たとえば、SMART on FHIR スコープ patient/*.read の許容されるバージョンは patient.all.read です。

Note

read スコープのみがサポートされています。

fhirUser または extension_fhirUser (FHIR ユーザークレーム) を確認します。 fhirUser または extension_fhirUser 要求は必須です。それがなかった場合、要求は失敗します。この要求により、ID プロバイダー内のユーザーが FHIR サービスのユーザーリソースにリンクされます。値は、アクセストークンが発行される個人を表す FHIR サービス内のリソースの完全修飾 URL であることが必要です。たとえば、ログインした患者に発行されたアクセストークンには、FHIR サービスの患者リソースの完全修飾 URL を持つ fhirUser または extension_fhirUser 要求が必要です。

スキーマで ID プロバイダーを構成する

smartIdentityProviders 要素は、1 つまたは 2 つの identity provider configurations を含む JSON 配列です。 identity provider configuration は次のもので構成されます。

ID プロバイダートークンオーソリティの完全修飾 URL である必要がある authority 文字列の値。
ID プロバイダーリソース application configurations を含む applications 配列。

{
  "properties": {
    "authenticationConfiguration": {
      "authority": "string",
      "audience": "string",
      "smartProxyEnabled": "bool",
      "smartIdentityProviders": [
        {
          "authority": "string",
          "applications": [
            {
              "clientId": "string",
              "allowedDataActions": "array",
              "audience": "string"
            }
          ]
        }
      ]
    }
  }
}

applications 要素は、1 つまたは 2 つの application configurationsを含む JSON 配列です。

application configuration は次の要素で構成されます。

ID プロバイダーリソースアプリケーションのクライアント ID (アプリケーション ID とも呼ばれます) の clientId 文字列値。
アクセストークンで aud 要求を検証するために使用される audience 文字列。
allowedDataActions の配列。 allowedDataActions 配列には文字列値 Read のみを含めることができます。

{
  "authority": "string",
  "applications": [
    {
      "clientId": "string",
      "allowedDataActions": "array",
      "audience": "string"
    }
  ]
}

{
  "clientId": "string",
  "allowedDataActions": "array",
  "audience": "string"
}

次のステップ

Azure Active Directory B2C を使用して FHIR サービスへのアクセスを許可する

複数の ID プロバイダーを構成する

Note

FHIR® は HL7 の登録商標であり、HL7 の許可を得て使用しています。

次の方法で共有

FHIR サービスの ID プロバイダー構成のトラブルシューティング

エラーメッセージ

FHIR API 要求のエラー

スキーマで ID プロバイダーを構成する

次のステップ

フィードバック

その他のリソース

次の方法で共有

FHIR サービスの ID プロバイダー構成のトラブルシューティング

エラー メッセージ

FHIR API 要求のエラー

スキーマで ID プロバイダーを構成する

次のステップ

フィードバック

その他のリソース

エラーメッセージ