From 7f27efcac15a22cd2e9c2a92dc7483528759dcc0 Mon Sep 17 00:00:00 2001 From: Maximilian Date: Wed, 3 Sep 2025 15:23:01 +0200 Subject: [PATCH] docs(inconsistent naming): custom domain (#10377) # Which Problems Are Solved partially #9342 # How the Problems Are Solved Name custom domain consistently in the docs according to https://github.com/zitadel/zitadel/issues/5888 # Additional Changes # Additional Context --- docs/docs/apis/introduction.mdx | 26 +++++++-------- docs/docs/apis/openidoauth/authrequest.mdx | 2 +- docs/docs/apis/openidoauth/endpoints.mdx | 30 ++++++++--------- docs/docs/apis/scim2.md | 2 +- docs/docs/examples/login/go.md | 2 +- docs/docs/examples/login/symfony.md | 2 +- docs/docs/examples/secure-api/go.md | 2 +- .../docs/examples/secure-api/python-flask.mdx | 5 +-- .../_custom_login_policy.mdx | 4 +-- .../identity-providers/introduction.md | 4 +-- .../identity-providers/linkedin_oauth.mdx | 2 +- .../integrate/login-ui/_list-mfa-options.mdx | 2 +- .../guides/integrate/login-ui/_logout.mdx | 4 +-- .../integrate/login-ui/_select-account.mdx | 2 +- .../login-ui/_update_session_webauthn.mdx | 2 +- .../guides/integrate/login-ui/device-auth.mdx | 6 ++-- .../integrate/login-ui/external-login.mdx | 16 +++++----- docs/docs/guides/integrate/login-ui/mfa.mdx | 32 +++++++++---------- .../integrate/login-ui/oidc-standard.mdx | 4 +-- .../guides/integrate/login-ui/passkey.mdx | 8 ++--- .../integrate/login-ui/password-reset.mdx | 6 ++-- .../integrate/login-ui/saml-standard.mdx | 4 +-- .../integrate/login-ui/username-password.mdx | 6 ++-- .../guides/integrate/login/hosted-login.mdx | 6 ++-- .../login/oidc/authmethods/_basic.mdx | 2 +- .../login/oidc/authmethods/_jwtpk.mdx | 2 +- .../login/oidc/authmethods/_pkce.mdx | 2 +- .../login/oidc/authmethods/_pkcenative.mdx | 2 +- .../guides/integrate/login/oidc/webkeys.md | 2 +- .../guides/integrate/retrieve-user-roles.md | 28 ++++++++-------- .../guides/integrate/services/auth0-oidc.mdx | 2 +- .../integrate/services/cloudflare-oidc.mdx | 8 ++--- .../integrate/services/gitlab-self-hosted.mdx | 4 +-- .../integrate/services/google-workspace.md | 14 ++++---- .../token-introspection/basic-auth.mdx | 2 +- .../token-introspection/private-key-jwt.mdx | 6 ++-- docs/docs/guides/integrate/tools/apache2.mdx | 4 +-- .../manage/console/default-settings.mdx | 8 ++--- .../guides/manage/console/organizations.mdx | 4 +-- docs/docs/guides/manage/console/overview.mdx | 2 +- docs/docs/guides/manage/console/projects.mdx | 2 +- docs/docs/guides/solution-scenarios/b2b.mdx | 2 +- docs/docs/guides/solution-scenarios/b2c.mdx | 4 +-- .../solution-scenarios/restrict-console.mdx | 2 +- docs/docs/self-hosting/manage/cache.md | 2 +- docs/src/components/authrequest.jsx | 2 +- docs/src/components/environment.jsx | 2 +- 47 files changed, 144 insertions(+), 143 deletions(-) diff --git a/docs/docs/apis/introduction.mdx b/docs/docs/apis/introduction.mdx index 905adfc0fb..f7f473cd75 100644 --- a/docs/docs/apis/introduction.mdx +++ b/docs/docs/apis/introduction.mdx @@ -87,7 +87,7 @@ The authentication API (aka Auth API) is used for all operations on the currentl #### GRPC Endpoint: -$ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/ +`${CUSTOM_DOMAIN}/zitadel.auth.v1.AuthService/` Definition: [Auth Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/auth.proto) @@ -95,7 +95,7 @@ Definition: #### REST Endpoint: -$ZITADEL_DOMAIN/auth/v1/ +`${CUSTOM_DOMAIN}/auth/v1/` API Reference: [OpenAPI Docs](/apis/resources/auth) @@ -120,7 +120,7 @@ To identify the current organization you can send a header `x-zitadel-orgid` or #### GRPC Endpoint: -$ZITADEL_DOMAIN/zitadel.management.v1.ManagementService/ +`${CUSTOM_DOMAIN}/zitadel.management.v1.ManagementService/` Definition: [Management Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/management.proto) @@ -128,7 +128,7 @@ Definition: #### REST Endpoint: -$ZITADEL_DOMAIN/management/v1/ +`${CUSTOM_DOMAIN}/management/v1/` API Reference: [OpenAPI Docs](/apis/resources/mgmt) @@ -151,7 +151,7 @@ This API is intended to configure and manage one ZITADEL instance itself. #### GRPC Endpoint: -$ZITADEL_DOMAIN/zitadel.admin.v1.AdminService/ +`${CUSTOM_DOMAIN}/zitadel.admin.v1.AdminService/` Definition: [Admin Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/admin.proto) @@ -159,7 +159,7 @@ Definition: #### REST Endpoint: -$ZITADEL_DOMAIN/admin/v1/ +`${CUSTOM_DOMAIN}/admin/v1/` API Reference: [OpenAPI Docs](/apis/resources/admin) @@ -184,7 +184,7 @@ Checkout the guide how to [access the ZITADEL System API](/docs/guides/integrate #### GRPC Endpoint: -$ZITADEL_DOMAIN/zitadel.system.v1.SystemService/ +`${CUSTOM_DOMAIN}/zitadel.system.v1.SystemService/` Definition: [System Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto) @@ -192,7 +192,7 @@ Definition: #### REST Endpoint: -$ZITADEL_DOMAIN/system/v1/ +`${CUSTOM_DOMAIN}/system/v1/` API Reference: [OpenAPI Docs](/apis/resources/system) @@ -215,7 +215,7 @@ The Assets API allows you to up- and download all kinds of assets. This can be f #### REST Endpoint: -$ZITADEL_DOMAIN/assets/v1/ +`${CUSTOM_DOMAIN}/assets/v1/` Definition: [Assets](./assets/assets.md) @@ -271,14 +271,14 @@ In the table below you can see the URI of those calls. | Service | URI | | :------ | :---------------------------------------------------- | -| REST | $ZITADEL_DOMAIN/auth/v1/users/me | -| GRPC | $ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/GetMyUser | +| REST | `${CUSTOM_DOMAIN}/auth/v1/users/me` | +| GRPC | `${CUSTOM_DOMAIN}/zitadel.auth.v1.AuthService/GetMyUser` | ## Domains -ZITADEL hosts everything under a single domain: `{instance}.zitadel.cloud` or your custom domain `$ZITADEL_DOMAIN` +ZITADEL hosts everything under a single domain: `{instance}.zitadel.cloud` or your custom domain `${CUSTOM_DOMAIN}` -The domain is used as the OIDC issuer and as the base url for the gRPC and REST APIs, the Login and Console UI, which you'll find under `{your_domain}/ui/console/`. +The domain is used as the OIDC issuer and as the base url for the gRPC and REST APIs, the Login and Console UI, which you'll find under `${CUSTOM_DOMAIN}/ui/console/`. Are you self-hosting and having troubles with _Instance not found_ errors? [Check out this page](/docs/self-hosting/manage/custom-domain). diff --git a/docs/docs/apis/openidoauth/authrequest.mdx b/docs/docs/apis/openidoauth/authrequest.mdx index c3be807ab1..95fdd6713b 100644 --- a/docs/docs/apis/openidoauth/authrequest.mdx +++ b/docs/docs/apis/openidoauth/authrequest.mdx @@ -24,7 +24,7 @@ Not all request parameters are available in the playground. Please refer to the ### Your Domain -The Instance Domain to your ZITADEL instance. Use the base-path, the playground will add the required path to the request. +The Custom Domain to your ZITADEL instance. Use the base-path, the playground will add the required path to the request. ### Required Parameters diff --git a/docs/docs/apis/openidoauth/endpoints.mdx b/docs/docs/apis/openidoauth/endpoints.mdx index 79d533ab3a..919e54822a 100644 --- a/docs/docs/apis/openidoauth/endpoints.mdx +++ b/docs/docs/apis/openidoauth/endpoints.mdx @@ -12,13 +12,13 @@ import TokenExchangeTypes from "./_token_exchange_types.mdx"; ## OpenID Connect 1.0 Discovery The OpenID Connect Discovery Endpoint is located within the issuer domain. -This would give us `{your_domain}/.well-known/openid-configuration`. +This would give us `${CUSTOM_DOMAIN}/.well-known/openid-configuration`. **Link to spec.** [OpenID Connect Discovery 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-discovery-1_0.html) ## authorization_endpoint -`{your_domain}/oauth/v2/authorize` +`${CUSTOM_DOMAIN}/oauth/v2/authorize` :::note The authorization_endpoint is located with the login page, due to the need of accessing the same cookie domain @@ -172,7 +172,7 @@ the error will be display directly to the user on the auth server ## token_endpoint -`{your_domain}/oauth/v2/token` +`${CUSTOM_DOMAIN}/oauth/v2/token` The token_endpoint will as the name suggests return various tokens (access, id and refresh) depending on the used `grant_type`. When using [`authorization_code`](#authorization-code-grant-code-exchange) flow call this endpoint after receiving the code from the authorization_endpoint. @@ -262,7 +262,7 @@ Send a client assertion as JWT for us to validate the signature against the regi ```BASH curl --request POST \ - --url {your_domain}/oauth/v2/token \ + --url ${CUSTOM_DOMAIN}/oauth/v2/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \ --data assertion=eyJhbGciOiJSUzI1Ni... @@ -360,7 +360,7 @@ Check [Client Secret Basic Auth Method](authn-methods#client-secret-basic) on ho ```BASH curl --request POST \ - --url {your_domain}/oauth/v2/token \ + --url ${CUSTOM_DOMAIN}/oauth/v2/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic ${BASIC_AUTH}' \ --data grant_type=client_credentials \ @@ -376,7 +376,7 @@ Or you can also send your `client_id` and `client_secret` as parameters in the b ```BASH curl --request POST \ - --url {your_domain}/oauth/v2/token \ + --url ${CUSTOM_DOMAIN}/oauth/v2/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data client_id=${CLIENT_ID} \ @@ -472,7 +472,7 @@ Send a `client_assertion` as JWT for us to validate the signature against the re ## introspection_endpoint -`{your_domain}/oauth/v2/introspect` +`${CUSTOM_DOMAIN}/oauth/v2/introspect` This endpoint enables clients to validate an `acccess_token`, either opaque or JWT. Unlike client side JWT validation, this endpoint will check if the token is not revoked (by client or logout). @@ -497,7 +497,7 @@ Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Se ```BASH curl --request POST \ - --url {your_domain}/oauth/v2/introspect \ + --url ${CUSTOM_DOMAIN}/oauth/v2/introspect \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic {your_basic_auth_header}' \ --data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn... @@ -516,7 +516,7 @@ Send a `client_assertion` as JWT for us to validate the signature against the re ```BASH curl --request POST \ - --url {your_domain}/oauth/v2/introspect \ + --url ${CUSTOM_DOMAIN}/oauth/v2/introspect \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \ --data client_assertion=eyJhbGciOiJSUzI1Ni... \ @@ -555,7 +555,7 @@ If the authorization fails, an HTTP 401 with `invalid_client` will be returned. ## userinfo_endpoint -`{your_domain}/oidc/v1/userinfo` +`${CUSTOM_DOMAIN}/oidc/v1/userinfo` This endpoint will return information about the authorized user. @@ -563,7 +563,7 @@ Send the `access_token` of the **user** (not the client) as Bearer Token in the ```BASH curl --request GET \ - --url {your_domain}/oidc/v1/userinfo + --url ${CUSTOM_DOMAIN}/oidc/v1/userinfo --header 'Authorization: Bearer dsfdsjk29fm2as...' ``` @@ -578,7 +578,7 @@ If the token is invalid or expired, an HTTP 401 will be returned. ## revocation_endpoint -`{your_domain}/oauth/v2/revoke` +`${CUSTOM_DOMAIN}/oauth/v2/revoke` This endpoint enables clients to revoke an `access_token` or `refresh_token` they have been granted. @@ -638,7 +638,7 @@ Send a `client_assertion` as JWT for ZITADEL to verify the signature against the ```BASH curl --request POST \ - --url {your_domain}/oauth/v2/revoke \ + --url ${CUSTOM_DOMAIN}/oauth/v2/revoke \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \ --data client_assertion=eyJhbGciOiJSUzI1Ni... \ @@ -650,7 +650,7 @@ curl --request POST \ ## end_session_endpoint -`{your_domain}/oidc/v1/end_session` +`${CUSTOM_DOMAIN}/oidc/v1/end_session` The endpoint has to be opened in the user agent (browser) to terminate the user sessions. @@ -672,7 +672,7 @@ If neither an `id_token_hint` nor a `client_id` parameter is provided, the `post ## jwks_uri -`{your_domain}/oauth/v2/keys` +`${CUSTOM_DOMAIN}/oauth/v2/keys` The endpoint returns a JSON Web Key Set (JWKS) containing the public keys that can be used to locally validate JWTs you received from ZITADEL. The alternative would be to validate tokens with the [introspection endpoint](#introspection_endpoint). diff --git a/docs/docs/apis/scim2.md b/docs/docs/apis/scim2.md index d342142cf0..c4a9a98a94 100644 --- a/docs/docs/apis/scim2.md +++ b/docs/docs/apis/scim2.md @@ -11,7 +11,7 @@ deprovisioning. ## Supported endpoints The Zitadel SCIM v2.0 service provider implementation supports the following endpoints. -The base URL for the SCIM endpoint in Zitadel is: `https://${ZITADEL_DOMAIN}/scim/v2/{orgId}`. +The base URL for the SCIM endpoint in Zitadel is: `https://${CUSTOM_DOMAIN}/scim/v2/{orgId}`. | Endpoint | Remarks | |-------------------------------------------------------------------------|------------------------------------------------------------| diff --git a/docs/docs/examples/login/go.md b/docs/docs/examples/login/go.md index ae24148952..ed4f9ba61f 100644 --- a/docs/docs/examples/login/go.md +++ b/docs/docs/examples/login/go.md @@ -122,7 +122,7 @@ https://github.com/zitadel/zitadel-go/blob/next/example/app/templates/profile.ht ### Start your application You will need to provide some values for the program to run: -- `domain`: Your ZITADEL instance domain, e.g. my-domain.zitadel.cloud +- `domain`: Your ZITADEL custom domain, e.g. my-domain.zitadel.cloud - `key`: Random secret string. Used for symmetric encryption of state parameters, cookies and PCKE. - `clientID`: The clientID provided by ZITADEL - `redirectURI`: The redirectURI registered at ZITADEL diff --git a/docs/docs/examples/login/symfony.md b/docs/docs/examples/login/symfony.md index 1856e68df5..8e5fd43b9c 100644 --- a/docs/docs/examples/login/symfony.md +++ b/docs/docs/examples/login/symfony.md @@ -375,7 +375,7 @@ OIDC_CLIENT_ID="248680248240075805@dev" OIDC_CLIENT_SECRET="BJPhEJULSUXseC4geqg5Yg4wWMoy7RgZKar86mbIpt8ZekC5kixMzYGcXLDeeJv7" ``` -> The well-known URL needs to be adjusted to your own instance domain. +> The well-known URL needs to be adjusted to your own custom domain. Activate the route that is used as callback by the OIDC bundle: diff --git a/docs/docs/examples/secure-api/go.md b/docs/docs/examples/secure-api/go.md index 7c1db14cf2..66d1f2d070 100644 --- a/docs/docs/examples/secure-api/go.md +++ b/docs/docs/examples/secure-api/go.md @@ -98,7 +98,7 @@ https://github.com/zitadel/zitadel-go/blob/next/example/api/http/main.go ``` You will need to provide some values for the program to run: -- `domain`: Your ZITADEL instance domain, e.g. https://my-domain.zitadel.cloud +- `domain`: Your ZITADEL custom domain, e.g. https://my-domain.zitadel.cloud - `key`: The path to the downloaded key.json - `port`: The port on which the API will be accessible, default it 8089 diff --git a/docs/docs/examples/secure-api/python-flask.mdx b/docs/docs/examples/secure-api/python-flask.mdx index 798dfe5f1e..1a03b2b03a 100644 --- a/docs/docs/examples/secure-api/python-flask.mdx +++ b/docs/docs/examples/secure-api/python-flask.mdx @@ -179,10 +179,11 @@ class ZitadelIntrospectTokenValidator(IntrospectTokenValidator): res = self.introspect_token(*args, **kwargs) return res ``` -3. Create a new file named ".env" in the directory. Copy the configuration in the [".env.example"](https://github.com/zitadel/example-api-python3-flask/blob/main/.env.example) file to the newly created .env file. Set the values with your Instance Domain/Issuer URL, Client ID, and Client Secret from the previous steps. Obtain your Issuer URL by following [these steps](/docs/guides/start/quickstart#referred1). + +3. Create a new file named ".env" in the directory. Copy the configuration in the [".env.example"](https://github.com/zitadel/example-api-python3-flask/blob/main/.env.example) file to the newly created .env file. Set the values with your Custom Domain/Issuer URL, Client ID, and Client Secret from the previous steps. Obtain your Issuer URL by following [these steps](/docs/guides/start/quickstart#referred1). ```python -ZITADEL_DOMAIN = "https://your-domain-abcdef.zitadel.cloud" +ZITADEL_DOMAIN = "https://custom-domain-abcdef.zitadel.cloud" CLIENT_ID = "197....@projectname" CLIENT_SECRET = "NVAp70IqiGmJldbS...." ``` diff --git a/docs/docs/guides/integrate/identity-providers/_custom_login_policy.mdx b/docs/docs/guides/integrate/identity-providers/_custom_login_policy.mdx index cf695df454..4303680869 100644 --- a/docs/docs/guides/integrate/identity-providers/_custom_login_policy.mdx +++ b/docs/docs/guides/integrate/identity-providers/_custom_login_policy.mdx @@ -1,6 +1,6 @@ 1. Go to the Settings - - To allow external IdP logins by default, go to your instance default settings at `$YOUR-DOMAIN/ui/console/instance?id=general` - - To allow external IdP logins on an organization, go to `$YOUR-DOMAIN/ui/console/org-settings?id=login` and ensure you have the right org context. + - To allow external IdP logins by default, go to your instance default settings at `${CUSTOM_DOMAIN}/ui/console/instance?id=general` + - To allow external IdP logins on an organization, go to `${CUSTOM_DOMAIN}/ui/console/org-settings?id=login` and ensure you have the right org context. 2. Modify your login policy in the menu "Login Behavior and Security" 3. Enable the attribute "External Login allowed" diff --git a/docs/docs/guides/integrate/identity-providers/introduction.md b/docs/docs/guides/integrate/identity-providers/introduction.md index 628b91a40b..6d434a8004 100644 --- a/docs/docs/guides/integrate/identity-providers/introduction.md +++ b/docs/docs/guides/integrate/identity-providers/introduction.md @@ -85,8 +85,8 @@ In ZITADEL, you have the flexibility to link an external Identity Provider (IdP) The login policy can be set as a default at the instance level and can be customized for each organization. The configuration process varies slightly depending on your focus: -- **For default settings**, navigate to: `$YOUR-DOMAIN/ui/console/instance?id=general` -- **For specific organization settings**, select the organization from the menu and visit: `$YOUR-DOMAIN/ui/console/org-settings?id=login` +- **For default settings**, navigate to: `${CUSTOM_DOMAIN}/ui/console/instance?id=general` +- **For specific organization settings**, select the organization from the menu and visit: `${CUSTOM_DOMAIN}/ui/console/org-settings?id=login` Once in the settings: diff --git a/docs/docs/guides/integrate/identity-providers/linkedin_oauth.mdx b/docs/docs/guides/integrate/identity-providers/linkedin_oauth.mdx index 5709c4e321..6bc9d200fd 100644 --- a/docs/docs/guides/integrate/identity-providers/linkedin_oauth.mdx +++ b/docs/docs/guides/integrate/identity-providers/linkedin_oauth.mdx @@ -23,7 +23,7 @@ import TestSetup from './_test_setup.mdx'; 2. Add your App Name, your Company Page and a Logo 3. Add "Sign In with LinkedIn using OpenID Connect" by clicking "Request access" 4. Go to the Auth Settings of the App and add the following URL to the "Authorized redirect URLs" - - `{your_domain}/ui/login/login/externalidp/callback` + - `${CUSTOM_DOMAIN}/ui/login/login/externalidp/callback` - Example redirect url for the domain `https://acme.zitadel.cloud` would look like this: `https://acme.zitadel.cloud/ui/login/login/externalidp/callback` 5. Verify the app as your company 6. In the Auth - OAuth 2.0 scopes section you should see `openid`, `profile` and `email` listed diff --git a/docs/docs/guides/integrate/login-ui/_list-mfa-options.mdx b/docs/docs/guides/integrate/login-ui/_list-mfa-options.mdx index 0694816238..37c082e47b 100644 --- a/docs/docs/guides/integrate/login-ui/_list-mfa-options.mdx +++ b/docs/docs/guides/integrate/login-ui/_list-mfa-options.mdx @@ -8,7 +8,7 @@ Request Example: ```bash curl --request GET \ - --url https://$ZITADEL_DOMAIN/v2/settings/login \ + --url https://${CUSTOM_DOMAIN}/v2/settings/login \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' ``` diff --git a/docs/docs/guides/integrate/login-ui/_logout.mdx b/docs/docs/guides/integrate/login-ui/_logout.mdx index c4d55fd0f9..c3b4dfaab9 100644 --- a/docs/docs/guides/integrate/login-ui/_logout.mdx +++ b/docs/docs/guides/integrate/login-ui/_logout.mdx @@ -16,7 +16,7 @@ Make sure that the provided token is from the authenticated user, resp. the mana ```bash curl --request DELETE \ - --url https://$ZITADEL_DOMAIN/v2/sessions/218480890961985793 \ + --url https://${CUSTOM_DOMAIN}/v2/sessions/218480890961985793 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' @@ -28,7 +28,7 @@ Send the session token in the body of the request: ```bash curl --request DELETE \ - --url https://$ZITADEL_DOMAIN/v2/sessions/218480890961985793 \ + --url https://${CUSTOM_DOMAIN}/v2/sessions/218480890961985793 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ diff --git a/docs/docs/guides/integrate/login-ui/_select-account.mdx b/docs/docs/guides/integrate/login-ui/_select-account.mdx index 44df859426..5d831b6d96 100644 --- a/docs/docs/guides/integrate/login-ui/_select-account.mdx +++ b/docs/docs/guides/integrate/login-ui/_select-account.mdx @@ -9,7 +9,7 @@ The list of session IDs can be sent in the “search sessions” request to get ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/sessions/search \ + --url https://${CUSTOM_DOMAIN}/v2/sessions/search \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ diff --git a/docs/docs/guides/integrate/login-ui/_update_session_webauthn.mdx b/docs/docs/guides/integrate/login-ui/_update_session_webauthn.mdx index 7a00d006a8..c6288779ea 100644 --- a/docs/docs/guides/integrate/login-ui/_update_session_webauthn.mdx +++ b/docs/docs/guides/integrate/login-ui/_update_session_webauthn.mdx @@ -8,7 +8,7 @@ Example Request: ```bash curl --request PATCH \ - --url https://$ZITADEL_DOMAIN/v2/sessions/218480890961985793 \ + --url https://${CUSTOM_DOMAIN}/v2/sessions/218480890961985793 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ diff --git a/docs/docs/guides/integrate/login-ui/device-auth.mdx b/docs/docs/guides/integrate/login-ui/device-auth.mdx index 32984a17ff..6e2585b391 100644 --- a/docs/docs/guides/integrate/login-ui/device-auth.mdx +++ b/docs/docs/guides/integrate/login-ui/device-auth.mdx @@ -76,7 +76,7 @@ With the user_code entered by the user you will now be able to get the informati ```bash curl --request GET \ - --url https://$ZITADEL_DOMAIN/v2/oidc/device_authorization/FWRK-JGWK \ + --url https://${CUSTOM_DOMAIN}/v2/oidc/device_authorization/FWRK-JGWK \ --header 'Authorization: Bearer '"$TOKEN"'' ``` @@ -122,7 +122,7 @@ Read more about the [Authorize or Deny Device Authorization Request Documentatio Make sure that the authorization header is from an account which is permitted to finalize the Auth Request through the `IAM_LOGIN_CLIENT` role. ```bash curl --request POST \ - --url $ZITADEL_DOMAIN/v2/oidc/device_authorization/XzNejv6NxqVU8Qur5uxEh7f_Wi1p0qUu4PJTJ6JUIx0xtJ2uqmU \ + --url ${CUSTOM_DOMAIN}/v2/oidc/device_authorization/XzNejv6NxqVU8Qur5uxEh7f_Wi1p0qUu4PJTJ6JUIx0xtJ2uqmU \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ @@ -142,7 +142,7 @@ If the user denies the device authorization request, you can deny the request by ```bash curl --request POST \ - --url $ZITADEL_DOMAIN/v2/oidc/device_authorization/ \ + --url ${CUSTOM_DOMAIN}/v2/oidc/device_authorization/ \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ diff --git a/docs/docs/guides/integrate/login-ui/external-login.mdx b/docs/docs/guides/integrate/login-ui/external-login.mdx index 6775d2cb3b..98458884fa 100644 --- a/docs/docs/guides/integrate/login-ui/external-login.mdx +++ b/docs/docs/guides/integrate/login-ui/external-login.mdx @@ -27,7 +27,7 @@ In the response, you will get an authentication URL of the provider you like. ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/idp_intents \ + --url https://${CUSTOM_DOMAIN}/v2/idp_intents \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ @@ -49,7 +49,7 @@ curl --request POST \ "changeDate": "2023-06-14T12:51:29.654819Z", "resourceOwner": "163840776835432705" }, - "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=Test&prompt=select_account&redirect_uri=https%3A%2F%2F$ZITADEL_DOMAIN%2Fidps%2Fcallback&response_type=code&scope=openid+profile+email&state=218525066445455617" + "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=Test&prompt=select_account&redirect_uri=https%3A%2F%2F${CUSTOM_DOMAIN}%2Fidps%2Fcallback&response_type=code&scope=openid+profile+email&state=218525066445455617" } ``` @@ -59,13 +59,13 @@ The next step is to call the auth URL you got in the response from the previous This will open up the login page of the given provider. In this guide, it is Google Login. ```bash -https://accounts.google.com/o/oauth2/v2/auth?client_id=Test&prompt=select_account&redirect_uri=https%3A%2F%2F$ZITADEL_DOMAIN%2Fidps%2Fcallback&response_type=code&scope=openid+profile+email&state=218525066445455617 +https://accounts.google.com/o/oauth2/v2/auth?client_id=Test&prompt=select_account&redirect_uri=https%3A%2F%2F${CUSTOM_DOMAIN}%2Fidps%2Fcallback&response_type=code&scope=openid+profile+email&state=218525066445455617 ``` After the user has successfully authenticated, a redirect to the ZITADEL backend /idps/callback will automatically be performed. :::warning -Note that the redirect URL is `https://{YOUR-DOMAIN}/idps/callback` when using the new V2 hosted login compared to the V1 hosted login, which was `https://{YOUR-DOMAIN}/ui/login/login/externalidp/callback`. +Note that the redirect URL is `https://${CUSTOM_DOMAIN}/idps/callback` when using the new V2 hosted login compared to the V1 hosted login, which was `https://${CUSTOM_DOMAIN}/ui/login/login/externalidp/callback`. ::: ## Get Provider Information @@ -79,7 +79,7 @@ To get the information of the provider, make a request to ZITADEL. ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/idp_intents/$INTENT_ID \ + --url https://${CUSTOM_DOMAIN}/v2/idp_intents/$INTENT_ID \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ @@ -138,7 +138,7 @@ This check requires that the previous step ended on the successful page and didn ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/sessions \ + --url https://${CUSTOM_DOMAIN}/v2/sessions \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ @@ -170,7 +170,7 @@ The display name is used to list the linkings on the users. ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/human \ + --url https://${CUSTOM_DOMAIN}/v2/users/human \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ @@ -209,7 +209,7 @@ If you want to link/connect to an existing account you can perform the add ident ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/users/218385419895570689/links \ + --url https://${CUSTOM_DOMAIN}/v2/users/users/218385419895570689/links \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ diff --git a/docs/docs/guides/integrate/login-ui/mfa.mdx b/docs/docs/guides/integrate/login-ui/mfa.mdx index 09046a2506..7814df1efd 100644 --- a/docs/docs/guides/integrate/login-ui/mfa.mdx +++ b/docs/docs/guides/integrate/login-ui/mfa.mdx @@ -41,7 +41,7 @@ Request Example: ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/totp \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/totp \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' --header 'Content-Type: application/json' \ @@ -73,7 +73,7 @@ Request Example: ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/totp/verify \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/totp/verify \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' --header 'Content-Type: application/json' \ @@ -99,7 +99,7 @@ Example Request ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/sessions \ + --url https://${CUSTOM_DOMAIN}/v2/sessions \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -136,7 +136,7 @@ More detailed information about the API: [Update session Documentation](/apis/re Example Request ```bash curl --request PATCH \ - --url https://$ZITADEL_DOMAIN/v2/sessions/$SESSION-ID \ + --url https://${CUSTOM_DOMAIN}/v2/sessions/$SESSION-ID \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ @@ -175,7 +175,7 @@ Example Request: ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER-ID/phone \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER-ID/phone \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -195,7 +195,7 @@ More detailed information about the API: [Verify phone](/apis/resources/user_ser Example Request: ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER-ID/phone/verify \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER-ID/phone/verify \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -213,7 +213,7 @@ More detailed information about the API: [Add OTP SMS for a user](/apis/resource Example Request: ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER-ID/otp_sms \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER-ID/otp_sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' @@ -237,7 +237,7 @@ Example Request ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/sessions \ + --url https://${CUSTOM_DOMAIN}/v2/sessions \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -264,7 +264,7 @@ Example Request ```bash curl --request PATCH \ - --url https://$ZITADEL_DOMAIN/v2/sessions/225307381909694507 \ + --url https://${CUSTOM_DOMAIN}/v2/sessions/225307381909694507 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -301,7 +301,7 @@ More detailed information about the API: [Add OTP Email for a user](/apis/resour Example Request: ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER-ID/otp_email \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER-ID/otp_email \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' @@ -325,7 +325,7 @@ Example Request ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/sessions \ + --url https://${CUSTOM_DOMAIN}/v2/sessions \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -352,7 +352,7 @@ Example Request ```bash curl --request PATCH \ - --url https://$ZITADEL_DOMAIN/v2/sessions/225307381909694507 \ + --url https://${CUSTOM_DOMAIN}/v2/sessions/225307381909694507 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -386,7 +386,7 @@ Request Example: ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/u2f \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/u2f \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' --header 'Content-Type: application/json' \ @@ -457,7 +457,7 @@ Example Request: ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/u2f/$PASSKEY_ID \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/u2f/$PASSKEY_ID \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ @@ -497,7 +497,7 @@ Example Request ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/sessions \ + --url https://${CUSTOM_DOMAIN}/v2/sessions \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -510,7 +510,7 @@ curl --request POST \ "metadata": {}, "challenges": { "webAuthN": { - "domain": "YOUR-Domain", + "domain": "CUSTOM_DOMAIN", "userVerificationRequirement": "USER_VERIFICATION_REQUIREMENT_DISCOURAGED" } } diff --git a/docs/docs/guides/integrate/login-ui/oidc-standard.mdx b/docs/docs/guides/integrate/login-ui/oidc-standard.mdx index 92068e5116..a8f19c9edf 100644 --- a/docs/docs/guides/integrate/login-ui/oidc-standard.mdx +++ b/docs/docs/guides/integrate/login-ui/oidc-standard.mdx @@ -55,7 +55,7 @@ With the ID from the redirect before you will now be able to get the information ```bash curl --request GET \ - --url https://$ZITADEL_DOMAIN/v2/oidc/auth_requests/V2_224908753244265546 \ + --url https://${CUSTOM_DOMAIN}/v2/oidc/auth_requests/V2_224908753244265546 \ --header 'Authorization: Bearer '"$TOKEN"'' ``` @@ -100,7 +100,7 @@ Read more about the [Finalize Auth Request Documentation](/docs/apis/resources/o Make sure that the authorization header is from an account which is permitted to finalize the Auth Request through the `IAM_LOGIN_CLIENT` role. ```bash curl --request POST \ - --url $ZITADEL_DOMAIN/v2/oidc/auth_requests/V2_224908753244265546 \ + --url ${CUSTOM_DOMAIN}/v2/oidc/auth_requests/V2_224908753244265546 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ diff --git a/docs/docs/guides/integrate/login-ui/passkey.mdx b/docs/docs/guides/integrate/login-ui/passkey.mdx index 9260b90f74..4e2dd09574 100644 --- a/docs/docs/guides/integrate/login-ui/passkey.mdx +++ b/docs/docs/guides/integrate/login-ui/passkey.mdx @@ -34,7 +34,7 @@ Send either the sendLink or the returnCode (empty message) in the request body, ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/passkeys/registration_link \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/passkeys/registration_link \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ @@ -81,7 +81,7 @@ The code only has to be filled if the user did get a registration code. ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/passkeys \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/passkeys \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ @@ -185,7 +185,7 @@ Example Request: ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/passkeys/$PASSKEY_ID \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/passkeys/$PASSKEY_ID \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ @@ -223,7 +223,7 @@ More detailed information about the API: [Create Session Documentation](/apis/re Example Request: ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/sessions \ + --url https://${CUSTOM_DOMAIN}/v2/sessions \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ diff --git a/docs/docs/guides/integrate/login-ui/password-reset.mdx b/docs/docs/guides/integrate/login-ui/password-reset.mdx index fd5028b2c2..0241877612 100644 --- a/docs/docs/guides/integrate/login-ui/password-reset.mdx +++ b/docs/docs/guides/integrate/login-ui/password-reset.mdx @@ -29,7 +29,7 @@ Make sure to also include the URL Template to customize the reset link in the em ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/password_reset \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/password_reset \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -48,7 +48,7 @@ Send the request with asking for the return Code in the body of the request. #### Request ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/password_reset \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/password_reset \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -96,7 +96,7 @@ In this case it requires additionally the current password instead of the verifi ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/password \ + --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/password \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ diff --git a/docs/docs/guides/integrate/login-ui/saml-standard.mdx b/docs/docs/guides/integrate/login-ui/saml-standard.mdx index 5196f6c81a..4bef906e75 100644 --- a/docs/docs/guides/integrate/login-ui/saml-standard.mdx +++ b/docs/docs/guides/integrate/login-ui/saml-standard.mdx @@ -55,7 +55,7 @@ With the ID from the redirect before you will now be able to get the information ```bash curl --request GET \ - --url https://$ZITADEL_DOMAIN/v2/saml/saml_requests/V2_224908753244265546 \ + --url https://${CUSTOM_DOMAIN}/v2/saml/saml_requests/V2_224908753244265546 \ --header 'Authorization: Bearer '"$TOKEN"'' ``` @@ -97,7 +97,7 @@ Read more about the [Finalize SAML Request Documentation](/docs/apis/resources/s Make sure that the authorization header is from an account which is permitted to finalize the SAML Request through the `IAM_LOGIN_CLIENT` role. ```bash curl --request POST \ - --url $ZITADEL_DOMAIN/v2/saml/saml_requests/V2_224908753244265546 \ + --url ${CUSTOM_DOMAIN}/v2/saml/saml_requests/V2_224908753244265546 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ diff --git a/docs/docs/guides/integrate/login-ui/username-password.mdx b/docs/docs/guides/integrate/login-ui/username-password.mdx index 8f796e48c9..bcb7e9b7c8 100644 --- a/docs/docs/guides/integrate/login-ui/username-password.mdx +++ b/docs/docs/guides/integrate/login-ui/username-password.mdx @@ -23,7 +23,7 @@ Read more about the metadata [here](/docs/guides/manage/customize/user-metadata) ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/users/human \ + --url https://${CUSTOM_DOMAIN}/v2/users/human \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -111,7 +111,7 @@ Send it to the Get Session Endpoint to find out how the user has authenticated. ```bash curl --request POST \ - --url https://$ZITADEL_DOMAIN/v2/sessions \ + --url https://${CUSTOM_DOMAIN}/v2/sessions \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"'' \ --header 'Content-Type: application/json' \ @@ -176,7 +176,7 @@ To update an existing session, add the session ID you got in the previous step t ```bash curl --request PATCH \ - --url https://$ZITADEL_DOMAIN/v2/sessions/$SESSION_ID \ + --url https://${CUSTOM_DOMAIN}/v2/sessions/$SESSION_ID \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '"$TOKEN"''\ --header 'Content-Type: application/json' \ diff --git a/docs/docs/guides/integrate/login/hosted-login.mdx b/docs/docs/guides/integrate/login/hosted-login.mdx index 09fb86f8f0..a9ed18c380 100644 --- a/docs/docs/guides/integrate/login/hosted-login.mdx +++ b/docs/docs/guides/integrate/login/hosted-login.mdx @@ -180,7 +180,7 @@ Your contributions will play a crucial role in shaping the future of our login s #### Step-by-step Guide -**Trying out the new login:** To preview the new login without changing your current setup, the easiest way is to visit `https:///ui/v2/login` on your Zitadel Cloud instance domain. You can also activate the v2 login for your apps, so users are redirected to `/ui/v2/login` for authentication. +**Trying out the new login:** To preview the new login without changing your current setup, the easiest way is to visit `https:///ui/v2/login` on your Zitadel Cloud custom domain. You can also activate the v2 login for your apps, so users are redirected to `/ui/v2/login` for authentication. **Customizing the new login:** The easiest way to actually customizing it is to fork the https://github.com/zitadel/typescript repo and use the "Deploy" button to run your code on Vercel. @@ -202,7 +202,7 @@ Your contributions will play a crucial role in shaping the future of our login s The simplest way to deploy the new login for yourself is by using the [“Deploy” button in our repository](https://github.com/zitadel/typescript?tab=readme-ov-file#deploy-to-vercel) to deploy the login directly to your Vercel. 1. [Create a service user](https://zitadel.com/docs/guides/integrate/service-users/personal-access-token#create-a-service-user-with-a-pat) with a PAT in your instance - 2. Give the user IAM_LOGIN_CLIENT Permissions in the default settings (YOUR_DOMAIN/ui/console/instance?id=organizations) + 2. Give the user IAM_LOGIN_CLIENT Permissions in the default settings (CUSTOM_DOMAIN/ui/console/instance?id=organizations) Note: [Zitadel Manager Guide](https://zitadel.com/docs/guides/manage/console/managers) 3. Deploy login to Vercel: You can do so by directly clicking the [“Deploy” button](https://github.com/zitadel/typescript?tab=readme-ov-file#deploy-to-vercel) at the bottom of the readme in our [repository](https://github.com/zitadel/typescript) 4. If you have used the deploy button in the steps before, you will automatically be asked for this step. Enter the environment variables in Vercel @@ -226,7 +226,7 @@ Your contributions will play a crucial role in shaping the future of our login s As this feature is currently in Beta, please be aware of some potential workarounds and important considerations before implementation. - **Create Users:** The new typescript login is built with the session and the user V2 API, the users V2 API does have some differences to the v1 API, so make sure you create users through the new API. -- **External IDPs:** If you want to use external identity provider login, such as Login with Google or Apple. You can follow our existing setup guides, just make sure to use the following redirect url: $YOUR-DOMAIN/idps/callback +- **External IDPs:** If you want to use external identity provider login, such as Login with Google or Apple. You can follow our existing setup guides, just make sure to use the following redirect url: `${CUSTOM_DOMAIN}/idps/callback` - **Passkey/U2F:** Those authentication methods are bound to a domain. As your new login runs on a different domain than the previous login, existing passwordless authentication and u2f (fingerprint, face id, etc.) can’t be used. Also when they are managed through the management console of ZITADEL, they are added on a different domain.
*Note: If you run the login on a subdomain of your current instance, this problem diff --git a/docs/docs/guides/integrate/login/oidc/authmethods/_basic.mdx b/docs/docs/guides/integrate/login/oidc/authmethods/_basic.mdx index 4833ae29a5..06ddc62332 100644 --- a/docs/docs/guides/integrate/login/oidc/authmethods/_basic.mdx +++ b/docs/docs/guides/integrate/login/oidc/authmethods/_basic.mdx @@ -60,7 +60,7 @@ So check [Client Secret Basic Auth Method](/apis/openidoauth/authn-methods#clien ```curl curl --request POST \ ---url {your-domain}/oauth/v2/token \ +--url ${CUSTOM_DOMAIN}/oauth/v2/token \ --header 'Authorization: Basic ${basic}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=authorization_code \ diff --git a/docs/docs/guides/integrate/login/oidc/authmethods/_jwtpk.mdx b/docs/docs/guides/integrate/login/oidc/authmethods/_jwtpk.mdx index 9efd8188ae..63b462379a 100644 --- a/docs/docs/guides/integrate/login/oidc/authmethods/_jwtpk.mdx +++ b/docs/docs/guides/integrate/login/oidc/authmethods/_jwtpk.mdx @@ -62,7 +62,7 @@ for us to validate the signature against the registered public key: ```curl curl --request POST \ ---url {your-domain}/oauth/v2/token \ +--url ${CUSTOM_DOMAIN}/oauth/v2/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=authorization_code \ --data code=${code} \ diff --git a/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx b/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx index aea1256bbc..ea1a2522d2 100644 --- a/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx +++ b/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx @@ -67,7 +67,7 @@ Send your `client_id` and the previously generated string as `code_verifier` for ```curl curl --request POST \ ---url {your-domain}/oauth/v2/token \ +--url ${CUSTOM_DOMAIN}/oauth/v2/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=authorization_code \ --data code=${code} \ diff --git a/docs/docs/guides/integrate/login/oidc/authmethods/_pkcenative.mdx b/docs/docs/guides/integrate/login/oidc/authmethods/_pkcenative.mdx index 2fd5f9f13a..0c4a1f8acf 100644 --- a/docs/docs/guides/integrate/login/oidc/authmethods/_pkcenative.mdx +++ b/docs/docs/guides/integrate/login/oidc/authmethods/_pkcenative.mdx @@ -53,7 +53,7 @@ Send your `client_id` and the previously generated string as `code_verifier` for ```curl curl --request POST \ ---url {your-domain}/oauth/v2/token \ +--url ${CUSTOM_DOMAIN}/oauth/v2/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=authorization_code \ --data code=${code} \ diff --git a/docs/docs/guides/integrate/login/oidc/webkeys.md b/docs/docs/guides/integrate/login/oidc/webkeys.md index 288284fefc..e4099c98c9 100644 --- a/docs/docs/guides/integrate/login/oidc/webkeys.md +++ b/docs/docs/guides/integrate/login/oidc/webkeys.md @@ -296,7 +296,7 @@ Next month, Key ID 6 will be activated, an new key added and Key ID 2 can be del ## JSON web key set The JSON web key set (JWKS) endpoint serves all available public keys for the instance on -`{your_domain}/oauth/v2/keys`. This includes activated, newly non-activated and deactivated web keys. The response format is defined in [RFC7517, section 5: JWK Set Format](https://www.rfc-editor.org/rfc/rfc7517#section-5). +`${CUSTOM_DOMAIN}/oauth/v2/keys`. This includes activated, newly non-activated and deactivated web keys. The response format is defined in [RFC7517, section 5: JWK Set Format](https://www.rfc-editor.org/rfc/rfc7517#section-5). And looks like: diff --git a/docs/docs/guides/integrate/retrieve-user-roles.md b/docs/docs/guides/integrate/retrieve-user-roles.md index cf69a18546..ad5aba168a 100644 --- a/docs/docs/guides/integrate/retrieve-user-roles.md +++ b/docs/docs/guides/integrate/retrieve-user-roles.md @@ -83,7 +83,7 @@ Alternatively, you can include the claims `urn:iam:org:project:roles` or/and `ur ### Retrieve roles from the userinfo endpoint -The user info endpoint is **$CUSTOM-DOMAIN/oidc/v1/userinfo**. +The user info endpoint is **`${CUSTOM_DOMAIN}`/oidc/v1/userinfo**. This endpoint will return information about the authenticated user. Send the access token of the user as `Bearer Token` in the `Authorization` header: @@ -91,7 +91,7 @@ Send the access token of the user as `Bearer Token` in the `Authorization` heade **cURL Request:** ```bash curl --request GET \ - --url $CUSTOM-DOMAIN/oidc/v1/userinfo + --url ${CUSTOM_DOMAIN}/oidc/v1/userinfo --header 'Authorization: Bearer ' ``` @@ -208,7 +208,7 @@ https://github.com/zitadel/actions/blob/main/examples/custom_roles.js ### Retrieve roles using the auth API Now we will use the auth API to retrieve roles from a logged in user using the user’s token -The base URL is: **https://$ZITADEL_DOMAIN/auth/v1** +The base URL is: **https://`${CUSTOM_DOMAIN}`/auth/v1** Let’s start with a user who has multiple roles in different organizations in a multi-tenanted set up. You can use the logged in user’s token or the machine user’s token to retrieve the authorizations using the [APIs listed under user authorizations/grants in the auth API](/docs/apis/resources/auth/user-authorizations-grants). @@ -219,11 +219,11 @@ Let’s start with a user who has multiple roles in different organizations in a Returns a list of roles for the authenticated user and for the requesting project (based on the token). -**URL: https://$CUSTOM-DOMAIN/auth/v1/permissions/me/_search** +**URL: https://`${CUSTOM_DOMAIN}`/auth/v1/permissions/me/_search** **cURL request:** ```bash -curl -L -X POST 'https://$CUSTOM-DOMAIN/auth/v1/permissions/me/_search' \ +curl -L -X POST 'https://${CUSTOM_DOMAIN}/auth/v1/permissions/me/_search' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer ' ``` @@ -244,12 +244,12 @@ Returns a list of permissions the authenticated user has in ZITADEL based on the This request can be used if you are building a management UI. For instance, if the UI is managing users, you can show the management functionality based on the permissions the user has. Here’s an example: if the user has `user.read` and `user.write` permission you can show the edit buttons, if the user only has `user.read` permission, you can hide the edit buttons. -**URL: https://$CUSTOM-DOMAIN/auth/v1/permissions/zitadel/me/_search** +**URL: https://`${CUSTOM_DOMAIN}`/auth/v1/permissions/zitadel/me/_search** **cURL Request:** ```bash -curl -L -X POST 'https://$CUSTOM-DOMAIN/auth/v1/permissions/zitadel/me/_search' \ +curl -L -X POST 'https://${CUSTOM_DOMAIN}/auth/v1/permissions/zitadel/me/_search' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer ' ``` @@ -290,12 +290,12 @@ curl -L -X POST 'https://$CUSTOM-DOMAIN/auth/v1/permissions/zitadel/me/_search' Returns a list of user grants the authenticated user has. User grants consist of an organization, a project and roles. -**URL: https://$CUSTOM-DOMAIN/auth/v1/usergrants/me/_search** +**URL: https://`${CUSTOM-DOMAIN}`/auth/v1/usergrants/me/_search** **cURL request:** ```bash -curl -L -X POST 'https://$CUSTOM-DOMAIN/auth/v1/usergrants/me/_search' \ +curl -L -X POST 'https://${CUSTOM_DOMAIN}/auth/v1/usergrants/me/_search' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer ' \ @@ -392,7 +392,7 @@ curl -L -X POST 'https://$CUSTOM-DOMAIN/auth/v1/usergrants/me/_search' \ ### Retrieve roles using the management API Now we will use the management API to retrieve user roles under an admin user. -The base URL is: **https://$CUSTOM-DOMAIN/management/v1** +The base URL is: **https://`${CUSTOM_DOMAIN}`/management/v1** In [APIs listed under user grants in the management API](/docs/apis/resources/mgmt/user-grants), you will see that you can use the management API to retrieve and modify user grants. The two API paths that we are interested in to fetch user roles are given below. @@ -402,12 +402,12 @@ In [APIs listed under user grants in the management API](/docs/apis/resources/mg Returns a list of user roles that match the search queries. A user with manager permissions will call this API and will also have to reside in the same organization as the user. -**URL: https://$CUSTOM-DOMAIN/management/v1/users/grants/_search** +**URL: https://`${CUSTOM_DOMAIN}`/management/v1/users/grants/_search** **cURL request:** ```bash -curl -L -X POST 'https://$CUSTOM-DOMAIN/management/v1/users/grants/_search' \ +curl -L -X POST 'https://${CUSTOM_DOMAIN}/management/v1/users/grants/_search' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer ' \ @@ -471,12 +471,12 @@ curl -L -X POST 'https://$CUSTOM-DOMAIN/management/v1/users/grants/_search' \ Returns a user grant per ID. A user grant is a role a user has for a specific project and organization. -**URL: https://$ZITADEL_DOMAIN//management/v1/users/:userId/grants/:grantId** +**URL: https://`${CUSTOM_DOMAIN}`/management/v1/users/:userId/grants/:grantId** **cURL request:** ```bash -curl -L -X GET 'https://$ZITADEL_DOMAIN/management/v1/users/:userId/grants/:grantId' \ +curl -L -X GET 'https://${CUSTOM_DOMAIN}/management/v1/users/:userId/grants/:grantId' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer ' ``` diff --git a/docs/docs/guides/integrate/services/auth0-oidc.mdx b/docs/docs/guides/integrate/services/auth0-oidc.mdx index ec574dd6d9..b30f8b7823 100644 --- a/docs/docs/guides/integrate/services/auth0-oidc.mdx +++ b/docs/docs/guides/integrate/services/auth0-oidc.mdx @@ -28,7 +28,7 @@ In Authentication > Enterprise 1. Press the "+" button right to "OpenID Connect" ![Create new connection](/img/oidc/auth0/auth0-create-app.png) 2. Set a connection name for example "ZITADEL" -3. The issuer url is `https:///.well-known/openid-configuration` +3. The issuer url is `https://${CUSTOM_DOMAIN}/.well-known/openid-configuration` 4. Copy the callback URL (ending with `/login/callback`) The configuration should look like this: diff --git a/docs/docs/guides/integrate/services/cloudflare-oidc.mdx b/docs/docs/guides/integrate/services/cloudflare-oidc.mdx index cd3624b32f..866196960c 100644 --- a/docs/docs/guides/integrate/services/cloudflare-oidc.mdx +++ b/docs/docs/guides/integrate/services/cloudflare-oidc.mdx @@ -30,7 +30,7 @@ Cloudflare will return an error "User email was not returned. API permissions ar 1. On the Cloudflare dashboard go to Zero Trust, click settings, and then select "Authentication" 2. Add a new login method with the type "OpenID Connect" -3. Fill in the required information. Check the discovery endpoint of your instance `https://{your_domain}/.well-known/openid-configuration` for the urls. As mentioned in the Cloudflare docs the Certificate Url is jwks_uri. +3. Fill in the required information. Check the discovery endpoint of your instance `https://${CUSTOM_DOMAIN}/.well-known/openid-configuration` for the urls. As mentioned in the Cloudflare docs the Certificate Url is jwks_uri. 4. Disable PKCE (Cloudflare requires a client secret for PKCE, which is currently not supported) 5. Add the following claims: "openid", "profile", "email" 6. Test the connection @@ -42,9 +42,9 @@ Cloudflare will return an error "User email was not returned. API permissions ar "config": { "client_id": "", "client_secret": "", - "auth_url": "https://{your_domain}.zitadel.cloud/oauth/v2/authorize", - "token_url": "https://{your_domain}.zitadel.cloud/oauth/v2/token", - "certs_url": "https://{your_domain}.zitadel.cloud/oauth/v2/keys", + "auth_url": "https://${CUSTOM_DOMAIN}.zitadel.cloud/oauth/v2/authorize", + "token_url": "https://${CUSTOM_DOMAIN}.zitadel.cloud/oauth/v2/token", + "certs_url": "https://${CUSTOM_DOMAIN}.zitadel.cloud/oauth/v2/keys", "scopes": ["openid", "email", "profile"], "pkce_enabled": false, }, diff --git a/docs/docs/guides/integrate/services/gitlab-self-hosted.mdx b/docs/docs/guides/integrate/services/gitlab-self-hosted.mdx index 17e3cc3af6..25b0cf9d68 100644 --- a/docs/docs/guides/integrate/services/gitlab-self-hosted.mdx +++ b/docs/docs/guides/integrate/services/gitlab-self-hosted.mdx @@ -36,12 +36,12 @@ gitlab_rails['omniauth_providers'] = [ { name: "openid_connect", label: "ZITADEL", - icon: "https:///ui/console/assets/icons/favicon-32x32.png", + icon: "https://${CUSTOM_DOMAIN}/ui/console/assets/icons/favicon-32x32.png", args: { name: "openid_connect", scope: ["openid","profile","email"], response_type: "code", - issuer: "https://", + issuer: "https://${CUSTOM_DOMAIN}", discovery: true, client_options: { identifier: "", diff --git a/docs/docs/guides/integrate/services/google-workspace.md b/docs/docs/guides/integrate/services/google-workspace.md index 14c9aba524..b2f4444481 100644 --- a/docs/docs/guides/integrate/services/google-workspace.md +++ b/docs/docs/guides/integrate/services/google-workspace.md @@ -33,25 +33,25 @@ Open the Google settings for [SSO with third-party IdP](https://admin.google.com ![SSO with third-party IdP](/img/guides/integrate/services/google-workspace-sso-overview.png) -Download the public certificate from your ZITADEL instance by requesting `$YOUR_DOMAIN/saml/v2/certificate` +Download the public certificate from your ZITADEL instance by requesting `${CUSTOM_DOMAIN}/saml/v2/certificate` ```bash - wget $YOUR_DOMAIN/saml/v2/certificate -O idp.crt + wget ${CUSTOM_DOMAIN}/saml/v2/certificate -O idp.crt ``` -Always replace `$YOUR_DOMAIN` with your instance domain. +Always replace `${CUSTOM_DOMAIN}` with your custom domain. Use the following configuration | Setting | Value | | --- | --- | | Set up SSO with third-party identity provider | Enable (check) | -| Sign-in page URL | $YOUR_DOMAIN/saml/v2/SSO | -| Sign-out page URL | $YOUR_DOMAIN/saml/v2/SLO | +| Sign-in page URL | `${CUSTOM_DOMAIN}`/saml/v2/SSO | +| Sign-out page URL | `${CUSTOM_DOMAIN}`/saml/v2/SLO | | Verification Certificate | Upload the certificate (idp.crt) | | Use a domain-specific issuer | Enable (check) | | Network masks | Leave blank| -| Change password URL | $YOUR_DOMAIN/ui/console/users/me?id=security | +| Change password URL | `${CUSTOM_DOMAIN}`/ui/console/users/me?id=security | ### Create a SAML application in ZITADEL @@ -125,7 +125,7 @@ Download the public certificate from your ZITADEL instance by requesting `$YOUR_ wget $YOUR_DOMAIN/saml/v2/certificate -O idp.crt ``` -Always replace `$YOUR_DOMAIN` with your instance domain. +Always replace `$YOUR_DOMAIN` with your custom domain. Use the following configuration diff --git a/docs/docs/guides/integrate/token-introspection/basic-auth.mdx b/docs/docs/guides/integrate/token-introspection/basic-auth.mdx index 6beb244ed0..1845b38574 100644 --- a/docs/docs/guides/integrate/token-introspection/basic-auth.mdx +++ b/docs/docs/guides/integrate/token-introspection/basic-auth.mdx @@ -78,7 +78,7 @@ The request from the API to the introspection endpoint should be in the followin ```bash curl --request POST \ - --url {your_domain}/oauth/v2/introspect \ + --url ${CUSTOM_DOMAIN}/oauth/v2/introspect \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic {your_basic_auth_header}' \ --data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn... diff --git a/docs/docs/guides/integrate/token-introspection/private-key-jwt.mdx b/docs/docs/guides/integrate/token-introspection/private-key-jwt.mdx index 57fa4abd31..6b74e606f4 100644 --- a/docs/docs/guides/integrate/token-introspection/private-key-jwt.mdx +++ b/docs/docs/guides/integrate/token-introspection/private-key-jwt.mdx @@ -135,7 +135,7 @@ Payload: { "iss": "78366401571920522@acme", (clientId from your key file) "sub": "78366401571920522@acme", (clientId from your key file) - "aud": "https://{your_domain}", (your ZITADEL domain/issuer URL) + "aud": "https://${CUSTOM_DOMAIN}", (your ZITADEL domain/issuer URL) "exp": 1605183582, (Unix timestamp of the expiry) "iat": 1605179982 (Unix timestamp of the creation signing time of the JWT, MUST NOT be older than 1h) } @@ -146,7 +146,7 @@ Create the JSON Web Token with the above header and payload, and sign it with th The request from the API to the introspection endpoint should be in the following format: ```bash curl --request POST \ - --url {your_domain}/oauth/v2/introspect \ + --url ${CUSTOM_DOMAIN}/oauth/v2/introspect \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \ --data client_assertion=eyJhbGciOiJSUzI1Ni... \ @@ -161,7 +161,7 @@ def introspect_token(self, token_string): payload = { "iss": API_PRIVATE_KEY_FILE["client_id"], "sub": API_PRIVATE_KEY_FILE["client_id"], - "aud": ZITADEL_DOMAIN, + "aud": CUSTOM_DOMAIN, "exp": int(time.time()) + 60 * 60, # Expires in 1 hour "iat": int(time.time()) } diff --git a/docs/docs/guides/integrate/tools/apache2.mdx b/docs/docs/guides/integrate/tools/apache2.mdx index c4cb18c8dd..06bf0c5ffe 100644 --- a/docs/docs/guides/integrate/tools/apache2.mdx +++ b/docs/docs/guides/integrate/tools/apache2.mdx @@ -26,7 +26,7 @@ You can find a minimal configuration in the [official documentation](https://git The following parameters must be set with the values from ZITADEL. ```yaml -OIDCProviderMetadataURL https://.zitadel.cloud/.well-known/openid-configuration +OIDCProviderMetadataURL https://${CUSTOM_DOMAIN}/.well-known/openid-configuration OIDCClientID # OIDCRedirectURI is a vanity URL that must point to a path protected by this module but must NOT point to any content OIDCRedirectURI @@ -40,7 +40,7 @@ With the following parameters | Parameter | Description | Example value| |---|---|---| -| OIDCProviderMetadataURL | Is the url to the discovery endpoint, which is typically located at `{your-domain}/.well-known/openid-configuration`| `https://.zitadel.cloud/.well-known/openid-configuration` | +| OIDCProviderMetadataURL | Is the url to the discovery endpoint | `https://${CUSTOM_DOMAIN}/.well-known/openid-configuration` | | OIDCClientID | Is the ID of the zitadel application. You can find it on the settings page of the application. | 123456789123@apache_test | | OIDCRedirectURI | Users will be redirected to this page after successful login. If you are using localhost or any other non-https endpoint, make sure to enable development mode in ZITADEL. | https://mysecureapp.io/secure/callback | | OIDCCryptoPassphrase | Create a secure passphrase. Consult the module's documentation for more details. | ... | diff --git a/docs/docs/guides/manage/console/default-settings.mdx b/docs/docs/guides/manage/console/default-settings.mdx index f255d15d93..896aa30a02 100644 --- a/docs/docs/guides/manage/console/default-settings.mdx +++ b/docs/docs/guides/manage/console/default-settings.mdx @@ -149,7 +149,7 @@ The Login Policy defines how the login process should look like and which authen The Default Redirect URI will be used, if a user calls the login page directly. More specifically, typically a client will initiate login with an auth request. The auth request contains a client-id and a redirect uri, that must match the configuration in ZITADEL. -If there is no [auth request](https://zitadel.com/playgrounds/oidc), users will be redirected to the Default Redirect URI, which is by default `https:///ui/console/` +If there is no [auth request](https://zitadel.com/playgrounds/oidc), users will be redirected to the Default Redirect URI, which is by default `https://${CUSTOM_DOMAIN}/ui/console/` Reasons why ZITADEL doesn't have a redirect URI: @@ -158,7 +158,7 @@ Reasons why ZITADEL doesn't have a redirect URI: We recommend setting your own default redirect URI, if you do not want end users to access ZITADEL console. -Change default redirect url of instance: `https:///ui/console/settings?id=login` +Change default redirect url of instance: `https://${CUSTOM_DOMAIN}/ui/console/settings?id=login` Empty Project
- +