--- updatedAt: 2026-05-14T16:47:47.000Z --- # Microsoft Entra This guide illustrates how to configure IBM Application Gateway (IAG) as an OIDC relying party for Microsoft Entra ID. This guide was written in October 2023.The following steps can change if a third-party provider modifies their administrative interfaces. ### Pre-requisites 1. Review the [Third-Party Providers](https://docs.verify.ibm.com/verify/docs/flow-designer-iag-with-thirdparty-identity-providers) documentation for high-level information about using IAG with third-party identity providers. 2. An active Microsoft Entra subscription. A **Microsoft Entra ID Free** tenant can be used. #### Reference Resources The following Microsoft documentation was used to prepare these configuration instructions: * [Entra ID Application Registration](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application) * [OpenID Connection on the Microsoft identity platform ](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc) ### Configuration #### Microsoft Entra Configuration Steps From the [Entra ID administration console](https://entra.microsoft.com/#home), browse to **Applications > App Registrations** and click **New registration**. [block:image] { "images": [ { "image": [ "https://files.readme.io/672174673a502c6ef239e0fde6963abaf55bd792714c268360f89a5de04e49f1-ms-entra-registrations.png", "672174673a502c6ef239e0fde6963abaf55bd792714c268360f89a5de04e49f1-ms-entra-registrations.png", 602, 348, "#e1e2e4", null, "69df9ee382dbd7dbc352f614" ] } ] } [/block] Complete the required **Name**, and **Supported account types** fields, and supply a **Web** type **Redirect URI**. The **Redirect URI** is of the format `https:///pkmsoidc`. [block:image] { "images": [ { "image": [ "https://files.readme.io/dc88967e99bd8b1444492f247ae51d10ef2e52c98fc809a6b1f663c931fcc971-ms-entra-registration.png", "dc88967e99bd8b1444492f247ae51d10ef2e52c98fc809a6b1f663c931fcc971-ms-entra-registration.png", 1379, 1407, "#dad5d8", null, "69df9ee43c1f5449fe40a5d0" ] } ] } [/block] After the initial application definition is created, note the **Application (client) ID** field. In IAG, the **Application (client) ID** value is used in the `client_id` field. [block:image] { "images": [ { "image": [ "https://files.readme.io/519e6966e788a6c8c8844904e87c99aa1d73da21d9ab8f34c0eeb9353227b562-ms-entra-clientid.png", "519e6966e788a6c8c8844904e87c99aa1d73da21d9ab8f34c0eeb9353227b562-ms-entra-clientid.png", 1379, 787, "#e0e5ea", null, "69df9ee4297466ef21a3d318" ] } ] } [/block] A client secret must be provisioned for the application. Note Microsoft Entra ID periodically expires client secrets, which must be considered in maintenance activities. [block:image] { "images": [ { "image": [ "https://files.readme.io/81d1ea9d0682a3ccc434670c4e4a28aa804e1002f6e8ecb67b558957107fb8e2-ms-entra-clientsecret.png", "81d1ea9d0682a3ccc434670c4e4a28aa804e1002f6e8ecb67b558957107fb8e2-ms-entra-clientsecret.png", 602, 543, "#d7d9dc", null, "69df9ee528d6421a38fddf35" ] } ] } [/block] The client secret **Value** can now be retrieved. The generated client secret value in this example is `njV8Q~Lg0-OPNrE0znn253NI.VyUAFG9t~ZV-cgL`. In IAG, the client secret **Value** is used in the `client_secret` field. [block:image] { "images": [ { "image": [ "https://files.readme.io/b4e53130e6605b38ea669526594bd21b9c588add942b6b53e9f0df4fcfa85350-ms-entra-clientsecret-2.png", "b4e53130e6605b38ea669526594bd21b9c588add942b6b53e9f0df4fcfa85350-ms-entra-clientsecret-2.png", 1379, 605, "#e0e5e9", null, "69df9ee699c2dad8cfe486ec" ] } ] } [/block] Find the OIDC metadata URL by browsing to **Applications > App Registrations** and selecting **Endpoints**. In the listed set of endpoints, locate the URL for the **OpenID Connect metadata document**. In IAG, this is the `discovery_endpoint` value. [block:image] { "images": [ { "image": [ "https://files.readme.io/00d9b56e2af0fc9d1f1799b0bb757b6663d4a6b95aea043983ec58d7009644cd-ms-entra-metadata.png", "00d9b56e2af0fc9d1f1799b0bb757b6663d4a6b95aea043983ec58d7009644cd-ms-entra-metadata.png", 1379, 592, "#dfdfe0", null, "69df9ee7297466ef21a3d357" ] } ] } [/block] #### IAG Configuration Steps Using the value retrieved in the previous steps, complete the IAG configuration. The sample configuration contains enough information to allow IAG to perform single sign-on with Microsoft Entra ID. ```yaml identity: oidc: discovery_endpoint: "https://login.microsoftonline.com/9f7a21ce-115d-4ebf-b41c-ed0952f5d43e/v2.0/.well-known/openid-configuration" client_id: "fa6ec2eb-3b51-4d16-9e58-f30a5a5c20d9" client_secret: "njV8Q~Lg0-OPNrE0znn253NI.VyUAFG9t~ZV-cgL" scopes: - "profile" - "email" ``` ### Extra Configuration #### Disabling user consent By default, Entra ID prompts users for consent to share single sign-on information between the IDP and the application the first time they sign in. In scenarios where the owner of the IAG instance and application is also the owner of the IDP, the consent step can be superfluous. Entra ID application configuration requires user consent by default, but consent can be granted at the administration level as an API permission. [block:image] { "images": [ { "image": [ "https://files.readme.io/0ec302b6cfbe5994aeeed1b89f62a865c336c3eed6d639a6852a2a087f6cae01-ms-entra-euc.png", "0ec302b6cfbe5994aeeed1b89f62a865c336c3eed6d639a6852a2a087f6cae01-ms-entra-euc.png", 1379, 679, "#dfe3e7", null, "69df9ee78e68bd6bade0f622" ] } ] } [/block] #### Supplying extra user attributes in the id\_token A protected application often requires extra user attributes from the third-party identity provider. The user attributes need to be propagated to IAG as claims in the id\_token. To configure extra attributes in Entra ID, select **Token configuration** and then click **Add optional claim**. In the **Add optional claim** window, set the **Token type** to **ID**, and then check the required **Claim** values. The screenshot illustrates the process for adding extra claims, including email, which requires an extra API permission to be granted. [block:image] { "images": [ { "image": [ "https://files.readme.io/4851071b21997bcf745fe6db48110be01961858570e6021297113afb36ba7a1e-ms-entra-idtoken.png", "4851071b21997bcf745fe6db48110be01961858570e6021297113afb36ba7a1e-ms-entra-idtoken.png", 1379, 1177, "#dbdada", null, "69df9ee828d6421a38fde32f" ] } ] } [/block] #### Front-channel logout URL Entra ID can be configured with a logout URL for the application. To configure this in Entra ID, select **Authentication** and enter the logout URL in the **Front-channel logout URL** field. The logout URL for IAG is of the format https\:///pkmslogout. [block:image] { "images": [ { "image": [ "https://files.readme.io/b661185c11fffb3924441da236a22c503d54138186634466476b45d6f529d99e-ms-entra-logout.png", "b661185c11fffb3924441da236a22c503d54138186634466476b45d6f529d99e-ms-entra-logout.png", 602, 325, "#cdced0", null, "69df9ee828d6421a38fde333" ] } ] } [/block] This URL is not related to the OpenID SLO profile, which is not supported by IAG. ### Testing the Entra ID Integration To test the configuration: 1. Browse to the IAG credential viewer application. For more information, see [Common IAG Configuration](https://www.ibm.com/docs/en/security-verify?topic=integrations-application-gateway). In this example, the URL is . [block:image] { "images": [ { "image": [ "https://files.readme.io/4a76910e150001122bdb643ad486d0aae5075480d86bf25ac38fef6190b32fbc-ms-entra-results-1.png", "4a76910e150001122bdb643ad486d0aae5075480d86bf25ac38fef6190b32fbc-ms-entra-results-1.png", 972, 273, "#e0e0e1", null, "69df9ee91d640f876335c125" ] } ] } [/block] 2. The browser is redirected to Microsoft Entra ID for authentication. When the user consent step is not required (see [Disabling user consent](#disabling-user-consent)), the browser is returned to the credential viewer application after authentication is completed. [block:image] { "images": [ { "image": [ "https://files.readme.io/ae0f08ab28e426c6a3544ed47e4976aec38ce088a1e419f758050c8d6b47b372-ms-entra-results-2.png", "ae0f08ab28e426c6a3544ed47e4976aec38ce088a1e419f758050c8d6b47b372-ms-entra-results-2.png", 579, 329, "#e0dcd9", null, "69df9ee92f8a0cf288f2726f" ] } ] } [/block] 3. The credential viewer application is displayed. Observe that the configured `id_token` attributes (see [Supplying extra user attributes in the id\_token](#supplying-extra-user-attributes-in-the-id_token)) are displayed. [block:image] { "images": [ { "image": [ "https://files.readme.io/06a9f349519d00bd4c8edfecb8c99239d92770bad5b8802e8d7c52948e351b05-ms-entra-results-3.png", "06a9f349519d00bd4c8edfecb8c99239d92770bad5b8802e8d7c52948e351b05-ms-entra-results-3.png", 663, 681, "#dadada", null, "69df9eeaa8d01cd91eed9471" ] } ] } [/block]