Merge pull request #285807 from Clare-Zheng82/0829-Add_Rest_SP_Cert

[New feature] Add SP cert auth content and TSG for REST

Author: PMEds28

articles/data-factory/connector-rest.md

@@ -6,7 +6,7 @@ author: jianleishen
 ms.subservice: data-movement
 ms.custom: synapse
 ms.topic: conceptual
-ms.date: 02/26/2024
+ms.date: 08/29/2024
 ms.author: makromer
 ---
 
@@ -140,12 +140,18 @@ Set the **authenticationType** property to **AadServicePrincipal**. In addition
 | Property | Description | Required |
 |:--- |:--- |:--- |
 | servicePrincipalId | Specify the Microsoft Entra application's client ID. | Yes |
-| servicePrincipalKey | Specify the Microsoft Entra application's key. Mark this field as a **SecureString** to store it securely in Data Factory, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | Yes |
+| servicePrincipalCredentialType | Specify the credential type to use for service principal authentication. Allowed values are `ServicePrincipalKey` and `ServicePrincipalCert`. | No |
+| ***For ServicePrincipalKey*** | | |
+| servicePrincipalKey | Specify the Microsoft Entra application's key. Mark this field as a **SecureString** to store it securely in Data Factory, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | No |
+| ***For ServicePrincipalCert*** | | |
+| servicePrincipalEmbeddedCert | Specify the base64 encoded certificate of your application registered in Microsoft Entra ID, and ensure the certificate content type is **PKCS #12**. Mark this field as a **SecureString** to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). Go to this [section](#save-the-service-principal-certificate-in-azure-key-vault) to learn how to save the certificate in Azure Key Vault. | No |
+| servicePrincipalEmbeddedCertPassword | Specify the password of your certificate if your certificate is secured with a password. Mark this field as a **SecureString** to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | No |
+|  |  |  |
 | tenant | Specify the tenant information (domain name or tenant ID) under which your application resides. Retrieve it by hovering the mouse in the top-right corner of the Azure portal. | Yes |
 | aadResourceId | Specify the Microsoft Entra resource you are requesting for authorization, for example, `https://management.core.windows.net`.| Yes |
 | azureCloudType | For Service Principal authentication, specify the type of Azure cloud environment to which your Microsoft Entra application is registered. <br/> Allowed values are **AzurePublic**, **AzureChina**, **AzureUsGovernment**, and **AzureGermany**. By default, the data factory's cloud environment is used. | No |
 
-**Example**                                                                          
+**Example 1: Using service principal key authentication**                                                                          
 
 ```json
 {
@@ -156,6 +162,7 @@ Set the **authenticationType** property to **AadServicePrincipal**. In addition
             "url": "<REST endpoint e.g. https://www.example.com/>",
             "authenticationType": "AadServicePrincipal",
             "servicePrincipalId": "<service principal id>",
+            "servicePrincipalCredentialType": "ServicePrincipalKey",
             "servicePrincipalKey": {
                 "value": "<service principal key>",
                 "type": "SecureString"
@@ -170,6 +177,59 @@ Set the **authenticationType** property to **AadServicePrincipal**. In addition
     }
 }
 ```
+
+**Example 2: Using service principal certificate authentication**
+
+```json
+{
+    "name": "RESTLinkedService",
+    "properties": {
+        "type": "RestService",
+        "typeProperties": {
+            "url": "<REST endpoint e.g. https://www.example.com/>",
+            "authenticationType": "AadServicePrincipal",
+            "servicePrincipalId": "<service principal id>",
+            "servicePrincipalCredentialType": "ServicePrincipalCert",
+            "servicePrincipalEmbeddedCert": {
+                "type": "SecureString",
+                "value": "<the base64 encoded certificate of your application registered in Microsoft Entra ID>"
+            },
+            "servicePrincipalEmbeddedCertPassword": {
+                "type": "SecureString",
+                "value": "<password of your certificate>"
+            },
+            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
+            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
+        },
+        "connectVia": {
+            "referenceName": "<name of Integration Runtime>",
+            "type": "IntegrationRuntimeReference"
+        }
+    }
+}
+```
+
+#### Save the service principal certificate in Azure Key Vault
+
+You have two options to save the service principal certificate in Azure Key Vault:
+
+- **Option 1**
+
+    1. Convert the service principal certificate to a base64 string. Learn more from this [article](https://blog.tekspace.io/convert-certificate-from-pfx-to-base64-with-powershell/).
+
+    
+    2. Save the base64 string as a secret in Azure Key Vault.
+    	
+       :::image type="content" source="media/connector-rest/secrets.png" alt-text="Screenshot of secrets.":::
+    
+       :::image type="content" source="media/connector-rest/secret-value.png" alt-text="Screenshot of secret value.":::
+
+- **Option 2**
+	
+    If you can't download the certificate from Azure Key Vault, you can use this [template](https://supportability.visualstudio.com/256c8350-cb4b-49c9-ac6e-a012aeb312d1/_apis/git/repositories/da6cf5d9-0dc5-4ba9-a5e2-6e6a93adf93c/Items?path=/AzureDataFactory/.attachments/ConvertCertToBase64StringInAKVPipeline-47f8e507-e7ef-4343-a73b-733b9a7f8e4e.zip&download=false&resolveLfs=true&%24format=octetStream&api-version=5.0-preview.1&sanitize=true&includeContentMetadata=true&versionDescriptor.version=master) to save the converted service principal certificate as a secret in Azure Key Vault. 
+        
+    :::image type="content" source="media/connector-rest/template-pipeline.png" alt-text="Screenshot of template pipeline to save service principal certificate as a secret in AKV.":::
+ 
 ### Use OAuth2 Client Credential authentication
 
 Set the **authenticationType** property to **OAuth2ClientCredential**. In addition to the generic properties that are described in the preceding section, specify the following properties:

articles/data-factory/connector-troubleshoot-rest.md

@@ -5,7 +5,7 @@ description: Learn how to troubleshoot issues with the REST connector in Azure D
 author: jianleishen
 ms.subservice: data-movement
 ms.topic: troubleshooting
-ms.date: 10/20/2023
+ms.date: 08/29/2024
 ms.author: jianleishen
 ms.custom: has-adal-ref, synapse
 ---
@@ -59,6 +59,12 @@ This article provides suggestions to troubleshoot common problems with the REST
 
       Tools like **Fiddler** are recommended for the preceding case.
 
+## The service principal certificate in Azure Key Vault is not correct
+
+- **Message**: `"Failed to create certificate from certificate raw data and password. Cannot find the requested object."` 
+- **Cause**: Only support the base64 string service principal certificate for Rest connector service principal certificate authentication.
+- **Recommendation**: Follow this [section](connector-rest.md#save-the-service-principal-certificate-in-azure-key-vault) to save the service principal certificate in Azure Key Vault correctly.
+
 ## Related content
 
 For more troubleshooting help, try these resources: