diff --git a/.env.sample b/.env.sample
index d9d38c6..d4aca8d 100644
--- a/.env.sample
+++ b/.env.sample
@@ -78,6 +78,18 @@ ENABLE_REGISTRATION=false
 # PEM private key: abra cannot generate this format — insert only (e.g. openssl genrsa 2048 | abra app secret insert …)
 #SECRET_MAS_SIGNING_RSA_VERSION=v1 # generate=false
 
+#### MAS upstream OIDC provider (e.g. Authentik)
+# See mas-authentik-and-roadmap.md for migration procedure.
+# Create a new OAuth2 app in your IdP with redirect URI: https://<DOMAIN>/upstream/callback/<MAS_UPSTREAM_PROVIDER_ID>
+#COMPOSE_FILE="$COMPOSE_FILE:compose.mas-upstream.yml"
+#MAS_UPSTREAM_PROVIDER_ID=          # ULID, e.g. 01JSHPZHAXC50QBKH67MH33TNF — generate at https://www.ulidtools.com
+#MAS_UPSTREAM_ISSUER=               # e.g. https://auth.example.com/application/o/matrix-mas/
+#MAS_UPSTREAM_CLIENT_ID=
+#MAS_UPSTREAM_HUMAN_NAME=Authentik
+# For migration from previous direct Keycloud-style config: set to oidc-<your old KEYCLOAK_ID> so syn2mas maps users correctly.
+#MAS_UPSTREAM_SYNAPSE_IDP_ID=
+#SECRET_MAS_UPSTREAM_CLIENT_SECRET_VERSION=v1
+
 ### Shared secret auth (bridges / automation)
 
 #COMPOSE_FILE="$COMPOSE_FILE:compose.shared_secret_auth.yml"
diff --git a/compose.mas-upstream.yml b/compose.mas-upstream.yml
new file mode 100644
index 0000000..317761c
--- /dev/null
+++ b/compose.mas-upstream.yml
@@ -0,0 +1,21 @@
+---
+version: "3.8"
+
+# Upstream OIDC provider for MAS (e.g. Authentik, Keycloak).
+# Requires compose.mas.yml. Adds the client secret and env vars needed by mas.config.yaml.tmpl.
+
+services:
+  mas:
+    environment:
+      - MAS_UPSTREAM_PROVIDER_ID
+      - MAS_UPSTREAM_ISSUER
+      - MAS_UPSTREAM_CLIENT_ID
+      - MAS_UPSTREAM_HUMAN_NAME
+      - MAS_UPSTREAM_SYNAPSE_IDP_ID
+    secrets:
+      - mas_upstream_client_secret
+
+secrets:
+  mas_upstream_client_secret:
+    external: true
+    name: ${STACK_NAME}_mas_upstream_client_secret_${SECRET_MAS_UPSTREAM_CLIENT_SECRET_VERSION}
diff --git a/mas.config.yaml.tmpl b/mas.config.yaml.tmpl
index 3d958d6..59a74e0 100644
--- a/mas.config.yaml.tmpl
+++ b/mas.config.yaml.tmpl
@@ -39,3 +39,33 @@ secrets:
 
 passwords:
   enabled: true
+  schemes:
+    - version: 1
+      algorithm: bcrypt
+      unicode_normalization: true
+    - version: 2
+      algorithm: argon2id
+
+{{ if env "MAS_UPSTREAM_PROVIDER_ID" }}
+# https://element-hq.github.io/matrix-authentication-service/setup/sso.html
+upstream_oauth2:
+  providers:
+    - id: {{ env "MAS_UPSTREAM_PROVIDER_ID" }}
+      {{ if env "MAS_UPSTREAM_SYNAPSE_IDP_ID" }}synapse_idp_id: {{ env "MAS_UPSTREAM_SYNAPSE_IDP_ID" }}{{ end }}
+      human_name: {{ or (env "MAS_UPSTREAM_HUMAN_NAME") "SSO" }}
+      issuer: {{ env "MAS_UPSTREAM_ISSUER" }}
+      client_id: {{ env "MAS_UPSTREAM_CLIENT_ID" }}
+      client_secret_file: /run/secrets/mas_upstream_client_secret
+      token_endpoint_auth_method: client_secret_basic
+      scope: "openid profile email"
+      claims_imports:
+        localpart:
+          action: require
+          template: "{{ "{{ user.preferred_username }}" }}"
+        displayname:
+          action: suggest
+          template: "{{ "{{ user.name }}" }}"
+        email:
+          action: suggest
+          template: "{{ "{{ user.email }}" }}"
+{{ end }}