Microsoft Entra ID (Azure AD) OIDC Configuration

This article will walk you through setting up Microsoft Entra ID for your WebReports environment, using OIDC (Open ID Connect).  Minimum WebReports required for Microsoft Entra ID and OIDC is v2024.09.18.

1. Login to the Microsoft Azure portal and navigate to Microsoft Entra ID
2. Navigate on App registrations and click the New registration button.
3. Enter WebReports for the Name.
4. Under Who can use this application or access this API select Accounts in this organization only (************ - Single tenant).
5. Enter the FQDN (Fully Qualified Domain Name) for your WebReports environment followed by /OIDCCallback.
6. The App registration will be completed, and you'll be taken to the WebReports configuration page.  Click on the link next to Client credentials.
7. Click the New Client Secret button.
8. Enter a Description, set the Expires value from the drop down, and click the Add button.
   • Please note: when the secret key expires users will no longer be able to access WebReports.  Please set a reminder to update your key prior to expiration. 
9. Click the Copy to clipboard button next to Value and keep this for configuring the appsettings.json later in this article. This value will be masked an inaccessible later, it's important you copy and retain this value now.
10. Next, click on Endpoints.  Copy and keep the URL values for OAuth 2.0 authorization endpoint (v2) and OAuth 2.0 token endpoint (v2) for configuring the appettings.json later in this article.
11. Using a web browser, browse to the URL inside OpenID Connect metadata document.
12. Locate, copy and keep the URL for the userinfo_endpoint and end_session_endpoint.  This value will be used when configuring the appsettings.json later in this article.
13. Next, click the Copy to clipboard button next to Application (client) ID and keep this value for configuring the appsettings.json later in this article.
14. Browse to Enterprise Applications and click on WebReports.
    1. You can search for Enterprise Applications using the Search resources, services, and docs option at the top of the page.
15. Navigate to Users and groups and click on the Add user/group button.
16. Select the Microsoft Users and/or group that you are authorizing to access to the WebReports application.
17. Login to your WebReports server's console and navigate to the appsettings.json file and make a backup of the file.  If something doesn't work properly you can restore the file, reverting to your last good configuration.  The default installation path for WebReports is c:\inetpub\wwwroot.
18. Next, open appsettings.json with a text editor.   
    • For security reasons, some environments may not allow you to save file changes when editing inside the WebReports installation path.  We recommend opening a text editor with elevated permissions (example: right click on Notepad and select Run As Administrator) then opening appsettings.json.
19. We recommend copying the entire OIDC configuration snippet below and pasting into appsettings.json, directly underneath the Authentication section (Example image of where to paste is in step 20.7), and then apply the values from step 20 below. 
    • The appsettings.json file is in a json structure and changes must be consistent with a json format.  Failure to do so will result in an Error 500 when starting the WebReports application.  Each section in a .json file starts with a }, and ends with a }, with the exception of the last entry in the file.

    • },
      "OIDC": {
      "AuthorizationEndpoint": "https://login.microsoftonline.com/************************/oauth2/v2.0/authorize",
      "TokenEndpoint": "https://login.microsoftonline.com/*************************/oauth2/v2.0/token",
      "UserInformationEndpoint": "https://graph.microsoft.com/oidc/userinfo",
      "LogoutEndpoint": "https://login.microsoftonline.com/*********************/oauth2/v2.0/logout",
      "Callback": "/OIDCCallback",
      "BlockUserCreation": false,
      "ClientId": "************************",
      "ClientSecret": "******************************",
      // Roles Mapping
      "Admin": "youradminaccount@yourdomain.com"
      },

20. Set the following values for each property list below.  Please note all values will go between the double quotes.
    1. Authentication Method: OIDC
       • This property supports Default, Okta, Windows, CAIA, and OIDC, and is located just above the OIDC code snippet you pasted into the appsettings.json.  For Microsoft Entra ID/Azure AD you will be using the value OIDC.
    2. AuthorizationEndpoint: URL from Step 10
    3. TokenEndpoint: URL from Step 10
    4. UserInformationEndpoint: URL from Step 12
    5. LogoutEndpoint: URL from Step 12
    6. BlockUserCreation (default value: false)
       1. This property prevents the creation of new users, even if they've successfully authenticated and are authorized to access the WebReports environment, locking down the WebReports server from accepting and creating new user accounts.
    7. ClientId: From Step 13
    8. ClientSecret: From Step 9
    9. Admin: Enter the WebReports administrator's email address, which will be automatically seeded into WebReports as an Admin.  If there are multiple admin emails separate with a ; (semicolon).  If the account already exists in the WebReports environment it will not be re-seeded or elevated to an admin.
21. Save the changes to the appsettings.json file.
22. Launch IIS Manager, navigate to Applications Pools, and restart your WebReports application pool.
23. Browse to the WebReports application, test and confirm the Microsoft Entra ID configuration is working properly.
    1. The initial login should be completed using one of the accounts included in the Admin list from Step 20.  This account will have access to fully manage the environment and setup user roles. 
    2. You will also be prompted to authorize the WebReports application on behalf of your organization during the first login attempt.  You will need to be a Microsoft Entra ID/Enterprise Admin to approve the WebReports application.

Important Notes:

If you were previously using Windows Authentication:

• You will need to update your WebReports Connection Profile inside of VDM to use an API Key.  More information is available here: Creating a WebReports API Secret Key – BridgeWorks Help Center (bridgeworksllc.com).
• You will need to disable Windows Authentication and enable Anonymous Authentication within IIS Manager before you'll be redirected to Microsoft Entra for authentication.