From 33316f8e25126ea31c7316f6a00ef1434af60c6d Mon Sep 17 00:00:00 2001 From: brentschaus-okta Date: Mon, 27 Oct 2025 21:35:12 -0400 Subject: [PATCH 1/4] updates --- .../docs/concepts/brands/index.md | 79 ++++++++----------- 1 file changed, 32 insertions(+), 47 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/concepts/brands/index.md b/packages/@okta/vuepress-site/docs/concepts/brands/index.md index 6e96eb5f1be..ec0d792cbc9 100644 --- a/packages/@okta/vuepress-site/docs/concepts/brands/index.md +++ b/packages/@okta/vuepress-site/docs/concepts/brands/index.md @@ -54,20 +54,33 @@ Multibrand orgs have a non-deletable default brand called the subdomain brand. H To use multibrand customization in the Admin Console, see [Branding](https://help.okta.com/okta_help.htm?type=oie&id=csh-branding). -### Use the Brands API +#### User Activation email + +If you try to use the Admin Console to send a branded User Activation email, the default Okta branding is applied. + +To ensure that the activation email is branded, use the [Users API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserLifecycle/#tag/UserLifecycle/operation/activateUser). In your request, change `subdomain.okta.com` to the custom domain associated with the brand. For example, `custom.domain.one`. See [Multibrand and custom domains](#multibrand-and-custom-domains). + +> **Note:** This solution works for Okta customers. If you import users with Active Directory or Human Resources as a Service (HRaaS), it can be difficult to use the API. + +### Use the Customizations APIs There are public APIs and updates to existing APIs for multibrand customization: -- [Domains](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/CustomDomain/) +- [Custom Domains](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/CustomDomain/) - [Email domains](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/EmailDomain/) - [Brands](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Brands/) -- [Loading page](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Themes/#tag/Themes/operation/listBrandThemes) +- [Themes](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Themes/) +- [Loading page](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Themes/#tag/Themes/operation/listBrandThemes!c=200&path=loadingPageTouchPointVariant&t=response) - [Sign-in page code editor and custom labels](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/CustomPages/#tag/CustomPages/operation/getCustomizedSignInPage) - [Error pages](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/CustomPages/#tag/CustomPages/operation/getCustomizedErrorPage) - [Sign-In Widget version](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/CustomPages/#tag/CustomPages/operation/listAllSignInWidgetVersions) -- [Default app for the Sign-In Widget](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Brands/#tag/Brands/operation/listBrands) +- [Default app for the Sign-In Widget](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Brands/#tag/Brands/operation/listBrands!c=200&path=defaultApp&t=response) - [Sign-out page](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/CustomPages/#tag/CustomPages/operation/getSignOutPageSettings) -- [Brand locale](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Brands/#tag/Brands/operation/listBrands) +- [Brand locale](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Brands/#tag/Brands/operation/listBrands!c=200&path=locale&t=response) + +### Default brand sign-in page and error page + +With multibrand customizations enabled, you can't update the default brand's sign-in page or error page HTML content. The API returns a 403 HTTP status message. See [About subdomain brands and custom brands](#about-subdomain-brands-and-custom-brands). ### Multibrand and resource sets @@ -88,6 +101,19 @@ If you want to use the Admin Console to send a branded email, consider the follo - Your theming appears in the content of the email (logo, palette, images). With a single custom brand or domain, the Admin Console assumes that you want to send themed content. - If your org doesn't have a custom brand, domain, and email address, you can only trigger Okta-branded emails from the Admin Console. +See [About custom email addresses](/docs/guides/custom-url-domain/main/#about-custom-email-addresses). + +#### Email domains + +Keep in mind the following when setting up domains for an org with branded emails: + +- If you don’t have any domains configured, or you have multiple domains configured, the emails use your org’s default brand. See [About subdomain brands versus custom domains](#about-subdomain-brands-and-custom-brands). +- If there's only one domain configured, the emails use the brand associated with that domain. + +#### Email senders + +The main Okta email provider allows you to use each unique email sender (root domain, no-reply@company.com) only once in each cell. To bypass this limitation, use a subdomain to keep email senders unique (for example, no-reply@brandA.company.com and no-reply@brandB.company.com). + ### Multibrand and redirect URIs Multibrand orgs use dynamic issuer mode for IdP. As a result, Okta uses the domain from the authorize request as the domain for the redirect URI when returning the authentication response. The Admin Console UI displays the org's Okta subdomain when the org has multiple custom domains configured. @@ -100,17 +126,7 @@ URIs that you use in the following settings revert to the Okta subdomain: You can replace the base path with a custom domain and Okta uses the brand associated with the domain. -## FAQs - -### How many custom domains per org? - -All paid orgs get a maximum of three custom domains. You can request up to 200 custom domains at no cost. - -### Can all custom domains use Okta-managed certificates? - -Yes. Okta recommends this approach so customers never have to maintain any certificates. - -### How are apps assigned to brands? +### Brands and assigned apps Users are routed to the desired app using the `client_id` in the custom domain as a URL parameter. @@ -125,34 +141,3 @@ In all three cases the user signs in to the same OIDC app, but sees three differ Access management to apps is controlled through app assignments, so any user can still access any app. You can apply any brand to any app. If a custom domain doesn’t contain a `client _id`, Okta routes the user to the default app. - -### Any limitations/assumptions to be aware of? - -#### Email domains - -Keep in mind the following when setting up domains for an org with branded emails: - -- If you don’t have any domains configured, or you have multiple domains configured, the emails use your org’s default brand. See [About subdomain brands versus custom domains](#about-subdomain-brands-and-custom-brands). -- If there's only one domain configured, the emails use the brand associated with that domain. - -#### Email senders - -The main Okta email provider allows you to use each unique email sender (root domain, no-reply@company.com) only once in each cell. To bypass this limitation, use a subdomain to keep email senders unique (for example, no-reply@brandA.company.com and no-reply@brandB.company.com). - -#### User Activation email - -If you try to use the Admin Console to send a branded User Activation email, the default Okta branding is applied. - -To ensure that the activation email is branded, use the [Users API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserLifecycle/#tag/UserLifecycle/operation/activateUser). In your request, change `subdomain.okta.com` to the custom domain associated with the brand. For example, `custom.domain.one`. See [Multibrand and custom domains](#multibrand-and-custom-domains). - -> **Note:** This solution works for Okta customers. If you import users with Active Directory or Human Resources as a Service (HRaaS), it can be difficult to use the API. - -#### Default brand sign-in page and error page - -With multibrand customizations enabled, you can't update the default brand's sign-in page or error page HTML content. The API returns a 403 HTTP status message. See [About subdomain brands and custom brands](#about-subdomain-brands-and-custom-brands). - -#### Data migrations - -- **Flag ON behavior:** Okta migrates any customizations (code, logos, labels) to a newly created brand. This is a one-time migration for only the first time that an org turns on multibrand. - -- **Flag ON/OFF/ON behavior:** Okta doesn't remigrate existing customizations made to the default brand so that customizations don’t overwrite the previously customized brand. From 7a096522fbf283247e0666b67fd896bf722db94a Mon Sep 17 00:00:00 2001 From: brentschaus-okta Date: Mon, 27 Oct 2025 21:39:35 -0400 Subject: [PATCH 2/4] acrolinx --- packages/@okta/vuepress-site/docs/concepts/brands/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/@okta/vuepress-site/docs/concepts/brands/index.md b/packages/@okta/vuepress-site/docs/concepts/brands/index.md index ec0d792cbc9..74392af153d 100644 --- a/packages/@okta/vuepress-site/docs/concepts/brands/index.md +++ b/packages/@okta/vuepress-site/docs/concepts/brands/index.md @@ -94,7 +94,7 @@ Make a custom admin role specific to a brand by using a customization resource t If you want to use the Admin Console to send a branded email, consider the following: - If your org has two or more custom brands, domains, and email addresses: - - You can't send branded emails from the Admin Console. Okta uses the request host in the URL to determine which brand and email address to use, and the console only works with the Okta subdomain. + - You can't send branded emails from the Admin Console. Okta uses the request host in the URL to determine which brand and email address to use. The console only works with the Okta subdomain. - Use an Okta API to trigger the email. To send a User Activation email, send a request to the [Activate a User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserLifecycle/#tag/UserLifecycle/operation/activateUser) endpoint. Remember to change the domain of your request to the custom domain that's associated with the brand. For example, change `subdomain.okta.com` to `custom.domain.one`. - If your org has one custom brand, domain, and email address: - Okta doesn't use your custom email address. The Okta subdomain appears in the *From* line. From 8ff49c13138ebd24b684613c0cffd0cd5825bcf4 Mon Sep 17 00:00:00 2001 From: brentschaus-okta Date: Tue, 28 Oct 2025 12:24:42 -0400 Subject: [PATCH 3/4] heading tweaks --- .../docs/concepts/brands/index.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/concepts/brands/index.md b/packages/@okta/vuepress-site/docs/concepts/brands/index.md index 74392af153d..ddd63cb361d 100644 --- a/packages/@okta/vuepress-site/docs/concepts/brands/index.md +++ b/packages/@okta/vuepress-site/docs/concepts/brands/index.md @@ -50,11 +50,11 @@ You can only visit a branded touchpoint (such as a logo or color) after you map Multibrand orgs have a non-deletable default brand called the subdomain brand. However, you can create several custom brands. The subdomain brand always appears at the Okta subdomain URL and can’t have a custom domain. You can swap out the logo and other assets, but you can’t edit custom code for the sign-in page or error pages. You can only use a custom domain and custom code for sign-in pages and error pages on custom brands. -### Use the Admin Console +## Use the Admin Console To use multibrand customization in the Admin Console, see [Branding](https://help.okta.com/okta_help.htm?type=oie&id=csh-branding). -#### User Activation email +### User Activation email If you try to use the Admin Console to send a branded User Activation email, the default Okta branding is applied. @@ -62,7 +62,7 @@ To ensure that the activation email is branded, use the [Users API](https://deve > **Note:** This solution works for Okta customers. If you import users with Active Directory or Human Resources as a Service (HRaaS), it can be difficult to use the API. -### Use the Customizations APIs +## Use the Customizations APIs There are public APIs and updates to existing APIs for multibrand customization: @@ -78,18 +78,18 @@ There are public APIs and updates to existing APIs for multibrand customization: - [Sign-out page](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/CustomPages/#tag/CustomPages/operation/getSignOutPageSettings) - [Brand locale](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Brands/#tag/Brands/operation/listBrands!c=200&path=locale&t=response) -### Default brand sign-in page and error page +## Default brand sign-in page and error page With multibrand customizations enabled, you can't update the default brand's sign-in page or error page HTML content. The API returns a 403 HTTP status message. See [About subdomain brands and custom brands](#about-subdomain-brands-and-custom-brands). -### Multibrand and resource sets +## Multibrand and resource sets Make a custom admin role specific to a brand by using a customization resource type. See: - [Create a resource set - Okta Identity Engine](https://help.okta.com/okta_help.htm?type=oie&id=ext-create-resource-set) - [Create a resource set - Okta Classic Engine](https://help.okta.com/okta_help.htm?id=ext-create-resource-set) -### Multibrand and emails +## Multibrand and emails If you want to use the Admin Console to send a branded email, consider the following: @@ -103,18 +103,18 @@ If you want to use the Admin Console to send a branded email, consider the follo See [About custom email addresses](/docs/guides/custom-url-domain/main/#about-custom-email-addresses). -#### Email domains +### Email domains Keep in mind the following when setting up domains for an org with branded emails: - If you don’t have any domains configured, or you have multiple domains configured, the emails use your org’s default brand. See [About subdomain brands versus custom domains](#about-subdomain-brands-and-custom-brands). - If there's only one domain configured, the emails use the brand associated with that domain. -#### Email senders +### Email senders The main Okta email provider allows you to use each unique email sender (root domain, no-reply@company.com) only once in each cell. To bypass this limitation, use a subdomain to keep email senders unique (for example, no-reply@brandA.company.com and no-reply@brandB.company.com). -### Multibrand and redirect URIs +## Multibrand and redirect URIs Multibrand orgs use dynamic issuer mode for IdP. As a result, Okta uses the domain from the authorize request as the domain for the redirect URI when returning the authentication response. The Admin Console UI displays the org's Okta subdomain when the org has multiple custom domains configured. @@ -126,7 +126,7 @@ URIs that you use in the following settings revert to the Okta subdomain: You can replace the base path with a custom domain and Okta uses the brand associated with the domain. -### Brands and assigned apps +## Brands and assigned apps Users are routed to the desired app using the `client_id` in the custom domain as a URL parameter. From ab38ba08f5fa0961bcc11633d7df437830b96c2c Mon Sep 17 00:00:00 2001 From: brentschaus-okta Date: Thu, 30 Oct 2025 10:02:33 -0400 Subject: [PATCH 4/4] addresses alex feedback --- packages/@okta/vuepress-site/docs/concepts/brands/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/concepts/brands/index.md b/packages/@okta/vuepress-site/docs/concepts/brands/index.md index ddd63cb361d..01e1957eaaf 100644 --- a/packages/@okta/vuepress-site/docs/concepts/brands/index.md +++ b/packages/@okta/vuepress-site/docs/concepts/brands/index.md @@ -80,7 +80,7 @@ There are public APIs and updates to existing APIs for multibrand customization: ## Default brand sign-in page and error page -With multibrand customizations enabled, you can't update the default brand's sign-in page or error page HTML content. The API returns a 403 HTTP status message. See [About subdomain brands and custom brands](#about-subdomain-brands-and-custom-brands). +With multibrand customizations enabled, you can't update the default brand's sign-in page or error page HTML content. The API returns a 403 HTTP status message. See [Multibrand and custom domains](#multibrand-and-custom-domains). ## Multibrand and resource sets @@ -107,7 +107,7 @@ See [About custom email addresses](/docs/guides/custom-url-domain/main/#about-cu Keep in mind the following when setting up domains for an org with branded emails: -- If you don’t have any domains configured, or you have multiple domains configured, the emails use your org’s default brand. See [About subdomain brands versus custom domains](#about-subdomain-brands-and-custom-brands). +- If you don’t have any domains configured, or you have multiple domains configured, the emails use your org’s default brand. See [Subdomain brands and custom brands](#subdomain-brands-and-custom-brands). - If there's only one domain configured, the emails use the brand associated with that domain. ### Email senders