website/integations/services: Slack integration docs

[tanberry]

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]

✅ Deploy Preview for authentik-storybook canceled.

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

[netlify]

✅ 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]

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]

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.

[4d62]

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.

[tanberry]

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?

[4d62]

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

[tanberry]

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.

[rissson]

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.

[tanberry]

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

[BeryJu]

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)

[4d62]

forgot to click submit sorry for delay

[4d62]

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

[4d62]

also added a few comments on the style guide

[4d62]

Not sure "above" is needed

[tanberry]

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

[4d62]

In that case this pr seems fine by me!

[4d62]

🚀

[BeryJu]

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

[tanberry]

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.

[kensternberg-authentik]

No complaints.

[kensternberg-authentik]

Still looks fine.