diff --git a/docs/reference/cli/syn2mas.md b/docs/reference/cli/syn2mas.md
index 0089cc704..de8b1af16 100644
--- a/docs/reference/cli/syn2mas.md
+++ b/docs/reference/cli/syn2mas.md
@@ -8,6 +8,11 @@ Global options:
 - `--synapse-config <synapse-config>`: Path to the Synapse configuration file.
 - `--synapse-database-uri <synapse-database-uri>`: Override the Synapse database URI.
 
+If your Synapse is configured with OIDC providers, note that you will need to
+configure the `synapse_idp_id` for them for each provider in the MAS
+`upstream_oauth2.providers` list. The Synapse IDP ID's can be removed after
+a successful migration has been completed.
+
 ## `syn2mas check`
 
 Check the setup for potential problems before running a migration
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 2303e889e..33882ea08 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -770,6 +770,20 @@ upstream_oauth2:
         # This helps end user identify what account they are using
         account_name:
           #template: "@{{ user.preferred_username }}"
+
+      # The ID of the provider that was used by Synapse when doing a
+      # Synapse-to-MAS migration.
+      #
+      # For `oidc_providers` this should be specified as `oidc-` followed by the ID 
+      # that was configured as `idp_id` in one of the `oidc_providers` in the Synapse
+      # configuration.
+      # For example, if Synapse's configuration contained `idp_id: wombat` for
+      # this provider, then specify `oidc-wombat` here.
+      # 
+      # For `oidc_config` (legacy), specify `oidc` here.
+      #
+      # This is safe to remove once the Synapse-to-MAS migration has been done.
+      #synapse_idp_id: oidc
 ```
 
 ## `experimental`