Integrate with AppFlowy

import TabItem from "@theme/TabItem"; import Tabs from "@theme/Tabs";

What is AppFlowy

AppFlowy is an open-source workspace collaboration platform (similar to Notion) that lets teams create, manage, and collaborate on documents, databases, and projects.

-- https://appflowy.com

Preparation

The following placeholders are used in this guide:

• appflowy.company is the FQDN of the AppFlowy installation.
• authentik.company is the FQDN of the authentik installation.

:::info This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. :::

authentik configuration

To support the integration of AppFlowy with authentik, you need to create a certificate and an application/provider pair in authentik.

Create a certificate-key pair

1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to System > Certificates and click Generate.
3. Set the following required fields:
   • Common name: set an appropriate name (For example: AppFlowyCertSAML).
   • Validity days: set an appropriate certificate validity period (or keep the default value of 365).
   • Private key algorithm: RSA
4. Click Generate and take note of the Certificate and Private key values as they will be required later on.

Create an application and provider in authentik

1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to Applications > Applications and click Create with Provider to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.)
   • Application: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings.
   • Choose a Provider type: select SAML Provider as the provider type.
   • Configure the Provider: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations.
     • ACS URL: https://appflowy.company/gotrue/sso/saml/acs
     • Issuer: authentik
     • Service Provider Binding: Post
     • Audience: https://appflowy.company/gotrue/sso/saml/metadata
     • Under Advanced protocol settings:
       • Signing certificate: select the certificate created earlier
       • Sign assertions: enabled
       • Sign responses: enabled
       • Verification certificate: select the same certificate
       • NameID Property Mapping: authentik default SAML Mapping: Email
       • Default relay state: https://appflowy.company/auth/callback
   • Configure Bindings (optional): you can create a binding (policy, group, or user) to manage the listing and access to applications on a user's My applications page.
3. Click Submit to create the application and provider.

Copy metadata download link

1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to Applications > Providers and click on the name of the provider that you created in the previous section.
3. Under Related objects > Metadata, click on Copy download URL. This URL is your SAML Metadata URL and it will be required in the next section.

AppFlowy configuration

Configure AppFlowy Cloud to use authentik as its SAML IdP.

Convert the certificate and private key

AppFlowy requires the private key in PKCS#1 and base64 (single-line) format, so you'll need to convert the certificate and private key to these formats.

1. Convert the private key to PKCS#1 format:

openssl rsa -in <certificate_private_key>.pem -traditional -out key_pkcs1.pem

2. Convert the PKCS#1 private key to a single-line base64 string:

sed -n '/^-----BEGIN RSA PRIVATE KEY-----$/,/^-----END RSA PRIVATE KEY-----$/p' key_pkcs1.pem      | grep -v '^-----'      | tr -d '\n'

The output of this command will be required for the GOTRUE_SAML_PRIVATE_KEY value in a later section.

3. Convert the certificate to a single-line format with \n escapes:

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0}' <certificate>.pem

The output of this command will be required for the AUTH_SAML_CERT value in a later section. See the AppFlowy documentation for more information.

1. Convert the private key to PKCS#1 format:

openssl rsa -in <certificate_private_key>.pem -traditional -out key_pkcs1.pem

2. Convert the PKCS#1 private key to a single-line base64 string:

(Get-Content key_pkcs1.pem) -join "`n" `
  | Select-String -Pattern '^-{5}' -NotMatch `
  | ForEach-Object { $_ -replace '\s','' } `
  | ForEach-Object { $_ } `
  | Out-String -Stream | ForEach-Object { $_.Trim() }

3. Convert the certificate to a single-line format with \n escapes:

(Get-Content <certificate>.pem) `
  | ForEach-Object { ($_ -replace "`r","") + "\n" } `
  | Out-String -Stream `
  | ForEach-Object { $_.TrimEnd() } `
  | ForEach-Object { $_ -replace "`n", "\\n" }

The output of this command will be required for the AUTH_SAML_CERT value in a later section.

Configure Metadata URL

1. Log in the AppFlowy Admin Console at https://appflowy.company/console.
2. Navigate to Admin > Create SSO.
3. Set the Metadata URL to the SAML Metadata URL from authentik.
4. Click Create.

Configure AppFlowy environment file

Add the following environment variables to your AppFlowy installation:

AUTH_SAML_ENABLED=true
GOTRUE_SAML_ENABLED=true

AUTH_SAML_ENTRY_POINT="https://authentik.company/application/saml/<application_slug>/sso/binding/post"

AUTH_SAML_ISSUER="authentik"
AUTH_SAML_CALLBACK_URL="https://appflowy.company/gotrue/sso/saml/acs"
AUTH_SAML_DEFAULT_REDIRECT_URL="https://appflowy.company/app"

# From the conversion steps above
GOTRUE_SAML_PRIVATE_KEY="<Base64 private key (single line)>"
AUTH_SAML_CERT="<Certificate with \\n escapes (single line)>"

:::info Ensure GOTRUE_DISABLE_SIGNUP=false is set so that first-time SAML users can sign in. :::

Restart AppFlowy to apply the changes.

Configuration verification

To confirm that authentik is properly configured with AppFlowy, log out and then log back in by clicking the application created for AppFlowy in the authentik User interface. You should be automatically redirected and signed in to AppFlowy.

Resources

• AppFlowy Documentation - How to login using Okta SAML 2.0
• AppFlowy Documentation - How to login using SAML 2.0