Updates self-hosted authn doc (#1588)

Updates self-hosted authn doc (#1566)

* updates self-hosted authn doc

* runs prettier

* reformats self-hosted authn page

* runs prettier

* 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.

* actually make product info langauge consistent

* remove example configuration

* prettier

* small text updates

* adds a why subsection

* prettier

* simplify explanation, move to info admonition

* update info admonition title



---------

Co-authored-by: zachary painter <[email protected]>
Co-authored-by: Kenneth Jenkins <[email protected]>

Author: 3 people

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.
 
-Introduced in Pomerium v0.22, the hosted authenticate service is available in Pomerium Zero, open-source Pomerium Core, and Pomerium Enterprise.
+Introduced in Pomerium v0.22, the hosted authenticate service is available for open-source Pomerium, Pomerium Zero, and Pomerium Enterprise.
 
 ## How the hosted authenticate service works
 

content/docs/capabilities/self-hosted-authenticate-service.md

@@ -3,81 +3,60 @@ 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 for both open-source Pomerium Core and Enterprise users.
+The self-hosted authenticate service is available for open-source Pomerium, Pomerium Zero, and Pomerium Enterprise.
 
-## How the Self-Hosted Authenticate Service works
+:::info
 
-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).
+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
+
+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 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 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.
 
-```yaml
-authenticate_service_url: https://authenticate.localhost.pomerium.io
-```
+This URL should not contain a path or query parameters. For example, `https://authenticate.corp.example.com`.
 
-### Identity provider
+This URL must be different from any of the route URLs you use with Pomerium.
 
-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.
+See the [Authenticate Service URL](/docs/reference/service-urls#authenticate-service-url) reference page for details on how to configure this setting.
 
-## Configure the Self-Hosted Authenticate Service
+:::info Why does Pomerium use a separate authenticate service URL?
 
-To configure Pomerium to use self-hosted services:
+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.
 
-1. Add your authenticate service URL
+:::
 
-```yaml pomerium-config.yaml
-authenticate_service_url: https://authenticate.localhost.pomerium.io
-```
+### Identity provider
 
-1. Include your IdP settings
+Pomerium relies on an IdP to authenticate users. Pomerium can use any IdP that implements the OpenID Connect (OIDC) protocol.
 
-```yaml pomerium-config.yaml
-idp_provider: google
-idp_client_id: my_client_id
-idp_client_secret: my_client_secret
-```
+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.
 
-1. Build a route and policy
+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.
 
-```yaml pomerium-config.yaml
-routes:
-  - from: https://verify.localhost.pomerium.io
-    to: http://verify:8000
-    policy:
-      - allow:
-          or:
-            - email:
-                is: [email protected]
-    pass_identity_headers: true
-```
+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`.
 
-Your self-hosted configuration file might look like this:
+:::tip
 
-```yaml pomerium-config.yaml
-authenticate_service_url: https://authenticate.localhost.pomerium.io
+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.
 
-idp_provider: google
-idp_client_id: my_client_id
-idp_client_secret: my_client_secret
+:::
 
-routes:
-  - from: https://verify.localhost.pomerium.io
-    to: http://verify:8000
-    policy:
-      - allow:
-          or:
-            - email:
-                is: [email protected]
-    pass_identity_headers: true
-```
+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 [Pomerium Core Docker quickstart](/docs/core/quickstart) for more examples.
+See the [Identity Provider Settings](/docs/reference/identity-provider-settings#identity-provider-client-id) reference page for details on how to configure these settings.

content/docs/identity-providers/index.md renamed to 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.
+## Identity provider 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