docs: make authorize service url more clear (#360)

- don't use script include for vscode recipe

Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com>

docs/docs/reference/examples/config/config.example.env

@@ -8,8 +8,9 @@
 # export LOG_LEVEL="info"                     # optional, default is debug
 
 export AUTHENTICATE_SERVICE_URL=https://authenticate.corp.beyondperimeter.com
-# AUTHORIZE_SERVICE_URL defaults to `localhost:5443` in all-in-one mode
-# export AUTHORIZE_SERVICE_URL=https://authorize.corp.beyondperimeter.com
+# AUTHORIZE_SERVICE_URL service url will default to localhost in all-in-one mode,
+# otherwise it should be set to a "behind-the-ingress" routable url
+# export AUTHORIZE_SERVICE_URL=https://pomerium-authorize-service.default.svc.cluster.local
 
 # Certificates can be loaded as files or base64 encoded bytes.
 # See : https://www.pomerium.io/docs/reference/certificates

docs/docs/reference/examples/config/config.example.yaml

@@ -6,7 +6,9 @@
 # log_level: info # optional, default is debug
 
 authenticate_service_url: https://authenticate.corp.beyondperimeter.com
-# authorize_service_url: https://authorize.corp.beyondperimeter.com # usually a behind an ingress url
+# authorize service url will default to localhost in all-in-one mode, otherwise
+# it should be set to a "behind-the-ingress" routable url
+# authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local
 
 # Certificates can be loaded as files or base64 encoded bytes.
 # certificate_file: "./cert.pem" # optional, defaults to `./cert.pem`

docs/docs/reference/examples/config/config.minimal.yaml

@@ -1,6 +1,5 @@
 # See detailed configuration settings : https://www.pomerium.io/docs/reference/reference/
 authenticate_service_url: https://authenticate.corp.beyondperimeter.com
-authorize_service_url: https://authorize.corp.beyondperimeter.com
 
 # identity provider settings : https://www.pomerium.io/docs/identity-providers.html
 idp_provider: google

docs/docs/reference/examples/config/config.visual-studio-code.yaml

@@ -1,15 +0,0 @@
-# See detailed configuration settings : https://www.pomerium.io/docs/reference/reference/
-authenticate_service_url: https://authenticate.corp.domain.example
-authorize_service_url: https://authorize.corp.domain.example
-
-# identity provider settings : https://www.pomerium.io/docs/identity-providers.html
-idp_provider: google
-idp_client_id: REPLACE_ME
-idp_client_secret: REPLACE_ME
-
-policy:
-  - from: https://code.corp.domain.example
-    to: http://codeserver:8443
-    allowed_users:
-      - some.user@domain.example
-    allow_websockets: true

docs/docs/reference/reference.md

@@ -609,8 +609,8 @@ Authenticate Service URL is the externally accessible URL for the authenticate s
 - Environmental Variable: `AUTHORIZE_SERVICE_URL`
 - Config File Key: `authorize_service_url`
 - Type: `URL`
-- Required
-- Example: `https://authorize.corp.example.com` or `https://pomerium-authorize-service.default.svc.cluster.local` or `https://localhost:5443`
+- Required; inferred in all-in-one mode to be localhost.
+- Example: https://pomerium-authorize-service.default.svc.cluster.local` or `https://localhost:5443`
 
 Authorize Service URL is the location of the internally accessible authorize service. NOTE: Unlike authenticate, authorize has no publicly accessible http handlers so this setting is purely for gRPC communication.
 
@@ -624,7 +624,7 @@ If your load balancer does not support gRPC pass-through you'll need to set this
 - Optional (but typically required if Authenticate Internal Service Address is set)
 - Example: `*.corp.example.com` if wild card or `authenticate.corp.example.com`/`authorize.corp.example.com`
 
-When Authenticate Internal Service Address is set, secure service communication can fail because the external certificate name will not match the internally routed service hostname/[SNI](https://en.wikipedia.org/wiki/Server_Name_Indication). This setting allows you to override that check.
+Secure service communication can fail if the external certificate does not match the internally routed service hostname/[SNI](https://en.wikipedia.org/wiki/Server_Name_Indication). This setting allows you to override that value.
 
 ## Certificate Authority
 

docs/recipes/vs-code-server.md

@@ -36,7 +36,23 @@ This guide assumes you have already completed one of the [quick start] guides, a
 
 ### Pomerium Config
 
-<<< @/docs/docs/reference/examples/config/config.visual-studio-code.yaml
+```
+# config.yaml
+# See detailed configuration settings : https://www.pomerium.io/docs/reference/reference/
+authenticate_service_url: https://authenticate.corp.domain.example
+
+# identity provider settings : https://www.pomerium.io/docs/identity-providers.html
+idp_provider: google
+idp_client_id: REPLACE_ME
+idp_client_secret: REPLACE_ME
+
+policy:
+  - from: https://code.corp.domain.example
+    to: http://codeserver:8443
+    allowed_users:
+      - some.user@domain.example
+    allow_websockets: true
+```
 
 ### Docker-compose