From 34a6bf0314ce549cdb3122b8763040a413816c8f Mon Sep 17 00:00:00 2001
From: zachary painter <60552605+ZPain8464@users.noreply.github.com>
Date: Wed, 21 Aug 2024 16:59:36 -0400
Subject: [PATCH 01/13] updates self-hosted authn doc

---
 .../self-hosted-authenticate-service.md            | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index b91ed2836..ad8eab76f 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -10,7 +10,7 @@ description: Use Pomerium's Self-Hosted Authenticate Service to set up and deplo
 
 Pomerium's **Self-Hosted Authenticate Service** allows you to configure your own **Authenticate Service URL** and **Identity Provider**.
 
-The Self-Hosted Authenticate Service is available for both open-source Pomerium Core and Enterprise users.
+The Self-Hosted Authenticate Service is available for Pomerium Zero, open-source Pomerium Core, and Enterprise users.
 
 ## How the Self-Hosted Authenticate Service works
 
@@ -18,7 +18,17 @@ Self-hosting your Pomerium instance requires you to configure an [Authenticate S
 
 ### Authenticate service URL
 
-The authenticate service URL is an externally accessible URL used by Pomerium's Authenticate Service. You can include your own URL for testing or use Pomerium's localhost URL, which is hardcoded to point to `127.0.0.1`.
+The authenticate service URL defines where Pomerium redirects end users (clients) to authenticate against an identity provider. The configured identity provider must also use this URL as its [redirect URI](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), and append the `/oauth2/callback` path to the URL. 
+
+For example, if your authenticate service URL is `https://authenticate.corp.example.com`, the identity provider's redirect URI would be `https://authenticate.corp.example.com/oauth2/callback`.
+
+:::tip 
+
+If you require a different callback path than `/oauth2/callback`, use the [Authenticate Callback Path](/docs/reference/authenticate-callback-path) setting to define a custom callback path.
+
+:::
+
+You can use your own authenticate service URL or use Pomerium's localhost URL for testing, which is hardcoded to point to `127.0.0.1`:
 
 ```yaml
 authenticate_service_url: https://authenticate.localhost.pomerium.io

From 56a114400fbbc9ba96750c7ec55b9f13f6cdc970 Mon Sep 17 00:00:00 2001
From: zachary painter <60552605+ZPain8464@users.noreply.github.com>
Date: Wed, 21 Aug 2024 17:04:14 -0400
Subject: [PATCH 02/13] runs prettier

---
 content/docs/capabilities/self-hosted-authenticate-service.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index ad8eab76f..ff20bdcd0 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -18,11 +18,11 @@ Self-hosting your Pomerium instance requires you to configure an [Authenticate S
 
 ### Authenticate service URL
 
-The authenticate service URL defines where Pomerium redirects end users (clients) to authenticate against an identity provider. The configured identity provider must also use this URL as its [redirect URI](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), and append the `/oauth2/callback` path to the URL. 
+The authenticate service URL defines where Pomerium redirects end users (clients) to authenticate against an identity provider. The configured identity provider must also use this URL as its [redirect URI](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), and append the `/oauth2/callback` path to the URL.
 
 For example, if your authenticate service URL is `https://authenticate.corp.example.com`, the identity provider's redirect URI would be `https://authenticate.corp.example.com/oauth2/callback`.
 
-:::tip 
+:::tip
 
 If you require a different callback path than `/oauth2/callback`, use the [Authenticate Callback Path](/docs/reference/authenticate-callback-path) setting to define a custom callback path.
 

From 8fb081232c091c682d691fc313acb62d5c39a7ae Mon Sep 17 00:00:00 2001
From: zachary painter <60552605+ZPain8464@users.noreply.github.com>
Date: Thu, 22 Aug 2024 09:52:33 -0400
Subject: [PATCH 03/13] reformats self-hosted authn page

---
 .../self-hosted-authenticate-service.md       | 90 ++++++++++---------
 1 file changed, 48 insertions(+), 42 deletions(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index ff20bdcd0..21c7b80e4 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -8,76 +8,82 @@ description: Use Pomerium's Self-Hosted Authenticate Service to set up and deplo
 
 # Self-Hosted Authenticate Service
 
-Pomerium's **Self-Hosted Authenticate Service** allows you to configure your own **Authenticate Service URL** and **Identity Provider**.
+Pomerium's **Self-Hosted Authenticate Service** allows you to configure your own authenticate service URL and identity provider.
 
-The Self-Hosted Authenticate Service is available for Pomerium Zero, open-source Pomerium Core, and Enterprise users.
+The self-hosted authenticate service is available in Pomerium Zero, open-source Pomerium Core, and Pomerium Enterprise.
 
-## How the Self-Hosted Authenticate Service works
+## How the self-hosted authenticate service works
 
-Self-hosting your Pomerium instance requires you to configure an [Authenticate Service URL](/docs/reference/service-urls#authenticate-service-url) and an OIDC-compliant [identity provider](/docs/identity-providers) (IdP).
+Self-hosting your Pomerium instance requires you to configure an [authenticate service URL](/docs/reference/service-urls#authenticate-service-url) and an OIDC-compliant [identity provider](/docs/identity-providers) (IdP).
 
 ### Authenticate service URL
 
-The authenticate service URL defines where Pomerium redirects end users (clients) to authenticate against an identity provider. The configured identity provider must also use this URL as its [redirect URI](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), and append the `/oauth2/callback` path to the URL.
+The authenticate service URL is an external URL that defines where Pomerium redirects users to authenticate against an identity provider. The configured identity provider requires the same authenticate service URL as its [redirect URI](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), with the `/oauth2/callback` path appended to the URL.
 
-For example, if your authenticate service URL is `https://authenticate.corp.example.com`, the identity provider's redirect URI would be `https://authenticate.corp.example.com/oauth2/callback`.
+For example, if your authenticate service URL is `https://authenticate.corp.example.com`,
 
-:::tip
-
-If you require a different callback path than `/oauth2/callback`, use the [Authenticate Callback Path](/docs/reference/authenticate-callback-path) setting to define a custom callback path.
+The identity provider's redirect URI would be `https://authenticate.corp.example.com/oauth2/callback`.
 
-:::
-
-You can use your own authenticate service URL or use Pomerium's localhost URL for testing, which is hardcoded to point to `127.0.0.1`:
+You can use Pomerium's localhost URL for testing, which is hardcoded to point to `127.0.0.1`:
 
 ```yaml
 authenticate_service_url: https://authenticate.localhost.pomerium.io
 ```
 
-### Identity provider
+:::tip
 
-Pomerium's Authenticate Service requires an IdP to authenticate and authorize users. Pomerium supports all major IdP solutions and any IdP that uses OAuth 2.0 and OIDC protocols as well.
+If you require a different callback path than `/oauth2/callback`, use the [Authenticate Callback Path](/docs/reference/authenticate-callback-path) setting to define a custom callback path.
 
-## Configure the Self-Hosted Authenticate Service
+:::
 
-To configure Pomerium to use self-hosted services:
+### Identity provider
 
-1. Add your authenticate service URL
+Pomerium's Authenticate Service requires an IdP to authenticate users. Pomerium can support any IdP that incorporates the OAuth 2.0 and OIDC protocols in the authentication flow. 
 
-```yaml pomerium-config.yaml
-authenticate_service_url: https://authenticate.localhost.pomerium.io
-```
+Although the steps to configure an IdP to integrate with Pomerium vary depending on the provider (see [identity providers](/docs/identity-providers) for vendor-specific guides), the Pomerium configuration always requires some (or all) of the following IdP-related settings:
 
-1. Include your IdP settings
+- Identity Provider Client ID
+- Identity Provider Client Secret
+- Identity Provider Name
+- Identity Provider URL
 
-```yaml pomerium-config.yaml
-idp_provider: google
-idp_client_id: my_client_id
-idp_client_secret: my_client_secret
-```
+See [Identity Provider Settings](/docs/reference/identity-provider-settings#identity-provider-client-id) for more information.
 
-1. Build a route and policy
+## Configure the self-hosted authenticate service
 
-```yaml pomerium-config.yaml
-routes:
-  - from: https://verify.localhost.pomerium.io
-    to: http://verify:8000
-    policy:
-      - allow:
-          or:
-            - email:
-                is: user@example.com
-    pass_identity_headers: true
-```
+To configure Pomerium to use the self-hosted authenticate service:
+
+1. Add your authenticate service URL 
+    ```yaml title="pomerium-config.yaml"
+    authenticate_service_url: https://authenticate.localhost.pomerium.io
+    ```
+1. Include your IdP settings
+    ```yaml title="pomerium-config.yaml"
+    idp_provider: <idp>
+    idp_client_id: <client_id>
+    idp_client_secret: <client_secret>
+    ```
+1. Build a route and policy
+    ```yaml title="pomerium-config.yaml"
+    routes:
+      - from: https://verify.localhost.pomerium.io
+        to: http://verify:8000
+        policy:
+          - allow:
+              or:
+                - email:
+                    is: user@example.com
+        pass_identity_headers: true
+    ```
 
 Your self-hosted configuration file might look like this:
 
-```yaml pomerium-config.yaml
+```yaml title="pomerium-config.yaml"
 authenticate_service_url: https://authenticate.localhost.pomerium.io
 
-idp_provider: google
-idp_client_id: my_client_id
-idp_client_secret: my_client_secret
+idp_provider: github
+idp_client_id: <client_id>
+idp_client_secret: <client_secret>
 
 routes:
   - from: https://verify.localhost.pomerium.io

From a2dbd6c9d6b51b5a444e4deee020be4c9da099c4 Mon Sep 17 00:00:00 2001
From: zachary painter <60552605+ZPain8464@users.noreply.github.com>
Date: Thu, 22 Aug 2024 10:10:07 -0400
Subject: [PATCH 04/13] runs prettier

---
 .../self-hosted-authenticate-service.md       | 42 +++++++++----------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index 21c7b80e4..82596c11a 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -38,7 +38,7 @@ If you require a different callback path than `/oauth2/callback`, use the [Authe
 
 ### Identity provider
 
-Pomerium's Authenticate Service requires an IdP to authenticate users. Pomerium can support any IdP that incorporates the OAuth 2.0 and OIDC protocols in the authentication flow. 
+Pomerium's Authenticate Service requires an IdP to authenticate users. Pomerium can support any IdP that incorporates the OAuth 2.0 and OIDC protocols in the authentication flow.
 
 Although the steps to configure an IdP to integrate with Pomerium vary depending on the provider (see [identity providers](/docs/identity-providers) for vendor-specific guides), the Pomerium configuration always requires some (or all) of the following IdP-related settings:
 
@@ -53,28 +53,28 @@ See [Identity Provider Settings](/docs/reference/identity-provider-settings#iden
 
 To configure Pomerium to use the self-hosted authenticate service:
 
-1. Add your authenticate service URL 
-    ```yaml title="pomerium-config.yaml"
-    authenticate_service_url: https://authenticate.localhost.pomerium.io
-    ```
+1. Add your authenticate service URL
+   ```yaml title="pomerium-config.yaml"
+   authenticate_service_url: https://authenticate.localhost.pomerium.io
+   ```
 1. Include your IdP settings
-    ```yaml title="pomerium-config.yaml"
-    idp_provider: <idp>
-    idp_client_id: <client_id>
-    idp_client_secret: <client_secret>
-    ```
+   ```yaml title="pomerium-config.yaml"
+   idp_provider: <idp>
+   idp_client_id: <client_id>
+   idp_client_secret: <client_secret>
+   ```
 1. Build a route and policy
-    ```yaml title="pomerium-config.yaml"
-    routes:
-      - from: https://verify.localhost.pomerium.io
-        to: http://verify:8000
-        policy:
-          - allow:
-              or:
-                - email:
-                    is: user@example.com
-        pass_identity_headers: true
-    ```
+   ```yaml title="pomerium-config.yaml"
+   routes:
+     - from: https://verify.localhost.pomerium.io
+       to: http://verify:8000
+       policy:
+         - allow:
+             or:
+               - email:
+                   is: user@example.com
+       pass_identity_headers: true
+   ```
 
 Your self-hosted configuration file might look like this:
 

From 5c71066983410f6a8f776154ccf7a00cd83322b7 Mon Sep 17 00:00:00 2001
From: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com>
Date: Wed, 4 Sep 2024 15:34:58 -0700
Subject: [PATCH 05/13] suggested revisions to self-hosted authenticate service
 page

Also make a small tweak to the hosted authenticate service page for
consistent language around the supported products, and update the
Identity Providers guides index page to link to all the guides right on
that page.
---
 .../hosted-authenticate-service.md            |  2 +-
 .../self-hosted-authenticate-service.md       | 69 ++++++++++---------
 .../{index.md => index.mdx}                   | 12 ++--
 3 files changed, 46 insertions(+), 37 deletions(-)
 rename content/docs/identity-providers/{index.md => index.mdx} (77%)

diff --git a/content/docs/capabilities/hosted-authenticate-service.md b/content/docs/capabilities/hosted-authenticate-service.md
index 7920a9859..e26b296dd 100644
--- a/content/docs/capabilities/hosted-authenticate-service.md
+++ b/content/docs/capabilities/hosted-authenticate-service.md
@@ -10,7 +10,7 @@ description: Use Pomerium's Hosted Authenticate Service to set up and deploy Pom
 
 Pomerium's **Hosted Authenticate Service** provides a hosted alternative to the Self-Hosted Authenticate Service.
 
-The Hosted Authenticate Service is available in Pomerium v0.22.0 for both open-source Pomerium Core and Enterprise users.
+The Hosted Authenticate Service is available for open-source Pomerium, Pomerium Zero, and Pomerium Enterprise.
 
 ## How the Hosted Authenticate Service works
 
diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index 82596c11a..8f6a70528 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -3,63 +3,70 @@ id: self-hosted-authenticate-service
 title: Self-Hosted Authenticate Service
 sidebar_label: Self-Hosted Authenticate Service
 keywords: [self-hosted authenticate service url, self-hosted identity provider]
-description: Use Pomerium's Self-Hosted Authenticate Service to set up and deploy Pomerium with your own hosted settings.
+description: Use Pomerium's Self-Hosted Authenticate Service to deploy Pomerium with your own identity provider.
 ---
 
 # Self-Hosted Authenticate Service
 
-Pomerium's **Self-Hosted Authenticate Service** allows you to configure your own authenticate service URL and identity provider.
+Pomerium's **Self-Hosted Authenticate Service** allows you to configure Pomerium with the identity provider of your choice.
 
-The self-hosted authenticate service is available in Pomerium Zero, open-source Pomerium Core, and Pomerium Enterprise.
+The self-hosted authenticate service is available for all versions of Pomerium (open-source, Pomerium Zero, and Pomerium Enterprise).
+
+:::info
+
+The _authenticate service_ is one of the [four logical services](/docs/internals/architecture#component-level) that make up Pomerium. The authenticate service is unique in that Pomerium can either run this service itself, or instead use the [Hosted Authenticate Service](/docs/capabilities/hosted-authenticate-service).
+
+:::
 
 ## How the self-hosted authenticate service works
 
-Self-hosting your Pomerium instance requires you to configure an [authenticate service URL](/docs/reference/service-urls#authenticate-service-url) and an OIDC-compliant [identity provider](/docs/identity-providers) (IdP).
+To configure the self-hosted authenticate service, you will need to set up:
+- a URL for the authenticate service
+- an identity provider (IdP)
 
 ### Authenticate service URL
 
-The authenticate service URL is an external URL that defines where Pomerium redirects users to authenticate against an identity provider. The configured identity provider requires the same authenticate service URL as its [redirect URI](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), with the `/oauth2/callback` path appended to the URL.
+The authenticate service URL is a public-facing URL that should resolve to your Pomerium instance. (If running in split service mode, this URL should resolve to the authenticate service.) Whenever a user is required to log in to access a route, Pomerium will redirect the user to the authenticate service using this URL.
 
-For example, if your authenticate service URL is `https://authenticate.corp.example.com`,
+This URL should not contain a path or query parameters. For example, `https://authenticate.corp.example.com`.
 
-The identity provider's redirect URI would be `https://authenticate.corp.example.com/oauth2/callback`.
+This URL must be different from any of the route URLs you use with Pomerium.
 
-You can use Pomerium's localhost URL for testing, which is hardcoded to point to `127.0.0.1`:
+See the [Authenticate Service URL](/docs/reference/service-urls#authenticate-service-url) reference page for details on how to configure this setting.
 
-```yaml
-authenticate_service_url: https://authenticate.localhost.pomerium.io
-```
 
-:::tip
+### Identity provider
 
-If you require a different callback path than `/oauth2/callback`, use the [Authenticate Callback Path](/docs/reference/authenticate-callback-path) setting to define a custom callback path.
+Pomerium relies on an identity provider (IdP) to authenticate users. Pomerium can use any IdP that implements the OpenID Connect (OIDC) protocol.
 
-:::
+The steps to configure your IdP will vary depending on the specific provider. See [**Identity Providers**](/docs/identity-providers) for a list of guides to configure commonly-used IdPs.
 
-### Identity provider
+You will generally need to configure your IdP client to allow an OAuth redirect URL based on your chosen authenticate service URL, with the path `/oauth2/callback` appended to it.
 
-Pomerium's Authenticate Service requires an IdP to authenticate users. Pomerium can support any IdP that incorporates the OAuth 2.0 and OIDC protocols in the authentication flow.
+For example, if your authenticate service URL is `https://authenticate.corp.example.com`, you should configure your identity provider to allow the redirect URI `https://authenticate.corp.example.com/oauth2/callback`.
 
-Although the steps to configure an IdP to integrate with Pomerium vary depending on the provider (see [identity providers](/docs/identity-providers) for vendor-specific guides), the Pomerium configuration always requires some (or all) of the following IdP-related settings:
+:::tip
 
-- Identity Provider Client ID
-- Identity Provider Client Secret
-- Identity Provider Name
-- Identity Provider URL
+If you require a different callback path than `/oauth2/callback`, you can use the [Authenticate Callback Path](/docs/reference/authenticate-callback-path) setting to change the callback path.
 
-See [Identity Provider Settings](/docs/reference/identity-provider-settings#identity-provider-client-id) for more information.
+:::
 
-## Configure the self-hosted authenticate service
+Once you have set up an IdP client, you will need to configure Pomerium with the IdP name, client ID and client secret, and possibly a URL assigned to your individual IdP client.
 
-To configure Pomerium to use the self-hosted authenticate service:
+See the [Identity Provider Settings](/docs/reference/identity-provider-settings#identity-provider-client-id) reference page for details on how to configure these settings.
 
-1. Add your authenticate service URL
+## Example
+
+To configure Pomerium to use the self-hosted authenticate service with GitHub authentication:
+
+1. Add your authenticate service URL to your Pomerium configuration:
    ```yaml title="pomerium-config.yaml"
    authenticate_service_url: https://authenticate.localhost.pomerium.io
    ```
-1. Include your IdP settings
+1. Register a new GitHub OAuth application by following the steps at [Create a GitHub OAuth 2.0 Application](/docs/identity-providers/github#create-a-github-oauth-20-application).
+1. Configure Pomerium to use the GitHub OAuth application:
    ```yaml title="pomerium-config.yaml"
-   idp_provider: <idp>
+   idp_provider: github
    idp_client_id: <client_id>
    idp_client_secret: <client_secret>
    ```
@@ -67,7 +74,7 @@ To configure Pomerium to use the self-hosted authenticate service:
    ```yaml title="pomerium-config.yaml"
    routes:
      - from: https://verify.localhost.pomerium.io
-       to: http://verify:8000
+       to: https://verify.pomerium.com
        policy:
          - allow:
              or:
@@ -76,7 +83,7 @@ To configure Pomerium to use the self-hosted authenticate service:
        pass_identity_headers: true
    ```
 
-Your self-hosted configuration file might look like this:
+Putting it all together:
 
 ```yaml title="pomerium-config.yaml"
 authenticate_service_url: https://authenticate.localhost.pomerium.io
@@ -87,7 +94,7 @@ idp_client_secret: <client_secret>
 
 routes:
   - from: https://verify.localhost.pomerium.io
-    to: http://verify:8000
+    to: https://verify.pomerium.com
     policy:
       - allow:
           or:
@@ -95,5 +102,3 @@ routes:
                 is: user@example.com
     pass_identity_headers: true
 ```
-
-See the [Pomerium Core Docker quickstart](/docs/core/quickstart) for more examples.
diff --git a/content/docs/identity-providers/index.md b/content/docs/identity-providers/index.mdx
similarity index 77%
rename from content/docs/identity-providers/index.md
rename to content/docs/identity-providers/index.mdx
index 29f4a9350..afcf562a5 100644
--- a/content/docs/identity-providers/index.md
+++ b/content/docs/identity-providers/index.mdx
@@ -16,6 +16,8 @@ pagination_prev: null
 pagination_next: null
 ---
 
+import DocCardList from '@theme/DocCardList';
+
 Pomerium provides authentication through your existing identity provider (**IdP**) and supports all major single sign-on (**SSO**) providers.
 
 Pomerium uses the OAuth 2.0 and OIDC protocols to integrate with your IdP so you can configure any IdP solution that supports these protocols.
@@ -32,13 +34,15 @@ For example, `https://{authenticate_service_url}.com/oauth2/callback`.
 
 See the guides in this section for specific steps to integrate your IdP with Pomerium.
 
-## Hosted identity provider
+:::tip
+
+If you want to try out Pomerium without configuring an IdP, you can use our [Hosted Authenticate Service](/docs/capabilities/hosted-authenticate-service) instead.
 
-Pomerium’s [**Hosted Authenticate Service**](/docs/capabilities/hosted-authenticate-service) provides a **Hosted Authenticate Service URL** and a **Hosted Identity Provider**.
+:::
 
-If you use the hosted services, you don’t need to include IdP settings or an authenticate service URL in your configuration.
+## List of guides
 
-See [Configure hosted services](/docs/capabilities/hosted-authenticate-service#configure-the-hosted-authenticate-service) for more information.
+<DocCardList />
 
 [client id]: /docs/reference/identity-provider-settings#identity-provider-client-id
 [client secret]: /docs/reference/identity-provider-settings#identity-provider-client-secret

From 4793badd4532ad71e751f479fd3fd27edf4e3b23 Mon Sep 17 00:00:00 2001
From: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com>
Date: Wed, 4 Sep 2024 15:41:57 -0700
Subject: [PATCH 06/13] actually make product info langauge consistent

---
 content/docs/capabilities/self-hosted-authenticate-service.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index 8f6a70528..30c1816d3 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -10,7 +10,7 @@ description: Use Pomerium's Self-Hosted Authenticate Service to deploy Pomerium
 
 Pomerium's **Self-Hosted Authenticate Service** allows you to configure Pomerium with the identity provider of your choice.
 
-The self-hosted authenticate service is available for all versions of Pomerium (open-source, Pomerium Zero, and Pomerium Enterprise).
+The self-hosted authenticate service is available for open-source Pomerium, Pomerium Zero, and Pomerium Enterprise.
 
 :::info
 

From 13130657ec1ef21ce87a25a2858f0c438eb64541 Mon Sep 17 00:00:00 2001
From: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com>
Date: Wed, 4 Sep 2024 15:43:52 -0700
Subject: [PATCH 07/13] remove example configuration

---
 .../self-hosted-authenticate-service.md       | 48 -------------------
 1 file changed, 48 deletions(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index 30c1816d3..7aec69bd3 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -54,51 +54,3 @@ If you require a different callback path than `/oauth2/callback`, you can use th
 Once you have set up an IdP client, you will need to configure Pomerium with the IdP name, client ID and client secret, and possibly a URL assigned to your individual IdP client.
 
 See the [Identity Provider Settings](/docs/reference/identity-provider-settings#identity-provider-client-id) reference page for details on how to configure these settings.
-
-## Example
-
-To configure Pomerium to use the self-hosted authenticate service with GitHub authentication:
-
-1. Add your authenticate service URL to your Pomerium configuration:
-   ```yaml title="pomerium-config.yaml"
-   authenticate_service_url: https://authenticate.localhost.pomerium.io
-   ```
-1. Register a new GitHub OAuth application by following the steps at [Create a GitHub OAuth 2.0 Application](/docs/identity-providers/github#create-a-github-oauth-20-application).
-1. Configure Pomerium to use the GitHub OAuth application:
-   ```yaml title="pomerium-config.yaml"
-   idp_provider: github
-   idp_client_id: <client_id>
-   idp_client_secret: <client_secret>
-   ```
-1. Build a route and policy
-   ```yaml title="pomerium-config.yaml"
-   routes:
-     - from: https://verify.localhost.pomerium.io
-       to: https://verify.pomerium.com
-       policy:
-         - allow:
-             or:
-               - email:
-                   is: user@example.com
-       pass_identity_headers: true
-   ```
-
-Putting it all together:
-
-```yaml title="pomerium-config.yaml"
-authenticate_service_url: https://authenticate.localhost.pomerium.io
-
-idp_provider: github
-idp_client_id: <client_id>
-idp_client_secret: <client_secret>
-
-routes:
-  - from: https://verify.localhost.pomerium.io
-    to: https://verify.pomerium.com
-    policy:
-      - allow:
-          or:
-            - email:
-                is: user@example.com
-    pass_identity_headers: true
-```

From f3039d36e9af036643aad7bd0a8128dbe3be11f7 Mon Sep 17 00:00:00 2001
From: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com>
Date: Wed, 4 Sep 2024 15:45:09 -0700
Subject: [PATCH 08/13] prettier

---
 content/docs/capabilities/self-hosted-authenticate-service.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index 7aec69bd3..21eb5812c 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -21,6 +21,7 @@ The _authenticate service_ is one of the [four logical services](/docs/internals
 ## How the self-hosted authenticate service works
 
 To configure the self-hosted authenticate service, you will need to set up:
+
 - a URL for the authenticate service
 - an identity provider (IdP)
 
@@ -34,7 +35,6 @@ This URL must be different from any of the route URLs you use with Pomerium.
 
 See the [Authenticate Service URL](/docs/reference/service-urls#authenticate-service-url) reference page for details on how to configure this setting.
 
-
 ### Identity provider
 
 Pomerium relies on an identity provider (IdP) to authenticate users. Pomerium can use any IdP that implements the OpenID Connect (OIDC) protocol.

From 3ac0713f1d33b39689c3fc492942448a26daef77 Mon Sep 17 00:00:00 2001
From: zachary painter <60552605+ZPain8464@users.noreply.github.com>
Date: Mon, 9 Sep 2024 17:20:17 -0400
Subject: [PATCH 09/13] small text updates

---
 content/docs/capabilities/self-hosted-authenticate-service.md | 2 +-
 content/docs/identity-providers/index.mdx                     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index 21eb5812c..5051e19c2 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -23,7 +23,7 @@ The _authenticate service_ is one of the [four logical services](/docs/internals
 To configure the self-hosted authenticate service, you will need to set up:
 
 - a URL for the authenticate service
-- an identity provider (IdP)
+- an identity provider
 
 ### Authenticate service URL
 
diff --git a/content/docs/identity-providers/index.mdx b/content/docs/identity-providers/index.mdx
index afcf562a5..c16258691 100644
--- a/content/docs/identity-providers/index.mdx
+++ b/content/docs/identity-providers/index.mdx
@@ -40,7 +40,7 @@ If you want to try out Pomerium without configuring an IdP, you can use our [Hos
 
 :::
 
-## List of guides
+## Identity provider guides
 
 <DocCardList />
 

From 5e9a1d4f04a9a65177a53fabe1b6179a18aba7e5 Mon Sep 17 00:00:00 2001
From: zachary painter <60552605+ZPain8464@users.noreply.github.com>
Date: Mon, 9 Sep 2024 18:13:07 -0400
Subject: [PATCH 10/13] adds a why subsection

---
 .../capabilities/self-hosted-authenticate-service.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index 5051e19c2..d91a628ba 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -23,7 +23,7 @@ The _authenticate service_ is one of the [four logical services](/docs/internals
 To configure the self-hosted authenticate service, you will need to set up:
 
 - a URL for the authenticate service
-- an identity provider
+- an identity provider (IdP) 
 
 ### Authenticate service URL
 
@@ -35,9 +35,17 @@ This URL must be different from any of the route URLs you use with Pomerium.
 
 See the [Authenticate Service URL](/docs/reference/service-urls#authenticate-service-url) reference page for details on how to configure this setting.
 
+#### Why use an authenticate service URL?
+
+In a typical OIDC authentication flow, the Relying Party (in this case, the upstream service) requires an OpenID (OP) client to authenticate users against an IdP (the OP client must be registered with the IdP). 
+
+Without the authenticate service URL setting, if you configured Pomerium to protect multiple upstream services, each service would require its own OP client.
+
+The authenticate service URL allows you to configure a single URL that you can reuse to authenticate users across multiple Pomerium-managed routes. This way, you don't need to configure and maintain multiple OP clients to authenticate end users.
+
 ### Identity provider
 
-Pomerium relies on an identity provider (IdP) to authenticate users. Pomerium can use any IdP that implements the OpenID Connect (OIDC) protocol.
+Pomerium relies on an IdP to authenticate users. Pomerium can use any IdP that implements the OpenID Connect (OIDC) protocol.
 
 The steps to configure your IdP will vary depending on the specific provider. See [**Identity Providers**](/docs/identity-providers) for a list of guides to configure commonly-used IdPs.
 

From 58d797af1d026f200583c684848f96c2bfeb2d60 Mon Sep 17 00:00:00 2001
From: zachary painter <60552605+ZPain8464@users.noreply.github.com>
Date: Mon, 9 Sep 2024 18:14:44 -0400
Subject: [PATCH 11/13] prettier

---
 content/docs/capabilities/self-hosted-authenticate-service.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index d91a628ba..7909d80df 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -23,7 +23,7 @@ The _authenticate service_ is one of the [four logical services](/docs/internals
 To configure the self-hosted authenticate service, you will need to set up:
 
 - a URL for the authenticate service
-- an identity provider (IdP) 
+- an identity provider (IdP)
 
 ### Authenticate service URL
 
@@ -37,7 +37,7 @@ See the [Authenticate Service URL](/docs/reference/service-urls#authenticate-ser
 
 #### Why use an authenticate service URL?
 
-In a typical OIDC authentication flow, the Relying Party (in this case, the upstream service) requires an OpenID (OP) client to authenticate users against an IdP (the OP client must be registered with the IdP). 
+In a typical OIDC authentication flow, the Relying Party (in this case, the upstream service) requires an OpenID (OP) client to authenticate users against an IdP (the OP client must be registered with the IdP).
 
 Without the authenticate service URL setting, if you configured Pomerium to protect multiple upstream services, each service would require its own OP client.
 

From 3c44e3ba5ff8b5456e70520ab0ef67d3a2bbe5a3 Mon Sep 17 00:00:00 2001
From: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com>
Date: Mon, 9 Sep 2024 17:24:28 -0700
Subject: [PATCH 12/13] simplify explanation, move to info admonition

---
 .../docs/capabilities/self-hosted-authenticate-service.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index 7909d80df..b8cc65012 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -35,13 +35,11 @@ This URL must be different from any of the route URLs you use with Pomerium.
 
 See the [Authenticate Service URL](/docs/reference/service-urls#authenticate-service-url) reference page for details on how to configure this setting.
 
-#### Why use an authenticate service URL?
+:::info Why does Pomerium use a separate URL for this?
 
-In a typical OIDC authentication flow, the Relying Party (in this case, the upstream service) requires an OpenID (OP) client to authenticate users against an IdP (the OP client must be registered with the IdP).
+In a typical OIDC authentication flow, all redirect URLs must be pre-registered with the IdP. Pomerium uses a single authenticate service URL so that you need to register only one redirect URL with your IdP. This way, Pomerium can protect multiple upstream services without requiring you to update your IdP client whenever you add a new service.
 
-Without the authenticate service URL setting, if you configured Pomerium to protect multiple upstream services, each service would require its own OP client.
-
-The authenticate service URL allows you to configure a single URL that you can reuse to authenticate users across multiple Pomerium-managed routes. This way, you don't need to configure and maintain multiple OP clients to authenticate end users.
+:::
 
 ### Identity provider
 

From 819386c5488e1c51f0d7c6712ffdf0e83d5b8894 Mon Sep 17 00:00:00 2001
From: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com>
Date: Tue, 10 Sep 2024 12:36:07 -0700
Subject: [PATCH 13/13] update info admonition title

Co-authored-by: zachary painter <60552605+ZPain8464@users.noreply.github.com>
---
 content/docs/capabilities/self-hosted-authenticate-service.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/docs/capabilities/self-hosted-authenticate-service.md b/content/docs/capabilities/self-hosted-authenticate-service.md
index b8cc65012..b9f9cfb46 100644
--- a/content/docs/capabilities/self-hosted-authenticate-service.md
+++ b/content/docs/capabilities/self-hosted-authenticate-service.md
@@ -35,7 +35,7 @@ This URL must be different from any of the route URLs you use with Pomerium.
 
 See the [Authenticate Service URL](/docs/reference/service-urls#authenticate-service-url) reference page for details on how to configure this setting.
 
-:::info Why does Pomerium use a separate URL for this?
+:::info Why does Pomerium use a separate authenticate service URL?
 
 In a typical OIDC authentication flow, all redirect URLs must be pre-registered with the IdP. Pomerium uses a single authenticate service URL so that you need to register only one redirect URL with your IdP. This way, Pomerium can protect multiple upstream services without requiring you to update your IdP client whenever you add a new service.