feat: custom domain concept and howto.

Author: asaf

docs/concepts/custom_domain.md

@@ -0,0 +1,21 @@
+---
+id: custom_domain
+title: Custom Domain
+sidebar_label: Custom Domain
+slug: /concepts/custom-domain
+description: What is a custom domain
+---
+
+A domain translates names into IP addresses, which browsers use to load internet pages. (e.g., "https://crossid.io")
+
+By default login and registration boxes are hosted under the `crossid.io` domain.
+
+Adding a custom domain let you serve the boxes under your own domain.
+
+So instead of a URL such `https://acme.us.crossid.io/auth/login` user will be redirected to `https://acme.io/auth/login`
+
+This has several advantages:
+
+- Branding, your users don't leave your own domain.
+- Easy migration between identity services.
+- Security and cookie data sharing.

docs/guides/howto/custom_domain.md

@@ -0,0 +1,83 @@
+---
+id: custom_domain
+title: Add custom domain.
+sidebar_label: Custom Domain
+slug: /guides/howto/custom_domain
+description: How to add a custom domain.
+---
+
+A [Custom Domain](/docs/concepts/custom-domain) let you serve login under your own domain.
+
+This page explains how to add a custom domain.
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+## Add the domain
+
+<Tabs
+defaultValue="console"
+values={[
+{label: 'Console', value: 'console'},
+]}>
+<TabItem value="console">
+
+1. In Admin console, navigate to **Branding &rarr; Domains**.
+1. Click on **Add Integration**.
+1. In the DNS record, put your chosen custom domain.
+   For example: _auth.acme.io_
+1. Click the **Add** button.
+
+</TabItem>
+</Tabs>
+
+## Domain validation
+
+For security reasons, we have to ensure that you own the domain,
+This requires you to add a TXT record with the given details in your domain entries.
+
+<img src="/img/howto/customdomain_dns_record.png" width="60%"/><br/><br/>
+
+(See below if your DNS provider is Godaddy)
+
+After adding the DNS record, click the **Verify Domain** button.
+
+The domain should be in a _verified_ state.
+
+![verified](/img/howto/customdomain_verified.png)
+
+## Certificate deployment
+
+For SSL to work, a certificate (with its key) should be provided,
+
+Issuing a certificate is beyond the scope of this tutorial.
+
+Once a certificate issued, you should have a PEM file with a full chain certificate and a key.
+
+In the domains action, click the **deploy** button (see screenshow above).
+
+Provide the certificate and key and click deploy.
+
+If everything is okay, the delpoyment state should be green.
+
+Wait a bit for the deployment process to end.
+
+## Use the domain
+
+Refer to your domain instead of _crossid.io_, for example, if your tenant is _acme_, located in US then
+
+OAuth endpoints would be refered to: _https://acme.crossid.io/oauth2/.well-known/openid-configuration_
+
+If your custom domain is _auth.acme.io_, your can refer now to the URL: _https://auth.acme.io/oauth2/.well-known/openid-configuration_ instead.
+
+## DNS Providers
+
+### Godaddy
+
+If your domain is hosted in Godaddy follow these steps:
+
+1. Open https://dcc.godaddy.com/manage/acme.io/dns
+1. Put a _TXT_ record with the given _name_ and _value_.
+1. Click the **Add Record**.
+
+![godaddy](/img/howto/customdomain_godaddy.png)

sidebars.js

@@ -16,10 +16,16 @@ module.exports = {
           "guides/howto/add_web_app",
           "guides/howto/app_user_assignment",
           "guides/howto/machine_to_machine",
+          "guides/howto/custom_domain",
         ],
       },
     ],
-    Concepts: ["concepts/tenant", "concepts/application", "concepts/identity"],
+    Concepts: [
+      "concepts/tenant",
+      "concepts/application",
+      "concepts/identity",
+      "concepts/custom_domain",
+    ],
     "Sample Apps": [
       "sample_apps/sample-monorepo",
       "sample_apps/sample-nodejs",