Secrets Management
Learn how to securely store, manage, and use secrets in Umbraco Cloud environments using Shared and Environment Secrets.
If your Umbraco Cloud project uses sensitive information such as API keys, encryption keys, or connection strings, you should store these as secrets.
You can add secrets to your Cloud project in two ways: Environment Secrets or Shared Secrets.
Environment Secrets are used within a specific environment during runtime of your Umbraco solution.
Shared Secrets are available across all environments and are automatically included in any new environment you create. Shared Secrets are well-suited for credentials needed during project development, such as access to private NuGet feeds.
Do not use environment-specific secrets for NuGet feeds. Use Shared Secrets to avoid environment creation failures.
Typical secrets are Private keys, third-party API tokens, database passwords, and other sensitive data that must be kept secure.
When secrets are added, they are exposed only to the assigned environments. Each secret is assigned as an environment variable at runtime using the secret name. The environment accesses the secret through a Key Vault reference secured by the environment’s managed identity.
Starter Plans have a limit of 5 secrets per environment, whereas higher-tier plans do not have a limit
How to add Secrets
Important
When adding a secret to your environment, the environment will restart.
Secrets are stored as environment variables. The underlying platform has a maximum size limit for all environment variables combined. If too many secrets are added, or if secret values are too large, your environment may fail to start.
Recommendations:
Keep secrets small and concise.
Store only sensitive values as secrets (for example, API keys and connection strings).
Use
appsettings.jsonfor general configuration values.
To add a secret to your environment, follow these steps:
Go to your Umbraco Cloud project
Go to Security.
Select Secrets.
Choose Shared Secrets or the environment where you want to add the secret.
Click Edit secrets.
Select Add secret.
Enter the Key and the Value in the Create secret window.
Click Add secret.
Click Save secrets to save the secret.
Working locally with Secrets
When developing locally, you cannot access secrets stored in the Key Vault for a Cloud environment.
It is recommended to use standard methods for handling secrets locally, such as the appsettings.development.json. Do not commit this file to your code repository. Add it to your .gitignore file to prevent accidental commits.
For example, if you have a secret in a Cloud environment with the key name ApiKey, you can create a corresponding entry in your appsettings.development.json:
Access secrets in an Umbraco Solution
Secrets for cloud environments are stored in a Key Vault and loaded by the App Service (using a Key Vault reference) as environment variables. This allows you to retrieve the value at runtime like any other environment variable.
You can access a secret in .NET using the System namespace:
_secretMessage = Environment.GetEnvironmentVariable("SecretMessage");
Secrets can also be used to override app settings defined in appsettings.json files. For this to work, when adding the secret, the key value should be all the settings names joined by double underscores.
For example, to change the Serilog default options under Serilog:MinimumLevel:Default, the Secret key would be: Serilog__MinimumLevel__Default .
The value defined in appsettings.json file will be overwritten by the Cloud secret value.
Naming standards for Secrets
When naming a secret, you can use alphanumeric characters and underscores (_).
If you need to use a dot (.) as part of an app setting, it should be replaced with a single underscore.
The app setting Umbraco:Licenses:Products:Umbraco.Commerce should become Umbraco__Licenses__Products__Umbraco_Commerce.
Reserved names
The following names are reserved and cannot be used:
COMMANDHOMEPORTREMOTEDEBUGGINGVERSIONREGION_NAMECONNECTIONSTRINGS__UMBRACODBDSN
Restricted prefixes
The following prefixes are not allowed:
UMBRACO_WEBSITE_SCM_SDEPLOY_DEPLOYMENT_DOCKER_CONTAINER_DIAGNOSTICS_APPSERVICEAPPLOGS_DOTNET_IDENTITY_MSI_WEBJOBS_FUNCTIONS_AzureWebJobsWP_PHP_FILE_DATABASE_WORDPRESS_MACHINEKEY_SQLCONNSTRSQLAZURECONNSTR_POSTGRESQLCONNSTR_CUSTOMCONNSTR_MYSQLCONNSTR_AZUREFILESSTORAGE_AZUREBLOBSTORAGE_NOTIFICATIONHUBCONNSTR_SERVICEBUSCONNSTR_EVENTHUBCONNSTR_DOCDBCONNSTR_REDISCACHECONNSTR_FILESHARESTORAGE_
The list of restricted prefixes is incomplete and will be updated as new cases arise.
Accepted Prefixes
The following prefixes are allowed for Secrets on Umbraco Cloud:
Umbraco__CMS__Global__Smtp__Umbraco__Forms__Security__FormsApiKey__Umbraco__Forms__FieldTypes__Recaptcha__Umbraco__CMS__Integrations__Umbraco__CMS__DeliveryAPI__UMBRACO__LICENSES__UMBRACO__AUTHORIZEDSERVICES__UMBRACO__COMMERCE__,UMBRACO__AI__,Umbraco__CMS__Imaging__HMACSecretKey
You can also use secrets to store API keys, passwords, and reCAPTCHA keys for Umbraco products on Umbraco Cloud.
If you have an existing or new secret that conflicts with the naming restrictions, contact Umbraco Support, and your request will be reviewed.
Last updated
Was this helpful?