Merge pull request #7329 from umbraco/Rewrite-rules

Added an example for serving files from .well-known path

Author: eshanrnh

13/umbraco-cms/reference/routing/iisrewriterules.md

@@ -184,5 +184,40 @@ An example configuration to help ensure your custom rules integrate properly:
 ```
 
 {% hint style="info" %}
-If you use **Umbraco Cloud**, check the [Rewrite Rules](https://docs.umbraco.com/umbraco-cloud/set-up/project-settings/manage-hostnames/rewrites-on-cloud) article.
+If you use **Umbraco Cloud**, check the [Rewrite Rules](https://docs.umbraco.com/umbraco-cloud/go-live/manage-hostnames/rewrites-on-cloud) article.
+{% endhint %}
+
+### Example: Serving Files from the `.well-known` Path
+
+Some third-party services such as Apple Pay, Google, or other integrations, require you to host a verification file at a specific URL like:
+
+```text
+https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association
+```
+
+On Umbraco Cloud, directly hosting files in the `.well-known` folder (for example, via Git or Kudu) may result in a 404 error due to platform restrictions.
+
+To work around this, you can serve the required file using Umbraco's **Media** library along with an IIS rewrite rule.
+
+To do so, follow these steps:
+
+1. Go to the **Media** section in the Umbraco backoffice.
+2. Create a folder named `.well-known`.
+   This folder is only for your own organization. It does not affect the public file URL.
+3. Upload the verification file. For example: *test.txt*.
+
+![Uploading Verification file in the Backoffice](images/upload-verification-file.png)
+
+4. Copy the Media file URL. For example, `/media/4jhhlmxk/verification.txt`.
+5. Add a rewrite rule in your `web.config` file:
+
+```xml
+<rule xdt:Transform="Insert" name="Rewrite Apple Developer Merchant ID" stopProcessing="true">
+  <match url="^\.well-known/apple-developer-merchantid-domain-association$" />
+  <action type="Rewrite" url="/media/4jhhlmxk/test.txt" />
+</rule>
+```
+
+{% hint style="info" %}
+Replace the `match` and `url` values with your specific Media path and verification filename.
 {% endhint %}

13/umbraco-cms/reference/routing/images/upload-verification-file.png

@@ -184,5 +184,40 @@ An example configuration to help ensure your custom rules integrate properly:
 ```
 
 {% hint style="info" %}
-If you use **Umbraco Cloud**, check the [Rewrite Rules](https://docs.umbraco.com/umbraco-cloud/set-up/project-settings/manage-hostnames/rewrites-on-cloud) article.
+If you use **Umbraco Cloud**, check the [Rewrite Rules](https://docs.umbraco.com/umbraco-cloud/go-live/manage-hostnames/rewrites-on-cloud) article.
+{% endhint %}
+
+### Example: Serving Files from the `.well-known` Path
+
+Some third-party services such as Apple Pay, Google, or other integrations, require you to host a verification file at a specific URL like:
+
+```text
+https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association
+```
+
+On Umbraco Cloud, directly hosting files in the `.well-known` folder (for example, via Git or Kudu) may result in a 404 error due to platform restrictions.
+
+To work around this, you can serve the required file using Umbraco's **Media** library along with an IIS rewrite rule.
+
+To do so, follow these steps:
+
+1. Go to the **Media** section in the Umbraco backoffice.
+2. Create a folder named `.well-known`.
+   This folder is only for your own organization. It does not affect the public file URL.
+3. Upload the verification file. For example: *test.txt*.
+
+![Uploading Verification file in the Backoffice](images/upload-verification-file.png)
+
+4. Copy the Media file URL. For example, `/media/4jhhlmxk/verification.txt`.
+5. Add a rewrite rule in your `web.config` file:
+
+```xml
+<rule xdt:Transform="Insert" name="Rewrite Apple Developer Merchant ID" stopProcessing="true">
+  <match url="^\.well-known/apple-developer-merchantid-domain-association$" />
+  <action type="Rewrite" url="/media/4jhhlmxk/test.txt" />
+</rule>
+```
+
+{% hint style="info" %}
+Replace the `match` and `url` values with your specific Media path and verification filename.
 {% endhint %}

15/umbraco-cms/reference/routing/iisrewriterules.md

@@ -184,5 +184,40 @@ An example configuration to help ensure your custom rules integrate properly:
 ```
 
 {% hint style="info" %}
-If you use **Umbraco Cloud**, check the [Rewrite Rules](https://docs.umbraco.com/umbraco-cloud/set-up/project-settings/manage-hostnames/rewrites-on-cloud) article.
+If you use **Umbraco Cloud**, check the [Rewrite Rules](https://docs.umbraco.com/umbraco-cloud/go-live/manage-hostnames/rewrites-on-cloud) article.
+{% endhint %}
+
+### Example: Serving Files from the `.well-known` Path
+
+Some third-party services such as Apple Pay, Google, or other integrations, require you to host a verification file at a specific URL like:
+
+```text
+https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association
+```
+
+On Umbraco Cloud, directly hosting files in the `.well-known` folder (for example, via Git or Kudu) may result in a 404 error due to platform restrictions.
+
+To work around this, you can serve the required file using Umbraco's **Media** library along with an IIS rewrite rule.
+
+To do so, follow these steps:
+
+1. Go to the **Media** section in the Umbraco backoffice.
+2. Create a folder named `.well-known`.
+   This folder is only for your own organization. It does not affect the public file URL.
+3. Upload the verification file. For example: *test.txt*.
+
+![Uploading Verification file in the Backoffice](images/upload-verification-file.png)
+
+4. Copy the Media file URL. For example, `/media/4jhhlmxk/verification.txt`.
+5. Add a rewrite rule in your `web.config` file:
+
+```xml
+<rule xdt:Transform="Insert" name="Rewrite Apple Developer Merchant ID" stopProcessing="true">
+  <match url="^\.well-known/apple-developer-merchantid-domain-association$" />
+  <action type="Rewrite" url="/media/4jhhlmxk/test.txt" />
+</rule>
+```
+
+{% hint style="info" %}
+Replace the `match` and `url` values with your specific Media path and verification filename.
 {% endhint %}

15/umbraco-cms/reference/routing/images/upload-verification-file.png

@@ -20,10 +20,11 @@ The rewrite rules should be added to the `<system.webServer><rewrite>` module in
 
 ## Best practices
 
-When you are doing rewrite rules on Umbraco Cloud there are a few important things to keep in mind:
+When setting up rewrite rules on Umbraco Cloud, there are a few important things to keep in mind:
 
-* Always make sure that you add a condition that negates the Umbraco Backoffice - `/umbraco`, otherwise, you will not be able to do deployments to/from the environment
-* To be able to continue working locally with your Umbraco Cloud project, you also need to add a condition that negates `localhost`
+* Always include a condition to exclude the Umbraco backoffice path (`/umbraco`). Failing to do so may prevent you from deploying to and from the environment.
+* To continue working locally with your Umbraco Cloud project, you should also add a condition to exclude `localhost`.
+* To serve verification files from the `.well-known` directory (for example, Apple Pay or Google), follow the [Rewrite rule workaround in the CMS documentation](https://docs.umbraco.com/umbraco-cms/reference/routing/iisrewriterules#example-serving-files-from-the-well-known-path).
 
 ## Hiding the default umbraco.io URL