From b82baccd4cd0ba2af80c6d010639279d5845d23a Mon Sep 17 00:00:00 2001 From: Ola Date: Tue, 30 Jun 2026 12:06:58 +0200 Subject: [PATCH 1/2] docs: document stripped secrets in project config API Reflects the project config API change where the SMTP connection URI password, OIDC client_secret, and apple_private_key are redacted from API responses. Adds a canonical "Stored secrets" section to the CLI config guide and short contextual notes (linking to the canonical section) on the API, gitops, identity CLI, SMTP, social sign-in overview, social sign-in get-started, and Apple provider pages. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/guides/cli/10_config-with-cli.mdx | 24 +++++++++++++++++++ .../guides/cli/15_config-identity-service.mdx | 8 +++++++ docs/guides/gitops.mdx | 8 +++++++ docs/guides/manage-project-via-api.mdx | 8 +++++++ .../identities/get-started/social-sign-in.mdx | 8 +++++++ .../emails-sms/01_sending-emails-smtp.mdx | 8 +++++++ docs/kratos/social-signin/01_overview.mdx | 8 +++++++ docs/kratos/social-signin/30_apple.mdx | 8 +++++++ 8 files changed, 80 insertions(+) diff --git a/docs/guides/cli/10_config-with-cli.mdx b/docs/guides/cli/10_config-with-cli.mdx index f3949171fd..73c29a6196 100644 --- a/docs/guides/cli/10_config-with-cli.mdx +++ b/docs/guides/cli/10_config-with-cli.mdx @@ -7,6 +7,30 @@ All Ory components use the same configuration format and APIs whether they are s This allows you to use the Ory CLI to configure your components, no matter how you use Ory! +## Stored secrets + +:::warning + +When you read your Ory Network project configuration through the API or the Ory CLI (for example with `ory get project` or +`ory get identity-config`), the following secret fields are returned **empty** even when a value is stored: + +- SMTP `courier.smtp.connection_uri` — the password segment of the URI is removed. +- OIDC provider `client_secret` — for every entry in `selfservice.methods.oidc.config.providers`. +- Apple provider `apple_private_key`. + +The stored value stays in place and continues to be used at runtime. Only the API response is redacted. + +When you write the configuration back: + +- **To keep the stored secret**: leave the field as the API returned it (`null` for OIDC `client_secret` and `apple_private_key`, + or a URI without the password segment for SMTP `connection_uri`). The server merges your update with the existing secret. +- **To rotate a secret**: set the new value explicitly. +- **Setting an OIDC `client_secret` or Apple `apple_private_key` to an empty string is rejected by configuration validation** — + these fields are required when the provider is configured, so you cannot accidentally clear them by sending an empty value. To + remove a secret entirely, remove the provider. + +::: + ## Configure projects There are two ways to adjust the configuration of projects. You can: diff --git a/docs/guides/cli/15_config-identity-service.mdx b/docs/guides/cli/15_config-identity-service.mdx index 463732ac07..e1601ee4ba 100644 --- a/docs/guides/cli/15_config-identity-service.mdx +++ b/docs/guides/cli/15_config-identity-service.mdx @@ -6,6 +6,14 @@ title: Ory Identities CLI Using the Ory CLI, you can quickly adjust the configuration of the Ory Identities and apply config from the Ory Network environment to self-hosted Ory Kratos Identity Server instances. +:::note + +When you export the configuration with `ory get identity-config`, the SMTP `connection_uri` password, OIDC provider +`client_secret`, and `apple_private_key` are returned empty even when a value is stored. See the +[stored secrets note](./config-with-cli#stored-secrets) for the behavior when writing the configuration back. + +::: + :::tip [Ory Kratos](https://github.com/ory/kratos) is the open-source project that powers the Ory Identities. diff --git a/docs/guides/gitops.mdx b/docs/guides/gitops.mdx index 924b1be8c8..d02ef53859 100644 --- a/docs/guides/gitops.mdx +++ b/docs/guides/gitops.mdx @@ -8,6 +8,14 @@ This guide will walk you through the process of managing your Ory Network config these steps, you'll be able to track changes, review, and approve them through pull requests, and automatically update the configuration upon merge. +:::note + +When you export the configuration with `ory get ...`, the SMTP `connection_uri` password, OIDC provider `client_secret`, and +`apple_private_key` are returned empty even when a value is stored. See the +[stored secrets note](./cli/config-with-cli#stored-secrets) for the behavior when writing the configuration back. + +::: + This guide uses the GitHub Actions to update the configuration and manage changes through pull requests. You can adapt this to GitLab CI, TravisCI, CircleCI, and other CI/CD systems. diff --git a/docs/guides/manage-project-via-api.mdx b/docs/guides/manage-project-via-api.mdx index d9acae39c3..35a3c4264a 100644 --- a/docs/guides/manage-project-via-api.mdx +++ b/docs/guides/manage-project-via-api.mdx @@ -107,6 +107,14 @@ curl --location --request GET "https://api.console.ory.com/projects/${ORY_PROJEC --header "Authorization: Bearer ${WORKSPACE_API_KEY}" | jq ``` +:::note + +The response does not include the password segment of the SMTP `connection_uri`, the OIDC provider `client_secret`, or the Apple +`apple_private_key`. These fields are returned empty even when a value is stored. The stored value is still used at runtime. See +the [stored secrets note](./cli/config-with-cli#stored-secrets) for the behavior when writing the configuration back. + +::: + ### Update an Ory Network project Configuration You can use Workspace API keys to change a projects configuration through the API. diff --git a/docs/identities/get-started/social-sign-in.mdx b/docs/identities/get-started/social-sign-in.mdx index ca8fd60a45..355ccadb39 100644 --- a/docs/identities/get-started/social-sign-in.mdx +++ b/docs/identities/get-started/social-sign-in.mdx @@ -80,6 +80,14 @@ The configuration includes: ``` +:::note + +When you export the configuration with `ory get identity-config`, the OIDC provider `client_secret` (and the Apple +`apple_private_key`) are returned empty even when a value is stored. See the +[stored secrets note](../../guides/cli/config-with-cli#stored-secrets) for the behavior when writing the configuration back. + +::: + To enable and configure social sign-in using the CLI: 1. First, download your Ory Identities configuration: diff --git a/docs/kratos/emails-sms/01_sending-emails-smtp.mdx b/docs/kratos/emails-sms/01_sending-emails-smtp.mdx index 8038e2d544..d9ab92183c 100644 --- a/docs/kratos/emails-sms/01_sending-emails-smtp.mdx +++ b/docs/kratos/emails-sms/01_sending-emails-smtp.mdx @@ -264,6 +264,14 @@ SparkPost separates US and EU accounts — pick data residency before integratio ### Your own server +:::note + +When you export the configuration with `ory get identity-config`, the password segment of the SMTP `connection_uri` is returned +empty even when a value is stored. See the [stored secrets note](../../guides/cli/config-with-cli#stored-secrets) for the behavior +when writing the configuration back. + +::: + You can send emails from your own SMTP server. Follow these steps to configure Ory to use a custom SMTP server: diff --git a/docs/kratos/social-signin/01_overview.mdx b/docs/kratos/social-signin/01_overview.mdx index bff4bd9f0c..3da79a566f 100644 --- a/docs/kratos/social-signin/01_overview.mdx +++ b/docs/kratos/social-signin/01_overview.mdx @@ -32,3 +32,11 @@ application. The Ory Network provides GUI-based flows for adding and configuring social sign-in providers through the [Ory Console](https://console.ory.com/login). Each flow is custom-tailored to accommodate configuration requirements of the specific identity provider. Alternatively, you can use the [Ory CLI](../../guides/cli/01_installation.mdx). + +:::note + +When you export the configuration with `ory get identity-config`, the OIDC provider `client_secret` and the Apple +`apple_private_key` are returned empty even when a value is stored. See the +[stored secrets note](../../guides/cli/config-with-cli#stored-secrets) for the behavior when writing the configuration back. + +::: diff --git a/docs/kratos/social-signin/30_apple.mdx b/docs/kratos/social-signin/30_apple.mdx index 3b9425171b..e5d004609b 100644 --- a/docs/kratos/social-signin/30_apple.mdx +++ b/docs/kratos/social-signin/30_apple.mdx @@ -111,6 +111,14 @@ middleware, as Apple uses a POST form request that does not include the CSRF coo ``` +:::note + +When you export the configuration with `ory get identity-config`, the `apple_private_key` is returned empty even when a value is +stored. See the [stored secrets note](../../guides/cli/config-with-cli#stored-secrets) for the behavior when writing the +configuration back. + +::: + Follow these steps to add Apple as a social sign-in provider to your project using the Ory CLI: 1. Using an Apple Developer Account, create an app, a service, and a private key. Check the Ory Console guide for the concrete From 964843bf3ab4ae75faa6adf5327dd8e7178584f9 Mon Sep 17 00:00:00 2001 From: Ola Date: Tue, 30 Jun 2026 12:20:10 +0200 Subject: [PATCH 2/2] Update strict-mode.mdx --- docs/keto/guides/strict-mode.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/keto/guides/strict-mode.mdx b/docs/keto/guides/strict-mode.mdx index 1503feb94f..bac5f3cc6b 100644 --- a/docs/keto/guides/strict-mode.mdx +++ b/docs/keto/guides/strict-mode.mdx @@ -143,5 +143,5 @@ See the [Ory Permission Language](../reference/ory-permission-language) guide. ## Enabling and disabling -Go to the [Ory Console](https://console.ory.sh), select your project, and navigate to **Permissions > Configuration**. Toggle +Go to the [Ory Console](https://console.ory.com), select your project, and navigate to **Permissions > Configuration**. Toggle **Strict mode** on or off and save. The change takes effect immediately — no restart required, and no data is modified.