website/integations/services: Slack integration docs by tanberry · Pull Request #9933 · goauthentik/authentik

tanberry · 2024-05-31T19:17:53Z

First draft, needs a thorough tech review by @BeryJu and anyone else who has Slack admin knowledge/access. The last section on setting up Slack feels a bit hand-wavy... and I am not sure that I caught of all the steps around setting up/implementing the property mappings.

The documentation has been updated
The documentation has been formatted (make website)

netlify · 2024-05-31T19:18:08Z

✅ Deploy Preview for authentik-storybook canceled.

Name	Link
🔨 Latest commit	`bc6e794`
🔍 Latest deploy log	https://app.netlify.com/sites/authentik-storybook/deploys/667061d6644c690008d87715

netlify · 2024-05-31T19:18:08Z

✅ Deploy Preview for authentik-docs ready!

Name	Link
🔨 Latest commit	`bc6e794`
🔍 Latest deploy log	https://app.netlify.com/sites/authentik-docs/deploys/667061d6e0f28e0008a60924
😎 Deploy Preview	https://deploy-preview-9933--authentik-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

codecov · 2024-05-31T19:24:31Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.62%. Comparing base (66a1675) to head (bc6e794).
Report is 142 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9933      +/-   ##
==========================================
- Coverage   92.63%   92.62%   -0.02%     
==========================================
  Files         710      711       +1     
  Lines       34767    34915     +148     
==========================================
+ Hits        32206    32339     +133     
- Misses       2561     2576      +15

Flag	Coverage Δ
e2e	`49.55% <ø> (-0.12%)`	⬇️
integration	`25.41% <ø> (-0.09%)`	⬇️
unit	`90.09% <ø> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

github-actions · 2024-05-31T20:01:54Z

authentik PR Installation instructions

Instructions for docker-compose

Add the following block to your .env file:

AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-ghcr.io/goauthentik/dev-server:gh-bc6e7942ea51d18495c4e881884bda01a0539eae
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s

For arm64, use these values:

AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-ghcr.io/goauthentik/dev-server:gh-bc6e7942ea51d18495c4e881884bda01a0539eae-arm64
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s

Afterwards, run the upgrade commands from the latest release notes.

Instructions for Kubernetes

Add the following block to your values.yml file:

authentik:
    outposts:
        container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
image:
    repository: ghcr.io/goauthentik/dev-server
    tag: gh-ghcr.io/goauthentik/dev-server:gh-bc6e7942ea51d18495c4e881884bda01a0539eae

For arm64, use these values:

authentik:
    outposts:
        container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
image:
    repository: ghcr.io/goauthentik/dev-server
    tag: gh-ghcr.io/goauthentik/dev-server:gh-bc6e7942ea51d18495c4e881884bda01a0539eae-arm64

Afterwards, run the upgrade commands from the latest release notes.

dominic-r · 2024-06-01T03:20:58Z

website/integrations/services/slack/index.md

+>
+> -- https://slack.com
+
+## Preparation


I know the "the following placeholders will be used" is a formality and is in all pages but there is no real reson to add it here if the placeholders are never used.

Ah, @4d62 so are they truly never used when integrated Slack? Then I agree, absolutely, let's remove that whole section.

Is there a simple formula for knowing which integrations will require those placeholders?

@tanberry

they truly never used when integrated Slack?

The way you wrote the documentation, authentik.company is never used. For slack.company, it's possible to use a custom domain or a .slack.com domain if i remember correctly. You could probably do something like "slack.company or my-workspace.slack.com is the FQDN of your Slack instance".

Is there a simple formula for knowing which integrations will require those placeholders?

A good rule of thumb is to add the install placeholder if the application needs to be self-hosted by the users and the authentik placeholder everywhere (e.g., my GitLab instance's URL is different from Jens'). For applications that are not self-hosted by the user (e.g., Amazon AWS, where everyone uses the same https://signin.aws.amazon.com/saml URL), only the authentik.company line should be added.

Great, thanks so much for this info. I'll create an internal task for me to go through the integrations and edit as needed... I should also add this info to our template... might be a while before I get to it but good to have a better understanding. Thanks!

rissson

I cannot review the slack part as I don't have permissions to see what we currently have set.

website/integrations/services/slack/index.md

rissson · 2024-06-03T16:32:25Z

website/integrations/services/slack/index.md

+
+### Step 1. Create custom property mappings
+
+Your Slack integration requires property mappings for `User.Email` and `User.Username` so that authetnik can retrieve and map these values from Slack.


We have one additional one for our slack workspace. The SAML attribute name is first_name and the expression is:

parts = request.user.name.split(" ") if len(parts) < 1: return request.user.name return parts[0]

Not sure if it's required though.

@BeryJu can you please confirm (or deny lol) if this property mapping is required? Thanks!

It's not required (see https://slack.com/help/articles/205168057-Custom-SAML-single-sign-on, and we should probably link that page in this doc too)

website/integrations/services/slack/index.md

dominic-r

forgot to click submit sorry for delay

dominic-r · 2024-06-10T23:10:25Z

website/integrations/services/slack/index.md

+>
+> -- https://slack.com
+
+## Preparation


@tanberry

they truly never used when integrated Slack?

The way you wrote the documentation, authentik.company is never used. For slack.company, it's possible to use a custom domain or a .slack.com domain if i remember correctly. You could probably do something like "slack.company or my-workspace.slack.com is the FQDN of your Slack instance".

Is there a simple formula for knowing which integrations will require those placeholders?

A good rule of thumb is to add the install placeholder if the application needs to be self-hosted by the users and the authentik placeholder everywhere (e.g., my GitLab instance's URL is different from Jens'). For applications that are not self-hosted by the user (e.g., Amazon AWS, where everyone uses the same https://signin.aws.amazon.com/saml URL), only the authentik.company line should be added.

dominic-r · 2024-06-11T02:03:34Z

also added a few comments on the style guide

website/integrations/services/slack/index.md

dominic-r · 2024-06-11T19:14:45Z

website/integrations/services/slack/index.md

+5. Click **Create**.
+
+:::info
+After you have created the provider and application, and the application is connected to the provider (Step 3 above) the **Overview** tab on the provider's detail page in the Admin UI will display additional information that you will need to configure Slack, using the following steps.


Not sure "above" is needed

True... but it is intended to ease the cognitive load of reading a bit... :-)

In that case this pr seems fine by me!

dominic-r

🚀

BeryJu · 2024-06-12T04:07:25Z

website/integrations/services/slack/index.md

+1. Log in to the Slack Admin Dashboard.
+2. Navigate to the **Configure SAML Authentication** page.
+3. Enter the following values:
+    - **SAML 2.0 Endpoint (HTTP)**: copy/paste in the **SSO URL (Redirect)** URL from the provider that you created in authentik.


This is where I'd usually use the placeholder authentik.company to give an example URL, but I suppose we don't have to do that

Ohhhh, let's do include an example, please @BeryJu. So would this work (but with proper formatting for the italics):

https://_authentik.company_/applications/saml/slack/sso/binding/redirect/

If we use it in an example here, I think I should add it back to the top of this page, under Preparation.

website/integrations/services/slack/index.md

kensternberg-authentik

No complaints.

kensternberg-authentik

Still looks fine.

* main: (1457 commits) root: use custom model serializer that saves m2m without bulk (#10139) core: bump urllib3 from 2.2.1 to 2.2.2 (#10143) ci: bump docker/build-push-action from 5 to 6 (#10144) web: bump the storybook group in /web with 7 updates (#10147) web: bump ws from 8.16.0 to 8.17.1 in /web (#10149) web: fix needed because recent upgrade to task breaks spinner button (#10142) core: include version in built JS files (#9558) website/integations/services: Slack integration docs (#9933) web: fix early modal stack depletion (#10068) website: bump react-tooltip from 5.26.4 to 5.27.0 in /website (#10129) web: bump @patternfly/elements from 3.0.1 to 3.0.2 in /web (#10132) core: bump github.com/gorilla/sessions from 1.2.2 to 1.3.0 (#10135) web: bump chromedriver from 126.0.0 to 126.0.1 in /tests/wdio (#10136) core: bump github.com/spf13/cobra from 1.8.0 to 1.8.1 (#10133) core, web: update translations (#10127) core: bump ruff from 0.4.8 to 0.4.9 (#10128) core: bump goauthentik.io/api/v3 from 3.2024042.11 to 3.2024042.13 (#10134) core, web: update translations (#10118) translate: Updates for file web/xliff/en.xlf in zh-Hans (#10121) translate: Updates for file web/xliff/en.xlf in zh_CN (#10120) ...

* main: (29 commits) web: fix docker build for non-release versions (#10154) root: makefile: add codespell to make-website (#10116) root: use custom model serializer that saves m2m without bulk (#10139) core: bump urllib3 from 2.2.1 to 2.2.2 (#10143) ci: bump docker/build-push-action from 5 to 6 (#10144) web: bump the storybook group in /web with 7 updates (#10147) web: bump ws from 8.16.0 to 8.17.1 in /web (#10149) web: fix needed because recent upgrade to task breaks spinner button (#10142) core: include version in built JS files (#9558) website/integations/services: Slack integration docs (#9933) web: fix early modal stack depletion (#10068) website: bump react-tooltip from 5.26.4 to 5.27.0 in /website (#10129) web: bump @patternfly/elements from 3.0.1 to 3.0.2 in /web (#10132) core: bump github.com/gorilla/sessions from 1.2.2 to 1.3.0 (#10135) web: bump chromedriver from 126.0.0 to 126.0.1 in /tests/wdio (#10136) core: bump github.com/spf13/cobra from 1.8.0 to 1.8.1 (#10133) core, web: update translations (#10127) core: bump ruff from 0.4.8 to 0.4.9 (#10128) core: bump goauthentik.io/api/v3 from 3.2024042.11 to 3.2024042.13 (#10134) core, web: update translations (#10118) ...

* web/automated-testing: (280 commits) Merge missed something. web: fix docker build for non-release versions (#10154) root: makefile: add codespell to make-website (#10116) root: use custom model serializer that saves m2m without bulk (#10139) core: bump urllib3 from 2.2.1 to 2.2.2 (#10143) ci: bump docker/build-push-action from 5 to 6 (#10144) web: bump the storybook group in /web with 7 updates (#10147) web: bump ws from 8.16.0 to 8.17.1 in /web (#10149) web: fix needed because recent upgrade to task breaks spinner button (#10142) core: include version in built JS files (#9558) website/integations/services: Slack integration docs (#9933) Somehow missed these in the merge. web: fix early modal stack depletion (#10068) website: bump react-tooltip from 5.26.4 to 5.27.0 in /website (#10129) web: bump @patternfly/elements from 3.0.1 to 3.0.2 in /web (#10132) core: bump github.com/gorilla/sessions from 1.2.2 to 1.3.0 (#10135) web: bump chromedriver from 126.0.0 to 126.0.1 in /tests/wdio (#10136) core: bump github.com/spf13/cobra from 1.8.0 to 1.8.1 (#10133) core, web: update translations (#10127) core: bump ruff from 0.4.8 to 0.4.9 (#10128) ...

* main: (27 commits) root: use custom model serializer that saves m2m without bulk (#10139) core: bump urllib3 from 2.2.1 to 2.2.2 (#10143) ci: bump docker/build-push-action from 5 to 6 (#10144) web: bump the storybook group in /web with 7 updates (#10147) web: bump ws from 8.16.0 to 8.17.1 in /web (#10149) web: fix needed because recent upgrade to task breaks spinner button (#10142) core: include version in built JS files (#9558) website/integations/services: Slack integration docs (#9933) web: fix early modal stack depletion (#10068) website: bump react-tooltip from 5.26.4 to 5.27.0 in /website (#10129) web: bump @patternfly/elements from 3.0.1 to 3.0.2 in /web (#10132) core: bump github.com/gorilla/sessions from 1.2.2 to 1.3.0 (#10135) web: bump chromedriver from 126.0.0 to 126.0.1 in /tests/wdio (#10136) core: bump github.com/spf13/cobra from 1.8.0 to 1.8.1 (#10133) core, web: update translations (#10127) core: bump ruff from 0.4.8 to 0.4.9 (#10128) core: bump goauthentik.io/api/v3 from 3.2024042.11 to 3.2024042.13 (#10134) core, web: update translations (#10118) translate: Updates for file web/xliff/en.xlf in zh-Hans (#10121) translate: Updates for file web/xliff/en.xlf in zh_CN (#10120) ...

Tana M Berry added 3 commits May 30, 2024 15:30

draft and sidebar

c61851c

added rest of config steps

ce180b1

formatting

7a86d06

tanberry requested a review from a team as a code owner May 31, 2024 19:17

tanberry requested a review from BeryJu May 31, 2024 19:18

typo

e21f764

dominic-r reviewed Jun 1, 2024

View reviewed changes

rissson requested changes Jun 3, 2024

View reviewed changes

tanberry requested review from dominic-r and rissson June 10, 2024 22:28

dominic-r requested changes Jun 11, 2024

View reviewed changes

Tana M Berry added 5 commits June 11, 2024 13:17

tweaks

e5e6332

contributors edit

409e45f

fixed support badge

3c19d96

fix formatting

c2c1d9a

marc edit

a7e835f

tanberry requested a review from dominic-r June 11, 2024 19:09

dominic-r requested changes Jun 11, 2024

View reviewed changes

website/integrations/services/slack/index.md Outdated Show resolved Hide resolved

dominic-r requested changes Jun 11, 2024

View reviewed changes

4d62 edit

676ef9f

dominic-r approved these changes Jun 11, 2024

View reviewed changes

BeryJu reviewed Jun 12, 2024

View reviewed changes

rissson requested changes Jun 12, 2024

View reviewed changes

website/integrations/services/slack/index.md Outdated Show resolved Hide resolved

website/integrations/services/slack/index.md Outdated Show resolved Hide resolved

Tana M Berry added 2 commits June 17, 2024 10:30

tech edits

e17434a

fix prettier error

84c4efc

kensternberg-authentik approved these changes Jun 17, 2024

View reviewed changes

add link from Jens

bc6e794

tanberry requested a review from rissson June 17, 2024 16:22

kensternberg-authentik approved these changes Jun 17, 2024

View reviewed changes

rissson approved these changes Jun 17, 2024

View reviewed changes

tanberry merged commit bdde677 into main Jun 17, 2024

tanberry deleted the slack-int branch June 17, 2024 20:20


		### Step 1. Create custom property mappings

		Your Slack integration requires property mappings for `User.Email` and `User.Username` so that authetnik can retrieve and map these values from Slack.

Uh oh!

Conversation

tanberry commented May 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented May 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for authentik-storybook canceled.

Uh oh!

netlify bot commented May 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for authentik-docs ready!

Uh oh!

codecov bot commented May 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions bot commented May 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rissson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dominic-r left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dominic-r commented Jun 11, 2024

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dominic-r left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tanberry Jun 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kensternberg-authentik left a comment

Choose a reason for hiding this comment

Uh oh!

kensternberg-authentik left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

tanberry commented May 31, 2024 •

edited

Loading

netlify bot commented May 31, 2024 •

edited

Loading

netlify bot commented May 31, 2024 •

edited

Loading

codecov bot commented May 31, 2024 •

edited

Loading

github-actions bot commented May 31, 2024 •

edited

Loading

tanberry Jun 12, 2024 •

edited

Loading