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

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

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

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

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

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

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

次の手順では、定数値を割り当てる方法について説明します。

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

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

特別なクレームの変換

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

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

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

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

要求の変換

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

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

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

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

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

次の画像は、変換の第 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 を呼び出し、サービス プリンシパルに対してカスタム署名キーを設定します。 カスタム署名キーを構成したら、アプリケーション コードで トークン署名キーを検証する必要があります。

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

• Azure portal のエンタープライズ アプリケーションのアプリケーションのエントリの [概要 ] ブレードにある、アプリケーションのサービス プリンシパルのオブジェクト ID。
• ユーザーをサインインさせ、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 は、アプリケーション GUID と一致するトークン対象ユーザー、またはテナントの検証済みドメイン内の対象ユーザーでのみサポートされます。 リソース識別子を変更するか、アプリケーション固有の署名キーを使います。

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

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

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

関連するコンテンツ

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