エンタープライズ アプリケーション用に JSON Web Token (JWT) で発行されるクレームをカスタマイズする

Microsoft ID プラットフォームは、Microsoft Entra アプリケーション ギャラリーとカスタム アプリケーションのほとんどの事前統合アプリケーションで シングル サインオン (SSO) をサポートしています。 ユーザーが OIDC プロトコルを使用して Microsoft ID プラットフォーム経由でアプリケーションに対する認証を行うと、アプリケーションにトークンが送信されます。 アプリケーションはトークンを検証し、ユーザー名とパスワードの入力を求める代わりに、そのトークンを使ってユーザーをサインインさせます。

OIDC および OAuth アプリケーションで使用されるこれらの JSON Web トークン (JWT) には、 クレームと呼ばれるユーザーに関する情報が含まれています。 要求とは、そのユーザーに発行するトークンの中にあるユーザーに関する ID プロバイダーが提示した情報を指します。 OIDC 応答では、要求データは通常、JWT の形式で ID プロバイダーによって発行された ID トークンに含まれます。

クレームを表示または編集する

オプションの JWT クレームは、元のアプリケーションの登録で構成できますが、エンタープライズ アプリケーション内でも構成できます。 アプリケーションの JWT で発行されたクレームを表示または編集するには、次の手順に従います。

1. Microsoft Entra 管理センターに、少なくともクラウド アプリケーション管理者としてサインインします。
2. [Entra ID]>[エンタープライズ アプリ]>[すべてのアプリケーション] を参照します。
3. アプリケーションを選択し、左側のメニューで [シングル サインオン] を選択し、[属性と要求] セクションで [編集] を選択します。

アプリケーションでは、さまざまな理由でクレームのカスタマイズが必要になる場合があります。 たとえば、アプリケーションで、別の一連のクレーム URI やクレーム値が必要な場合です。 [属性と要求] セクションを使用すると、アプリケーションの要求を追加または削除できます。 ユース ケースに基づいて、アプリケーションに固有のカスタム クレームを作成することもできます。

次の手順は、定数値を割り当てる方法を示しています。

1. 変更するクレームを選択します。
2. 組織に従って Source 属性 に引用符なしで定数値を入力し、[保存] を選択 します。

属性の概要には、定数値が表示されます。

特別なクレームの変換

特別なクレームの変換関数を使用できます。

アプリケーション固有のクレームを追加する

アプリケーション固有の要求を追加するには:

1. [ユーザー属性] & [要求] で、[新しい要求の追加] を選択して、[ユーザー要求の管理] ページを開きます。
2. 要求の 名前 を入力します。 値は、URI パターンに厳密に従う必要はありません。 URI パターンが必要な場合は、[ 名前空間] フィールドに配置できます。
3. 要求の値を取得する ソース を選択します。 ソース属性のドロップダウンからユーザー属性を選択するか、または要求として生成する前にユーザー属性に変換を適用することができます。

要求の変換

ユーザー属性に変換を適用するには、次の手順を行います。

1. [ 要求の管理] で、要求ソースとして [変換 ] を選択し、[ 変換の管理 ] ページを開きます。
2. 変換ドロップダウンから関数を選択します。 選択した関数に応じて、変換で評価するパラメーターと定数値を指定します。
3. ソースを複数値として扱う は、変換がすべての値に適用されるか、最初の値のみに適用されるかを示します。 既定では、複数値クレームの最初の要素に変換が適用されます。 このチェックボックスをオンにすると、すべてに適用されます。 このチェックボックスは、複数値の属性に対してのみ有効になります。 たとえば、「 user.proxyaddresses 」のように入力します。
4. 複数の変換を適用するには、[ 変換の追加] を選択します。 要求には、最大 2 つの変換を適用できます。 たとえば、最初に user.mail のメール プレフィックスを抽出できます。 次に、文字列を大文字にします。

次の関数を使用して、要求を変換できます。

他の変換が必要な場合は、SaaS アプリケーション カテゴリの Microsoft Entra ID のフィードバック フォーラムでアイデアを送信してください。

正規表現ベースのクレーム変換

正規表現を使用して要求を変換できます。 正規表現ベースの要求変換を使用する場合、最大 20 個の正規表現置換を行うことができます。

次の画像は、変換の第 1 レベルの例を示したものです。

次の表では、変換の第 1 レベルに関する情報を示します。 表に示されているアクションは、前の画像のラベルに対応しています。 [ 編集] を 選択して要求変換ブレードを開きます。

次の画像は、変換の 2 番目のレベルの例を示したものです。

次の表では、変換の 2 番目のレベルに関する情報を示します。 表に示されているアクションは、前の画像のラベルに対応しています。

次の図は、変換のテストの例を示したものです。

次の表では、変換のテストに関する情報を示します。 表に示されているアクションは、前の画像のラベルに対応しています。

RegexReplace() 変換は、グループ要求変換でも使用できます。

変換の検証

[テストの追加] または [実行] を選択した後に次の条件が発生した場合に、メッセージに詳細が表示されます。

• ユーザー属性が重複する入力パラメーターが使用された。
• 使われていない入力パラメーターが見つかりました。 定義された入力パラメーターは、置換パターン テキストでそれぞれ使用される必要があります。
• 指定されたテスト正規表現入力が、指定された正規表現と一致しません。
• 置換パターンのグループのソースが見つからない。

条件に基づいてクレームを出力する

ユーザーの種類とユーザーが属するグループに基づいて、要求のソースを指定することができます。

ユーザーの種類は次のとおりです。

• Any - すべてのユーザーがアプリケーションにアクセスできます。
• メンバー: テナントのネイティブ メンバー
• すべてのゲスト: ユーザーは、Microsoft Entra ID の有無にかかわらず外部組織から移動しました。
• Microsoft Entra ゲスト: ゲスト ユーザーは、Microsoft Entra ID を使用して別の組織に属しています。
• 外部ゲスト: ゲスト ユーザーは、Microsoft Entra ID を持たない外部組織に属しています。

ユーザーの種類が役立つのは、クレームのソースが、ゲストとアプリケーションにアクセスする従業員とで異なる場合です。 ユーザーが従業員である場合は NameID を user.email から取得するように指定できます。 ユーザーがゲストの場合は、NameID は user.extensionattribute1 から取得されます。

要求条件を追加するには、次の手順を行います。

1. [ 要求の管理] で、[要求の条件] を展開します。
2. ユーザーの種類を選択します。
3. ユーザーが属するグループを選択します。 特定のアプリケーションに対するすべての要求で、最大 50 個の一意のグループを選択できます。
4. 要求の値を取得する ソース を選択します。 ソース属性のドロップダウンからユーザー属性を選択するか、または要求として生成する前にユーザー属性に変換を適用することができます。

条件を追加する順序は重要です。 Microsoft Entra では、まず、すべての条件をソース Attribute で評価し、次に、すべての条件をソース Transformation で評価して、クレームに出力する値を決定します。 Microsoft Entra ID では、上から下まで同じソースで条件を評価します。 クレームによって、クレームの式と一致する最後の値が出力されます。 IsNotEmpty や Contains などの変換は、制限のように機能します。

たとえば、Britta Simon は Contoso テナントのゲスト ユーザーです。 Britta は、Microsoft Entra ID も使用する別の組織に属しています。 Fabrikam アプリケーションが次のように構成されている場合、Britta が Fabrikam にサインインしようとすると、Microsoft ID プラットフォームで条件が評価されます。

まず、Microsoft ID プラットフォームは、Britta のユーザーの種類が [すべてのゲスト] であるかどうかを確認します。 種類は [すべてのゲスト] であるため、Microsoft ID プラットフォームは要求のソースを user.extensionattribute1に割り当てます。 次に、Microsoft ID プラットフォームは、Britta のユーザーの種類が Microsoft Entra ゲストであるかどうかを確認します。 種類は [すべてのゲスト] であるため、Microsoft ID プラットフォームは要求のソースを user.mailに割り当てます。 最終的に、クレームは Britta の user.mail の値を使って出力されます。

もう 1 つの例として、Britta Simon が次の構成を使用してサインインしようとする場合を考えてみます。 Microsoft Entra では、まず、すべての条件をソース Attribute で評価します。 Britta のユーザータイプが user.mail である場合、要求の根拠は です。 次に、Microsoft Entra ID によって変換が評価されます。 Britta はゲストであるため、user.extensionattribute1 がクレームの新しいソースです。 Britta は Microsoft Entra ゲストにあるため、 user.othermail がこの要求の新しいソースです。 最終的に、クレームは Britta の user.othermail の値を使って出力されます。

最後の例として、Britta の user.othermail が構成されていない場合、または空の場合にどうなるかを考えます。 どちらの場合も、条件エントリは無視され、クレームは user.extensionattribute1 にフォールバックします。

セキュリティに関する考慮事項

トークンを受信するアプリケーションは、改ざんできないクレーム値に依存しています。 クレームのカスタマイズによってトークンの内容を変更すると、この前提が通用しなくなることがあります。 アプリケーションでは、悪意のあるアクターによって作成されたカスタマイズから自身を保護するために、トークンが変更されていることを明示的に承認する必要があります。 次のいずれかの方法で不適切なカスタマイズから保護します。

• カスタム署名キーを構成する
• は、マップされた要求を受け入れるようにアプリケーション マニフェストを更新します。

これを指定しないと、Microsoft Entra ID は AADSTS50146エラー コードを返します。

カスタム署名キーを構成する

マルチテナント アプリでは、カスタム署名キーを使用する必要があります。 アプリ マニフェストには acceptMappedClaims を設定しないでください。 Azure portal でアプリをセットアップすると、アプリ登録オブジェクトとサービス プリンシパルがテナントに作成されます。 そのアプリでは Azure グローバル サインイン キーを使用します。このキーではトークンのクレームをカスタマイズできません。 トークンにカスタム クレームを使用するには、証明書からカスタム サインイン キーを作成してサービス プリンシパルに追加します。 テスト目的で、自己署名証明書を使用してもかまいません。 カスタム署名キーを構成したら、アプリケーション コードでトークン署名キーを検証する必要があります。

次の情報をサービス プリンシパルに追加します。

• 秘密キー ( キー資格情報として)
• パスワード (パスワード資格情報)
• 公開キー ( キー資格情報として)

証明書からエクスポートした PFX ファイルから、base-64 でエンコードした秘密キーと公開キーを抽出します。 “Sign” に使用する keyId の keyCredential が keyId の passwordCredential に一致することを確認します。 証明書の拇印のハッシュを取得することで、customkeyIdentifier を生成できます。

リクエスト

次の例は、カスタム署名キーをサービス プリンシプルに追加する HTTP PATCH 要求の形式を示しています。 keyCredentials プロパティの “key” の値は、読みやすいように短縮してあります。 この値は base-64 でエンコードしてあります。 秘密キーでは、プロパティの "usage" (用途) は Sign です。 公開キーでは、プロパティの "usage" (用途) は Verify です。

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/aaaaaaaa-bbbb-cccc-1111-222222222222

Content-type: servicePrincipals/json
Authorization: Bearer {token}

{
    "keyCredentials":[
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=", 
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "X509CertAndPassword",
            "usage": "Sign",
            "key":"cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
            "displayName": "CN=contoso"
        },
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "bbbbbbbb-1c1c-2d2d-3e3e-444444444444",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
            "displayName": "CN=contoso"
        }

    ],
    "passwordCredentials": [
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
            "keyId": "cccccccc-2d2d-3e3e-4f4f-555555555555",
            "endDateTime": "2022-01-27T19:40:33Z",
            "startDateTime": "2020-04-20T19:40:33Z",
            "secretText": "mypassword"
        }
    ]
}

PowerShell でカスタム署名キーを設定する

PowerShell を使用して MSAL パブリック クライアント アプリケーションをインスタンス化 し、 承認コード付与 フローを使用して Microsoft Graph の委任されたアクセス許可アクセス トークンを取得します。 このアクセス トークンを使用して Microsoft Graph を呼び出し、サービス プリンシパルに対してカスタム署名キーを設定します。 カスタム署名キーを構成したら、アプリケーション コードで トークン署名キーを検証する必要があります。

このスクリプトを実行するには、次のものが必要です。

• アプリケーションのサービス プリンシパルのオブジェクト ID。Azure portal の [エンタープライズ アプリケーション] から、目的のアプリケーションの項目の [概要] ブレードで確認できます。
• ユーザーをサインインさせ、Microsoft Graph を呼び出すアクセス トークンを取得するためのアプリの登録。 Azure portal の [App registrations]\(アプリの登録)\ の目的のアプリケーションの項目の [Overview]\(概要\) ブレードで、このアプリのアプリケーション (クライアント) ID を取得します。 アプリの登録には次の構成が必要です。
  • "http://localhost" のリダイレクト URI。モバイル アプリケーションとデスクトップアプリケーション プラットフォームの構成に記載されています。
  • API のアクセス許可で、Microsoft Graph によって委任されたアクセス許可 Application.ReadWrite.All と User.Read (これらのアクセス許可に対する管理者の同意を必ず付与してください)。
• ログインして Microsoft Graph アクセス トークンを取得するユーザー。 このユーザーは、次の Microsoft Entra 管理者ロールのいずれかである必要があります (サービス プリンシパルの更新に必要です)。
  • クラウド アプリケーション管理者
  • アプリケーション管理者
• アプリケーションのカスタム署名キーに設定する証明書。 自己署名証明書を作成する方法と、信頼できる証明機関から証明書を取得する方法があります。 スクリプトでは、証明書に含まれる次の要素を使用します。
  • 公開キー (通常は .cer ファイル)
  • PKCS#12 形式の秘密キー ( .pfx ファイル内)
  • 秘密キーのパスワード (.pfx ファイル)

##########################################################
# Replace the variables below with the appropriate values 

$fqdn="yourDomainHere" # This is used for the 'issued to' and 'issued by' field of the certificate
$pwd="password" # password for exporting the certificate private key
$tenantId   = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Replace with your Tenant ID
$appObjId = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" # Replace with the Object ID of the App Registration

##########################################################

# Create a self-signed cert

$cert = New-SelfSignedCertificate -certstorelocation cert:\currentuser\my -DnsName $fqdn
$pwdSecure = ConvertTo-SecureString -String $pwd -Force -AsPlainText
$path = 'cert:\currentuser\my\' + $cert.Thumbprint
$___location="C:\\temp" # path to folder where both the pfx and cer file will be written to
$cerFile = $___location + "\\" + $fqdn + ".cer"
$pfxFile = $___location + "\\" + $fqdn + ".pfx"
 
# Export the public and private keys
Export-PfxCertificate -cert $path -FilePath $pfxFile -Password $pwdSecure
Export-Certificate -cert $path -FilePath $cerFile

$pfxpath = $pfxFile # path to pfx file
$cerpath = $cerFile # path to cer file
$password = $pwd  # password for the pfx file
 
# Check PowerShell version (minimum 5.1) (.Net) or PowerShell Core (.Net Core) and read the certificate file accordingly
 
if ($PSVersionTable.PSVersion.Major -gt 5)
    { 
        $core = $true
    }
else
    { 
        $core = $false
    }
 
    #  this is for PowerShell Core
    $Secure_String_Pwd = ConvertTo-SecureString $password -AsPlainText -Force
 
    # reading certificate files and creating Certificate Object
    if ($core)
    {
        $pfx_cert = get-content $pfxpath -AsByteStream -Raw
        $cer_cert = get-content $cerpath -AsByteStream -Raw
        $cert = Get-PfxCertificate -FilePath $pfxpath -Password $Secure_String_Pwd
    }
    else
    {
        $pfx_cert = get-content $pfxpath -Encoding Byte
        $cer_cert = get-content $cerpath -Encoding Byte
        # calling Get-PfxCertificate in PowerShell 5.1 prompts for password - using alternative method
        $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfxpath, $password)
    }

 
    # base 64 encode the private key and public key
    $base64pfx = [System.Convert]::ToBase64String($pfx_cert)
    $base64cer = [System.Convert]::ToBase64String($cer_cert)
 
    # getting id for the keyCredential object
    [string]$guid1 = New-Guid
    [string]$guid2 = New-Guid
 
    # get the custom key identifier from the certificate thumbprint:
    $hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
    $hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($cert.Thumbprint))
    $customKeyIdentifier = [System.Convert]::ToBase64String($hash)
 
    # get end date and start date for our keycredentials
    $endDateTime = ($cert.NotAfter).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
    $startDateTime = ($cert.NotBefore).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
 
    # building our json payload
    $object = [ordered]@{    
    keyCredentials = @(       
         [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid1
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Sign"
            key = $base64pfx
            displayName = "CN=$fqdn" 
        },
        [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid2
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Verify"
            key = $base64cer
            displayName = "CN=$fqdn"   
        }
        )  
    passwordCredentials = @(
        [ordered]@{
            customKeyIdentifier = $customKeyIdentifier
            displayName = "CN=$fqdn"
            keyId = $guid1           
            endDateTime = $endDateTime
            startDateTime = $startDateTime
            secretText = $password
            hint = $null
        }
    )
    }
 
Connect-MgGraph -tenantId $tenantId -Scopes Application.ReadWrite.All
$graphuri = "https://graph.microsoft.com/v1.0/applications/$appObjId"
Invoke-MgGraphRequest -Method PATCH -Uri $graphuri -Body $object

    $json = $object | ConvertTo-Json -Depth 99
    Write-Host "JSON Payload:"
    Write-Output $json

トークン署名キーを承認する

要求マッピングが有効になっているアプリでは、appid={client_id}にを追加してトークン署名キーを検証する必要があります。 次の例は、使用する必要がある OpenID Connect メタデータ ドキュメントの形式を示しています。

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

アプリケーション マニフェストを更新する

シングル テナント アプリの場合は、acceptMappedClaims プロパティをtrueでするように設定できます。 apiApplication リソースの種類に関するドキュメントに記載されているとおり。 このプロパティを設定すると、アプリケーションでカスタム署名キーを指定せずにクレーム マッピングを使用できるようになります。

要求されたトークンの対象者は、Microsoft Entra テナントの検証済みドメイン名を使用する必要があります。つまり、(アプリケーション マニフェストで Application ID URI で表される) identifierUris を、たとえば https://contoso.com/my-api に設定するか、(単に既定のテナント名を使用して) https://contoso.onmicrosoft.com/my-api に設定する必要があります。

検証済みドメインを使用していない場合、Microsoft Entra ID から AADSTS501461 エラー コードが返され、"_AcceptMappedClaims is only supported for a token audience matching the application GUID or an audience within the tenant's verified domains. Either change the resource identifier or use an application-specific signing key." (_AcceptMappedClaims は、アプリケーション GUID と一致するトークン対象者、またはテナントの検証済みドメイン内の対象者でのみサポートされます。リソース識別子を変更するか、アプリケーション固有の署名キーを使用してください。) というメッセージが表示されます。

クレームの詳細オプション

同じクレームを SAML トークンとして公開するには、OIDC アプリケーションに対してクレームの詳細オプションを構成します。 また、SAML2.0 と OIDC の両方の応答トークンに同じクレームを使用するアプリケーションについても同様です。

[要求の管理] ブレードの [ 詳細要求オプション ] の下にあるチェック ボックスをオンにして、詳細 要求 オプションを構成します。

関連するコンテンツ

• Microsoft Entra ID で使用される要求とトークン。