In this blog post, I will elaborate on some troubleshooting steps in Azure storage static websites. Azure storage static websites are a feature that allows you to host static content (HTML, CSS, JavaScript, and image files) directly from a storage container named $web. This is a great option for scenarios where you don't need a web server to render content, but you still want to leverage Azure services such as Functions, App Service, or CDN.
However, sometimes you may encounter some issues when setting up or deploying your static website. Here are some common problems and how to solve them:
How to Secure Your Azure Static Website?
One of the challenges of hosting a static website on Azure is that it does not support role-based access control (RBAC) permissions. This means that anyone who knows the URL of your website can access it anonymously. To prevent this:
- You can apply storage account firewall and network rules to your static website. This will allow you to restrict access to your website based on IP address ranges or virtual networks. You can also use service endpoints or private endpoints to connect your website to other Azure resources securely.
Configure Azure Storage firewalls and virtual networks | Microsoft Learn - Change the access level of the $web container that hosts your website file.
However, changing the access level of the $web container may also affect the functionality of your website while using the Blob endpoint. For example, if you have any blobs that are referenced from within your HTML or JavaScript files, such as images or scripts, they will not be accessible anymore. To solve this problem, you can use shared access signatures (SAS) tokens to access those blobs.
Configure anonymous public read access for containers and blobs - Azure Storage | Microsoft Learn
On the other hand, this will make no difference to the access of static websites using the Web endpoint.
How to set access permissions on Static Websites?
The hosted static website on the Azure storage account is completely public by default. Anyone who knows the URL can access it without authentication or authorization. If you want to restrict access to your static website, you have a few options:
- Use Azure Content Delivery Network (CDN) to add custom headers or rules to your website requests. For example, you can use CDN rules engine to redirect requests based on IP address or user agent.
Integrate a static website with Azure CDN - Azure Storage | Microsoft Learn
- Host your static website as a blob in a container with private access, and then use Shared Access Signatures (SAS) to grant temporary access to specific blobs. You can generate SAS tokens programmatically using Azure Functions or other services.
Grant limited access to data with shared access signatures (SAS) - Azure Storage | Microsoft Learn
What is the impact of setting access level on the $web container?
If you are hosting a static website on Azure Blob Storage, you might wonder how to control the public access level for your files.
The $web container is a special container that stores the files for your static website. You can access your static website by using the static website endpoint, which has the format https://<storage-account-name>.z22.web.core.windows.net. You can also access your files by using the primary blob service endpoint, which has the format https://<storage-account-name>.blob.core.windows.net/$web.
By default, the access level on the $web container is set to Private, which means that only authorized users can access the files. However, this does not affect the static website endpoint, which is always publicly accessible.
Configure anonymous public read access for containers and blobs - Azure Storage | Microsoft Learn
However, changing the access level on the $web container does not have any effect on the static website endpoint access. The static website endpoint will always be publicly accessible, regardless of the access level on the $web container.
On the other hand, it does impact the primary blob service endpoint access. For example, if you change the access level from Private to Blob, you will be able to access your files by using both endpoints. If you change it back to Private, you will only be able to access your files by using the static website endpoint.
Here is an example:
Access level on $web: Blob
Access to https://contosoblobaccount.z22.web.core.windows.net/index.html doesn't change
Access to https://contosoblobaccount.blob.core.windows.net/$web/index.html does change from private to public
Now users can open that file by using either of these two endpoints.
However, disabling public access on a storage account does not affect static websites either.
Here is an example:
Public access on storage account: Disabled
Access to https://contosoblobaccount.z22.web.core.windows.net/index.html doesn't change
Access to https://contosoblobaccount.blob.core.windows.net/$web/index.html changes from public to private
Now users can only open that file by using the static website endpoint.
Troubleshooting Common Issues and Scenarios:
- Root not redirecting to the index document:
When you enable static website hosting on Azure Storage, you need to specify the name of the index document that will be served when a user requests the root URL of your website. For example, if you set the index document name to "index.html", then your website will display the content of that file when someone visits https://yourwebsite.zxx.web.core.windows.net/.
However, sometimes you may find that the root URL does not redirect to the index document, and instead shows a blank page or an error message. This could happen for several reasons:
- Ensure the name and extension as set in the file name on the portal are the exact same of the file in the $web container, including case sensitivity. File names along with extensions are case sensitive. Even though this is served over HTTP, index.html != Index.html for Static Websites.
- Ensure that the index document exists in the $web container and has a valid content type. You can check this by using Azure Portal, Azure CLI, or Azure Storage Explorer.
- Ensure that there are no other files or folders in the $web container that have the same name as the index document. For example, if you have a folder named "index.html" in the $web container, it will conflict with the index document and prevent it from being served.
- HTTP 404 Error:
Another common issue that you may encounter when hosting your static website on Azure is getting an HTTP 404 error when requesting a specific file or resource. This means that the server could not find the requested file or resource. This could happen for several reasons:
- The request is blocked by Storage Firewall. Since all the requests sent to *.web.core.windows.net will be regarded as Anonymous request, for security reasons, all the Authorization Error will return a 404 instead of a 403. To fix this issue, you need to allow access from all networks or specify a list of allowed IP addresses or virtual networks in the Storage Firewall settings.
- The file or resource does not exist in the $web container or has a different name or extension than what is requested. For example, if you request https://yourwebsite.zxx.web.core.windows.net/images/logo.png but there is no such file in the $web container, you will get a 404 error. Make sure that you upload all the files and resources that your website needs to the $web container and use the correct URLs to reference them.
- The file or resource has an invalid content type or encoding. For example, if you upload a text file with a .jpg extension or a binary file with a .txt extension, it may not be recognized by the server and cause a 404 error. Make sure that you set the correct content type and encoding for each file and resource that you upload to the $web container.
- HTTP 400 Error:
An HTTP 400 error means that there is something wrong with your request and the server cannot process it. This could happen for several reasons:
- The CDN endpoint is throwing 400 due to missing "origin host header".
If you use Azure CDN to deliver your static website content faster and more securely, you need to configure the origin host header to match the Static Websites domain name. Otherwise, the CDN endpoint may reject your request and return a 400 error. You can change the origin host header by using Azure Portal or Azure CLI. - The request URL is too long or contains invalid characters. For example, if you request https://yourwebsite.zxx.web.core.windows.net/?q=%E2%98%BA%F0%9F%98%8A%F0%9F%98%81%F0%9F%98%82%F0%9F%...
- IPAuthorization error when accessing static websites in Azure Storage:
The most likely cause of this error is that you have enabled storage firewalls for your storage account and your client IP address is not whitelisted. If a request comes from an IP address that is not on the allow list, it will be rejected with an IPAuth error.
To fix this error, you need to whitelist your client IP address in the storage firewall settings.
Configure Azure Storage firewalls and virtual networks | Microsoft Learn
Note:
It is possible that even after whitelisting your client IP address in the storage firewalls, you still get the IPAuth error. This may happen if your client IP address is also blocked by your corporate firewall rules. In this case, you need to work with your network team to allow access to your static website from your network.
- Unsupported HTTP Verb Error on Static Websites
If you are hosting a static website on Azure, you might encounter the following error message when you try to perform a POST or PUT request:
Issue:
405 The resource doesn't support specified Http Verb.
HttpStatusCode: 405
ErrorCode: UnsupportedHttpVerb
This error means that the request method you are using is not allowed by the server. Static websites are designed to serve static content, such as HTML, CSS, JavaScript, and images. They do not support dynamic operations such as creating, updating, or deleting data. Therefore, only GET and HEAD requests are supported on static websites.
To resolve this issue, you need to change your request method to GET or HEAD, depending on what you want to achieve.
If you want to perform some dynamic operations on your data, make use of serverless functions, such as Azure Functions, or alternatively, consider hosting your website on Azure App Service.
- Static Website Issues with Private Endpoints
Sometimes you may encounter issues when accessing your static website hosted on Azure Storage like a 404 error, a 403 error, or a blank page. One possible cause of these issues is the configuration of your private endpoint.
If you enable a private endpoint for your Azure Storage account, you need to make sure that you also create a separate Private Endpoint of static website as it won’t work with the Blob PE.
Use private endpoints - Azure Storage | Microsoft Learn
To troubleshoot your static website issues with a private endpoint, you can follow these steps:
- Check the status of your private endpoint: You can use the Azure portal or the Azure CLI to verify that your private endpoint is in a connected state and that it has a valid private IP address assigned.
- Check the DNS settings of your private endpoint: You can use the Azure portal or the Azure CLI to verify that you have configured the DNS settings of your private endpoint correctly according to the option you chose (Azure-provided DNS or custom DNS).
- Check the DNS resolution of your static website URL: You can use tools such as nslookup or dig to test the DNS resolution of your static website URL from within your VNet. You should see that it resolves to the private IP address of your service.
- Check the network connectivity to your static website URL: You can use tools such as ping or curl to test the network connectivity to your static website URL from within your VNet. You should see that it responds with a valid HTTP status code (such as 200 OK).
References:
About Static Websites: Static website hosting in Azure Storage | Microsoft Learn
How to host Static Websites: Host a static website in Azure Storage | Microsoft Learn