website/docs: Flesh out Google Workspaces SAML. #12701
Conversation
✅ Deploy Preview for authentik-storybook canceled.
|
✅ Deploy Preview for authentik-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
- Moves Google Cloud doc page to sibling article.
GirlBossRush
force-pushed
the
5035-google-workspace-saml
branch
from
2ef83a4 to
d6a2c14
Compare
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #12701 +/- ##
==========================================
- Coverage 92.75% 92.70% -0.06%
==========================================
Files 769 769
Lines 38840 38886 +46
==========================================
+ Hits 36026 36048 +22
- Misses 2814 2838 +24
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
| | Entity ID | `https://authentik.company` | | ||
| | Name ID format | EMAIL | | ||
| | Name ID | Basic Information › Primary Email | | ||
|
|
There was a problem hiding this comment.
Hey! Wanted to start off by saying this looks fantastic and is really helpful. I'm trying this out for myself and this section does not seem to specify whether the user should select the Signed response option (Found right underneath "Start URL"). Could be worth mentioning as signing the response would help with security.
| | | | | ||
| | ---------------- | --------------------------------------------------------- | | ||
| | SSO URL | `https://accounts.google.com/o/saml2/idp?idpid=#########` | | ||
| | Entity ID/Issuer | `https://accounts.google.com/o/saml2?idpid=#########` | |
There was a problem hiding this comment.
On line 97 you tell the user to set the Entity ID to https://authentik.company. On this line, you tell the user to set the Entity ID/Issuer in authentik to this value. When trying this out for myself, I receive the error app_not_configured_for_user which was resolved by updating authentik to use the same value as the one configured in GWorkspace
There was a problem hiding this comment.
Thanks for catching this!
Ironically, I made this mix-up on my first run through setting up SAML. The "idP-to-idP" flow can make keeping track of this distinction especially tricky!
After speaking with the authentik team about the differences between the existing Google documentation and the new SAML instructions, I can follow up with an update for each integration flow 😊
| | Entity ID | `https://authentik.company` | | ||
| | Name ID format | EMAIL | | ||
| | Name ID | Basic Information › Primary Email | | ||
| | Signed Response | Enabled ✅ | |
There was a problem hiding this comment.
Signed responses are enabled here, but I don't see anything in the rest of the guide telling the user to sign responses on their side / adding the signing key in authentik. I do believe there's a page that provides a step-by-step to add a certain, that could be linked.
|
|
||
| In the Google Workspace Admin Console, go to Menu › Apps › Web and mobile apps. | ||
|
|
||
| 1. In the app list, locate the SAML app generating the error. |
There was a problem hiding this comment.
This guide provides a step-by-step to configure authentik with GWorkspace. You should be more specific when you say "the SAML generating the error". I'm not sure on exactly how I would say it. otherwise I would have linked a suggestion.
|
|
||
| Google Workspace (formerly G Suite) is a collection of cloud computing, productivity and collaboration tools, software and products developed and marketed by Google. | ||
|
|
||
| Organizations using Google Workspace allow their users to authenticate into applications using their company email addresses. This guide shows how to set up Security Assertion Markup Language (<abbr>SAML</abbr>) as the authentication method between Google Workspace and authentik. |
There was a problem hiding this comment.
I think we might want to make this distinction a bit more easily findable, maybe a small index page for the sidebar category that says when to use either method?
There was a problem hiding this comment.
Is the distinction between 1) not using authentik at all (users just authenticate via GWS), and 2) this process on this page, of using authentik with GWS as a source (via SAML)? I didn't even catch the two methods when reading this paragraph. Yes, agree they need to be more clearly two separate options... instead of adding another page, I'd suggesting either creating a top-level landing page for that and other conceptual info, or adding it to the top of this page as a conceptual topic/paragraph. I doubt there is enough content to warrant a whole 'nother page?
There was a problem hiding this comment.
In general we need a sentence or two at top of every page clarifying what this page is about...
| Next, you'll be presented with information we'll need to configure authentik. Under _Option 2_, copy the SSO URL and download the certificate. | ||
|
|
||
| :::warning | ||
| authentik is acting as both a Service Provider (SP) to Google and an Identity Provider (idP) to your applications. Since we only need the SP configuration, you can ignore the Entity ID provided by Google. |
There was a problem hiding this comment.
While the config is correct the explanation doesn't make sense (and I believe it should still work with google's entity ID set in both)
| | Entity ID | `https://authentik.company` | | ||
| | Name ID format | EMAIL | | ||
| | Name ID | Basic Information › Primary Email | | ||
| | Signed Response | Enabled ✅ | |
| @@ -1,5 +1,7 @@ | |||
| --- | |||
| title: Google | |||
| title: Integrate with Google Cloud | |||
There was a problem hiding this comment.
| title: Integrate with Google Cloud | |
| title: Google Cloud (with OAuth) |
There was a problem hiding this comment.
The title shown in the navigation pane on left should be the same as the title at the top of the page (consistency in what-I click-is-what-I-shoud-see)... and I don't think we should use the word "Integrate" because we want a distinction between what we are calling Integrations and what we call Sources. This docs is about using Google as a source (haha correct me if I am wrong, quite possible!).
And is it specifically OAuth, this particular setup?
|
|
||
| ## SAML Authentication Flow | ||
|
|
||
| This sequence diagram shows a high-level flow between user, authentik, Google, and the target application. |
There was a problem hiding this comment.
Do we need to specify Google Workspace, Google Cloud, Google Google... ?
|
|
||
| In short, the user navigates to the application, is redirected to authentik, chooses Google Workspace as the authentication method, authenticates with Google, and is redirected back to the application. | ||
|
|
||
| The key characteristic that makes this an idP-to-idP flow is that Authentik is acting as an intermediary identity provider, brokering trust between your application and Google Workspace. |
There was a problem hiding this comment.
| The key characteristic that makes this an idP-to-idP flow is that Authentik is acting as an intermediary identity provider, brokering trust between your application and Google Workspace. | |
| The key characteristic that makes this an idP-to-idP flow is that authentik is acting as an intermediary identity provider, brokering trust between your application and Google Workspace. |
|
|
||
| --- | ||
|
|
||
| ## Integration |
There was a problem hiding this comment.
| ## Integration | |
| ## Preparation |
There was a problem hiding this comment.
Let's keep the Preparation section title as is; it's a clear indicator that these things need to be done/known. And for consistency with other Source docs, which yeah are kinda a hot mess, but are consistent on this Preparation section. Also I'd like to avoid the word integration (even though it clearly in an integration haha).
|
|
||
| ## Integration | ||
|
|
||
| By the end of this integration, your authentik instance will allow users to authenticate using their Google Workspace credentials. |
There was a problem hiding this comment.
@teffen you and I had a good convo the other day about our need to make it more clear at the beginning of each page what exactly the page is about, what the task/goal of the process described on the page is. This sort of sentence ("By the end of this integration, your authentik instance will allow users to authenticate using their Google Workspace credentials.") is really what we need at very top of page. I'll go back up and make a suggestion.
|
|
||
| :::info | ||
|
|
||
| The following placeholders are used in this guide: |
There was a problem hiding this comment.
I have come to the realization that I am not a fan of using a table for such a short list of values. If there were many many values then perhaps. But adding a table here is a lot more "visual load" than I think is needed. Also... it would again be inconsistent. For across-many-docs changes like this, let's look at doing a separate PR that would change it everywhere (a huge task that I don't thiink we need to undertake right now).
|
|
||
| By the end of this integration, your authentik instance will allow users to authenticate using their Google Workspace credentials. | ||
|
|
||
| You'll need to have authentik instance running and accessible on an HTTPS domain, and a Google Workspace domain with super-administrator access. |
There was a problem hiding this comment.
I like the friendliness of this tone.. am not sure I like it better than the lean-mean bullet points normally seen in a Prerequsites section (that people need to be able to quickly scan). But let's leave it for now and think on it and get feedback.
|
|
||
| ::: | ||
|
|
||
| ## Google Workspace Configuration |
There was a problem hiding this comment.
| ## Google Workspace Configuration | |
| ## Google Workspace configuration |
|
|
||
| ## Google Workspace Configuration | ||
|
|
||
| We'll need some information from Google to complete the integration, so we'll |
There was a problem hiding this comment.
| We'll need some information from Google to complete the integration, so we'll | |
| We'll need some information from Google to complete the integration, so |
| We'll need some information from Google to complete the integration, so we'll | ||
| start by logging into [Workspace Admin Console](https://admin.google.com/) as a super-admin. | ||
|
|
||
| ### Creating a new app |
There was a problem hiding this comment.
| ### Creating a new app | |
| ### Create a new application |
There was a problem hiding this comment.
We moved away from gerunds, and lets spell out application in almost all cases.
| From the Workspace Admin Console, navigate to the _Apps_ section, and then to _Web and mobile apps_. | ||
| Continue by expanding the **Add app** dropdown and selecting **Add custom SAML app.** | ||
|
|
||
| Within the app creation page, fill in the following fields with your desired values: |
There was a problem hiding this comment.
| Within the app creation page, fill in the following fields with your desired values: | |
| Within the app creation page, define the following **Name** and **Description** for the new application. |
There was a problem hiding this comment.
Because these are pretty basics fields, I don't think we need to list them out in a table. Bolding the field name and reducing it to one sentence helps keep the doc "lean".
|
|
||
| Within the app creation page, fill in the following fields with your desired values: | ||
|
|
||
| | Field | Value | |
There was a problem hiding this comment.
Let's remove the table and just mention the filed names inlne.
|
|
||
| ### Google Identity Provider details | ||
|
|
||
| Next, you'll be presented with information we'll need to configure authentik. Under _Option 2_, copy the SSO URL and download the certificate. |
There was a problem hiding this comment.
Is Option 2 a UI component, a tab... an area of the UI/page? If it's a UI element or label, etc., it should be bold. Per Style Guide, we use italics for variables (and for emphasis lol).
Can we provide a bit more info about where to find this Option 2?
|
|
||
| We'll now configure authentik to accept SAML authentication from Google Workspace. | ||
|
|
||
| Start by logging into your authentik instance as an administrator and navigating to the _Admin Interface_. |
There was a problem hiding this comment.
| Start by logging into your authentik instance as an administrator and navigating to the _Admin Interface_. | |
| Start by logging into your authentik instance as an administrator and navigating to the Admin Interface. |
There was a problem hiding this comment.
We don't do any special formatting for the Admin interface, since it is not really a UI component or element... it is the UI. ;-)
| | --------------------------------- | -------------- | | ||
| | Basic Information › Primary Email | `email` | | ||
|
|
||
| ### Enable the app for your organization |
There was a problem hiding this comment.
| ### Enable the app for your organization | |
| ### Enable the application for your organization |
|
|
||
| ### Enable the app for your organization | ||
|
|
||
| Finally, we complete the app creation process by saving the configuration. |
There was a problem hiding this comment.
| Finally, we complete the app creation process by saving the configuration. | |
| Finally, we complete the application creation process by saving the configuration. |
|
|
||
| Keep these values handy in your text editor, as we'll need them later. | ||
|
|
||
| ### Attribute Mapping |
There was a problem hiding this comment.
| ### Attribute Mapping | |
| ### Attribute mapping |
| | --------------- | --------------------------------------------------- | | ||
| | ACS URL | `https://authentik.company/source/saml/google/acs/` | | ||
| | Entity ID | `https://authentik.company` | | ||
| | Name ID format | EMAIL | |
There was a problem hiding this comment.
IS EMAIL the literal value that they enter? For Name ID, what do they enter? (Also we need to say "email address" not just "email".)
| @@ -0,0 +1,197 @@ | |||
| --- | |||
| title: Google Workspace with SAML | |||
There was a problem hiding this comment.
| title: Google Workspace with SAML | |
| title: Google Workspace (with SAML) |
| @@ -0,0 +1,197 @@ | |||
| --- | |||
| title: Google Workspace with SAML | |||
| sidebar_label: Workspace SAML | |||
There was a problem hiding this comment.
| sidebar_label: Workspace SAML | |
| sidebar_label: Google Workspace (SAML) |
| @@ -1,5 +1,7 @@ | |||
| --- | |||
| title: Google | |||
| title: Integrate with Google Cloud | |||
| sidebar_label: Google Cloud OAuth | |||
There was a problem hiding this comment.
| sidebar_label: Google Cloud OAuth | |
| sidebar_label: Google Cloud (OAuth) |
| @@ -79,7 +81,7 @@ Here is an example of a complete authentik Google OAuth Source | |||
| Save, and you now have Google as a source. | |||
|
|
|||
| :::note | |||
| For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page). | |||
| For more details on how-to have the new source display on the Login Page see [here](../../../index.md#add-sources-to-default-login-page). | |||
There was a problem hiding this comment.
| For more details on how-to have the new source display on the Login Page see [here](../../../index.md#add-sources-to-default-login-page). | |
| For more details on how to have the new source display on the Login Page see [here](../../../index.md#add-sources-to-default-login-page). |
| --- | ||
|
|
||
| <span className="badge badge--primary">Support level: authentik</span> | ||
|
|
There was a problem hiding this comment.
| This topic covers configuring authentik to authenticate users with their Google Workspace credentials. | |
|
|
||
| ### Service Provider details | ||
|
|
||
| We'll need to provide Google with some information about our authentik instance, specifically the Assertion Consumer Service (ACS) URL. This URL is where Google will send the SAML response after a user has authenticated. We'll also need to provide the Entity ID, which can be any unique identifier, but we recommend using the URL of your authentik instance. |
There was a problem hiding this comment.
| We'll need to provide Google with some information about our authentik instance, specifically the Assertion Consumer Service (ACS) URL. This URL is where Google will send the SAML response after a user has authenticated. We'll also need to provide the Entity ID, which can be any unique identifier, but we recommend using the URL of your authentik instance. | |
| We'll need to provide Google with some information about our authentik instance, specifically the Assertion Consumer Service (ACS) URL. This URL is where Google sends the SAML response after a user is authenticated. We'll also need to provide the Entity ID, which can be any unique identifier, but we recommend using the URL of your authentik instance. |
|
|
||
| Finally, we complete the app creation process by saving the configuration. | ||
|
|
||
| You should now see the new app in the list of SAML apps. View the app details and confirm that the SSO URL and Entity ID are correct. Note that you may need to **enable the app** for your organization to allow users to authenticate. |
There was a problem hiding this comment.
| You should now see the new app in the list of SAML apps. View the app details and confirm that the SSO URL and Entity ID are correct. Note that you may need to **enable the app** for your organization to allow users to authenticate. | |
| You should now see the new application in the list of SAML apps. View the application details and confirm that the SSO URL and Entity ID are correct. Note that you may need to **enable the app** for your organization to allow users to authenticate. |
|
|
||
| --- | ||
|
|
||
| ## authentik Configuration |
There was a problem hiding this comment.
| ## authentik Configuration | |
| ## authentik configuration |
|
|
||
| ### Creating a Federation Source | ||
|
|
||
| From the admin interface, navigate to _Directory_ › _Federation & Social login_ and press **Create**. |
There was a problem hiding this comment.
| From the admin interface, navigate to _Directory_ › _Federation & Social login_ and press **Create**. | |
| In the admin interface, navigate to **Directory -> Federation & Social login** and press **Create**. |
|
|
||
| From the admin interface, navigate to _Directory_ › _Federation & Social login_ and press **Create**. | ||
|
|
||
| Within the new source dialog, choose **SAML Source** and continue by filling in the following fields with your desired values: |
There was a problem hiding this comment.
| Within the new source dialog, choose **SAML Source** and continue by filling in the following fields with your desired values: | |
| In the **New source** modal, choose **SAML Source** and continue by filling in the following fields: |
| | Slug | `google` | | ||
|
|
||
| :::info | ||
|
|
|
|
||
| Heads up! Your choice of `slug` should match the ACS URL you provided to Google Workspace. | ||
| You can choose a different slug, but you will need to update the ACS URL in Google Workspace to match. | ||
|
|
|
|
||
| ::: | ||
|
|
||
| #### Protocol Settings |
There was a problem hiding this comment.
| #### Protocol Settings | |
| #### Protocol settings |
| | SSO URL | `https://accounts.google.com/o/saml2/idp?idpid=#########` | | ||
| | Entity ID/Issuer | `https://authentik.company` | | ||
|
|
||
| #### Advanced Protocol Settings |
There was a problem hiding this comment.
| #### Advanced Protocol Settings | |
| #### Advanced protocol settings |
| | | | | ||
| | ---------------- | --------------------------------------------------------- | | ||
| | SSO URL | `https://accounts.google.com/o/saml2/idp?idpid=#########` | | ||
| | Entity ID/Issuer | `https://authentik.company` | |
There was a problem hiding this comment.
| | Entity ID/Issuer | `https://authentik.company` | | |
| | Issuer (Entity ID) | `https://authentik.company` | |
There was a problem hiding this comment.
want to reflect the UI as closely as possible.
| | Field | Value | | ||
| | ------------------------- | ------------- | | ||
| | Allow idP-initiated Login | Enabled ✅ | | ||
| | NameID Policy | Email Address | |
There was a problem hiding this comment.
| | NameID Policy | Email Address | | |
| | NameID Policy | Email address | |
| | Allow idP-initiated Login | Enabled ✅ | | ||
| | NameID Policy | Email Address | | ||
|
|
||
| Finally, save the source configuration and confirm the app is present in the list of federated sources. |
There was a problem hiding this comment.
| Finally, save the source configuration and confirm the app is present in the list of federated sources. | |
| Finally, save the source configuration and confirm the application is present in the list of federated sources. |
|
|
||
| ### `403 app_not_enabled_for_user` | ||
|
|
||
| In the Google Workspace Admin Console, go to Menu › Apps › Web and mobile apps. |
There was a problem hiding this comment.
| In the Google Workspace Admin Console, go to Menu › Apps › Web and mobile apps. | |
| In the Google Workspace Admin Console, go to **Menu -> Apps -> Web and mobile apps**. |
|
|
||
| In the Google Workspace Admin Console, go to Menu › Apps › Web and mobile apps. | ||
|
|
||
| 1. In the app list, locate the SAML app generating the error. |
There was a problem hiding this comment.
| 1. In the app list, locate the SAML app generating the error. | |
| 1. In the application list, locate the SAML app generating the error. |
| In the Google Workspace Admin Console, go to Menu › Apps › Web and mobile apps. | ||
|
|
||
| 1. In the app list, locate the SAML app generating the error. | ||
| 2. Click the app to open its Settings page. |
There was a problem hiding this comment.
| 2. Click the app to open its Settings page. | |
| 2. Click the application to open its Settings page. |
|
|
||
| 1. In the app list, locate the SAML app generating the error. | ||
| 2. Click the app to open its Settings page. | ||
| 3. Click User access. |
There was a problem hiding this comment.
| 3. Click User access. | |
| 3. Click **User access**. |
| 1. In the app list, locate the SAML app generating the error. | ||
| 2. Click the app to open its Settings page. | ||
| 3. Click User access. | ||
| 4. Turn the app ON for everyone or for the user’s organization. |
There was a problem hiding this comment.
| 4. Turn the app ON for everyone or for the user’s organization. | |
| 4. Turn the application ON for everyone or for the user’s organization. |
|
|
||
| This may take a few minutes to propagate, so try logging in again after a short wait. | ||
|
|
||
| ## External links |
There was a problem hiding this comment.
I think I like this new addition... though as I mentioned, it creates a maintenance load to verify these links don;t change, and to add this section to the other docs. Let's leave it and think on the ROI. ;-)
There was a problem hiding this comment.
Thanks so much @GirlBossRush for this new doc! Apologies there are so very many edits; don't be daunted, they are mostly Style Guide adherence things, and you can click Accept suggestion and move through most of them quickly. Thank you also for introducing some new ways of presenting info, and the friendly tone.
Details
This pull request documents how to integrate Google Workspaces into authentik as a SAML identity provider.
Closes #5035
Checklist
ak test authentik/)make lint-fix)If an API change has been made
make gen-build)If changes to the frontend have been made
make web)If applicable
make website)