Introduction
Microsoft Entra ID provides the ability to make use of a client certificate in lieu of client secret on Azure app registrations, which follow service principle (client credentials) authentication. This ability is particularly useful where using shared client secrets is undesirable. Client secret values also have shorter periods of validity than do client certificates, making app registrations that use client certificates easier to manage long-term.
This article will provide instructions for configuring a web service and connection that accommodates Azure app registrations which use a client certificate in lieu of a client secret for authentication purposes.
Please note that the resultant web connection will only accommodate the OAuth 2.0 client credentials grant flow, also known as service principal authentication.
Requirements
- FME Form 2024.1+, and optionally FME Flow 2024.1+
- Administrative rights to Microsoft Azure Portal, to be able to view and edit app registrations
- An Azure app registration (single or multitenant) which has Graph API Application Permissions applied to it, as appropriate for accessing your target Microsoft-based resources. For guidance on configuring an Azure app registration, please see Part 1 of How to Create a SharePointOnlineConnector Web Connection with Application Permissions
- The API permissions listed in this article are specific to accessing SharePoint Online resources. Please configure the Graph API Application Permissions required to access your target resources if they're not held in SharePoint Online.
- Skip Part 1 - Step 4, obtaining a client secret. The client certificate will be used for authentication in lieu of a client secret.
- A client certificate (.cer format) which complies with Microsoft's guidance, as outlined in this article
- This Microsoft article warns against using self-signed certificates for public-facing websites and applications. While self-signed certificates are useful for testing purposes, users are encouraged to generate client certificates that are signed by a trusted third-party CA. This Microsoft article is linked here for guidance only, and does not constitute a recommendation from Safe Software.
- The generated .cer should not contain a private key
- The instructions in the linked Microsoft article contain an optional step to generate a separate private key as a .pfx. It is necessary to generate this separate private key, as this .pfx should be used to sign the needed JSON Web Token (JWT) for client assertion to work correctly. Once the certificate is generated, a .cer and .pfx should be available for further use.
- The generated .cer must be uploaded to the Certificates & Secrets page of your Azure app registration
- A JSON Web Token (JWT) that's been signed by (generated using) the certificate .pfx, as per this Microsoft article. This JWT value should be securely stored in the same way a client secret value would be stored.
Step-by-Step Instructions
FME Form
With your Azure app registration complete, including the client certificate .cer uploaded to the Certificates & secrets page of the app, and your signed JWT value available, please carefully follow the below steps to build your web service and connection in FME Workbench 2024.1+.
1. Upload your Client Certificate CER File to your Azure App Registration
If your client certificate has not already been applied to your Azure app registration, you must upload its .cer file to the Certificates & Secrets page of the app registration in Azure Portal. Once this upload is complete, you will see it appear with its Thumbprint and Certificate ID values listed on the Certificates & Secrets page.
2. Install version 1.2.0+ of the SharePoint Online FME Package to FME Workbench
The FME web service needed to accommodate the client certificate authentication ships with version 1.2.0+ of the SharePoint Online FME Package. Open FME Workbench 2024.1+ to a blank canvas. Access Tools > FME Options > FME Packages, and check the list of installed packages for a SharePoint Online entry. If the SharePoint Online package is present, single-click it and have a look at the package details presented in the right-side display.
Verify that the version of the package available to you is, at minimum, v1.2.0. If you currently have, at minimum, version 1.2.0 of the SharePoint Online package available, proceed to Step 2 below.
If you do not see the SharePoint Online package listed, please select OK on the FME Tools dialog to return to the main canvas. Add a SharePointOnlineConnector to your canvas to prompt the SharePoint Online package to download and install to FME Workbench.
If you do not have an internet connection available, or are not permitted to perform in-app downloads, you can find the SharePoint Online package on FME Hub. Please choose to download v1.2.0+ of the SharePoint Online package. Once the downloaded .fpkg file is available, drag-and-drop it into a blank FME Workbench 2024.1+ canvas to start its install.
3. Create a New Web Service from the Microsoft Graph (App Only) Web Service Template
After verifying that the SharePoint Online FME Package v1.2.0+ is available to you, navigate to FME Workbench > Tools > FME Options > Web Connections > Manage Services. The Manage Web Services dialog should open.
In the Manage Web Services dialog, select the plus (+) button below the list of web services, and choose Create From > Microsoft Graph (App Only). A new derived web service definition should appear in the right-side pane of the Manage Web Services dialog, ready to be configured for client certificate authentication.
If you do not see the Microsoft Graph (App Only) web service presented as an option, please return to Step 1 and verify that you have v1.2.0 of the SharePoint Online package available for use. If you still encounter issues with the Microsoft Graph (App Only) web service missing after verifying v1.20 of the SharePoint Online package is present in your FME Workbench, please contact Safe Support for assistance.
4. Configure the New Microsoft Graph (App Only) Derived Web Service
With the new web service definition showing in the right-side pane of the Manage Web Services dialog, adjust the following parameters:
-
Web Service Name
- something unique that helps you identify its purpose (eg. MSGraph_ClientCertificate)
-
Parameters Table
- Client Secret Prompt should be changed to Client Assertion
- CLIENT_SECRET Key Name should be changed to CLIENT_ASSERTION
-
Token Generation REST API - Request Data
- delete the value currently in place, and replace it with the following value
client_id=[CLIENT_ID]&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=[CLIENT_ASSERTION]&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&grant_type=client_credentials
Be sure you do not introduce any leading or trailing whitespace when you paste the above value into the Request Data parameter input box. Any unexpexted whitespace will cause errors.
When the web service definition is complete, it should look like the following image
Select Apply at bottom right of the Manage Web Services dialog to save your web service definition. You should see your newly configured web service appear in the list of web services along the left side of the Manage Web Services dialog.
5. Create a New Web Connection
Once you have verified that your new web service shows up in the list of web services in the Manage Web Services dialog, click OK at bottom-right of the dialog to close it and return to the Web Connections menu of FME Options. Click the plus (+) button just below the Connections table, and select Add to add a new web connection. The Add Web Connection dialog will open.
In the Add Web Connection dialog, choose the web service you configured in Step 2, above, from the Web Service parameter's dropdown menu. Enter a name for the Connection Name parameter that indicates the web connection's purpose or functionality (e.g., MSGraph—ClientCertificateAuth).
Next, enter the required Tenant ID and Client ID values, as displayed on the Overview page of the Azure app registration that you uploaded your client certificate to. Finally, paste in your JWT value as the value for the Client Assertion parameter. Click OK.
You will see a quick pop-up appear on screen that looks similar to the following:
If your web connection is able to successfully authorize, you will be returned to the FME Options > Web Connections menu, and your new web connection will appear in the Connections table.
Congratulations, your Microsoft Graph Client Certificate-based web connection is now ready for use in your FME Form integrations.
FME Flow
Once the web connection is working well in FME Form 2024.1+, simply publish a workspace that uses the web connection to FME Flow 2024.1+, from FME Form, using the FME Form Publish Wizard. Please be sure to choose to publish the SharePoint Online package if this package is not already installed in FME Flow. Once published to FME Flow, no further adjustments to the web service or connection are required.
JWT values typically have short validity periods. If you receive a 401 Unauthorized error while using the web connection in FME Form or FME Flow, you may need to regenerate your JWT value and then apply this new JWT value to your web connection's Client Assertion parameter to acquire a new, valid access token.