Updates self-hosted authn doc #1566
Conversation
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| # 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. |
There was a problem hiding this comment.
I think if we're going to do a substantial rewrite of the page, we can probably make this even clearer.
For example here, it doesn't make sense to me to phrase this as "allows you to configure your own authenticate service URL" — that doesn't seem like a goal in and of itself, does it? I think it would be better to put the second half of that sentence up front, i.e. "allows you to configure Pomerium to use your own identify provider."
Let's try to figure out what is the most relevant information, and make sure we put that up front.
| 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 in Pomerium Zero, open-source Pomerium Core, and Pomerium Enterprise. |
There was a problem hiding this comment.
I also wonder if there's enough background context to understand what the authenticate service is? Do users need to know that Pomerium consists of four logical services, and "authenticate" is one of them, but the authenticate service is unique in that you can decide whether to run it yourself or use the hosted version?
Would it help to link to https://www.pomerium.com/docs/internals/configuration#all-in-one-vs-split-service-mode here? (I don't know.) For that matter — should we also update that page to call out that the authenticate service is special?
| ## 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). |
There was a problem hiding this comment.
This seems confusing to me as well: if Pomerium runs its own authenticate service is that the same thing as "self-hosting your Pomerium instance"?
| ## 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). |
There was a problem hiding this comment.
Side note: while most supported identity providers are in fact OIDC-compliant, a couple are not (GitHub and Apple).
| ### 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 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. |
There was a problem hiding this comment.
I think this is the crux of it. Let's try to make it really obvious that the authenticate service URL should resolve to the Pomerium instance itself.
It might also help some users to explain here why Pomerium uses a separate URL for the authenticate service in the first place.
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.
kenjenkins
force-pushed
the
zpain/update-self-hosted-authn
branch
from
c2f1add to
4793bad
Compare
kenjenkins
left a comment
kenjenkins
left a comment
There was a problem hiding this comment.
I've pushed some suggested revisions directly. Please take a look and feel free to refine further. I think this should address all of the concerns I mentioned, except for one (trying to explain why Pomerium uses a separate authenticate service URL in the first place).
I also made some tweaks to the Identity Providers guides index page. Let me know if you'd prefer to pull those out into a separate PR.
|
@kenjenkins I added this section under an H4, but it might be more effective/noticeable in an "info" admonition? If you think it's fine as is, I'm fine merging it like this as well. The other changes you made make a lot of sense as well. I appreciate it. I made a few small adjustments. |
|
Thanks for taking a pass at a "why" section. Some of the details seem a little muddled — let me try to revise it a little, if that's OK with you. And I like the idea of putting this into an "info" admonition. I think that would be a nice touch. |
Co-authored-by: zachary painter <60552605+ZPain8464@users.noreply.github.com>
* 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 <60552605+ZPain8464@users.noreply.github.com> --------- Co-authored-by: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com>
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 <60552605+ZPain8464@users.noreply.github.com> Co-authored-by: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com>
This PR updates the Self-hosted Authenticate Service Setting page "Authenticate Service URL" section by mentioning that the configured IdP's redirect URI must match the URL defined by the
authenticate_service_urlsetting.