website: Flesh out docs split.
website: Copy files during build. website: Allow for mixed env builds. website: Reduce build size. website: Expose build. website: Add build memory debugging. WIP: Disable broken links check to compare memory usage. website: Update deps. website: Clean up API paths. website: Flesh out 3.8 fixes. Format. website: Update ignore paths. Website: Clean up integrations build. website: Fix paths. website: Optimize remark. website: Update deps. website: Format. website: Remove linking. website: Fix paths. wip: Attempt API only build. Prep. Migrate render to runtime. Tidy sidebar. Clean up templates. docs: Move directory. WIP docs: Flesh out split. website: Fix issue where routes have collisions.
This commit is contained in:
Teffen Ellis
36
docs/integrations/applications.mdx
Normal file
36
docs/integrations/applications.mdx
Normal file
@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Integrate with Applications
|
||||
sidebar_label: Applications
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
import SupportBadge from "@goauthentik/docusaurus-theme/components/SupportBadge.tsx";
|
||||
|
||||
import DocCardList from "@theme/DocCardList";
|
||||
|
||||
# Applications
|
||||
|
||||
Most third-party services that support authentication protocols such as SAML, OAuth, and OpenID Connect can be integrated with authentik, allowing users to log in to these services using their authentik credentials.
|
||||
|
||||
If you don't see an application you're looking for, let us know. You can reach us on [GitHub](https://github.com/goauthentik/authentik), [Discord](https://goauthentik.io/discord), or via email to [hello@goauthentik.io](mailto:hello@goauthentik.io). You can also add your own documentation for a new application integration following [these instructions](#add-a-new-application).
|
||||
|
||||
All documented app integrations will have one of these badges:
|
||||
|
||||
- <SupportBadge level="community" />: Community maintained.
|
||||
- <SupportBadge level="vendor" />: Supported by the vendor.
|
||||
- <SupportBadge level="authentik" />: Regularly tested by the authentik team.
|
||||
- <SupportBadge level="deprecated" />: Deprecated and may be removed.
|
||||
|
||||
### Add a new application
|
||||
|
||||
<a id="add-new"></a>
|
||||
|
||||
To add documentation for a new application (with support level Community or Vendor), please use the integration template [`service.md`](https://github.com/goauthentik/authentik/blob/main/docs/topics/integrations/template/service.md) file from our GitHub repo. You can download the template file using the following command:
|
||||
|
||||
```shell
|
||||
wget https://raw.githubusercontent.com/goauthentik/authentik/main/docs/topics/integrations/template/service.md
|
||||
```
|
||||
|
||||
## Integration categories
|
||||
|
||||
<DocCardList />
|
||||
@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Integrate with EspoCRM
|
||||
sidebar_label: EspoCRM
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is EspoCRM?
|
||||
|
||||
> EspoCRM is a CRM (customer relationship management) web application that allows users to store, visualize, and analyze their company's business-related relationships such as opportunities, people, businesses, and projects.
|
||||
>
|
||||
> -- https://www.espocrm.com/
|
||||
|
||||
:::warning
|
||||
This guide does _not_ cover Team Mapping. Please refer to EspoCRM's [documentation](https://docs.espocrm.com/administration/oidc/#team-mapping).
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `espocrm.company` is the FQDN of the EspoCRM installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 EspoCRM with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to <kbd>https://<em>espocrm.company</em>/oauth-callback.php</kbd>.
|
||||
- Select any available signing key.
|
||||
- Under **Advanced Protocol Settings**, set **Subject mode** to be `Based on the Users's username`.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## EspoCRM configuration
|
||||
|
||||
To configure EspoCRM for OpenID Connect authentication, navigate to your instance and login as an administrator user. Then, navigate to **Administration** > **Authentication** and select the **OIDC method**. A panel allowing you to configure OIDC settings should appear.
|
||||
|
||||
Configure the following fields:
|
||||
|
||||
- **Client ID**: The Client ID from authentik
|
||||
- **Client Secret**: The Client Secret from authentik
|
||||
- **Authorization Redirect URI**: `https://espocrm.company/oauth-callback.php`
|
||||
- **Fallback Login**: Toggle this option if you wish to have the option to use EspoCRM's integrated login as a fallback.
|
||||
- **Allow OIDC login for admin users**: Toggle this option if you wish to allow administrator users to log in with OIDC.
|
||||
- **Authorization Endpoint**: `https://authentik.company/application/o/authorize`
|
||||
- **Token Endpoint**: `https://authentik.company/application/o/token`
|
||||
- **JSON Web Key Set Endpoint**: `https://authentik.company/application/o/<application_slug>/jwks`
|
||||
- **Logout URL**: `https://authentik.company/application/o/<application_slug>/end_session`
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is properly configured with EspoCRM, log out and log back in via authentik. Clicking the "Login" button on the homepage should redirect you to authentik.
|
||||
|
||||
## Resources
|
||||
|
||||
- [EspoCRM administrator documentation on OpenID Connect authentication](https://docs.espocrm.com/administration/oidc/)
|
||||
@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Integrate with HedgeDoc
|
||||
sidebar_label: HedgeDoc
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is HedgeDoc
|
||||
|
||||
> HedgeDoc lets you create real-time collaborative markdown notes.
|
||||
>
|
||||
> -- https://github.com/hedgedoc/hedgedoc
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `hedgedoc.company` is the FQDN of the HedgeDoc installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 HedgeDoc with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://hedgedoc.company/auth/oauth2/callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## HedgeDoc configuration
|
||||
|
||||
You need to set the following `env` Variables for Docker based installations.
|
||||
|
||||
Set the following values:
|
||||
|
||||
```yaml
|
||||
CMD_OAUTH2_PROVIDERNAME: "authentik"
|
||||
CMD_OAUTH2_CLIENT_ID: "<Client ID from above>"
|
||||
CMD_OAUTH2_CLIENT_SECRET: "<Client Secret from above>"
|
||||
CMD_OAUTH2_SCOPE: "openid email profile"
|
||||
CMD_OAUTH2_USER_PROFILE_URL: "https://authentik.company/application/o/userinfo/"
|
||||
CMD_OAUTH2_TOKEN_URL: "https://authentik.company/application/o/token/"
|
||||
CMD_OAUTH2_AUTHORIZATION_URL: "https://authentik.company/application/o/authorize/"
|
||||
CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR: "preferred_username"
|
||||
CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR: "name"
|
||||
CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR: "email"
|
||||
```
|
||||
@ -0,0 +1,134 @@
|
||||
---
|
||||
title: Integrate with Kimai
|
||||
sidebar_label: Kimai
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Kimai
|
||||
|
||||
> Kimai is a free & open source timetracker. It tracks work time and prints out a summary of your activities on demand. Yearly, monthly, daily, by customer, by project … Its simplicity is its strength. Due to Kimai's browser based interface it runs cross-platform, even on your mobile device.
|
||||
>
|
||||
> -- https://www.kimai.org/about/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `kimai.company` is the FQDN of the Kimai Install
|
||||
- `authentik.company` is the FQDN of the authentik Install
|
||||
- `admin.group` is the authentik group to be made Admin in Kimai
|
||||
|
||||
:::note
|
||||
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 Kimai with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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. Take note of the **slug** as it will be required later.
|
||||
- **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.
|
||||
- Set the **ACS URL** to `https://kimai.company/auth/saml/acs`.
|
||||
- Set the **Audience** to `https://kimai.companyauth/saml`.
|
||||
- Set the **Issuer** to `https://authentik.company`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, select an available signing certificate.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Kimai Configuration
|
||||
|
||||
Paste the following block in your `local.yaml` file, after replacing the placeholder values from above. The file is usually located in `/opt/kimai/config/packages/local.yaml`.
|
||||
|
||||
To get the value for `x509cert`, go to _System_ > _Certificates_, and download the public Signing Certificate. To avoid further problems, concat it into "string format" using e.g.: https://www.samltool.com/format_x509cert.php
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
```yaml
|
||||
# Optionally add this for docker debug-logging
|
||||
# monolog:
|
||||
# handlers:
|
||||
# main:
|
||||
# path: php://stderr
|
||||
|
||||
kimai:
|
||||
saml:
|
||||
activate: true
|
||||
title: Login with authentik
|
||||
mapping:
|
||||
- {
|
||||
saml: $http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress,
|
||||
kimai: email,
|
||||
}
|
||||
- {
|
||||
saml: $http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name,
|
||||
kimai: alias,
|
||||
}
|
||||
roles:
|
||||
attribute: http://schemas.xmlsoap.org/claims/Group
|
||||
mapping:
|
||||
# Insert your roles here (ROLE_USER is added automatically)
|
||||
- { saml: admin.group, kimai: ROLE_ADMIN }
|
||||
connection:
|
||||
# You SAML provider
|
||||
# Your authentik instance, replace https://authentik.company with your authentik URL
|
||||
idp:
|
||||
entityId: "https://authentik.company/"
|
||||
singleSignOnService:
|
||||
url: "https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/"
|
||||
binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
|
||||
# the "single logout" feature was not yet tested, if you want to help, please let me know!
|
||||
singleLogoutService:
|
||||
url: "https://authentik.company/application/saml/<application_slug>/slo/binding/redirect/"
|
||||
binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
|
||||
# Signing certificate from *Advanced protocol settings*
|
||||
x509cert: "XXXXXXXXXXXXXXXXXXXXXXXXXXX=="
|
||||
# Service Provider Data that we are deploying.
|
||||
# Your Kimai instance, replace https://kimai.company with your Kimai URL
|
||||
sp:
|
||||
entityId: "https://kimai.company/"
|
||||
assertionConsumerService:
|
||||
url: "https://kimai.company/auth/saml/acs"
|
||||
binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
|
||||
singleLogoutService:
|
||||
url: "https://kimai.company/auth/saml/logout"
|
||||
binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
|
||||
#privateKey: ''
|
||||
# only set baseurl, if auto-detection doesn't work
|
||||
baseurl: "https://kimai.company/auth/saml/"
|
||||
strict: false
|
||||
debug: true
|
||||
security:
|
||||
nameIdEncrypted: false
|
||||
authnRequestsSigned: false
|
||||
logoutRequestSigned: false
|
||||
logoutResponseSigned: false
|
||||
wantMessagesSigned: false
|
||||
wantAssertionsSigned: false
|
||||
wantNameIdEncrypted: false
|
||||
requestedAuthnContext: true
|
||||
signMetadata: false
|
||||
wantXMLValidation: true
|
||||
signatureAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
|
||||
digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256"
|
||||
contactPerson:
|
||||
technical:
|
||||
givenName: "Kimai Admin"
|
||||
emailAddress: "admin@example.com"
|
||||
organization:
|
||||
en:
|
||||
name: "Kimai"
|
||||
displayname: "Kimai"
|
||||
url: "https://kimai.company"
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Afterwards, either [rebuild the cache](https://www.kimai.org/documentation/cache.html) or restart the docker container.
|
||||
@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Integrate with mailcow
|
||||
sidebar_label: mailcow
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is mailcow
|
||||
|
||||
> mailcow is a Dockerized, open-source groupware and email suite based on Docker. It relies on many well-known and long-used components, which, when combined, result in a comprehensive email server solution.
|
||||
>
|
||||
> -- https://mailcow.email/
|
||||
|
||||
:::info
|
||||
In order to use authentik in mailcow, at least version `2025-03` of mailcow is required.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `mailcow.company` is the FQDN of the mailcow installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 mailcow with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID** and **Client Secret** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://mailcow.company`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## mailcow configuration
|
||||
|
||||
To configure mailcow with authentik, log in as an administrator and navigate to **System** > **Configuration**.
|
||||
Then, go to **Access** > **Identity Provider** and enter the following information in the form:
|
||||
|
||||
- **Identity Provider**: `Generic-OIDC`
|
||||
- **Authorization endpoint**: `https://authentik.company/application/o/authorize/`
|
||||
- **Token endpoint**: `https://authentik.company/application/o/token/`
|
||||
- **User info endpoint**: `https://authentik.company/application/o/userinfo/`
|
||||
- **Client ID**: The `Client ID` from the authentik provider
|
||||
- **Client Secret**: The `Client secret` from the authentik provider
|
||||
- **Redirect Url**: `https://mailcow.company`
|
||||
- **Client Scopes**: `openid profile email`
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is properly configured with mailcow, log out and log back in via authentik.
|
||||
@ -0,0 +1,74 @@
|
||||
---
|
||||
title: Integrate with Mastodon
|
||||
sidebar_label: Mastodon
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Mastodon
|
||||
|
||||
> Mastodon is free and open-source software for running self-hosted social networking services. It has microblogging features similar to Twitter
|
||||
>
|
||||
> -- https://joinmastodon.org/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `mastodon.company` is the FQDN of the mastodon installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Mastodon with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://mastodon.company/auth/auth/openid_connect/callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Mastodon configuration
|
||||
|
||||
Configure Mastodon `OIDC_` settings by editing the `.env.production` and add the following:
|
||||
|
||||
:::warning
|
||||
When using `preferred_username` as the user identifier, ensure that the [Allow users to change username setting](https://docs.goauthentik.io/docs/sys-mgmt/settings#allow-users-to-change-username) is disabled to prevent authentication issues.
|
||||
:::
|
||||
|
||||
:::info
|
||||
You can configure Mastodon to use either the `sub` or `preferred_username` as the UID field under `OIDC_UID_FIELD`. The `sub` option uses a unique, stable identifier for the user, while `preferred_username` uses the username configured in authentik.
|
||||
:::
|
||||
|
||||
```
|
||||
OIDC_ENABLED=true
|
||||
OIDC_DISPLAY_NAME=authentik
|
||||
OIDC_DISCOVERY=true
|
||||
OIDC_ISSUER=< OpenID Configuration Issuer>
|
||||
OIDC_AUTH_ENDPOINT=https://authentik.company/application/o/authorize/
|
||||
OIDC_SCOPE=openid,profile,email
|
||||
OIDC_UID_FIELD=preferred_username
|
||||
OIDC_CLIENT_ID=<Client ID>
|
||||
OIDC_CLIENT_SECRET=<Client Secret>
|
||||
OIDC_REDIRECT_URI=https://mastodon.company/auth/auth/openid_connect/callback
|
||||
OIDC_SECURITY_ASSUME_EMAIL_IS_VERIFIED=true
|
||||
```
|
||||
|
||||
Restart mastodon-web.service
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- https://github.com/mastodon/mastodon/pull/16221
|
||||
- https://forum.fedimins.net/t/sso-fuer-verschiedene-dienste/42
|
||||
@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Integrate with Matrix Synapse
|
||||
sidebar_label: Matrix Synapse
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Matrix Synapse
|
||||
|
||||
> Matrix is an open source project that publishes the Matrix open standard for secure, decentralised, real-time communication, and its Apache licensed reference implementations.
|
||||
>
|
||||
> -- https://matrix.org/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `matrix.company` is the FQDN of the Matrix installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Matrix Synapse with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://matrix.company/\_synapse/client/oidc/callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Matrix configuration
|
||||
|
||||
Add the following block to your Matrix config
|
||||
|
||||
:::info
|
||||
For more info, see https://matrix-org.github.io/synapse/latest/openid.html?highlight=authentik#authentik
|
||||
:::
|
||||
|
||||
```yaml
|
||||
oidc_providers:
|
||||
- idp_id: authentik
|
||||
idp_name: authentik
|
||||
discover: true
|
||||
issuer: "https://authentik.company/application/o/<application_slug>/"
|
||||
client_id: "*client id*"
|
||||
client_secret: "*client secret*"
|
||||
scopes:
|
||||
- "openid"
|
||||
- "profile"
|
||||
- "email"
|
||||
user_mapping_provider:
|
||||
config:
|
||||
localpart_template: "{{ user.preferred_username }}"
|
||||
display_name_template: "{{ user.name|capitalize }}"
|
||||
```
|
||||
@ -0,0 +1,199 @@
|
||||
---
|
||||
title: Integrate with Mautic
|
||||
sidebar_label: Mautic
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Mautic
|
||||
|
||||
> Mautic provides free and open source marketing automation software available to everyone. Free email marketing and lead management software.
|
||||
>
|
||||
> -- https://mautic.org/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `mautic.company` is the FQDN of the Mautic installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `mautic-provider` is the [SAML provider](/docs/add-secure-apps/providers/saml) whose settings will be imported into Mautic.
|
||||
|
||||
:::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.
|
||||
:::
|
||||
|
||||
:::warning
|
||||
Mautic and authentik both require X.509 certificates.
|
||||
However, Mautic specifically requires the key to contain the phrase `RSA` or `ENCRYPTED` in its header.
|
||||
|
||||
See [Troubleshooting](#troubleshooting) if the following error occurs in Mautic:
|
||||
|
||||
> Private key is invalid. It should begin with `-----BEGIN RSA PRIVATE KEY-----` or `-----BEGIN ENCRYPTED PRIVATE KEY-----`
|
||||
|
||||
:::
|
||||
|
||||
## authentik configuration
|
||||
|
||||
To support the integration of Mautic with authentik, you need to create property mappings and an application/provider pair in authentik.
|
||||
|
||||
### Create property mappings
|
||||
|
||||
Because Mautic requires a first name and last name attribute, create two [SAML provider property mappings](/docs/users-sources/sources/property-mappings):
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**:
|
||||
- **Name**: `SAML-FirstName-from-Name`
|
||||
- **SAML Attribute Name**: `FirstName`
|
||||
- **Expression**:
|
||||
```py
|
||||
names = request.user.name.split(" ", 1)
|
||||
if (len(names) == 1):
|
||||
return ""
|
||||
return names[0]
|
||||
```
|
||||
This first name mapping will return everything up to the first space (or an empty string if there is no space).
|
||||
3. Again, click **Create**:
|
||||
- **Name**: `SAML-LastName-from-Name`
|
||||
- **SAML Attribute Name**: `LastName`
|
||||
- **Expression**:
|
||||
```py
|
||||
return request.user.name.split(" ", 1)[-1]
|
||||
```
|
||||
This second name mapping returns everything after the first space (or the whole name if there is no space).
|
||||
|
||||
### 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**: select **SAML Provider** as the provider type.
|
||||
- **Configure the Provider**:
|
||||
- Set the **Name** to `mautic-provider`
|
||||
- Set the **ACS URL** to `https://mautic.company/s/saml/login_check`
|
||||
- Set the **Issuer** to `mautic.company`
|
||||
- Set the **Service Provider Binding** to `Post`
|
||||
- Under **Advanced protocol settings** set the **Signing Certificate** to `authentik Self-signed Certificate` and check **Sign assertions** and **Sign responses**
|
||||
- Under **Advanced protocol settings** add the newly created property mappings `SAML-FirstName-from-Name` and `SAML-LastName-from-Name` under **Property Mappings**. **Property Mappings**.
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
4. Go to **Applications** > **Providers** and click on `mautic-provider`.
|
||||
- Under **Metadata** click on **Download** to save the file as `mautic-provider\_authentik_meta.xml`.
|
||||
|
||||
## Mautic configuration
|
||||
|
||||
:::note
|
||||
|
||||
When running behind an SSL-terminating reverse proxy (e.g. traefik): In **Configuration > System Settings**, make sure that:
|
||||
|
||||
- the **Site URL** starts with `https://`
|
||||
- **trusted proxies** includes the IP-address of the reverse proxy
|
||||
|
||||
:::
|
||||
|
||||
In **Configuration > User/Authentication Settings**, set the following values:
|
||||
|
||||
- **Entity ID for the IDP**: `https://mautic.company`
|
||||
- **Identity provider metadata file**: The `mautic-provider\_authentik_meta.xml` file
|
||||
- **Default role for created users**: Choose one to enable creating users.
|
||||
- **Email**: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` (as per provider > preview in authentik)
|
||||
- **Username**: `http://schemas.goauthentik.io/2021/02/saml/username` (as per provider > preview in authentik)
|
||||
- **First name**: `FirstName` (as per Provider > Preview in authentik)
|
||||
- **Last name**: `LastName` (as per Provider > Preview in authentik)
|
||||
- **X.509 certificate**: The `certificate.crt` file
|
||||
- **Private key**: The `private_key.pem` file
|
||||
Click on **Save**.
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is properly configured with Mautic, open a new incognito/private window or another browser and login at `mautic.company`.
|
||||
By using an incognito/private window or other browser, you can still access the configuration interface of Mautic if anything went wrong.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `Uncaught PHP Exception TypeError`
|
||||
|
||||
> ```
|
||||
> mautic.CRITICAL: Uncaught PHP Exception TypeError: "Mautic\UserBundle\Entity\User::getUserIdentifier(): Return value must be of type string, null returned" at /app/bundles/UserBundle/Entity/User.php line 335 {"exception":"[object] (TypeError(code: 0): Mautic\\UserBundle\\Entity\\User::getUserIdentifier(): Return value must be of type string, null returned at /app/bundles/UserBundle/Entity/User.php:335)"}
|
||||
> ```
|
||||
|
||||
This message in Mautic's **System Info > Log in** with an error 500 on its login page indicates a problem with the mapping of the attributes.
|
||||
(See [Mautic configuration](#mautic-configuration) > Email/Username/First Name/Last Name or [Create property mappings](#create-property-mappings) > Step 2 or [Create an application and provider in authentik](#create-an-application-and-provider-in-authentik) > Step 2.)
|
||||
|
||||
### Unable to verify Signature
|
||||
|
||||
> Unable to verify Signature
|
||||
|
||||
This error occurs when logging in, and indicates that the certificate does not match the private key.
|
||||
(E.g. when the certificate was generated without the `RSA` and only the private key was changed afterwards.)
|
||||
|
||||
### Assertions
|
||||
|
||||
> Assertions must be signed
|
||||
|
||||
This error occurs when logging in, and indicates that the **Sign assertions** and **Sign responses** settings were not checked in authentik.
|
||||
(See [Create an application and provider in authentik](#create-an-application-and-provider-in-authentik) > Step 2.)
|
||||
|
||||
### Invalid private key
|
||||
|
||||
> Private key is invalid. It should begin with `-----BEGIN RSA PRIVATE KEY-----` or `-----BEGIN ENCRYPTED PRIVATE KEY-----`
|
||||
|
||||
The private key does not provide the header and footer which Mautic expects.
|
||||
(E.g., Mautic requires the phrases `RSA` or `ENCRYPTED` in the header and footer.)
|
||||
To fix this, a new certificate must be generated.
|
||||
Therefore, follow these steps (where the placeholder `Mautic Self-signed Certificate` is used for the new certificate):
|
||||
|
||||
To avoid changing certificates in authentik, go to the authentik Admin interface and generate a new one:
|
||||
|
||||
1. Go to **System > Certificates** and click on **Generate**. Use the following values:
|
||||
- **Common Name**: `Mautic Self-signed Certificate`
|
||||
- **Private key Algorithm**: `RSA`
|
||||
2. Click the caret (**>**) next to the newly generated certificate, then select **Download certificate** to get the `Mautic Self-signed Certificate\_certificate.pem` file and **Download Private key** to get the `Mautic Self-signed Certificate\_private_key.pem` file.
|
||||
3. Make sure that the `Mautic Self-signed Certificate\_private_key.pem` is in PKCS#1 format.
|
||||
To verify, use `grep`to check for`RSA` in the header and footer of the file:
|
||||
`sh
|
||||
grep "RSA PRIVATE KEY" "Mautic Self-signed Certificate_private_key.pem"
|
||||
`
|
||||
If the command returns the correct match (e.g., `-----BEGIN RSA PRIVATE KEY-----` and `-----BEGIN RSA PRIVATE KEY-----`), the key is in PKCS#1 format, and you can skip steps 4 to 6.
|
||||
4. If the key is not in PKCS#1 format, add RSA after `BEGIN` and `END` in `Mautic Self-signed Certificate\_private_key.pem` as shown below and save the file as `private_key_new.pem`:
|
||||
```diff
|
||||
- -----BEGIN PRIVATE KEY-----
|
||||
+ -----BEGIN RSA PRIVATE KEY-----
|
||||
```
|
||||
and
|
||||
```diff
|
||||
- -----END PRIVATE KEY-----
|
||||
+ -----END RSA PRIVATE KEY-----
|
||||
```
|
||||
5. Regenerate the X.509-certificate by first creating a signing request, using the following command:
|
||||
|
||||
```sh
|
||||
openssl req -new -key private_key_new.pem -out request.csr
|
||||
```
|
||||
|
||||
This will prompt you to enter values for the certificate which you can choose freely.
|
||||
For some, you can use authentik's generated values:
|
||||
- **Organization Name**: `authentik`
|
||||
- **Organizational Unit Name**: `Self-signed`
|
||||
- **Common Name**: `Mautic Self-signed Certificate`
|
||||
|
||||
6. Next, generate the certificate with the (now) PKCS#1-compliant key and the previously generated signing request using the following command:
|
||||
|
||||
```sh
|
||||
openssl x509 -req -days 365 -in request.csr -signkey private_key_new.pem -out certificate_new.pem
|
||||
```
|
||||
|
||||
7. In authentik, navigate to **System > Certificates** and click on **Edit** the update previously generated certificate.
|
||||
Click on the description below the text inputs to activate the inputs.
|
||||
- **Certificate**: Enter the contents of `certificate_new.pem` or, if steps 4 to 6 were skipped, `Mautic Self-signed Certificate\_certificate.pem`
|
||||
- **Private Key**: Enter the contents of `private_key_new.pem` or, if steps 4 to 6 were skipped, `Mautic Self-signed Certificate\_private_key.pem`
|
||||
- Click on **Update**
|
||||
8. Navigate to **Applications > Providers** and **Edit** `mautic-provider` (which was created in [Create an application and provider in authentik](#create-an-application-and-provider-in-authentik)).
|
||||
In **Advanced protocol settings**, change **Signing Certificate** to `Mautic Self-signed Certificate`
|
||||
9. Save the provider, view it, and download the metadata file to `mautic-provider\_authentik_meta.xml`
|
||||
10. In Mautic, navigate to **Configuration > User/Authentication Settings** and set the following values:
|
||||
|
||||
- **X.509 certificate**: The `certificate_new.crt` file
|
||||
- **Private key**: The `private_key_new.pem` file
|
||||
- **Identity provider metadata file**: The new `mautic-provider\_authentik_meta.xml` file
|
||||
|
||||
11. Click on **Save**.
|
||||
@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Integrate with Mobilizon
|
||||
sidebar_label: Mobilizon
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Mobilizon
|
||||
|
||||
> Gather, organize and mobilize yourselves with a convivial, ethical, and emancipating tool. https://joinmobilizon.org
|
||||
>
|
||||
> -- https://joinmobilizon.org/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `mobilizon.company` is the FQDN of the Mobilizon installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Mobilizon with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://mobilizon.company/auth/keycloak/callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Mobilizon configuration
|
||||
|
||||
Configure Mobilizon settings by editing the `config.exs` and add the following:
|
||||
|
||||
```
|
||||
config :ueberauth,
|
||||
Ueberauth,
|
||||
providers: [
|
||||
keycloak: {Ueberauth.Strategy.Keycloak, [default_scope: "openid profile email"]}
|
||||
]
|
||||
|
||||
config :mobilizon, :auth,
|
||||
oauth_consumer_strategies: [
|
||||
{:keycloak, "authentik"}
|
||||
]
|
||||
|
||||
config :ueberauth, Ueberauth.Strategy.Keycloak.OAuth,
|
||||
client_id: "<Client ID>",
|
||||
client_secret: "<Client Secret>",
|
||||
site: "https://authentik.company",
|
||||
authorize_url: "https://authentik.company/application/o/authorize/",
|
||||
token_url: "https://authentik.company/application/o/token/",
|
||||
userinfo_url: "https://authentik.company/application/o/userinfo/",
|
||||
token_method: :post
|
||||
```
|
||||
|
||||
Restart mobilizon.service
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- https://docs.joinmobilizon.org/administration/configure/auth/
|
||||
@ -0,0 +1,407 @@
|
||||
---
|
||||
title: Integrate with Nextcloud
|
||||
sidebar_label: Nextcloud
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Nextcloud
|
||||
|
||||
> Nextcloud is a suite of client-server software for creating and using file hosting services. Nextcloud is free and open-source, which means that anyone is allowed to install and operate it on their own private server devices.
|
||||
>
|
||||
> -- https://nextcloud.com/
|
||||
|
||||
:::warning
|
||||
If you require [server side encryption](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html), you must use LDAP. OpenID and SAML will cause **irrevocable data loss**. Nextcloud server side encryption requires access to the user's cleartext password, which Nextcloud has access to only when using LDAP because the user enters their password directly into Nextcloud.
|
||||
:::
|
||||
|
||||
:::caution
|
||||
This setup only works when Nextcloud is running with HTTPS enabled. See [here](https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/reverse_proxy_configuration.html?highlight=overwriteprotocol#overwrite-parameters) on how to configure this.
|
||||
:::
|
||||
|
||||
:::info
|
||||
If there’s an issue with the configuration, you can log in using the built-in authentication by visiting http://nextcloud.company/login?direct=1.
|
||||
:::
|
||||
|
||||
## Configuration methods
|
||||
|
||||
It is possible to configure Nextcloud to use OIDC, SAML, or LDAP for authentication. Below are the steps to configure each method.
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
<Tabs
|
||||
defaultValue="oidc"
|
||||
values={[
|
||||
{ label: "OIDC", value: "oidc" },
|
||||
{ label: "SAML", value: "saml" },
|
||||
{ label: "LDAP", value: "ldap" }
|
||||
]}
|
||||
>
|
||||
<TabItem value="oidc">
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `nextcloud.company` is the FQDN of the Nextcloud installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
:::warning
|
||||
If you require [server side encryption](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html), you must use LDAP. OpenID and SAML will cause **irrevocable data loss**.
|
||||
:::
|
||||
|
||||
Let's start by considering which user attributes need to be available in Nextcloud:
|
||||
|
||||
- name
|
||||
- email
|
||||
- unique user ID
|
||||
- storage quota (optional)
|
||||
- groups (optional)
|
||||
|
||||
authentik already provides some default _scopes_ with _claims_, such as:
|
||||
|
||||
- `email` scope: includes `email` and `email_verified`
|
||||
- `profile` scope: includes `name`, `given_name`, `preferred_username`, `nickname`, `groups`
|
||||
- `openid` scope: a default required by the OpenID spec (contains no claims)
|
||||
|
||||
## Create property mapping _(optional)_
|
||||
|
||||
If you do not need storage quota, group information, or to manage already existing users in Nextcloud, skip to the [next section](#create-an-application-and-provider-in-authentik).
|
||||
|
||||
If you want to control user storage and designate Nextcloud administrators, you will need to create a property mapping.
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property mappings** and click **Create**.
|
||||
- **Select type**: select **Scope mapping**.
|
||||
- **Create Scope Mapping**:
|
||||
- **Name**: `Nextcloud Profile`
|
||||
- **Scope name**: `nextcloud`
|
||||
- **Expression**:
|
||||
|
||||
```python
|
||||
# Extract all groups the user is a member of
|
||||
groups = [group.name for group in user.ak_groups.all()]
|
||||
|
||||
# In Nextcloud, administrators must be members of a fixed group called "admin".
|
||||
|
||||
# If a user is an admin in authentik, ensure that "admin" is appended to their group list.
|
||||
if user.is_superuser and "admin" not in groups:
|
||||
groups.append("admin")
|
||||
|
||||
return {
|
||||
"name": request.user.name,
|
||||
"groups": groups,
|
||||
# Set a quota by using the "nextcloud_quota" property in the user's attributes
|
||||
"quota": user.group_attributes().get("nextcloud_quota", None),
|
||||
# To connect an existing Nextcloud user, set "nextcloud_user_id" to the Nextcloud username.
|
||||
"user_id": user.attributes.get("nextcloud_user_id", str(user.uuid)),
|
||||
}
|
||||
```
|
||||
|
||||
3. Click **Finish**.
|
||||
|
||||
:::note
|
||||
To set a quota, define the `nextcloud_quota` attribute for individual users or groups. For example, setting it to `1 GB` will restrict the user to 1GB of storage. If not set, storage is unlimited.
|
||||
:::
|
||||
|
||||
:::note
|
||||
To connect to an existing Nextcloud user, set the `nextcloud_user_id` attribute to match the Nextcloud username (found under the user's `Display name` in Nextcloud).
|
||||
:::
|
||||
|
||||
## 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID** and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://nextcloud.company/apps/user_oidc/code`.
|
||||
- Select any available signing key.
|
||||
- Under **Advanced Protocol Settings**:
|
||||
- _(optional)_ If you created the `Nextcloud Profile` scope mapping, add it to **Selected Scopes**.
|
||||
- **Subject Mode**: `Based on the User's UUID`
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
:::note
|
||||
Depending on your Nextcloud configuration, you may need to use `https://nextcloud.company/index.php/` instead of `https://nextcloud.company/`.
|
||||
:::
|
||||
|
||||
## Nextcloud configuration
|
||||
|
||||
1. In Nextcloud, ensure that the **OpenID Connect user backend** app is installed.
|
||||
2. Log in to Nextcloud as an administrator and navigate to **Settings** > **OpenID Connect**.
|
||||
3. Click the **+** button and enter the following settings:
|
||||
- **Identifier**: `authentik`
|
||||
- **Client ID**: Client ID from authentik
|
||||
- **Client secret**: Client secret from authentik
|
||||
- **Discovery endpoint**: `https://authentik.company/application/o/<application_slug>/.well-known/openid-configuration`
|
||||
- **Scope**: `email nextcloud openid`
|
||||
- Under **Attribute mappings**:
|
||||
- **User ID mapping**: `sub` (or `user_id` for existing users)
|
||||
- **Display name mapping**: `name`
|
||||
- **Email mapping**: `email`
|
||||
- **Quota mapping**: `quota` (leave blank if the `Nextcloud Profile` property mapping was skipped)
|
||||
- **Groups mapping**: `groups` (leave blank if the `Nextcloud Profile` property mapping was skipped)
|
||||
|
||||
:::tip
|
||||
Enable **Use group provisioning** to allow writing to this field.
|
||||
:::
|
||||
|
||||
- **Use unique user ID**: If this option is disabled, Nextcloud will use the mapped user ID as the Federated Cloud ID.
|
||||
|
||||
:::note
|
||||
If authentik and Nextcloud are running on the same host, you will need to add `'allow_local_remote_servers' => true` to your nextcloud `config.php` file. This setting allows remote servers with local addresses.
|
||||
:::
|
||||
|
||||
:::tip
|
||||
To avoid a hashed Federated Cloud ID, deselect **Use unique user ID** and use `user_id` for the User ID mapping.
|
||||
:::
|
||||
|
||||
:::danger
|
||||
If you're using the `Nextcloud Profile` property mapping and want administrators to retain their ability to log in, make sure that **Use unique user ID** is disabled. If this setting is enabled, it will remove administrator users from the internal admin group and replace them with a hashed group ID named "admin," which does not have real administrative privileges.
|
||||
:::
|
||||
|
||||
## Making OIDC the default login method
|
||||
|
||||
Automatically redirect users to authentik when they access Nextcloud by running the following command on your Nextcloud docker host:
|
||||
|
||||
```bash
|
||||
sudo docker exec --user www-data -it nextcloud-aio-nextcloud php occ config:app:set --value=0 user_oidc allow_multiple_user_backends
|
||||
```
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is correctly configured with Nextcloud, log out and then log back in by clicking **OpenID Connect**. You'll then be redirected to authentik to log in, and once authentication is successful, you'll reach the Nextcloud dashboard.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="saml">
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `nextcloud.company` is the FQDN of the Nextcloud installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
:::warning
|
||||
If you require [server side encryption](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html), you must use LDAP. OpenID and SAML will cause **irrevocable data loss**.
|
||||
:::
|
||||
|
||||
## 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.
|
||||
- Note the application slug because it will be required later.
|
||||
- **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.
|
||||
- Set the **ACS URL** to `https://nextcloud.company/apps/user_saml/saml/acs`.
|
||||
- Set the **Issuer** to `https://authentik.company`.
|
||||
- Set the **Audience** to `https://nextcloud.company/apps/user_saml/saml/metadata`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, set an available signing certificate.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
:::note
|
||||
Depending on your Nextcloud configuration, you might need to use `https://nextcloud.company/index.php/` instead of `https://nextcloud.company/`.
|
||||
:::
|
||||
|
||||
## Download the signing certificate
|
||||
|
||||
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 newly created Nextcloud provider.
|
||||
3. Under **Download signing certificate** click **Download**. The contents of this certificate will be required in the next section.
|
||||
|
||||
## Configure group quotas _(optional)_
|
||||
|
||||
To configure group quotas you will need to create groups in authentik for each quota, and a property mapping.
|
||||
|
||||
### Create group/s in authentik _(optional)_
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Directory** > **Groups** and click **Create**.
|
||||
3. Set a name for the group (e.g. `nextlcloud-15GB`), assign a custom attribute (e.g., `nextcloud_quota`), and click **Create**.
|
||||
4. Click the name of the newly created group and navigate to the **Users** tab.
|
||||
5. Click **Add existing user**, select the users that require this storage quota and click **Add**.
|
||||
|
||||
### Create property mapping in authentik _(optional)_
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property mappings** and click **Create**.
|
||||
- **Select type**: select **SAML Provider Property Mapping** as the property mapping type.
|
||||
- **Create SAML Provider Property Mapping**:
|
||||
- **Name**: Provide a name for the property mapping.
|
||||
- **SAML Attribute Name**: `nextcloud_quota`
|
||||
- **Expression**:
|
||||
|
||||
```python
|
||||
return user.group_attributes().get("nextcloud_quota", "1 GB")
|
||||
```
|
||||
|
||||
:::note
|
||||
Where `"1 GB"` is the default if a quota is not set.
|
||||
:::
|
||||
|
||||
3. Click **Finish** to save the property mapping.
|
||||
|
||||
### Configure quota attribute in Nextcloud _(optional)_
|
||||
|
||||
1. Log in to Nextcloud as an administrator.
|
||||
2. Navigate to **Settings** > **SSO & SAML Authentication**.
|
||||
3. Set **Attribute to map the quota to** to `nextcloud_quota`.
|
||||
|
||||
## Configure admin group _(optional)_
|
||||
|
||||
To grant Nextcloud admin access to authentik users you will need to create a property mapping.
|
||||
|
||||
### Create property mapping in authentik _(optional)_
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property mappings** and click **Create**.
|
||||
- **Select type**: select **SAML Provider Property Mapping** as the property mapping type.
|
||||
- **Create SAML Provider Property Mapping**:
|
||||
- **Name**: Provide a name for the property mapping.
|
||||
- **SAML Attribute Name**: `http://schemas.xmlsoap.org/claims/Group`
|
||||
- **Expression**:
|
||||
|
||||
```python
|
||||
for group in request.user.all_groups():
|
||||
yield group.name
|
||||
if ak_is_group_member(request.user, name="<authentik nextcloud admin group's name>"):
|
||||
yield "admin"
|
||||
```
|
||||
|
||||
### Configure group attribute in Nextcloud _(optional)_
|
||||
|
||||
1. Log in to Nextcloud as an administrator.
|
||||
2. Navigate to **Settings** > **SSO & SAML Authentication**.
|
||||
3. Set the groups mapping to `http://schemas.xmlsoap.org/claims/Group`.
|
||||
|
||||
## Nextcloud configuration
|
||||
|
||||
1. In Nextcloud, ensure that the **SSO & SAML Authentication** app is installed.
|
||||
2. Log in to Nextcloud as an administrator, navigate to **Settings** > **SSO & SAML Authentication**, and configure the following settings:
|
||||
- **Attribute to map the UID to**: `http://schemas.goauthentik.io/2021/02/saml/uid`
|
||||
|
||||
:::danger
|
||||
Using the UID attribute as username is **not recommended** because of its mutable nature. If you map to the username instead, [disable username changing](https://docs.goauthentik.io/docs/sys-mgmt/settings#allow-users-to-change-username) and set the UID attribute to `http://schemas.goauthentik.io/2021/02/saml/username`.
|
||||
:::
|
||||
- **Optional display name**: `authentik`
|
||||
- **Identifier of the IdP entity**: `https://authentik.company`
|
||||
- **URL target for authentication requests**: `https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/`
|
||||
- **URL for SLO requests**: `https://authentik.company/application/saml/<application_slug>/slo/binding/redirect/`
|
||||
- **Public X.509 certificate of the IdP**: Paste the contents of your certificate file.
|
||||
- **Set attribute mappings**:
|
||||
- **Display name**: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
|
||||
- **Email**: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
|
||||
- **User groups**: `http://schemas.xmlsoap.org/claims/Group`
|
||||
|
||||
:::note
|
||||
If Nextcloud is behind a reverse proxy, force HTTPS by adding `'overwriteprotocol' => 'https'` to the Nextcloud `config/config.php` file. See [this guide](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/reverse_proxy_configuration.html#overwrite-parameters) for more details.
|
||||
:::
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is properly configured with Nextcloud, log out and log back in using the **SSO and SAML log in** option. You will be redirected to authentik to log in; if successful you will then be redirected to the Nextcloud dashboard.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="ldap">
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `nextcloud.company` is the FQDN of the Nextcloud installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
## 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 **LDAP** as the provider type.
|
||||
- **Configure the Provider**: provide a name (or accept the auto-provided name) and the bind flow to use for this provider
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Create an LDAP outpost
|
||||
|
||||
1. Log in to authentik as an admin, and open the authentik Admin interface.
|
||||
2. Navigate to **Applications** > **Outposts** and click **Create**.
|
||||
- **Name**: provide a suitable name for the outpost.
|
||||
- **Type**: `LDAP`
|
||||
- Under applications, add the newly created Nextcloud application to **Selected Applications**.
|
||||
|
||||
3. Click **Create**.
|
||||
|
||||
## Nextcloud configuration
|
||||
|
||||
1. In Nextcloud, ensure that the **LDAP user and group backend** app is installed.
|
||||
2. Log in to Nextcloud as an administrator.
|
||||
3. Navigate to **Settings** > **LDAP user and group backend** and configure the following settings:
|
||||
- On the **Server** tab:
|
||||
- Click the **+** icon and enter the following settings:
|
||||
- **Host**: enter the hostname/IP address of the authentik LDAP outpost preceded by `ldap://` or `ldaps://`. If using LDAPS you will also need to specify the certificate that is being used.
|
||||
- **Port**: `389` or `636` for secure LDAP.
|
||||
- Under **Credentials**, enter the **Bind DN** of the authentik LDAP provider and the associated user password.
|
||||
- Under **Base DN**, enter the **Search base** of the authentik LDAP provider.
|
||||
|
||||
- On the **Users** tab:
|
||||
- Set **Only these object classes** to `Users`.
|
||||
|
||||
- On the **LDAP/AD integration** tab:
|
||||
- Uncheck **LDAP/AD Username**.
|
||||
- Set **Other Attributes** to `cn`.
|
||||
- Click **Expert** in the top right corner and enter these settings:
|
||||
- **Internal Username Attribute**: `uid`
|
||||
- **UUID Attribute for Users**: `uid`
|
||||
- **UUID Attribute for Groups**: `gidNumber`
|
||||
- Click **Advanced** in the top right corner and enter these settings:
|
||||
- Under **Connection Settings**:
|
||||
- **Configuration Active**: checked
|
||||
- Under **Directory Settings**:
|
||||
- **User Display Name Field**: `name`
|
||||
- **Base User Tree**: enter the **Search base** of the authentik LDAP provider.
|
||||
- **Group Display Name Field**: `cn`
|
||||
- **Base Group Tree**: enter the **Search base** of the authentik LDAP provider.
|
||||
- **Group-Member Association**: `gidNumber`
|
||||
- Under **Special Attributes**:
|
||||
- **Email Field**: `mailPrimaryAddress`
|
||||
|
||||
- On the **Groups** tab:
|
||||
- Set **Only these object classes** to `groups`.
|
||||
- Select the authentik groups that require Nextcloud access.
|
||||
|
||||
:::note
|
||||
If Nextcloud is behind a reverse proxy, force HTTPS by adding `'overwriteprotocol' => 'https'` to the Nextcloud `config/config.php` file. See [the Nextcloud admin manual](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/reverse_proxy_configuration.html#overwrite-parameters) for more details.
|
||||
:::
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is properly configured with Nextcloud, log out and log back in using LDAP credentials. If successful you will then be redirected to the Nextcloud dashboard.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Resources
|
||||
|
||||
- [Nextcloud docs - User authentication with LDAP](https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/user_auth_ldap.html)
|
||||
- [Nextcloud OIDC App - User Documentation](https://github.com/H2CK/oidc/wiki/User-Documentation)
|
||||
@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Integrate with OnlyOffice
|
||||
sidebar_label: OnlyOffice
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is OnlyOffice
|
||||
|
||||
> OnlyOffice, stylized as ONLYOFFICE, is a free software office suite developed by Ascensio System SIA, a company headquartered in Riga, Latvia. It features online document editors, platform for document management, corporate communication, mail and project management tools
|
||||
>
|
||||
> -- https://en.wikipedia.org/wiki/OnlyOffice
|
||||
|
||||
:::note
|
||||
This is based on authentik 2021.10.4 and OnlyOffice 11.5.4.1582. Instructions may differ between versions.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company` is the FQDN of authentik.
|
||||
- `onlyoffice.company` is the FQDN of the OnlyOffice instance.
|
||||
|
||||
Open your OnlyOffice instance, navigate to the settings by clicking the cog-icon in the navbar, then click on _Control Panel_ on the sidebar.
|
||||
|
||||
In the new tab, click on _SSO_ in the sidebar.
|
||||
|
||||
Click the _Enable Single Sign-on Authentication_ checkbox to enable SSO.
|
||||
|
||||
Scroll down to _ONLYOFFICE SP Metadata_, and copy the _SP Entity ID (link to metadata XML)_ URL. Open this URL in a new tab, and download the XML file.
|
||||
|
||||
:::note
|
||||
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 Setup
|
||||
|
||||
Create an application in authentik, and create a SAML Provider by using _SAML Provider from Metadata_. Give the provider a name, and upload the XML file you've downloaded in the previous step.
|
||||
|
||||
Edit the resulting Provider, and ensure _Signing Certificate_ is set to any certificate.
|
||||
|
||||
Navigate on the _Metadata_ tab on the Provider page, and click _Copy download URL_.
|
||||
|
||||
## OnlyOffice Setup
|
||||
|
||||
Navigate back to your OnlyOffice Control panel, and paste the URL into _Load metadata from XML to fill the required fields automatically_, and click the upload button next to the input field.
|
||||
|
||||
Under _Attribute Mapping_, set the following values
|
||||
|
||||
- _First Name_: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
|
||||
- _Last Name_: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
|
||||
- _Email_: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
|
||||
|
||||
Click save and a new SSO button will appear on the OnlyOffice login page.
|
||||
@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Integrate with OpenProject
|
||||
sidebar_label: OpenProject
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is OpenProject
|
||||
|
||||
> OpenProject is a web-based project management software. Use OpenProject to manage your projects, tasks and goals. Collaborate via work packages and link them to your pull requests on Github.
|
||||
>
|
||||
> -- https://www.openproject.org/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `openproject.company` is the FQDN of the OpenProject installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 OpenProject with authentik, you need to create a property mapping and an application/provider pair in authentik.
|
||||
|
||||
### Create a scope mapping
|
||||
|
||||
OpenProject requires a first and last name for each user. By default authentik only provides a full name, as a single string value. Therefore you need to create a property mapping to provide first and last names to OpenProject.
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**.
|
||||
|
||||
- **Select type**: select **Scope Mapping** as the property mapping type.
|
||||
- **Configure the Scope Mapping**: Provide a descriptive name (e.g. `Open Project Profile Scope`), and an optional description
|
||||
- **Scope name**: `profile`
|
||||
- **Expression**:
|
||||
|
||||
```python showLineNumbers
|
||||
return {
|
||||
"name": request.user.name,
|
||||
"preferred_username": request.user.username,
|
||||
"nickname": request.user.username,
|
||||
"groups": [group.name for group in request.user.ak_groups.all()],
|
||||
"last_name": request.user.name.rsplit(" ", 1)[-1],
|
||||
"first_name": request.user.name.rsplit(" ", 1)[0],
|
||||
}
|
||||
```
|
||||
|
||||
3. Click **Finish** to save the property mapping.
|
||||
|
||||
### 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 **OAuth2/OpenID 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.
|
||||
- **Protocol settings**:
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- **Redirect URI**:
|
||||
- Strict: `https://openproject.company/auth/oidc-authentik/callback`
|
||||
- **Signing key**: select any available signing key.
|
||||
- **Advanced protocol settings**:
|
||||
- **Scopes**:
|
||||
- Remove `authentik default OAuth Mapping: OpenID 'profile'` from **Selected Scopes**.
|
||||
- Add the scope that you created in the previous section (e.g. `Open Project Profile Scope`) to **Selected Scopes**.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## OpenProject configuration
|
||||
|
||||
To support the integration of authentik with OpenProject, you need to configure authentication in the OpenProject administration interface.
|
||||
|
||||
1. Login to OpenProject as an administrator, click on your profile icon at the top right and then **Administration**.
|
||||
2. Navigate to **Authentication** > **OpenID providers**.
|
||||
3. Provide a display name (e.g. `Authentik`) and click **Save**.
|
||||
4. Click on **I have a discover endpoint URL** and enter:
|
||||
`https://authentik.company/application/o/openproject/.well-known/openid-configuration`
|
||||
5. Under **Advanced configuration** > **Metadata** the values should be automatically populated based on your discovery endpoint URL. If not, these values can be copied from the **Overview** page of the OpenProject provider in authentik.
|
||||
6. Under **Advanced configuration** > **Client details** enter your authentik client ID and client secret.
|
||||
7. Under **Optional configuration** > **Attribute mapping** enter the following required configurations:
|
||||
- **Mapping for: Username**: `preferred_username`
|
||||
- **Mapping for: Email**: `email`
|
||||
- **Mapping for: First Name**: `first_name`
|
||||
- **Mapping for: Last Name**: `last_name`
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is properly configured with OpenProject, log out of OpenProject, and then click on **authentik** and enter your authentik credentials to log back in.
|
||||
@ -0,0 +1,201 @@
|
||||
---
|
||||
title: Integrate with ownCloud
|
||||
sidebar_label: ownCloud
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is ownCloud
|
||||
|
||||
> ownCloud is a free and open-source software project for content collaboration and sharing and syncing of files.
|
||||
>
|
||||
> -- https://owncloud.com
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `owncloud.company` is the FQDN of the ownCloud installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::info
|
||||
This guide focuses on deploying ownCloud installations using Docker. If you deployed ownCloud using a different mechanism, there might be some differences in the process. Furthermore, these instructions use the [official OIDC plugin](https://github.com/owncloud/openidconnect). Advanced configuration details can be found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html).
|
||||
:::
|
||||
|
||||
## authentik configuration
|
||||
|
||||
To support the integration of ownCloud with authentik, you need to create multiple application/provider pairs in authentik. A different pair is required for the Web UI, Desktop application, Android application, and iOS application.
|
||||
|
||||
The configuration for each application is nearly identical, except for the **Client ID**, **Client Secret**, and the **Redirect URI** values, which are [predefined](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-ids-secrets-and-redirect-uris) by ownCloud for the Desktop, Android, and iOS applications.
|
||||
|
||||
### 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.) You will need to repeat the process four times: once each for the Desktop application, Web UI, Android application, and iOS application.
|
||||
|
||||
- **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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- **Protocol settings:**
|
||||
|
||||
**Web UI:**
|
||||
- **Signing Key**: Select any available signing key.
|
||||
- **Client ID**: Use the value generated by authentik.
|
||||
- **Client Secret**: Use the value generated by authentik.
|
||||
- **Redirect URIs**:
|
||||
- Strict: `https://owncloud.company/apps/openidconnect/redirect`
|
||||
|
||||
**Desktop Application**
|
||||
- **Signing Key**: Select any available signing key.
|
||||
- **Client ID**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-id).
|
||||
- **Client Secret**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-secret).
|
||||
- **Redirect URIs**:
|
||||
- Regex: `http://localhost:\d+`
|
||||
- Regex: `http://127.0.0.1:\d+`
|
||||
|
||||
**Android Application**
|
||||
- **Signing Key**: Select any available signing key.
|
||||
- **Client ID**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-id).
|
||||
- **Client Secret**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-secret).
|
||||
- **Redirect URI**:
|
||||
- Strict: `oc://android.owncloud.com`
|
||||
|
||||
**iOS Application**
|
||||
- **Signing Key**: Select any available signing key.
|
||||
- **Client ID**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-id).
|
||||
- **Client Secret**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-secret).
|
||||
- **Redirect URI**:
|
||||
- Strict: `oc://ios.owncloud.com`
|
||||
|
||||
- **Advanced protocol settings:**
|
||||
- **Scopes**: Select the following scopes for each of the four application/provider pairs: `email`, `offline_access`, `openid`, `profile`.
|
||||
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
### Service discovery
|
||||
|
||||
To allow ownCloud applications to log in via OIDC, your reverse proxy must be configured to rewrite `https://owncloud.company/.well-known/openid-configuration` to `https://owncloud.company/index.php/apps/openidconnect/config`.
|
||||
|
||||
Refer to the [ownCloud Admin Manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#set-up-service-discovery) for an example configuration using [Apache HTTPD](https://httpd.apache.org/).
|
||||
|
||||
For other reverse proxies, consult the provider-specific documentation for guidance on implementing this rewrite rule.
|
||||
|
||||
## ownCloud Configuration
|
||||
|
||||
To enable OIDC functionality in ownCloud, follow these steps:
|
||||
|
||||
1. **Navigate to the Market**:
|
||||
- Access the Market by visiting:
|
||||
`https://owncloud.company/apps/market/#/`
|
||||
or by clicking the **Hamburger Menu** in the top-left corner of any page in your ownCloud deployment and selecting **Market**.
|
||||
- Search for and enable the **OIDC plugin**.
|
||||
|
||||
2. **OIDC Plugin Configuration**:
|
||||
The OIDC plugin cannot be configured via the ownCloud UI. Configuration must be performed either:
|
||||
|
||||
- by editing the `config.php` file
|
||||
OR
|
||||
- by storing the configuration in the ownCloud database
|
||||
|
||||
The location of the `config.php` file depends on your deployment method. Consult the setup guide for your chosen deployment method to identify the file’s location within your installation.
|
||||
|
||||
:::note
|
||||
|
||||
Instructions for configuring the OIDC plugin using the ownCloud database can be found in the OIDC plugin's [README.md file](https://github.com/owncloud/openidconnect?tab=readme-ov-file#settings-in-database). Both methods produce identical configurations, differing only in whether the settings are stored in a `php` file or in the database (via an `occ` command).
|
||||
:::
|
||||
|
||||
3. **Create the `oidc.config.php` File**:
|
||||
- Place a file named `oidc.config.php` in the same directory as the existing `config.php` file in your ownCloud installation.
|
||||
- Files named with this pattern are treated as "override" files, allowing ownCloud to override matching configuration keys in the `config.php` file.
|
||||
|
||||
The location of this file depends on your Docker configuration. By default, the file resides in `/mnt/data/config` within the container. This location is exposed via the `files` volume in the [official setup guide](https://doc.owncloud.com/server/next/admin_manual/installation/docker/#docker-compose).
|
||||
|
||||
4. **Minimal Contents of `oidc.config.php`**:
|
||||
Add the necessary configuration settings to this file. Ensure it includes at least the minimal requirements for your setup:
|
||||
|
||||
:::warning
|
||||
You can configure ownCloud to use either the `sub` or `preferred_username` as the UID field under `search-attribute`. When using `preferred_username` as the user identifier, ensure that the [**Allow users to change username** setting](https://docs.goauthentik.io/docs/sys-mgmt/settings#allow-users-to-change-username) is disabled to prevent authentication issues. The `sub` option uses a unique, stable identifier for the user, while `preferred_username` uses the username configured in authentik.
|
||||
:::
|
||||
|
||||
```php
|
||||
<?php
|
||||
$CONFIG = [
|
||||
'http.cookie.samesite' => 'None',
|
||||
'openid-connect' => [
|
||||
'provider-url' => 'https://authentik.company/application/o/owncloud/',
|
||||
'client-id' => '<Client ID from authentik>',
|
||||
'client-secret' => '<Client secret from authentik',
|
||||
'loginButtonName' => 'Log in with authentik',
|
||||
'mode' => 'userid',
|
||||
'search-attribute' => 'preferred_username',
|
||||
],
|
||||
],
|
||||
];
|
||||
```
|
||||
|
||||
To enable automatic provisioning of new users, you can augment the `openid-connect` configuration in your `oidc.config.php` file with the following settings:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$CONFIG = [
|
||||
'http.cookie.samesite' => 'None',
|
||||
'openid-connect' => [
|
||||
'provider-url' => 'https://authentik.company/application/o/owncloud/',
|
||||
'client-id' => '<Client ID from authentik>',
|
||||
'client-secret' => '<Client secret from authentik>',
|
||||
'loginButtonName' => 'Log in with authentik',
|
||||
'mode' => 'userid',
|
||||
'search-attribute' => 'preferred_username',
|
||||
'auto-provision' => [
|
||||
'enabled' => true,
|
||||
'email-claim' => 'email',
|
||||
'display-name-claim' => 'given_name',
|
||||
'update' => [
|
||||
'enabled' => true,
|
||||
],
|
||||
],
|
||||
],
|
||||
];
|
||||
```
|
||||
|
||||
:::note
|
||||
The configuration above will result in new ownCloud users being assigned the same username as the authentik username. If you prefer to use the user's email address as the ownCloud username, you can remove the `mode` and `search-attribute` settings.
|
||||
|
||||
Note that using email as the username may cause mobile app interfaces to display usernames in an unusual format (e.g., `user@email.com@owncloud.company`).
|
||||
:::
|
||||
|
||||
In addition to the above settings, here are some additional options for configuring the OIDC integration in ownCloud:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$CONFIG = [
|
||||
'token_auth_enforced' => true, // Forces OIDC authentication on all desktop, Android, and iOS clients, and disconnects existing sessions.
|
||||
'openid-connect' => [
|
||||
'autoRedirectOnLoginPage' => true, // Enables automatic redirection to the authentik login page
|
||||
],
|
||||
];
|
||||
```
|
||||
|
||||
:::warning
|
||||
Enabling the `autoRedirectOnLoginPage` setting may lock you out of the system if your OIDC setup is misconfigured. To regain access, you can disable this setting and restart ownCloud, which will restore the standard login page.
|
||||
:::
|
||||
|
||||
:::tip
|
||||
For more information on other available configuration options, refer to the OIDC plugin's [README](https://github.com/owncloud/openidconnect?tab=readme-ov-file#settings-in-database).
|
||||
:::
|
||||
|
||||
### You're done!
|
||||
|
||||
You have successfully configured OIDC authentication through authentik. Here's what you can expect next:
|
||||
|
||||
- **Login Behavior:**
|
||||
- If the `autoRedirectOnLoginPage` option is **set to false**, navigating to `https://owncloud.company` will present the standard login page, which now includes an "Log in with authentik" button (or any custom text defined in the `loginButtonName` field).
|
||||
- If the `autoRedirectOnLoginPage` option is **set to true**, users will be automatically redirected to the authentik login page when attempting to access `https://owncloud.company`.
|
||||
|
||||
- **ownCloud Applications:**
|
||||
Any new connections through the ownCloud desktop, Android, or iOS applications will automatically use OIDC for authentication.
|
||||
|
||||
- **Force Re-authentication:**
|
||||
To enforce re-authentication using OIDC for existing sessions, set the `token_auth_enforced` option to **true** in the `oidc.config.php` file (as detailed in the above section). This will prompt users to re-authenticate on their ownCloud clients.
|
||||
@ -0,0 +1,125 @@
|
||||
---
|
||||
title: Integrate with Rocket.chat
|
||||
sidebar_label: Rocket.chat
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Rocket.chat
|
||||
|
||||
> Rocket.Chat is an open-source fully customizable communications platform developed in JavaScript for organizations with high standards of data protection. It is licensed under the MIT License with some other licenses mixed in. See [Rocket.chat GitHub](https://github.com/RocketChat/Rocket.Chat/blob/develop/LICENSE) for licensing information.
|
||||
>
|
||||
> -- https://github.com/RocketChat/Rocket.Chat
|
||||
|
||||
:::note
|
||||
This is based on authentik 2022.3.1 and Rocket.chat 4.5.1 using the [Docker-Compose install](https://docs.rocket.chat/quick-start/installing-and-updating/rapid-deployment-methods/docker-and-docker-compose/docker-containers). Instructions may differ between versions.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `rocket.company` is the FQDN of Rocket.chat installation.
|
||||
- `authentik.company` is the FQDN of authentik installation.
|
||||
|
||||
:::note
|
||||
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 Rocket.chat with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://rocket.company/\_oauth/authentik`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Rocket.chat configuration
|
||||
|
||||
:::note
|
||||
Only settings that have been modified from default have been listed.
|
||||
|
||||
You may have different settings for some of the group and role mapping for advanced configurations. The settings below are the base settings to connect authentik and Rocket.chat.
|
||||
:::
|
||||
|
||||
In Rocket.chat, follow the procedure below:
|
||||
|
||||
1. Log in as a System Administrator, click on your avatar, and choose _Administration_
|
||||
|
||||
2. Scroll down and click on _OAuth_
|
||||
|
||||
3. In the top right corner, click _Add custom oauth_
|
||||
|
||||
4. Give your new oauth the name of _Authentik_, then click _Send_
|
||||
|
||||
|
||||
|
||||
5. Scroll down to the new OAuth application, expand the dropdown, and enter the following settings:
|
||||
- Enable: Turn the radio button to the _on_ position
|
||||
- URL: https://authentik.company/application/o
|
||||
- Token Path: /token/
|
||||
- Token Sent Via: Payload
|
||||
- Identity Token Sent Via: Same as "Token Sent Via"
|
||||
- Identity Path: /userinfo/
|
||||
- Authorize Path: /authorize/
|
||||
- Scope: email profile openid
|
||||
- Param Name for access token: access_token
|
||||
- Id: _THIS IS THE CLIENT ID YOU COPIED FROM STEP 1 in authentik_
|
||||
- Secret: _THIS IS THE CLIENT SECRET YOU COPIED FROM STEP 1 in authentik_
|
||||
- Login Style: Redirect
|
||||
- Button Text: _Fill in with what you want the SSO button to say_
|
||||
- Button Text Color: _Hex Color for Text on the SSO login button_
|
||||
- Button Color: _Hex Color for the SSO login button_
|
||||
- Key Field: Username
|
||||
- Username field: preferred_username
|
||||
- Email field: email
|
||||
- Name field: name
|
||||
- Roles/Groups field name: groups
|
||||
- Roles/Groups field for channel mapping: groups
|
||||
- User Data Group Map: rocket.cat
|
||||
- Merge users: Turn the radio button to the _on_ position
|
||||
- Show Button on Login Page: Turn the radio button to the _on_ position
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
6. Click _Save changes_ in the top right corner of the screen
|
||||
|
||||
### Step 4 (Optional)
|
||||
|
||||
:::note
|
||||
By default, Rocket.chat will attempt to use two-factor authentication with any new user coming in to the system and allows users to change their information
|
||||
:::
|
||||
|
||||
**To disable changing user information and other options inside Rocket.chat:**
|
||||
|
||||
Navigate to the _Accounts_ settings to change the following:
|
||||
|
||||
- Allow Name Change: Off
|
||||
- Allow Username Change: Off
|
||||
- Allow Email Change: Off
|
||||
- Allow Password Change for OAuth Users: Off
|
||||
|
||||
**If you are using Two Factor authentication through authentik:**
|
||||
|
||||
Navigate to the _Accounts_ settings, Scroll Down to Two Factor Authentication and turn off _Enable Two Factor Authentication_
|
||||
|
||||
**Registration Options**
|
||||
Navigate to the _Accounts_ settings, Scroll Down to Registration and choose your [registration options](https://docs.rocket.chat/guides/administration/settings/account-settings#registration), such as:
|
||||
|
||||
- Registration Form: Disabled
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 7.4 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 6.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 8.0 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.3 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
@ -0,0 +1,108 @@
|
||||
---
|
||||
title: Integrate with Roundcube
|
||||
sidebar_label: Roundcube
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Roundcube
|
||||
|
||||
> **Roundcube** is a browser-based multilingual IMAP client with an application-like user interface.
|
||||
> It provides full functionality you expect from an email client, including MIME support, address book, folder manipulation, message searching and spell checking
|
||||
>
|
||||
> -- https://roundcube.net
|
||||
|
||||
This integration describes how to use Roundcube's oauth support with authentik to automatically sign into an email account.
|
||||
The mail server must support XOAUTH2 for both SMTPD and IMAP/POP. Postfix SMTP server can also use Dovecot for authentication which provides Postfix with xoauth2 capability without configuring it separately.
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `roudcube.company` is the FQDN of the Roundcube installation.
|
||||
|
||||
:::note
|
||||
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 Roundcube with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### Create property mappings
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**. Create a **Scope Mapping** with the following settings:
|
||||
- **Name**: Set an appropriate name.
|
||||
- **Scope Name**: `dovecotprofile`
|
||||
- **Description**: Set an appropriate description, if desired.
|
||||
- **Expression**:
|
||||
```python
|
||||
return {
|
||||
"name": request.user.name,
|
||||
"given_name": request.user.name,
|
||||
"family_name": "",
|
||||
"preferred_username": request.user.username,
|
||||
"nickname": request.user.username,
|
||||
}
|
||||
```
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://roundcube.company/index.php?\_task=settings&\_action=plugin.oauth_redirect`.
|
||||
- Select any available signing key.
|
||||
- Under **Advanced protocol settings**, add the scope you just created to the list of selected scopes.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Roundcube Configuration
|
||||
|
||||
```
|
||||
$config['oauth_provider'] = 'generic';
|
||||
$config['oauth_provider_name'] = 'authentik';
|
||||
$config['oauth_client_id'] = '<Client ID>';
|
||||
$config['oauth_client_secret'] = '<Client Secret>';
|
||||
$config['oauth_auth_uri'] = 'https://authentik.company/application/o/authorize/';
|
||||
$config['oauth_token_uri'] = 'https://authentik.company/application/o/token/';
|
||||
$config['oauth_identity_uri'] = 'https://authentik.company/application/o/userinfo/';
|
||||
$config['oauth_scope'] = "email openid dovecotprofile";
|
||||
$config['oauth_auth_parameters'] = [];
|
||||
$config['oauth_identity_fields'] = ['email'];
|
||||
```
|
||||
|
||||
## Dovecot Configuration
|
||||
|
||||
Add xoauth2 as an authentication mechanism and configure the following parameters in your Dovecot configuration.
|
||||
|
||||
```
|
||||
tokeninfo_url = https://authentik.company/application/o/userinfo/?access_token=
|
||||
introspection_url = https://<Client ID>:<Client Secret>@authentik.company/application/o/introspect/
|
||||
introspection_mode = post
|
||||
force_introspection = yes
|
||||
active_attribute = active
|
||||
active_value = true
|
||||
username_attribute = email
|
||||
tls_ca_cert_file = /etc/ssl/certs/ca-certificates.crt
|
||||
```
|
||||
|
||||
:::note
|
||||
With this setup Dovecot can also be used with other email clients that support XOAUTH2 authentication, however
|
||||
most available software (including Fair Email for Android and Thunderbird) only come with support for Gmail,
|
||||
Outlook etc with no way to configure custom email servers.
|
||||
:::
|
||||
|
||||
## Additional Resources
|
||||
|
||||
Please refer to the following for further configuration information:
|
||||
|
||||
- https://roundcube.net
|
||||
- https://github.com/roundcube/roundcubemail/wiki/Configuration:-OAuth2
|
||||
- https://doc.dovecot.org/configuration_manual/authentication/oauth2/
|
||||
@ -0,0 +1,376 @@
|
||||
---
|
||||
title: Integrate with SharePoint Server SE
|
||||
sidebar_label: SharePoint Server SE
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Microsoft SharePoint
|
||||
|
||||
> SharePoint is a proprietary, web-based collaborative platform that integrates natively with Microsoft 365.
|
||||
>
|
||||
> Launched in 2001, SharePoint is primarily sold as a document management and storage system, although it is also used for sharing information through an intranet, implementing internal applications, and for implementing business processes.
|
||||
>
|
||||
> -- https://en.wikipedia.org/wiki/SharePoint
|
||||
|
||||
> Organizations use Microsoft SharePoint to create websites.
|
||||
>
|
||||
> You can use it as a secure place to store, organize, share, and access information from any device.
|
||||
> All you need is a web browser, such as Microsoft Edge, Internet Explorer, Chrome, or Firefox.
|
||||
>
|
||||
> -- https://support.microsoft.com/en-us/office/what-is-sharepoint-97b915e6-651b-43b2-827d-fb25777f446f
|
||||
|
||||
:::note
|
||||
There are many ways to implement SSO mechanism within Microsoft SharePoint Server Subscription Edition.
|
||||
|
||||
These guidelines provides the procedure to integrate authentik with an OIDC provider based on Microsoft documentation.
|
||||
(cf. https://learn.microsoft.com/en-us/sharepoint/security-for-sharepoint-server/set-up-oidc-auth-in-sharepoint-server-with-msaad)
|
||||
|
||||
In addition, it provides the procedure to enable claims augmentations in order to resolve group memberships.
|
||||
|
||||
For all other integration models, read Microsoft official documentation.
|
||||
(cf. https://learn.microsoft.com/en-us/sharepoint/security-for-sharepoint-server/plan-user-authentication)
|
||||
:::
|
||||
|
||||
:::caution
|
||||
This setup only works starting with **authentik** version **2023.10** and Microsoft **SharePoint** Subscription Edition starting with the **Cumulative Updates** of **September 2023**.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
When you configure OIDC with authentik, you need the following resources:
|
||||
|
||||
1. A SharePoint Server Subscription Edition farm starting with CU of September 2023
|
||||
2. An authentik instance starting with version 2023.10
|
||||
3. (Optional) [LDAPCP](https://www.ldapcp.com/docs/overview/introduction/) installed on the target SharePoint farm
|
||||
|
||||
:::info
|
||||
Ensure that the authentik and SharePoint Server clocks are synchronized.
|
||||
:::
|
||||
|
||||
These guidelines use the following placeholders for the overall setup:
|
||||
|
||||
| Name | Placeholder | Sample value |
|
||||
| -------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
|
||||
| authentik Application Name | `auth.applicationName` | SharePoint SE |
|
||||
| authentik Application Slug | `auth.applicationSlug` | sharepoint-se |
|
||||
| authentik OIDC Name | `auth.providerName` | OIDC-SP |
|
||||
| authentik OIDC Configuration URL | `auth.providerConfigURL` | https://authentik.company/application/o/sharepoint-se/.well-known/openid-configuration |
|
||||
| authentik OIDC Client ID | `auth.providerClientID` | 0ab1c234d567ef8a90123bc4567890e12fa3b45c |
|
||||
| authentik OIDC Redirect URIs | `auth.providerRedirectURI` | https://sharepoint.company/.\* |
|
||||
| (Optional) authentik LDAP Outpost URI | `ldap.outpostURI` | ak-outpost-ldap.authentik.svc.cluster.local |
|
||||
| (Optional) authentik LDAP Service Account | `ldap.outpostServiceAccount` | cn=ldapservice,ou=users,dc=ldap,dc=goauthentik,dc=io |
|
||||
| (Optional) authentik LDAP Service Account Password | `ldap.outpostServiceAccountPassword` | mystrongpassword |
|
||||
| SharePoint Default Web Application URL | `sp.webAppURL` | https://sharepoint.company |
|
||||
| SharePoint Trusted Token Issuer Name | `sp.issuerName` | Authentik |
|
||||
| SharePoint Trusted Token Issuer Description | `sp.issuerDesc` | authentik IDP |
|
||||
|
||||
## authentik configuration
|
||||
|
||||
### Step 1: Create authentik OpenID Property Mappings
|
||||
|
||||
SharePoint requires additional properties within the OpenID and profile scopes in order to operate OIDC properly and be able to map incoming authentik OID Claims with Microsoft Claims.
|
||||
|
||||
Additional information from Microsoft documentation:
|
||||
|
||||
- https://learn.microsoft.com/en-us/entra/identity-platform/id-tokens#validate-tokens
|
||||
- https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#payload-claims
|
||||
|
||||
#### Add an OpenID scope mapping for SharePoint
|
||||
|
||||
From the authentik Admin Dashboard:
|
||||
|
||||
1. Open **Customization > Property Mappings** page from the sidebar.
|
||||
2. Click **Create** from the property mapping list command bar.
|
||||
3. Within the new property mapping form, select **Scope Mapping**.
|
||||
4. Click **Next** and enter the following values:
|
||||
- **Name**: SPopenid
|
||||
- **Scope name**: openid
|
||||
- **Expression**:
|
||||
|
||||
```python
|
||||
return {
|
||||
"nbf": "0", # Identifies the time before which the JWT can't be accepted for processing.
|
||||
# 0 stand for the date 1970-01-01 in unix timestamp
|
||||
"oid": user.uid, # This ID uniquely identifies the user across applications - two different applications signing in the same user receives the same value in the oid claim.
|
||||
"upn": user.username # (Optional) User Principal Name, used for troubleshooting within JWT tokens or to setup SharePoint like ADFS
|
||||
}
|
||||
```
|
||||
|
||||
5. Click **Finish**.
|
||||
|
||||
#### Add a profile scope mapping for SharePoint
|
||||
|
||||
From the authentik Admin Dashboard:
|
||||
|
||||
1. Open **Customization > Property Mappings** page from the sidebar.
|
||||
2. Click **Create** from the property mapping list command bar.
|
||||
3. Within the new property mapping form, select **Scope Mapping**.
|
||||
4. Click **Next** and enter the following values:
|
||||
- **Name**: SPprofile
|
||||
- **Scope name**: profile
|
||||
- **Expression**:
|
||||
|
||||
```python
|
||||
return {
|
||||
"name": request.user.name, # The name claim provides a human-readable value that identifies the subject of the token.
|
||||
"given_name": request.user.name, # Interoperability with Microsoft Entra ID
|
||||
"unique_name": request.user.name, # (Optional) Used for troubleshooting within JWT tokens or to setup SharePoint like ADFS
|
||||
"preferred_username": request.user.username, # (Optional) The primary username that represents the user.
|
||||
"nickname": request.user.username, # (Optional) Used for troubleshooting within JWT tokens or to setup SharePoint like ADFS
|
||||
"roles": [group.name for group in request.user.ak_groups.all()], # The set of roles that were assigned to the user who is logging in.
|
||||
}
|
||||
```
|
||||
|
||||
5. Click **Finish**.
|
||||
|
||||
### Step 2: Create authentik Open ID Connect Provider
|
||||
|
||||
From the authentik Admin Dashboard:
|
||||
|
||||
1. Open **Applications > Providers** page from the sidebar.
|
||||
2. Click **Create** from the provider list command bar.
|
||||
3. Within the new provider form, select **OAuth2/OpenID Provider**.
|
||||
4. Click **Next** and enter the following values:
|
||||
- **Name**: `auth.providerName`
|
||||
- **Authentication flow**: default-authentication-flow
|
||||
- **Authorization flow**: default-provider-authorization-implicit-consent
|
||||
:::note
|
||||
use the explicit flow if user consents are required
|
||||
:::
|
||||
- **Redirect URIs / Origins**: `auth.providerRedirectURI`
|
||||
- **Signing Key**: authentik Self-signed Certificate
|
||||
:::note
|
||||
The certificate is used for signing JWT tokens;, if you change it after the integration do not forget to update your SharePoint Trusted Certificate.
|
||||
:::
|
||||
- **Access code validity**: minutes=5
|
||||
:::note
|
||||
The minimum is 5 minutes, otherwise SharePoint backend might consider the access code expired.
|
||||
:::
|
||||
- **Access Token validity**: minutes=15
|
||||
:::note
|
||||
The minimum is 15 minutes, otherwise SharePoint backend will consider the access token expired.
|
||||
:::
|
||||
- **Scopes**: select default email, SPopenid and SPprofile
|
||||
- **Subject mode**: Based on the User's hashed ID
|
||||
5. Click **Finish**.
|
||||
|
||||
### Step 3: Create an application in authentik
|
||||
|
||||
From the authentik Admin Dashboard:
|
||||
|
||||
1. Open **Applications > Applications** page from the sidebar.
|
||||
2. Click **Create** from the application list command bar.
|
||||
3. Within the new application form, enter the following values:
|
||||
- **Name**: `auth.applicationName`
|
||||
- **Slug**: `auth.applicationSlug`
|
||||
- **Provider**: `auth.providerName`
|
||||
- (Optional) **Launch URL**: `sp.webAppURL`
|
||||
- (Optional) **Icon**: https://res-1.cdn.office.net/files/fabric-cdn-prod_20221209.001/assets/brand-icons/product/svg/sharepoint_48x1.svg
|
||||
4. Click **Create**.
|
||||
|
||||
### Step 4: Setup OIDC authentication in SharePoint Server
|
||||
|
||||
#### Pre-requisites
|
||||
|
||||
##### Update SharePoint farm properties
|
||||
|
||||
The following PowerShell script must be updated according to your environment and executed as **Farm Admin account** with **elevated privileges** on a SharePoint Server.
|
||||
|
||||
:::caution
|
||||
|
||||
- Update placeholders
|
||||
- Read all script's comments
|
||||
|
||||
:::
|
||||
|
||||
```PowerShell
|
||||
Add-PSSnapin microsoft.sharepoint.powershell
|
||||
|
||||
# Setup farm properties to work with OIDC
|
||||
$cert = New-SelfSignedCertificate -CertStoreLocation Cert:\LocalMachine\My -Provider 'Microsoft Enhanced RSA and AES Cryptographic Provider' -Subject "CN=SharePoint Cookie Cert"
|
||||
$rsaCert = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
|
||||
$fileName = $rsaCert.key.UniqueName
|
||||
|
||||
#If you have multiple SharePoint servers in the farm, you need to export certificate by Export-PfxCertificate and import certificate to all other SharePoint servers in the farm by Import-PfxCertificate and apply the same permissions as below.
|
||||
|
||||
#After certificate is successfully imported to SharePoint Server, we will need to grant access permission to certificate private key.
|
||||
|
||||
$path = "$env:ALLUSERSPROFILE\Microsoft\Crypto\RSA\MachineKeys\$fileName"
|
||||
$permissions = Get-Acl -Path $path
|
||||
|
||||
#Please replace the <web application pool account> with the real application pool account of your web application.
|
||||
$access_rule = New-Object System.Security.AccessControl.FileSystemAccessRule("$($env:computername)\WSS_WPG", 'Read', 'None', 'None', 'Allow')
|
||||
$permissions.AddAccessRule($access_rule)
|
||||
Set-Acl -Path $path -AclObject $permissions
|
||||
|
||||
#Then we update farm properties only once.
|
||||
$f = Get-SPFarm
|
||||
$f.Farm.Properties['SP-NonceCookieCertificateThumbprint']=$cert.Thumbprint
|
||||
$f.Farm.Properties['SP-NonceCookieHMACSecretKey']='seed'
|
||||
$f.Farm.Update()
|
||||
```
|
||||
|
||||
##### SharePoint settings in case of SSL offloading
|
||||
|
||||
Update the SharePoint farm to accept OAuth authentication over HTTP.
|
||||
|
||||
The following PowerShell script must be updated according to your environment and executed as **Farm Admin account** with **elevated privileges** on a SharePoint Server.
|
||||
|
||||
```PowerShell
|
||||
Add-PSSnapin microsoft.sharepoint.powershell
|
||||
$c = get-spsecuritytokenserviceconfig
|
||||
$c.AllowOAuthOverHttp = $true
|
||||
$c.update()
|
||||
```
|
||||
|
||||
#### Create SharePoint authentication provider
|
||||
|
||||
The following PowerShell script must be updated according to your environment and executed as **Farm Admin account** with **elevated privileges** on a SharePoint Server.
|
||||
|
||||
:::caution
|
||||
|
||||
- Update placeholders
|
||||
- Read all script's comments.
|
||||
|
||||
:::
|
||||
|
||||
```PowerShell
|
||||
Add-PSSnapin microsoft.sharepoint.powershell
|
||||
|
||||
# OIDC Settings
|
||||
$metadataendpointurl = "auth.providerConfigURL"
|
||||
$clientIdentifier = "auth.providerClientID"
|
||||
$trustedTokenIssuerName = "sp.issuerName"
|
||||
$trustedTokenIssuerDescription = "sp.issuerDesc"
|
||||
|
||||
# OIDC Claims Mapping
|
||||
## Identity claim: oid => defined within the Authentik scope mapping
|
||||
$idClaim = New-SPClaimTypeMapping "http://schemas.microsoft.com/identity/claims/objectidentifier" -IncomingClaimTypeDisplayName "oid" -SameAsIncoming
|
||||
|
||||
## User claims mappings
|
||||
$claims = @(
|
||||
$idClaim
|
||||
## User Roles (Group membership)
|
||||
,(New-SPClaimTypeMapping ([System.Security.Claims.ClaimTypes]::Role) -IncomingClaimTypeDisplayName "Role" -SameAsIncoming)
|
||||
## User email
|
||||
,(New-SPClaimTypeMapping ([System.Security.Claims.ClaimTypes]::Email) -IncomingClaimTypeDisplayName "Email" -SameAsIncoming)
|
||||
## User given_name
|
||||
,(New-SPClaimTypeMapping ([System.Security.Claims.ClaimTypes]::GivenName) -IncomingClaimTypeDisplayName "GivenName" -SameAsIncoming )
|
||||
## (Optional) User account name
|
||||
#,(New-SPClaimTypeMapping ([System.Security.Claims.ClaimTypes]::NameIdentifier) -IncomingClaimTypeDisplayName "Username" -SameAsIncoming)
|
||||
|
||||
)
|
||||
|
||||
# Trust 3rd party identity token issuer
|
||||
$trustedTokenIssuer = New-SPTrustedIdentityTokenIssuer -Name $trustedTokenIssuerName -Description $trustedTokenIssuerDescription -ClaimsMappings $claims -IdentifierClaim $idClaim.InputClaimType -DefaultClientIdentifier $clientIdentifier -MetadataEndPoint $metadataendpointurl -Scope "openid email profile"
|
||||
#Note: Remove the profile scope if you plan to use the LDAPCP claims augmentation.
|
||||
|
||||
# Create the SharePoint authentication provider based on the trusted token issuer
|
||||
New-SPAuthenticationProvider -TrustedIdentityTokenIssuer $trustedTokenIssuer
|
||||
|
||||
```
|
||||
|
||||
#### Configure SharePoint web applications
|
||||
|
||||
From the Central Administration opened as a Farm Administrator:
|
||||
|
||||
1. Open the **Application Management > Manage web applications** page.
|
||||
2. Select your web application `sp.webAppURL`.
|
||||
3. Click **Authentication Providers** from the ribbon bar.
|
||||
4. According to your environment, click on the target zone such as "Default".
|
||||
5. Update the authentication provider form as following:
|
||||
- Check **Trusted Identity Provider**
|
||||
- Check the newly created provider named `sp.issuerName`
|
||||
- (Optional) Set **Custom Sign In Page**: /\_trust/default.aspx
|
||||
6. Click **Save**.
|
||||
|
||||
Repeat all steps for each target web applications that matches with `auth.providerRedirectURI`.
|
||||
|
||||
## (Optional) SharePoint enhancements
|
||||
|
||||
Objectives :
|
||||
|
||||
- Integrate SharePoint People Picker with authentik to search users and groups
|
||||
- Augment SharePoint user claims at login stage
|
||||
- Resolve user's membership
|
||||
|
||||
:::caution
|
||||
[LDAPCP](https://www.ldapcp.com/docs/overview/introduction/) must be installed on the target SharePoint farm.
|
||||
:::
|
||||
|
||||
### Step 1: Assign LDAPCP as claim provider for the identity token issuer
|
||||
|
||||
The following PowerShell script must be updated according to your environment and executed as **Farm Admin account** with **elevated privileges** on a SharePoint Server.
|
||||
|
||||
:::caution
|
||||
|
||||
- Update placeholders
|
||||
- Read all script's comments
|
||||
|
||||
:::
|
||||
|
||||
```PowerShell
|
||||
Add-PSSnapin microsoft.sharepoint.powershell
|
||||
$trustedTokenIssuerName = "sp.issuerName"
|
||||
|
||||
$sptrust = Get-SPTrustedIdentityTokenIssuer $trustedTokenIssuerName
|
||||
$sptrust.ClaimProviderName = "LDAPCP"
|
||||
$sptrust.Update()
|
||||
```
|
||||
|
||||
### Step 2: Configure LDAPCP claim types
|
||||
|
||||
From the SharePoint Central Administration opened as a Farm Administrator:
|
||||
|
||||
1. Open **Security > LDAPCP Configuration > Claim types configuration** page.
|
||||
2. Update the mapping table to match these value:
|
||||
|
||||
| Claim type | Entity type | LDAP class | LDAP Attribute to query | LDAP attribute to display | PickerEntity metadata |
|
||||
| ------------------------------------------------------------- | ----------- | ---------- | ----------------------- | ------------------------- | --------------------- |
|
||||
| http://schemas.microsoft.com/identity/claims/objectidentifier | User | user | uid | sn | UserId |
|
||||
| LDAP attribute linked to the main mapping for object User | User | user | mail | | Email |
|
||||
| LDAP attribute linked to the main mapping for object User | User | user | sn | | DisplayName |
|
||||
| http://schemas.microsoft.com/ws/2008/06/identity/claims/role | Group | group | cn | | DisplayName |
|
||||
| LDAP attribute linked to the main mapping for object Group | Group | group | uid | | SPGroupID |
|
||||
|
||||
### Step 3: Create an authentik LDAP Outpost
|
||||
|
||||
From the authentik Admin Dashboard:
|
||||
|
||||
:::note
|
||||
The following procedure apply to an authentik deployment within Kubernetes.
|
||||
|
||||
For other kinds of deployment, please refer to the [authentik documentation](https://goauthentik.io/docs/).
|
||||
:::
|
||||
|
||||
1. Follow authentik [LDAP Provider Generic Setup](https://version-2023-10.goauthentik.io/docs/providers/ldap/generic_setup) with the following steps :
|
||||
- **Create User/Group** to create a "service account" for `ldap.outpostServiceAccount` and a searchable group of users & groups
|
||||
- **LDAP Flow** to create the authentication flow for the LDAP Provider
|
||||
- **LDAP Provider** to create an LDAP provider which can be consumed by the LDAP Application
|
||||
2. Open **Applications > Applications** page from the sidebar.
|
||||
3. Open the edit form of your application `auth.applicationName`.
|
||||
4. In the edit form:
|
||||
- **Backchannel Providers**: add the LDAP provider previously created
|
||||
5. Click **Update**.
|
||||
|
||||
### Step 4: Configure LDAPCP global configuration
|
||||
|
||||
From the SharePoint Central Administration opened as a Farm Administrator:
|
||||
|
||||
1. Open the **Security > LDAPCP Configuration > Global configuration** page.
|
||||
2. Add an LDAP connection with th following properties:
|
||||
- **LDAP Path**: LDAP://`ldap.outpostURI`/dc=ldap,dc=goauthentik,dc=io
|
||||
- **Username**: `ldap.outpostServiceAccount`
|
||||
- **Password**: `ldap.outpostServiceAccountPassword`
|
||||
- **Authentication types**: check ServerBind
|
||||
3. Augmentation - Check **Enable augmentation**
|
||||
4. Augmentation - Select the Role claim "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
|
||||
5. Augmentation - Check only "**Query this server**" for your `ldap.outpostURI`
|
||||
6. User identifier properties:
|
||||
- **LDAP class**: user
|
||||
- **LDAP attribute**: uid
|
||||
7. Display of user identifier results:
|
||||
- Tick **Show the value of another LDAP attribute**: sn
|
||||
8. Click on "**OK**"
|
||||
|
||||
_Note: The `ldap.outpostURI` should be the IP, hostname, or FQDN of the LDAP Outpost service deployed accessible by your SharePoint farm_.
|
||||
@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Integrate with Slack
|
||||
sidebar_label: Slack
|
||||
support_level: authentik
|
||||
---
|
||||
|
||||
## What is Slack
|
||||
|
||||
> Slack is a platform for collaboration, with chat and real-time video capabilities. To learn more, visit https://slack.com.
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `company.slack.com` is the FQDN of your Slack workspace.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
For additional information about integrating with Slack, refer to their [documentation](https://slack.com/help/topics/205168057-Custom-SAML-single-sign-on).
|
||||
|
||||
## authentik configuration
|
||||
|
||||
To support the integration of Slack with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### Create property mappings
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**. Create two **SAML Provider Property Mapping**s with the following settings:
|
||||
- **Name Mapping:**
|
||||
- **Name**: Choose a descriptive name
|
||||
- **SAML Attribute Name**: `User.Email`
|
||||
- **Friendly Name**: Leave blank
|
||||
- **Expression**: `return request.user.email`
|
||||
- **Email Mapping:**
|
||||
- **Name**: Choose a descriptive name
|
||||
- **SAML Attribute Name**: `User.Username`
|
||||
- **Friendly Name**: Leave blank
|
||||
- **Expression**: `return request.user.username`
|
||||
|
||||
### 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. Take note of the **slug** as it will be required later.
|
||||
- **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.
|
||||
- Set the **ACS URL** to `https://company.slack.com/sso/saml`.
|
||||
- Set the **Issuer** to `https://slack.com`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, add the two **Property Mappings** you created in the previous section, then select a **Signing Certificate**.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Slack configuration
|
||||
|
||||
### Step 4. Configure Slack
|
||||
|
||||
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. **Example**: `https://_authentik.company_/applications/saml/slack/sso/binding/redirect/`
|
||||
- **Identity Provider Issuer**: set to `https://slack.com`
|
||||
- **Public Certificate**: add the certificate, which you can download from the authentik provider, under **Download signing certificate**.
|
||||
4. Optionally, configure the other settings and customize the Sign in button label.
|
||||
5. Click **Save**.
|
||||
@ -0,0 +1,47 @@
|
||||
---
|
||||
title: Integrate with The Lounge
|
||||
sidebar_label: The Lounge
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is The Lounge
|
||||
|
||||
> The Lounge is a modern, web-based IRC (Internet Relay Chat) client that allows users to stay connected to IRC servers even when offline.
|
||||
>
|
||||
> -- https://thelounge.chat/
|
||||
|
||||
:::note
|
||||
This guide assumes you already deployed an LDAP Provider, if not check [here](https://docs.goauthentik.io/docs/add-secure-apps/providers/ldap/generic_setup).
|
||||
If you made any changes, e.g. using a different name for the user, make sure to apply them here as well.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik LDAP outpost installation.
|
||||
- `dc=company,dc=com` the Base DN of the LDAP outpost. If you followed the LDAP provider guide this is: `dc=goauthentik,dc=io`
|
||||
- `ldap_bind_user` the username of the desired LDAP Bind User. If you followed the LDAP provider guide this is: `ldapservice`
|
||||
|
||||
:::note
|
||||
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
|
||||
|
||||
Follow [official documentation](/docs/add-secure-apps/outposts/#create-and-configure-an-outpost) to create an **LDAP outpost**. If you already have an LDAP outpost configured, you can use it without additional setup. No further configuration in authentik is needed.
|
||||
|
||||
### The Lounge configuration
|
||||
|
||||
In the `config.js` file find the `ldap` section and make the following changes:
|
||||
|
||||
1. Set `enable` to `true`
|
||||
2. Set `url` to `ldap://authentik.company`
|
||||
3. Set `primaryKey` to `cn`
|
||||
4. In the `searchDN` section make the following changes:
|
||||
1. Set `rootDN` to `cn=ldap_bind_user,ou=users,dc=company,dc=com`
|
||||
2. Set `rootPassword` to the password you have given to the `ldap_bind_user`
|
||||
3. Set `filter` to `(&(objectClass=user)`
|
||||
1. Alternatively, if you want to restrict access by group, you can set it to: `(&(objectClass=user)(memberOf=cn=group_name,ou=groups,dc=ldap,dc=company,dc=com))`
|
||||
4. Set `base` to `dc=ldap,dc=company,dc=com`
|
||||
5. Finally, save the `config.js` file and restart The Lounge. You should be able to log in via LDAP now, as long as a user with the same name exists.
|
||||
@ -0,0 +1,101 @@
|
||||
---
|
||||
title: Integrate with Vikunja
|
||||
sidebar_label: Vikunja
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Vikunja
|
||||
|
||||
> Vikunja is an Open-Source, self-hosted To-Do list application for all platforms. It is licensed under the GPLv3.
|
||||
>
|
||||
> -- https://vikunja.io/
|
||||
|
||||
:::note
|
||||
This is based on authentik 2021.7.3 and Vikunja V0.17.1 using the Docker-Compose install https://vikunja.io/docs/full-docker-example/. Instructions may differ between versions.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `vik.company` is the FQDN of Vikunja.
|
||||
- `authentik.company` is the FQDN of authentik.
|
||||
- `authentik Login` is the name shown on Vikunja set in config.yml, and used for the Redirect URI. If the name set in config.yml has capitalization or spaces like in this example, they will be set to lowercase and no spaces in the callback URL, like `authentiklogin`.
|
||||
|
||||
:::note
|
||||
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 Vikunja with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://vik.company/auth/openid/authentiklogin`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
|
||||
|
||||
## Vikunja configuration
|
||||
|
||||
Edit/Create your `config.yml` file for Vikunja. Local authentication can be safely disabled in the Local block if all users must login through authentik, in this example it is left enabled.
|
||||
|
||||
Incorporate the following example Auth block into your `config.yml`:
|
||||
|
||||
```bash
|
||||
auth:
|
||||
# Local authentication will let users log in and register (if enabled) through the db.
|
||||
# This is the default auth mechanism and does not require any additional configuration.
|
||||
local:
|
||||
# Enable or disable local authentication
|
||||
enabled: true
|
||||
# OpenID configuration will allow users to authenticate through a third-party OpenID Connect compatible provider.<br/>
|
||||
# The provider needs to support the `openid`, `profile` and `email` scopes.<br/>
|
||||
# **Note:** Some openid providers (like gitlab) only make the email of the user available through openid claims if they have set it to be publicly visible.
|
||||
# If the email is not public in those cases, authenticating will fail.
|
||||
# **Note 2:** The frontend expects to be redirected after authentication by the third party
|
||||
# to <frontend-url>/auth/openid/<auth key>. Please make sure to configure the redirect url with your third party
|
||||
# auth service accordingly if you're using the default Vikunja frontend.
|
||||
# Take a look at the [default config file](https://github.com/go-vikunja/api/blob/main/config.yml.sample) for more information about how to configure openid authentication.
|
||||
openid:
|
||||
# Enable or disable OpenID Connect authentication
|
||||
enabled: true
|
||||
# A list of enabled providers
|
||||
providers:
|
||||
# The name of the provider as it will appear in the frontend.
|
||||
- name: "authentik Login"
|
||||
# The auth url to send users to if they want to authenticate using OpenID Connect.
|
||||
authurl: https://authentik.company/application/o/vikunja/
|
||||
# The client ID used to authenticate Vikunja at the OpenID Connect provider.
|
||||
clientid: THIS IS THE CLIENT ID YOU COPIED FROM STEP 1 in authentik
|
||||
# The client secret used to authenticate Vikunja at the OpenID Connect provider.
|
||||
clientsecret: THIS IS THE CLIENT SECRET YOU COPIED FROM STEP 1 in authentik
|
||||
```
|
||||
|
||||
:::note
|
||||
You need to restart the Vikunja API after applying the OpenID configuration to Vikunja.
|
||||
:::
|
||||
|
||||
:::note
|
||||
Vikunja Configuration Reference: https://vikunja.io/docs/config-options/#auth
|
||||
:::
|
||||
|
||||
### Step 3
|
||||
|
||||
In authentik, create an application which uses this provider. Optionally apply access restrictions to the application using policy bindings.
|
||||
|
||||
- Name: Vikunja
|
||||
- Slug: vikunja
|
||||
- Provider: vikunja
|
||||
- Launch URL: https://vik.company
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
@ -0,0 +1,94 @@
|
||||
---
|
||||
title: Integrate with Wekan
|
||||
sidebar_label: Wekan
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Wekan
|
||||
|
||||
> Wekan is an open-source kanban board which allows a card-based task and to-do management.
|
||||
>
|
||||
> -- https://github.com/wekan/wekan/wiki
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `wekan.company` is the FQDN of the wekan installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Wekan with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://wekan.company/\_oauth/oidc`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Wekan configuration
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
<Tabs
|
||||
defaultValue="docker"
|
||||
values={[
|
||||
{label: 'Docker', value: 'docker'},
|
||||
{label: 'Standalone', value: 'standalone'},
|
||||
]}>
|
||||
<TabItem value="docker">
|
||||
If your Wekan is running in docker, add the following environment variables for authentik
|
||||
|
||||
```yaml
|
||||
environment: OAUTH2_ENABLED=true
|
||||
OAUTH2_LOGIN_STYLE=redirect
|
||||
OAUTH2_CLIENT_ID=<Client ID from above>
|
||||
OAUTH2_SERVER_URL=https://authentik.company
|
||||
OAUTH2_AUTH_ENDPOINT=/application/o/authorize/
|
||||
OAUTH2_USERINFO_ENDPOINT=/application/o/userinfo/
|
||||
OAUTH2_TOKEN_ENDPOINT=/application/o/token/
|
||||
OAUTH2_SECRET=<Client Secret from above>
|
||||
OAUTH2_ID_MAP=sub
|
||||
OAUTH2_USERNAME_MAP=email
|
||||
OAUTH2_FULLNAME_MAP=given_name
|
||||
OAUTH2_EMAIL_MAP=email
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="standalone">
|
||||
|
||||
edit `.env` and add the following:
|
||||
|
||||
```ini
|
||||
# authentik OAUTH Config
|
||||
OAUTH2_ENABLED='true'
|
||||
OAUTH2_LOGIN_STYLE='redirect'
|
||||
OAUTH2_CLIENT_ID='<Client ID from above>'
|
||||
OAUTH2_SERVER_URL='https://authentik.company'
|
||||
OAUTH2_AUTH_ENDPOINT='/application/o/authorize/'
|
||||
OAUTH2_USERINFO_ENDPOINT='/application/o/userinfo/'
|
||||
OAUTH2_TOKEN_ENDPOINT='/application/o/token/'
|
||||
OAUTH2_SECRET='<Client Secret from above>'
|
||||
OAUTH2_ID_MAP='sub'
|
||||
OAUTH2_USERNAME_MAP='email'
|
||||
OAUTH2_FULLNAME_MAP='given_name'
|
||||
OAUTH2_EMAIL_MAP='email'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
@ -0,0 +1,104 @@
|
||||
---
|
||||
title: Integrate with Writefreely
|
||||
sidebar_label: Writefreely
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Writefreely
|
||||
|
||||
> An open source platform for building a writing space on the web.
|
||||
>
|
||||
> -- https://writefreely.org/
|
||||
|
||||
:::caution
|
||||
Currently it is not possible to connect Writefreely to authentik without making an adjustment in the database. See [here](https://github.com/writefreely/writefreely/issues/516) and [Writefreely Setup](../writefreely/index.md#writefreely-setup)
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `writefreely.company` is the FQDN of the Writefreely installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Writefreely with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://writefreely.company/oauth/callback/generic`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Writefreely Setup
|
||||
|
||||
### Database
|
||||
|
||||
Currently the column `access_token` is configured too small, so it needs to be adjusted
|
||||
|
||||
```
|
||||
ALTER TABLE `oauth_users` MODIFY `access_token` varchar(2048);
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Configure Writefreely settings by editing the `config.ini` and add the following:
|
||||
|
||||
So that new users can be created the following variable must be set to true
|
||||
|
||||
```
|
||||
open_registration = false
|
||||
```
|
||||
|
||||
To disable the local login/registration use the following setting (this is useful because writefreely attracts a lot of spam)
|
||||
|
||||
```
|
||||
disable_password_auth = false
|
||||
```
|
||||
|
||||
The following settings must be made for oauth
|
||||
|
||||
```
|
||||
[oauth.generic]
|
||||
client_id = <Client ID>
|
||||
client_secret = <Client Secret>
|
||||
host = https://authentik.company
|
||||
display_name = authentik
|
||||
callback_proxy =
|
||||
callback_proxy_api =
|
||||
token_endpoint = /application/o/token/
|
||||
inspect_endpoint = /application/o/userinfo/
|
||||
auth_endpoint = /application/o/authorize/
|
||||
scope = openid profile email
|
||||
allow_disconnect = false
|
||||
map_user_id = sub
|
||||
map_username = nickname
|
||||
map_display_name = name
|
||||
map_email = email
|
||||
```
|
||||
|
||||
Restart writefreely.service
|
||||
|
||||
## Account linking
|
||||
|
||||
If your usernames in authentik and WriteFreely are different, you might need to link your accounts before being able to use SSO.
|
||||
|
||||
To link the accounts, first log into Writefreely with local credentials, and then navigate to **Customize -->Account Settings**. In the option "Linked Accounts", click on "authentik".
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- https://writefreely.org/docs/latest/admin/config
|
||||
@ -0,0 +1,88 @@
|
||||
---
|
||||
title: Integrate with Zulip
|
||||
sidebar_label: Zulip
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Zulip
|
||||
|
||||
> Zulip is an open-source team chat application that organizes conversations into topic-based streams, enabling more structured and efficient communication compared to traditional linear chat platforms.
|
||||
>
|
||||
> -- https://zulip.com
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `zulip.company` is the FQDN of the Zulip instance.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Zulip with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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. Take note of the **slug** as it will be required later.
|
||||
- **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.
|
||||
- Set the **ACS URL** to `https://zulip.company/complete/saml/`.
|
||||
- Set the **Issuer** to `https://authentik.company`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, select an available signing certificate.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Zulip configuration
|
||||
|
||||
Zulip is a Django application and is configured using `/etc/zulip/settings.py`. Only settings that differ
|
||||
from the defaults are displayed below. Please make sure you have the latest `settings.py` file as more settings
|
||||
might have been added to defaults since you installed Zulip.
|
||||
|
||||
Uncomment `zproject.backends.SAMLAuthBackend` inside the `AUTHENTICATION_BACKENDS` parameter to enable SAML support
|
||||
and fill in the following required configuration.
|
||||
|
||||
```
|
||||
SOCIAL_AUTH_SAML_ORG_INFO = {
|
||||
"en-US": {
|
||||
"displayname": "authentik Zulip",
|
||||
"name": "zulip",
|
||||
"url": "{}{}".format("https://", EXTERNAL_HOST),
|
||||
},
|
||||
}
|
||||
|
||||
SOCIAL_AUTH_SAML_ENABLED_IDPS: Dict[str, Any] = {
|
||||
# idp identifier and settings
|
||||
"authentik": {
|
||||
|
||||
# KEEP OTHER SETTINGS AS DEFAULT OR CONFIGURE THEM ACCORDING TO YOUR PREFERENCES
|
||||
"entity_id": "https://authentik.company",
|
||||
"url": "https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/",
|
||||
"display_name": "authentik SAML",
|
||||
},
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Place the certificate you associated with the SAML provider in authentik inside the `/etc/zulip/saml/idps` directory.
|
||||
The certificate file name must match the idp identifier name you set in the configuration (i.e. authentik.crt).
|
||||
|
||||
:::note
|
||||
Remember to restart Zulip.
|
||||
:::
|
||||
|
||||
## Additional Resources
|
||||
|
||||
Please refer to the following for further information:
|
||||
|
||||
- https://zulip.com/
|
||||
- https://zulip.readthedocs.io
|
||||
- https://chat.zulip.org/ (Official public Zulip Chat instance)
|
||||
204
docs/integrations/cloud-providers/aws/index.mdx
Normal file
204
docs/integrations/cloud-providers/aws/index.mdx
Normal file
@ -0,0 +1,204 @@
|
||||
---
|
||||
title: Integrate with Amazon Web Services
|
||||
sidebar_label: Amazon Web Services
|
||||
support_level: authentik
|
||||
---
|
||||
|
||||
## What is AWS
|
||||
|
||||
> Amazon Web Services (AWS) is the world's most comprehensive and broadly adopted cloud, with more than 200 fully featured services available from data centers globally. Millions of customers—including the fastest-growing startups, largest enterprises, and leading government agencies—are using AWS to lower costs, increase security, become more agile, and innovate faster.
|
||||
>
|
||||
> -- https://www.aboutamazon.com/what-we-do/amazon-web-services
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `123412341234` is your AWS account ID.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="iam" label="Classic IAM" default>
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- An AWS account with permissions to create IAM roles and identity providers
|
||||
- An authentik instance with administrator access
|
||||
|
||||
### authentik configuration
|
||||
|
||||
To support the integration of AWS with authentik using the classic IAM method, you need to create an application/provider pair and property mappings in authentik.
|
||||
|
||||
#### Create property mappings
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**. Create two **SAML Provider Property Mapping**s with the following settings:
|
||||
- **Role Mapping:**
|
||||
- **Name**: Choose a descriptive name
|
||||
- **SAML Attribute Name**: `https://aws.amazon.com/SAML/Attributes/Role`
|
||||
- **Friendly Name**: Leave blank
|
||||
- **Expression**: Choose one of these options:
|
||||
|
||||
For a static role:
|
||||
|
||||
```python
|
||||
return "arn:aws:iam::123412341234:role/saml_role,arn:aws:iam::123412341234:saml-provider/authentik"
|
||||
```
|
||||
|
||||
For role assignment based on group membership:
|
||||
|
||||
```python
|
||||
role_name = user.group_attributes().get("aws_role", "")
|
||||
return f"arn:aws:iam::123412341234:role/{role_name},arn:aws:iam::123412341234:saml-provider/authentik"
|
||||
```
|
||||
|
||||
For multiple role choices:
|
||||
|
||||
```python
|
||||
return [
|
||||
"arn:aws:iam::123412341234:role/role_a,arn:aws:iam::123412341234:saml-provider/authentik",
|
||||
"arn:aws:iam::123412341234:role/role_b,arn:aws:iam::123412341234:saml-provider/authentik",
|
||||
"arn:aws:iam::123412341234:role/role_c,arn:aws:iam::123412341234:saml-provider/authentik",
|
||||
]
|
||||
```
|
||||
|
||||
- **Session Name Mapping:**
|
||||
- **Name**: Choose a descriptive name
|
||||
- **SAML Attribute Name**: `https://aws.amazon.com/SAML/Attributes/RoleSessionName`
|
||||
- **Friendly Name**: Leave blank
|
||||
- **Expression**: `return user.username`
|
||||
|
||||
#### 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 (e.g. "AWS"), an optional group for the type of application, the policy engine mode, and optional UI settings. The **slug** will be used in URLs and should match the `aws-slug` placeholder defined earlier.
|
||||
- **Choose a Provider type**: select **SAML Provider** as the provider type.
|
||||
- **Configure the Provider**: provide a name (or accept the auto-provided name), and configure the following required settings:
|
||||
- Set the **ACS URL** to `https://signin.aws.amazon.com/saml`
|
||||
- Set the **Audience** to `urn:amazon:webservices`
|
||||
- Under **Advanced protocol settings**, add both property mappings you created in the previous section
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
4. Download the **Metadata file** from the provider's page.
|
||||
|
||||
### AWS configuration
|
||||
|
||||
1. Log in to the AWS Management Console as an administrator
|
||||
2. Create an IAM role with the desired permissions and note the ARN
|
||||
3. Navigate to [IAM Identity Providers](https://console.aws.amazon.com/iam/home#/providers)
|
||||
4. Click **Create Provider** and configure:
|
||||
- Select **SAML** as the provider type
|
||||
- Upload the metadata file from authentik
|
||||
5. Add the property mappings to the SAML Provider
|
||||
6. Create an application and assign the appropriate policies
|
||||
7. Connect the provider to your application
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="identity-center" label="IAM Identity Center">
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- An AWS account with IAM Identity Center enabled
|
||||
- An authentik instance with administrator access
|
||||
- A certificate for signing SAML assertions (you can use authentik's default or provide your own)
|
||||
|
||||
### authentik configuration
|
||||
|
||||
To support the integration of AWS with authentik using IAM Identity Center, you need to create an application/provider pair in authentik.
|
||||
|
||||
#### 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 (e.g. "AWS Identity Center"), an optional group for the type of application, the policy engine mode, and optional UI settings. The **slug** will be used in URLs and should match the `aws-slug` placeholder defined earlier.
|
||||
- **Choose a Provider type**: select **SAML Provider from metadata** as the provider type.
|
||||
- **Configure the Provider**: provide a name (or accept the auto-provided name), and configure the following required settings:
|
||||
- Upload the metadata file from AWS (obtained in AWS Configuration steps)
|
||||
- Copy the **Issuer URL** to the **Audience** field
|
||||
- Under **Advanced Protocol Settings**, set your **Signing Certificate**
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
4. Under **Related Objects**, download both:
|
||||
- The **Metadata file**
|
||||
- The **Signing Certificate**
|
||||
|
||||
### AWS configuration
|
||||
|
||||
1. Navigate to **IAM Identity Center -> Settings -> Identity Source**
|
||||
2. Click **Actions -> Change identity source**
|
||||
3. Select **External Identity Provider**
|
||||
4. Download the **Service Provider metadata** file
|
||||
5. Upload authentik's metadata file and signing certificate
|
||||
6. Under **Actions -> Manage Authentication**, note the AWS access portal sign-in URL
|
||||
7. Update your authentik application's **Start URL** to match the AWS portal URL.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="scim" label="SCIM Provisioning (Optional)">
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Completed either Classic IAM or IAM Identity Center setup
|
||||
- AWS Identity Center enabled with administrator access
|
||||
- authentik instance with administrator access
|
||||
|
||||
### authentik configuration
|
||||
|
||||
To support the integration of AWS with authentik using SCIM, you need to create a SCIM provider and custom mapping in authentik.
|
||||
|
||||
#### Create property mappings
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**. Create a **SCIM Mapping** with the following settings:
|
||||
- **Name**: Choose a name lexically lower than `authentik default` (e.g. `AWS SCIM User mapping`)
|
||||
- **Expression**:
|
||||
```python
|
||||
# This expression strips the default mapping from its 'photos' attribute,
|
||||
# which is a forbidden property in AWS IAM.
|
||||
return {
|
||||
"photos": None,
|
||||
}
|
||||
```
|
||||
|
||||
#### Create a SCIM provider in authentik
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Providers** > **Providers** and click **Create**.
|
||||
3. Select **SCIM Provider** as the provider type.
|
||||
4. Configure the provider with the following settings:
|
||||
- Set a descriptive name
|
||||
- Set **URL** to the AWS SCIM Endpoint
|
||||
- Set **Token** to the AWS Access Token
|
||||
- Configure user filtering as needed
|
||||
5. Under **User Property Mappings**, add:
|
||||
- The default mapping
|
||||
- Your custom mapping
|
||||
6. Add the SCIM provider to your AWS application's **Backchannel providers**
|
||||
|
||||
### AWS configuration
|
||||
|
||||
1. In AWS Identity Center **Settings**, locate the **Automatic Provisioning** information box
|
||||
2. Click **Enable**
|
||||
3. Note the provided **SCIM Endpoint** and **Access Token**
|
||||
|
||||
The SCIM provider will automatically sync when users, groups, or memberships change. You can manually sync from the provider page.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [AWS IAM SAML Documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html)
|
||||
- [AWS IAM Identity Center Documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)
|
||||
- [AWS SCIM Documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/scim-profile.html)
|
||||
63
docs/integrations/cloud-providers/google/index.md
Normal file
63
docs/integrations/cloud-providers/google/index.md
Normal file
@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Integrate with Google Workspace
|
||||
sidebar_label: Google Workspace
|
||||
support_level: authentik
|
||||
---
|
||||
|
||||
## What is Google Workspace
|
||||
|
||||
> Google Workspace is a collection of cloud computing, productivity and collaboration tools, software and products developed and marketed by Google.
|
||||
>
|
||||
> -- https://en.wikipedia.org/wiki/Google_Workspace
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `example.com` is the default E-mail address configured in Google workspace.
|
||||
|
||||
:::note
|
||||
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
|
||||
|
||||
Create an application in authentik and note the slug, as this will be used later. Set the _Launch URL_ to `https://mail.google.com/a/example.com`.
|
||||
|
||||
Create a SAML provider with the following parameters:
|
||||
|
||||
- ACS URL: `https://www.google.com/a/example.com/acs`
|
||||
- Issuer: `google.com/a/example.com`
|
||||
- Binding: `Post`
|
||||
- Audience: `google.com/a/example.com`
|
||||
|
||||
Under _Advanced protocol settings_, set the option _NameID Property Mapping_ to the default E-mail property mapping called _authentik default SAML Mapping: Email_. Also make sure a _Signing Certificate_ is selected in the same section.
|
||||
|
||||
Copy the values of _SSO URL (Redirect)_ and _SLO URL (Redirect)_ fields from the provider page.
|
||||
|
||||
Click the _Download_ button next to the _Download signing certificate_ label.
|
||||
|
||||
## Google Workspace Configuration
|
||||
|
||||
Log in to the Google Workspace Admin portal by navigating to https://admin.google.com/, and authenticating with a super-admin account.
|
||||
|
||||
Navigate to _Security_ -> _Authentication_ -> _SSO with third-party IdP_.
|
||||
|
||||
Open the _Third-party SSO profile for your organization_ section.
|
||||
|
||||
Check the checkbox _Set up SSO with third-party identity provider_.
|
||||
|
||||
Set the value of _Sign-in page URL_ to the copied _SSO URL (Redirect)_ from above.
|
||||
|
||||
Set the value of _Sign-out page URL_ to the copied _SLO URL (Redirect)_ from above.
|
||||
|
||||
For _Verification certificate_, upload the certificate that you downloaded previously.
|
||||
|
||||
Ensure the option _Use a domain specific issuer_ is enabled.
|
||||
|
||||
## Notes
|
||||
|
||||
Google will not use these SSO settings with super-admins, although they will apply for any other user account. User accounts must already exist in Google workspace when attempting to login with authentik; Google will not create them automatically.
|
||||
|
||||
To verify that the configuration is correct for a super-admin account, navigate to `https://mail.google.com/a/example.com`, which redirects to the configured authentik instance.
|
||||
52
docs/integrations/cloud-providers/hashicorp-cloud/index.md
Normal file
52
docs/integrations/cloud-providers/hashicorp-cloud/index.md
Normal file
@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Integrate with HashiCorp Cloud Platform
|
||||
sidebar_label: HashiCorp Cloud Platform
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is HashiCorp Cloud
|
||||
|
||||
> HashiCorp Cloud Platform is a fully managed platform for Terraform, Vault, Consul, and more.
|
||||
>
|
||||
> -- https://cloud.hashicorp.com/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
## HashiCorp Cloud preparation
|
||||
|
||||
Login in under https://portal.cloud.hashicorp.com. Navigate to the _Settings_ entry in the sidebar, then _SSO_. Enable SSO and configure domain verification for the domain your users email have.
|
||||
|
||||
Under _Initiate SAML integration_, copy _SSO Sign-On URL_ and _Entity ID_.
|
||||
|
||||
## authentik Configuration
|
||||
|
||||
To support the integration of HashiCorp Cloud with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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**.
|
||||
- **Application**: Provide a descriptive name, an optional group, and UI settings. Take note of the **slug** as it will be required later.
|
||||
- **Choose a Provider type**: Select **SAML Provider**.
|
||||
- **Configure the Provider**:
|
||||
- Set the **ACS URL** to the value of `SSO Sign-On URL` in the **HashiCorp Cloud preparation** section.
|
||||
- Set the **Issuer** and **Audience** to the value of `Entity ID` in the **HashiCorp Cloud preparation** section.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, select an available signing certificate.
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## HashiCorp Cloud configuration
|
||||
|
||||
Open the Application's page in authentik and click on the provider name. Copy the value of _SSO URL (Redirect)_ and paste it into the _SAML IDP Single Sign-On URL_ field in the HashiCorp Cloud settings.
|
||||
|
||||
Download the certificate, open it in a text editor, and paste the contents into _SAML IDP Certificate_ in the HashiCorp Cloud settings.
|
||||
|
||||
Afterwards, logging in to HashiCorp Cloud with any email address ending in the domains verified above will redirect to your authentik instance, if those email addresses don't have an existing account.
|
||||
51
docs/integrations/cloud-providers/oracle-cloud/index.md
Normal file
51
docs/integrations/cloud-providers/oracle-cloud/index.md
Normal file
@ -0,0 +1,51 @@
|
||||
---
|
||||
title: Integrate with Oracle Cloud
|
||||
sidebar_label: Oracle Cloud
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Oracle Cloud
|
||||
|
||||
> Oracle Cloud is the first public cloud built from the ground up to be a better cloud for every application. By rethinking core engineering and systems design for cloud computing, we created innovations that accelerate migrations, deliver better reliability and performance for all applications, and offer the complete services customers need to build innovative cloud applications.
|
||||
>
|
||||
> -- https://www.oracle.com/cloud/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `tenant.identity.oraclecloud.com` is the FQDN of your Oracle IDCS endpoint.
|
||||
|
||||
:::note
|
||||
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 Oracle Cloud with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://tenant.identity.oraclecloud.com/oauth2/v1/authorize`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Oracle Cloud configuration
|
||||
|
||||
In Oracle Cloud, open the top-left navigation and go to _Identity & Security_ and then _Domains_. Click on the domain of your choice. Click on _Security_ in the sidebar, then on _Identity providers_.
|
||||
|
||||
Create a new _Social IdP_ via the _Add IdP_ button. Set the name to authentik and fill in the client ID and secret from above.
|
||||
|
||||
Set the _Discovery service URL_ to `https://authentik.company/application/o/oracle-cloud/.well-known/openid-configuration` and save the IdP. The IdP has now been created but must be enabled before it can be used to login with.
|
||||
|
||||
Navigate to _IdP Policies_ in the sidebar and open the default policy by clicking on it. Edit the first rule within the policy. Add authentik under _Assign identity providers_. Here you can optionally also remove username-based logins, however it is recommended to not remove the option until you've verified SSO works.
|
||||
7
docs/integrations/custom.css
Normal file
7
docs/integrations/custom.css
Normal file
@ -0,0 +1,7 @@
|
||||
.theme-doc-sidebar-item-category-level-1 .menu__list-item-collapsible {
|
||||
border-top: 0.5px solid;
|
||||
border-top-color: var(--ifm-category-color, var(--ifm-menu-color-background-active));
|
||||
border-radius: 0;
|
||||
font-weight: 600;
|
||||
padding-block: 0.25em;
|
||||
}
|
||||
59
docs/integrations/dashboards/homarr/index.md
Normal file
59
docs/integrations/dashboards/homarr/index.md
Normal file
@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Integrate with Homarr
|
||||
sidebar_label: Homarr
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Homarr
|
||||
|
||||
> A sleek, modern dashboard that puts all of your apps and services at your fingertips. Control everything in one convenient location. Seamlessly integrates with the apps you've added, providing you with valuable information.
|
||||
>
|
||||
> -- https://homarr.dev/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `homarr.company` is the FQDN of the Homarr installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Homarr with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Create two `strict` redirect URIs and set to `https://homarr.company/api/auth/callback/oidc` and ` http://localhost:50575/api/auth/callback/oidc`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Homarr configuration
|
||||
|
||||
Add the following environment variables to your Homarr configuration. Make sure to fill in the Client ID, Client Secret, OIDC Issuer, and OIDC URI from your authentik instance.
|
||||
|
||||
```sh
|
||||
AUTH_PROVIDERS="oidc,credentials"
|
||||
AUTH_OIDC_CLIENT_ID=<Client ID from authentik>
|
||||
AUTH_OIDC_CLIENT_SECRET=<Client secret from authentik>
|
||||
AUTH_OIDC_ISSUER=https://authentik.company/application/o/<application_slug>/
|
||||
AUTH_OIDC_URI=https://authentik.company/application/o/authorize
|
||||
AUTH_OIDC_CLIENT_NAME=authentik
|
||||
OAUTH_ALLOW_DANGEROUS_EMAIL_ACCOUNT_LINKING=true
|
||||
# Optional: You can add this if you only want to allow auto login via authentik
|
||||
# AUTH_OIDC_AUTO_LOGIN=true
|
||||
```
|
||||
|
||||
Restart the Homarr service for the changes to take effect.
|
||||
57
docs/integrations/dashboards/linkwarden/index.md
Normal file
57
docs/integrations/dashboards/linkwarden/index.md
Normal file
@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Integrate with Linkwarden
|
||||
sidebar_label: Linkwarden
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Linkwarden
|
||||
|
||||
> Linkwarden is an open-source collaborative bookmark manager used to collect, organize, and preserve webpages.
|
||||
>
|
||||
> -- https://linkwarden.app/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `linkwarden.company` is the FQDN of the Linkwarden installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Linkwarden with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://linkwarden.company/api/v1/auth/callback/authentik`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Linkwarden configuration
|
||||
|
||||
To configure Linkwarden to use authentik, add the following values to your `.env` file:
|
||||
|
||||
```
|
||||
NEXT_PUBLIC_AUTHENTIK_ENABLED=true
|
||||
AUTHENTIK_CUSTOM_NAME=authentik # Optionally set a custom provider name. Will be displayed on the login page
|
||||
AUTHENTIK_ISSUER=https://authentik.company/application/o/<application_slug>
|
||||
AUTHENTIK_CLIENT_ID=<Your Client ID>
|
||||
AUTHENTIK_CLIENT_SECRET=<Your Client Secret>
|
||||
```
|
||||
|
||||
After making these changes, restart your Docker containers to apply the new configuration.
|
||||
|
||||
Once completed, Linkwarden should be successfully configured to use authentik as its Single Sign-On SSO provider.
|
||||
82
docs/integrations/dashboards/organizr/index.md
Normal file
82
docs/integrations/dashboards/organizr/index.md
Normal file
@ -0,0 +1,82 @@
|
||||
---
|
||||
title: Integrate with organizr
|
||||
sidebar_label: organizr
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is organizr
|
||||
|
||||
> Organizr allows you to setup "Tabs" that will be loaded all in one webpage.
|
||||
>
|
||||
> -- https://github.com/causefx/Organizr
|
||||
|
||||
This integration leverages authentik's LDAP for the identity provider to achieve an SSO experience. See [ldap provider generic setup](https://docs.goauthentik.io/add-secure-apps/providers/ldap/generic_setup) for setting up the LDAP provider.
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `organizr.company` is the FQDN of the Service installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
Create a new user account _(or reuse an existing)_ for organizr to use for LDAP bind under _Directory_ -> _Users_ -> _Create_, in this example called `ldapservice`.
|
||||
|
||||
Note the DN of this user will be `cn=ldapservice,ou=users,dc=ldap,dc=goauthentik,dc=io`
|
||||
|
||||
:::tip
|
||||
_Optionally_, create a new group like `organizr users` to scope access to the organizr application.
|
||||
:::
|
||||
|
||||
## authentik Configuration
|
||||
|
||||
1. Create a new Proxy Provider for `https://organizr.company`
|
||||
|
||||
_Optionally_, add the regular expression to allow api calls in the advanced protocol settings.
|
||||
|
||||
2. Create a new Application for the `https://organizr.company` Provider.
|
||||
|
||||
:::tip
|
||||
_Optionally_, bind the group to control access to the organizr to the application.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
::: 3. Add the Application to the authentik Embedded Outpost.
|
||||
|
||||
## organizr Configuration
|
||||
|
||||
:::caution
|
||||
Ensure any local usernames/email addresses in organizr do not conflict with usernames/email addresses in authentik.
|
||||
:::
|
||||
|
||||
1. Enable Auth Proxy in organizr _system settings_ -> _main_ -> _Auth Proxy_
|
||||
|
||||
Auth Proxy Header Name: `X-authentik-username`
|
||||
Auth Proxy Whitelist: _your network subnet in CIDR notation IE_ `10.0.0.0/8`
|
||||
Auth Proxy Header Name for Email: `X-authentik-email`
|
||||
Logout URL: `/outpost.goauthentik.io/sign_out`
|
||||
|
||||
|
||||
2. Setup Authentication in organizr _system settings_ -> _main_ -> _Authentication_
|
||||
|
||||
Authentication Type: `Organizr DB + Backend`
|
||||
Authentication Backend: `Ldap`
|
||||
Host Address: `<LDAP Outpost IP address:port>`
|
||||
Host Base DN: `dc=ldap,dc=goauthentik,dc=io`
|
||||
Account Prefix: `cn=`
|
||||
Account Suffix: `,ou=users,dc=ldap,dc=goauthentik,dc=io`
|
||||
Bind Username: `cn=ldapservice,ou=users,dc=ldap,dc=goauthentik,dc=io`
|
||||
Bind Password: `<LDAP bind account password>`
|
||||
LDAP Backend Type: `OpenLDAP`
|
||||
|
||||
|
||||
:::info
|
||||
Access for authentik users is managed locally within organizr under _User Management_. By default, new users are assigned the `User` group.
|
||||
:::
|
||||
:::tip
|
||||
Consider front-ending your application with a [forward auth provider](https://docs.goauthentik.io/docs/add-secure-apps/providers/proxy/forward_auth) for an SSO experience.
|
||||
:::
|
||||
BIN
docs/integrations/dashboards/organizr/organizr1.png
Normal file
BIN
docs/integrations/dashboards/organizr/organizr1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
BIN
docs/integrations/dashboards/organizr/organizr2.png
Normal file
BIN
docs/integrations/dashboards/organizr/organizr2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
BIN
docs/integrations/dashboards/organizr/organizr3.png
Normal file
BIN
docs/integrations/dashboards/organizr/organizr3.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
BIN
docs/integrations/dashboards/organizr/organizr4.png
Normal file
BIN
docs/integrations/dashboards/organizr/organizr4.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
BIN
docs/integrations/dashboards/organizr/organizr5.png
Normal file
BIN
docs/integrations/dashboards/organizr/organizr5.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
BIN
docs/integrations/dashboards/organizr/organizr6.png
Normal file
BIN
docs/integrations/dashboards/organizr/organizr6.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
BIN
docs/integrations/dashboards/organizr/organizr7.png
Normal file
BIN
docs/integrations/dashboards/organizr/organizr7.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 74 KiB |
62
docs/integrations/development/coder/index.md
Normal file
62
docs/integrations/development/coder/index.md
Normal file
@ -0,0 +1,62 @@
|
||||
---
|
||||
title: Integrate with Coder
|
||||
sidebar_label: Coder
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Coder
|
||||
|
||||
> Coder is an open-source platform that provides browser-based cloud development environments, enabling developers and teams to securely write, edit, and manage code remotely without the need for local setup.
|
||||
>
|
||||
> -- https://coder.com
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `coder.company` is the FQDN of your Coder installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Coder with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://coder.company/api/v2/users/oidc/callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Coder configuration
|
||||
|
||||
To support the integration of Coder with authentik, add the following environment variables to your Coder deployment:
|
||||
|
||||
```yaml showLineNumbers
|
||||
CODER_OIDC_ISSUER_URL=https://authentik.company/application/o/<application_slug>/
|
||||
CODER_OIDC_EMAIL_DOMAIN=acme.company,acme-corp.company
|
||||
CODER_OIDC_CLIENT_ID=<Client ID from authentik>
|
||||
CODER_OIDC_CLIENT_SECRET=<Client secret from authentik>
|
||||
CODER_OIDC_SIGN_IN_TEXT=Log in with authentik
|
||||
CODER_OIDC_ICON_URL=https://authentik.company/static/dist/assets/icons/icon.png
|
||||
```
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is properly configured with Coder, log out and attempt to log back in by clicking **Log in with authentik**.
|
||||
|
||||
## Resources
|
||||
|
||||
- [Coder OIDC authentication documentatiom](https://coder.com/docs/admin/users/oidc-auth/)
|
||||
90
docs/integrations/development/engomo/index.mdx
Normal file
90
docs/integrations/development/engomo/index.mdx
Normal file
@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Integrate with engomo
|
||||
sidebar_label: engomo
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is engomo
|
||||
|
||||
> engomo is an low-code app development platform to create enterprise apps for smartphones and tablets based on Android, iOS, or iPadOS.
|
||||
>
|
||||
> -- https://engomo.com/
|
||||
>
|
||||
> This guide explains how to set up engomo to use authentik as the OAuth provider for the application login on the smartphone/tablet and login to the admin WebGUI (composer).
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `engomo.company` is the FQDN of the engomo installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Engomo with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### Create property mappings
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**. Create a **Scope Mapping** with the following settings:
|
||||
- **Name**: Set an appropriate name.
|
||||
- **Scope Name**: `profile`
|
||||
- **Description**: Set an appropriate description, if desired.
|
||||
- **Expression**: `return {"preferred_username": request.user.email}`
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID** and **slug** values because they will be required later.
|
||||
- Set the **Client type** to `Public`.
|
||||
- Add two `Strict` redirect URIs and set them to `https://engomo.company/auth` and `com.engomo.engomo://callback/`.
|
||||
- Select any available signing key.
|
||||
- Under **Advanced Protocol Settings**, add the scope you just created to the list of available scopes.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## engomo configuration
|
||||
|
||||
Navigate to `https://engomo.company/composer` and log in with your admin credentials.
|
||||
|
||||
1. Select **Server**.
|
||||
2. Select **Authentication**.
|
||||
3. Add a new authentication method by clicking on the plus icon on the right.
|
||||
4. Name: `authentik`
|
||||
5. Type: **OpenID Connect**
|
||||
6. Click **Create**.
|
||||
7. Configure the following values using information from the authentik provider:
|
||||
- Set **Issuer** to `https://authentik.company/application/o/engomo`.
|
||||
- Set **Client ID** to the Client ID copied from authentik.
|
||||
- Set **Client secret** to the Client Secret copied from authentik.
|
||||
|
||||
## engomo user creation
|
||||
|
||||
engomo doesn't create users automatically when signing in. So you have to do it manually right now.
|
||||
Navigate to `https://engomo.company/composer` and log in with your admin credentials.
|
||||
|
||||
- Select **Users & Devices**.
|
||||
- Click the plus button in the Users section.
|
||||
- Choose `authentik` from the Authenticator dropdown.
|
||||
- Create your user by entering the email address as the username. This email must match the one used for the user in authentik.
|
||||
|
||||
## Test the login
|
||||
|
||||
- Open a browser of your choice and open the URL `https://engomo.company`.
|
||||
- Enter the created user's email address and click the small arrow icon to log in.
|
||||
- You should be redirected to authentik (with the login flows you created) and then authentik should redirect you back to `https://engomo.company/composer` URL.
|
||||
- If you are redirected back to the `https://engomo.company/composer` URL you did everything correct.
|
||||
|
||||
:::note
|
||||
The created user will only have access to the app or composer page if they have been granted the necessary permissions.
|
||||
:::
|
||||
BIN
docs/integrations/development/frappe/frappe1.png
Normal file
BIN
docs/integrations/development/frappe/frappe1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
BIN
docs/integrations/development/frappe/frappe2.png
Normal file
BIN
docs/integrations/development/frappe/frappe2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
BIN
docs/integrations/development/frappe/frappe3.png
Normal file
BIN
docs/integrations/development/frappe/frappe3.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
BIN
docs/integrations/development/frappe/frappe4.png
Normal file
BIN
docs/integrations/development/frappe/frappe4.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
93
docs/integrations/development/frappe/index.md
Normal file
93
docs/integrations/development/frappe/index.md
Normal file
@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Integrate with Frappe
|
||||
sidebar_label: Frappe
|
||||
support_level: community
|
||||
---
|
||||
|
||||
:::note
|
||||
These instructions apply to all projects in the Frappe Family.
|
||||
:::
|
||||
|
||||
## What is Frappe
|
||||
|
||||
> Frappe is a full stack, batteries-included, web framework written in Python and JavaScript.
|
||||
>
|
||||
> -- https://frappe.io/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `frappe.company` is the FQDN of the Frappe installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `provider` is the name for the social login provider in Frappe.
|
||||
|
||||
:::note
|
||||
This documentation only lists the settings that have been changed from their default values. Please verify your changes carefully to avoid any issues accessing your application.
|
||||
:::
|
||||
|
||||
## authentik configuration
|
||||
|
||||
To support the integration of Frappe with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://frappe.company/api/method/frappe.integrations.oauth2_logins.custom/provider`.
|
||||
- Select any available signing key.
|
||||
- Under **Advanced Protocol Settings**, set **Subject mode** to be `Based on the Users's username`.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Frappe configuration
|
||||
|
||||
1. **Navigate to Integrations**
|
||||
- From the Frappe main menu, go to **Integrations** and then select **Social Login Key**.
|
||||
|
||||
2. **Add a New Social Login Key**
|
||||
- Click the black **+ New** button in the top-right corner.
|
||||
|
||||
|
||||
3. **Enter the Required Settings**
|
||||
- **Client Credentials**
|
||||
- **Enable Social Login**: Turn the toggle to the **on** position.
|
||||
- **Client ID**: Enter the Client ID from the authentik wizard.
|
||||
- **Client Secret**: Enter the Client Secret from the authentik wizard.
|
||||
|
||||
- **Configuration**
|
||||
- **Sign-ups**: Set to **Allow**.
|
||||
|
||||
|
||||
- **Identity Details**
|
||||
- **Base URL**: `https://authentik.company/`
|
||||
- **Client URLs**:
|
||||
- **Authorize URL**: `/application/o/authorize/`
|
||||
- **Access Token URL**: `/application/o/token/`
|
||||
- **Redirect URL**: `https://frappe.company/api/method/frappe.integrations.oauth2_logins.custom/provider`
|
||||
- **API Endpoint**: `/application/o/userinfo/`
|
||||
|
||||
|
||||
- **Client Information**
|
||||
- **Auth URL Data**:
|
||||
```json
|
||||
{ "response_type": "code", "scope": "email profile openid" }
|
||||
```
|
||||
|
||||
|
||||
4. **Save the Configuration**
|
||||
- Click the black **Save** button in the top-right corner to complete the setup.
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To verify that authentik is correctly set up with Frappe, navigate to your Frappe installation and click **Login with Provider**. A successful login should redirect you to the main page of your installation.
|
||||
|
||||
## Resources
|
||||
|
||||
- [Frappe's official OpenID Connect guide](https://docs.frappe.io/framework/user/en/guides/integration/openid_connect_and_frappe_social_login)
|
||||
BIN
docs/integrations/development/gitea/gitea1.png
Normal file
BIN
docs/integrations/development/gitea/gitea1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 242 KiB |
200
docs/integrations/development/gitea/index.md
Normal file
200
docs/integrations/development/gitea/index.md
Normal file
@ -0,0 +1,200 @@
|
||||
---
|
||||
title: Integrate with Gitea
|
||||
sidebar_label: Gitea
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Gitea
|
||||
|
||||
> Gitea is a community managed lightweight code hosting solution written in Go. It is published under the MIT license.
|
||||
>
|
||||
> -- https://gitea.io/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `gitea.company` is the FQDN of the Gitea installation.
|
||||
|
||||
:::note
|
||||
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 Gitea with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://<gitea.company>/user/oauth2/authentik/callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Gitea configuration
|
||||
|
||||
1. Log in to Gitea as an administrator, then click on your profile icon at the top right and select **Site Administration**.
|
||||
2. Select the **Authentication Sources** tab and then click on **Add Authentication Source**.
|
||||
3. Set the following required configurations:
|
||||
- **Authentication Name**: `authentik` (This must match the name used in the **Redirect URI** in the previous section)
|
||||
- **OAuth2 Provider**: `OpenID Connect`
|
||||
- **Client ID (Key)**: Enter the Client ID from authentik.
|
||||
- **Client Secret**: Enter the Client Secret from authentik.
|
||||
- **Icon URL**: `https://authentik.company/static/dist/assets/icons/icon.png`
|
||||
- **OpenID Connect Auto Discovery URL**: `https://authentik.company/application/o/<application_slug>/.well-known/openid-configuration`
|
||||
- **Additional Scopes**: `email profile`
|
||||
|
||||
|
||||
|
||||
4. Click **Add Authentication Source**.
|
||||
|
||||
### Claims for authorization management (optional)
|
||||
|
||||
:::note
|
||||
This step is _optional_ and shows how to set claims to control the permissions of users in Gitea by adding them to groups.
|
||||
:::
|
||||
|
||||
#### Create groups
|
||||
|
||||
The following groups will be created:
|
||||
|
||||
- `gituser`: normal Gitea users.
|
||||
- `gitadmin`: Gitea users with administrative permissions.
|
||||
- `gitrestricted`: restricted Gitea users.
|
||||
|
||||
:::note
|
||||
Users who are in none of these groups will not be able to log in to gitea.
|
||||
:::
|
||||
|
||||
1. Log in to authentik as an administrator, and open the authentik Admin interface.
|
||||
2. Navigate to **Directory** > **Groups** and click **Create**.
|
||||
3. Set the group name to `gituser` and click **Create**.
|
||||
4. Repeat steps 2 and 3 to create two additional groups named `gitadmin` and `gitrestricted`.
|
||||
5. Click the name of a newly created group and navigate to the **Users** tab.
|
||||
6. Click **Add existing user**, select the user/s that need Gitea access and click **Add**.
|
||||
7. Repeat steps 5 and 6 for the two additional groups.
|
||||
|
||||
:::note
|
||||
You can add users to the groups at any point.
|
||||
:::
|
||||
|
||||
#### Create custom property mapping
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**. Create a **Scope Mapping** with the following configurations:
|
||||
- **Name**: Choose a descriptive name (.e.g `authentik gitea OAuth Mapping: OpenID 'gitea'`)
|
||||
- **Scope name**: `gitea`
|
||||
- **Expression**:
|
||||
|
||||
```python showLineNumbers
|
||||
gitea_claims = {}
|
||||
|
||||
if request.user.ak_groups.filter(name="gituser").exists():
|
||||
gitea_claims["gitea"]= "user"
|
||||
if request.user.ak_groups.filter(name="gitadmin").exists():
|
||||
gitea_claims["gitea"]= "admin"
|
||||
if request.user.ak_groups.filter(name="gitrestricted").exists():
|
||||
gitea_claims["gitea"]= "restricted"
|
||||
|
||||
return gitea_claims
|
||||
```
|
||||
|
||||
3. Click **Finish**.
|
||||
|
||||
#### Add the custom property mapping to the Gitea provider
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Applications** > **Providers** and click on the **Edit** icon of the Gitea provider.
|
||||
3. Under **Advanced protocol settings** > **Scopes** add the following scopes to **Selected Scopes**:
|
||||
- `authentik default OAuth Mapping: OpenID 'email'`
|
||||
- `authentik default OAuth Mapping: OpenID 'profile'`
|
||||
- `authentik default OAuth Mapping: OpenID 'openid'`
|
||||
- `authentik gitea OAuth Mapping: OpenID 'gitea'`
|
||||
|
||||
4. Click **Update**.
|
||||
|
||||
#### Configure Gitea to use the new claims
|
||||
|
||||
:::note
|
||||
For this to function, the Gitea `ENABLE_AUTO_REGISTRATION: true` variable must be set. More information on configurations variables in the [Gitea Configuration Cheat Sheet](https://docs.gitea.com/administration/config-cheat-sheet).
|
||||
:::
|
||||
|
||||
1. Log in to Gitea as an admin. Click on your profile icon at the top right > **Site Administration**.
|
||||
2. Select the **Authentication Sources** tab and edit the **authentik** Authentication Source.
|
||||
3. Set the following configurations:
|
||||
- **Additional Scopes**: `email profile gitea`
|
||||
- **Required Claim Name**: `gitea`
|
||||
- **Claim name providing group names for this source.** (Optional): `gitea`
|
||||
- **Group Claim value for administrator users.** (Optional - requires claim name to be set): `admin`
|
||||
- **Group Claim value for restricted users.** (Optional - requires claim name to be set): `restricted`
|
||||
4. Click **Update Authentication Source**.
|
||||
|
||||
:::note
|
||||
Users who are not part of any defined group will be denied login access.
|
||||
In contrast, members of the `gitadmin` group will have full administrative privileges, while those in the `gitrestricted` group will have limited access.
|
||||
:::
|
||||
|
||||
### Helm Chart Configuration
|
||||
|
||||
authentik authentication can be configured automatically in Kubernetes deployments using its [Helm chart](https://gitea.com/gitea/helm-chart/).
|
||||
|
||||
Add the following to your Gitea Helm chart `values.yaml` file:
|
||||
|
||||
```yaml showLineNumbers title="values.yaml"
|
||||
gitea:
|
||||
oauth:
|
||||
- name: "authentik"
|
||||
provider: "openidConnect"
|
||||
key: "<Client ID from authentik>"
|
||||
secret: "<Client secret from authentik>"
|
||||
autoDiscoverUrl: "https://authentik.company/application/o/<application_slug>/.well-known/openid-configuration"
|
||||
iconUrl: "https://authentik.company/static/dist/assets/icons/icon.png"
|
||||
scopes: "email profile"
|
||||
```
|
||||
|
||||
### Kubernetes Secret
|
||||
|
||||
You can also utilize a Kubernetes Secret object to store and manage the sensitive `key` and `secret` values.
|
||||
|
||||
1. Create a Kubernetes secret with the following variables:
|
||||
|
||||
```yaml showLineNumbers
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: gitea-authentik-secret
|
||||
type: Opaque
|
||||
stringData:
|
||||
key: "<Client ID from authentik>"
|
||||
secret: "<Client secret from authentik>"
|
||||
```
|
||||
|
||||
2. Add the following configurations to your Gitea Helm Chart `values.yaml` file:
|
||||
|
||||
```yaml showLineNumbers title="values.yaml"
|
||||
gitea:
|
||||
oauth:
|
||||
- name: "authentik"
|
||||
provider: "openidConnect"
|
||||
existingSecret: gitea-authentik-secret
|
||||
autoDiscoverUrl: "https://authentik.company/application/o/<application_slug>/.well-known/openid-configuration"
|
||||
iconUrl: "https://authentik.company/static/dist/assets/icons/icon.png"
|
||||
scopes: "email profile"
|
||||
```
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To verify that authentik is correctly set up with Gitea, log out and then log back in using the **Sign in with authentik** button.
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Gitea Documentation](https://docs.gitea.com/)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 416 KiB |
@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Integrate with GitHub Enterprise Cloud
|
||||
sidebar_label: GitHub Enterprise Cloud
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is GitHub Enterprise Cloud
|
||||
|
||||
> GitHub is a complete developer platform to build, scale, and deliver secure software. Businesses use our suite of products to support the entire software development lifecycle, increasing development velocity and improving code quality.
|
||||
>
|
||||
> -- https://docs.github.com/en/enterprise-cloud@latest/admin/overview/about-github-for-enterprises
|
||||
|
||||
:::note
|
||||
GitHub Enterprise Cloud EMU (Enterprise Managed Users) are not compatible with authentik. GitHub currently only permits SAML/OIDC for EMU organizations with Okta and/or Microsoft Entra ID (Azure AD).
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `github.com/enterprises/foo` is your GitHub organization, where `foo` is the name of your enterprise
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 GitHub Enterprise Cloud with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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.
|
||||
- Set the **ACS URL** to `https://github.com/enterprises/foo/saml/consume`.
|
||||
- Set the **Audience** to `https://github.com/enterprises/foo`.
|
||||
- Set the **Issuer** to `https://github.com/enterprises/foo`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, select an available signing certificate. It is advised to download this certificate as it will be required later. It can be found under **System** > **Certificates** in the Admin Interface.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## GitHub Configuration
|
||||
|
||||
Navigate to your enterprise settings by clicking your GitHub user portrait in the top right of GitHub.com, select `Your enterprises` and click `Settings` for the enterprise you wish to configure.
|
||||
|
||||
In the left-hand navigation, within the `Settings` section, click `Authentication security`
|
||||
|
||||
On this page:
|
||||
|
||||
- Select the `Require SAML authentication` checkbox.
|
||||
- In `Sign on URL`, type `https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/`
|
||||
- For `Issuer`, type `https://github.com/enterprises/foo` or the `Audience` you set in authentik
|
||||
- For `Public certificate`, paste the _full_ signing certificate into this field.
|
||||
- Verify that the `Signature method` and `Digest method` match your SAML provider settings in authentik.
|
||||
|
||||
|
||||
|
||||
Once these fields are populated, you can use the `Test SAML configuration` button to test the authentication flow. If the flow completes successfully, you will see a green tick next to the Test button.
|
||||
|
||||
Scroll down to hit the `Save` button below.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
126
docs/integrations/development/github-enterprise-emu/index.md
Normal file
126
docs/integrations/development/github-enterprise-emu/index.md
Normal file
@ -0,0 +1,126 @@
|
||||
---
|
||||
title: Integrate with GitHub Enterprise Cloud - Enterprise Managed Users
|
||||
sidebar_label: GitHub Enterprise Cloud EMU
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is GitHub Enterprise Cloud - Enterprise Managed Users
|
||||
|
||||
> With Enterprise Managed Users, you manage the lifecycle and authentication of your users on GitHub from an external identity management system, or IdP:
|
||||
>
|
||||
> - Your IdP provisions new user accounts on GitHub, with access to your enterprise.
|
||||
> - Users must authenticate on your IdP to access your enterprise's resources on GitHub.
|
||||
> - You control usernames, profile data, organization membership, and repository access from your IdP.
|
||||
> - If your enterprise uses OIDC SSO, GitHub will validate access to your enterprise and its resources using your IdP's Conditional Access Policy (CAP). See "About support for your IdP's Conditional Access Policy."
|
||||
> - Managed user accounts cannot create public content or collaborate outside your enterprise. See "Abilities and restrictions of managed user accounts."
|
||||
>
|
||||
> -- https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `github.com/enterprises/foo` is your GitHub organization, where `foo` is the name of your enterprise
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `GitHub Users` is an authentik group used for holding GitHub users.
|
||||
- `GitHub Admins` is an authentik group used for indicating GitHub administrators.
|
||||
|
||||
:::note
|
||||
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 GitHub Enterprise Cloud EMU with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
:::note
|
||||
In order to use GitHub Enterprise Cloud EMU, SCIM must also be set up.
|
||||
:::
|
||||
|
||||
:::note
|
||||
GitHub will create usenames for your EMU users based on the SAML `NameID` property which must also match SCIM's `_userName_` attribute.
|
||||
:::note
|
||||
|
||||
### 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.
|
||||
- Set the **ACS URL** to `https://github.com/enterprises/foo/saml/consume`.
|
||||
- Set the **Audience** to `https://github.com/enterprises/foo`.
|
||||
- Set the **Issuer** to `https://github.com/enterprises/foo`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, select an available signing certificate. It is advised to download this certificate as it will be required later. It can be found under **System** > **Certificates** in the Admin Interface.
|
||||
- Under **NameID Property Mapping**, set **NameID Property Mapping** to be based on the `Email` field.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
**Create the users and administrator groups**
|
||||
|
||||
In the authentik Admin Interface, navigate to **Directory** > **Groups** and click **Create**. Set the group's name, any other desired settings, and click **Create**. Repeat this step twice: Once for the users group and once for the administrator group.
|
||||
|
||||
After creating the groups, select a group, navigate to the **Users** tab, and manage its members by using the **Add existing user** and **Create user** buttons as needed.
|
||||
|
||||
## GitHub SAML Configuration
|
||||
|
||||
When your EMU is provisioned by GitHub, you will receive an email inviting you reset the password of your 'setup user'. This user cannot be linked with SSO and is an emergency access account, as it will be the only account that can bypass SSO requirements.
|
||||
|
||||
Before enabling SAML, go to your [Personal access tokens](https://github.com/settings/tokens) on your EMU setup user and Generate a new _personal access token (classic)_. This should have a descriptive note like `SCIM Token`. It is advisable to set this to not expire. For scopes, select only _admin:enterprise_ and click _Generate token_.
|
||||
|
||||
Copy the resulting token to a safe location.
|
||||
|
||||
After you have set a password for this account and generated your SCIM token, navigate to your enterprise settings by clicking your GitHub user portrait in the top right of GitHub.com, select `Your enterprise`, click the `Settings` link, then click `Authentication security`.
|
||||
|
||||
On this page:
|
||||
|
||||
- Select the `Require SAML authentication` checkbox.
|
||||
- In `Sign on URL`, input the _SSO URL (Redirect)_ entry from the SAML provider you created.
|
||||
- For `Issuer`, input the `Issuer` you set in authentik
|
||||
- For `Public certificate`, paste the _full_ signing certificate into this field.
|
||||
- Verify that the `Signature method` and `Digest method` match your SAML provider settings in authentik.
|
||||
|
||||
|
||||
|
||||
Once these fields are populated, you can use the `Test SAML configuration` button to test the authentication flow. If the flow completes successfully, you will see a green tick next to the Test button.
|
||||
|
||||
Scroll down to hit the `Save SAML settings` button below.
|
||||
|
||||
You will now be prompted to save your SAML recovery codes, these will be necessary if you need to disable or change your SAML settings, so keep them safe!
|
||||
|
||||
## SCIM Provider
|
||||
|
||||
Before we create a SCIM provider, we also have to create a new Property Mapping. In authentik, go to _Customization_, then _Property Mappings_. Here, click _Create_, select _SCIM Provider Mapping_. Name the mapping something memorable and paste the following code in the _Expression_ field:
|
||||
|
||||
```python
|
||||
roles = []
|
||||
# Edit this if statement if you need to add more GitHub roles.
|
||||
# Valid roles include:
|
||||
# user, guest_collaborator, enterprise_owner, billing_manager
|
||||
if ak_is_group_member(request.user, name='GitHub Admins'):
|
||||
roles.append({'value': 'enterprise_owner', 'primary': True})
|
||||
else:
|
||||
roles.append({'value': 'user', 'primary': True})
|
||||
return {
|
||||
"roles": roles,
|
||||
}
|
||||
```
|
||||
|
||||
If you named your group anything other than `GitHub Admins`, please ensure you change it in the code above.
|
||||
|
||||
Create a new SCIM provider with the following parameters:
|
||||
|
||||
- URL: `https://api.github.com/scim/v2/enterprises/foo/` (Replacing `foo` with your Enterprise slug.)
|
||||
- Token: Paste the token provided from GitHub here.
|
||||
- In the _User filtering_ section, you can select your `GitHub Users` group.
|
||||
- In the _Attribute mapping_ section, de-select the `authentik default SCIM Mapping: User` mapping by selecting it on the right-hand side and clicking the left-facing single chevron.
|
||||
- Select the property mapping you created in the previous step and add it by clicking the right-facing single chevron.
|
||||
- You can leave the _Group Property Mappings_ as is.
|
||||
- Click _Finish_.
|
||||
|
||||
Go back to your GitHub EMU Application created in the first step and add your new SCIM provider in the _Backchannel Providers_ field, then click the _Update_ button.
|
||||
|
||||
You should now be ready to assign users to your _GitHub Users_ and _GitHub Admins_ groups, which will be provisioend by the SCIM provisioner. If you do not see your users being provisioned, go to your SCIM provider and click the _Run sync again_ option. A few seconds later, you should see results of the SCIM sync.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 353 KiB |
114
docs/integrations/development/github-enterprise-server/index.md
Normal file
114
docs/integrations/development/github-enterprise-server/index.md
Normal file
@ -0,0 +1,114 @@
|
||||
---
|
||||
title: Integrate with GitHub Enterprise Server
|
||||
sidebar_label: GitHub Enterprise Server
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is GitHub Enterprise Server
|
||||
|
||||
> GitHub Enterprise Server is a self-hosted platform for software development within your enterprise. Your team can use GitHub Enterprise Server to build and ship software using Git version control, powerful APIs, productivity and collaboration tools, and integrations. Developers familiar with GitHub.com can onboard and contribute seamlessly using familiar features and workflows.
|
||||
>
|
||||
> -- https://docs.github.com/en/enterprise-server@3.5/admin/overview/about-github-enterprise-server
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `https://github.company` is your GitHub Enterprise Server installation
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `GitHub Users` is an authentik group used for holding GitHub users.
|
||||
- `GitHub Admins` is an authentik group used for indicating GitHub administrators.
|
||||
|
||||
:::note
|
||||
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 GitHub Enterprise Server with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
:::note
|
||||
In order to use GitHub Enterprise Server, SCIM must also be set up.
|
||||
:::
|
||||
|
||||
### 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.
|
||||
- Set the **ACS URL** to `https://github.company/saml/consume`.
|
||||
- Set the **Audience** and **Issuer** to `https://github.company`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, select an available signing certificate. It is advised to download this certificate as it will be required later. It can be found under **System** > **Certificates** in the Admin Interface.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
### Create the users and administrator groups
|
||||
|
||||
In the authentik Admin Interface, navigate to **Directory** > **Groups** and click **Create**. Set the group's name, any other desired settings, and click **Create**. Repeat this step twice: Once for the users group and once for the administrator group.
|
||||
|
||||
After creating the groups, select a group, navigate to the **Users** tab, and manage its members by using the **Add existing user** and **Create user** buttons as needed.
|
||||
|
||||
## SAML Configuration
|
||||
|
||||
If you are planning to use SCIM, (available from GHES 3.14.0) you should create a first administrator user on your instance and go to your personal access tokens at `https://github.company/settings/tokens/new`, click _Generate new token_ and click _Generate new token (classic)_. Your token should have a descriptive name and ideally, no expiration date. For permission scopes, you need to select _admin:enterprise_. Click _Generate token_ and store the resulting token in a safe location.
|
||||
|
||||
To enable SAML, navigate to your appliance maintenance settings. These are found at `https://github.company:8443`. Here, sign in with an administrator user and go to the Authentication section.
|
||||
|
||||
On this page:
|
||||
|
||||
- Select the _SAML_ option.
|
||||
- In _Sign on URL_, input your _SSO URL (Redirect)_ from authentik.
|
||||
- For _Issuer_, use the _Audience_ you set in authentik.
|
||||
- Verify that the _Signature method_ and _Digest method_ match your SAML provider settings in authentik.
|
||||
- For _Validation certificate_, upload the signing certificate you downloaded after creating the provider.
|
||||
- If you plan to enable SCIM, select _Allow creation of accounts with built-in authentication_ and _Disable administrator demotion/promotion_ options. These are selected so you can use your administrator user as an emergency non-SSO account, as well as create machine users, and to ensure users are not promoted outside your IdP.
|
||||
- In the _User attributes_ section, enter `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` in the _Username_ field to ensure the emails become normalized into usernames in GitHub.
|
||||
- Press Save settings on the left-hand side and wait for the changes to apply.
|
||||
|
||||
|
||||
|
||||
Once the appliance has saved the settings and reloaded the services, you should be able to navigate to your instance URL at `https://github.company` and sign in with SAML.
|
||||
|
||||
## SCIM Configuration
|
||||
|
||||
This section only applies if you have taken the steps prior to prepare the instance for SCIM enablement.
|
||||
|
||||
After enabling SAML, log into your initial administrator account again. Click the user portrait in tee top right, click _Enterprise settings_, click _Settigs_ in the left-hand sidebar, click _Authentication security_. On this page you have to check _Enable SCIM configuration_ and press _Save_. After which you should get a message reading _SCIM Enabled_.
|
||||
|
||||
Before we create a SCIM provider, we have to create a new Property Mapping. In authentik, go to _Customization_, then _Property Mappings_. Here, click _Create_, select _SCIM Provider Mapping_. Name the mapping something memorable and paste the following code in the _Expression_ field:
|
||||
|
||||
```python
|
||||
roles = []
|
||||
# Edit this if statement if you need to add more GitHub roles.
|
||||
# Valid roles include:
|
||||
# user, guest_collaborator, enterprise_owner, billing_manager
|
||||
if ak_is_group_member(request.user, name='GitHub Admins'):
|
||||
roles.append({'value': 'enterprise_owner', 'primary': True})
|
||||
else:
|
||||
roles.append({'value': 'user', 'primary': True})
|
||||
|
||||
return {
|
||||
"roles": roles,
|
||||
}
|
||||
```
|
||||
|
||||
If you named your group anything other than `GitHub Admins`, please ensure you change it in the code above.
|
||||
|
||||
Create a new SCIM provider with the following parameters:
|
||||
|
||||
- URL: `https://github.company/api/v3/scim/v2`
|
||||
- Token: Paste the token you generated earlier here.
|
||||
- In the _User filtering_ section, you can select your `GitHub Users` group.
|
||||
- In the _Attribute mapping_ section, de-select the `authentik default SCIM Mapping: User` mapping from the _User Property Mappings_ by selecting it on the right-hand side and clicking the left-facing single chevron.
|
||||
- Select the property mapping you created in the previous step and add it by clicking the right-facing single chevron.
|
||||
- Ensure that `authentik default SCIM Mapping: Group` is the only one active in the _Group Property Mappings_.
|
||||
- Click _Finish_.
|
||||
|
||||
Go back to your GitHub Enterprise Server Application created in the first step and add your new SCIM provider in the _Backchannel Providers_ field, then click the _Update_ button.
|
||||
|
||||
You should now be ready to assign users to your _GitHub Users_ and _GitHub Admins_ groups, which will be provisioend by the SCIM provisioner. If you do not see your users being provisioned, go to your SCIM provider and click the _Run sync again_ option. A few seconds later, you should see results of the SCIM sync.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 544 KiB |
65
docs/integrations/development/github-organization/index.md
Normal file
65
docs/integrations/development/github-organization/index.md
Normal file
@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Integrate with GitHub Organization
|
||||
sidebar_label: GitHub Organization
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is GitHub Organizations
|
||||
|
||||
> Organizations are shared accounts where businesses and open-source projects can collaborate across many projects at once, with sophisticated security and administrative features.
|
||||
>
|
||||
> -- https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `github.com/orgs/foo` is your GitHub organization, where `foo` is the name of your GitHub organization.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 AWX Tower with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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. Take note of the **slug** as it will be required later.
|
||||
- **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.
|
||||
- Set the **ACS URL** to `https://github.com/orgs/foo/saml/consume`.
|
||||
- Set the **Audience** to `https://github.com/orgs/foo`.
|
||||
- Set the **Issuer** to `https://github.com/orgs/foo`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, select an available signing certificate. It is advised to download this certificate as it will be required later. It can be found under **System** > **Certificates** in the Admin Interface.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## GitHub Configuration
|
||||
|
||||
Navigate to your organization settings by going to your organization page at https://github.com/foo, then click Settings.
|
||||
|
||||
In the left-hand navigation, scroll down to the Security section and click `Authentication security`
|
||||
|
||||
On this page:
|
||||
|
||||
- Select the `Enable SAML authentication` checkbox.
|
||||
- In `sign-on URL`, type `https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/`
|
||||
- For `Issuer`, type `https://github.com/orgs/foo` or the `Audience` you set in authentik
|
||||
- For `Public certificate`, paste the _full_ signing certificate into this field.
|
||||
- Verify that the `Signature method` and `Digest method` match your SAML provider settings in authentik.
|
||||
|
||||
Once these fields are populated, you can use the `Test SAML configuration` button to test the authentication flow. If the flow completes successfully, you will see a green tick next to the Test button.
|
||||
|
||||
Scroll down to hit the `Save` button below.
|
||||
|
||||
|
||||
|
||||
This enables SAML as an authentication _option_. If you want to _require_ SAML for your organization, visit your SSO url at `https://github.com/orgs/foo/sso` and sign in. Once signed in, you can navigate back to the `Authentication security` page and check `Require SAML SSO authentication for all members of the foo organization.`
|
||||
160
docs/integrations/development/gitlab/index.mdx
Normal file
160
docs/integrations/development/gitlab/index.mdx
Normal file
@ -0,0 +1,160 @@
|
||||
---
|
||||
title: Integrate with GitLab
|
||||
sidebar_label: GitLab
|
||||
support_level: authentik
|
||||
---
|
||||
|
||||
## What is GitLab
|
||||
|
||||
> GitLab is a complete DevOps platform with features for version control, CI/CD, issue tracking, and collaboration, facilitating efficient software development and deployment workflows.
|
||||
>
|
||||
> -- https://about.gitlab.com/what-is-gitlab/
|
||||
|
||||
:::info
|
||||
In case something goes wrong with the configuration or you need to log in as admin, you can use the URL `https://gitlab.company/users/sign_in?auto_sign_in=false` to log in using the built-in authentication.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `gitlab.company` is the FQDN of the GitLab installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
## Configuration methods
|
||||
|
||||
There are two ways to configure single sign-on for GitLab. You can configure it via SAML authentication or via OpenID Connect.
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
<Tabs
|
||||
defaultValue="saml"
|
||||
values={[
|
||||
{ label: "SAML", value: "saml" },
|
||||
{ label: "OIDC", value: "oidc" },
|
||||
]}
|
||||
>
|
||||
<TabItem value="saml">
|
||||
|
||||
## authentik Configuration
|
||||
|
||||
To support the integration of GitLab with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### Create an Application and Provider in authentik
|
||||
|
||||
1. Log in to authentik as an admin and open the authentik Admin interface.
|
||||
2. Navigate to **Applications** > **Applications** and click **Create with Provider**.
|
||||
- **Application**: Provide a descriptive name, an optional group, and UI settings. Take note of the **slug** as it will be required later.
|
||||
- **Choose a Provider type**: Select **SAML Provider**.
|
||||
- **Configure the Provider**:
|
||||
- Set the **ACS URL** to `https://gitlab.company/users/auth/saml/callback`.
|
||||
- Set the **Audience** and **Issuer** to `https://gitlab.company`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, select an available signing certificate.
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
### GitLab configuration
|
||||
|
||||
Paste the following block in your `/etc/gitlab/gitlab.rb` file:
|
||||
|
||||
```ruby
|
||||
gitlab_rails['omniauth_enabled'] = true
|
||||
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
|
||||
gitlab_rails['omniauth_sync_email_from_provider'] = 'saml'
|
||||
gitlab_rails['omniauth_sync_profile_from_provider'] = ['saml']
|
||||
gitlab_rails['omniauth_sync_profile_attributes'] = ['email']
|
||||
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
|
||||
gitlab_rails['omniauth_block_auto_created_users'] = false
|
||||
gitlab_rails['omniauth_auto_link_saml_user'] = true
|
||||
gitlab_rails['omniauth_providers'] = [
|
||||
{
|
||||
name: 'saml',
|
||||
args: {
|
||||
assertion_consumer_service_url: 'https://gitlab.company/users/auth/saml/callback',
|
||||
# Shown when navigating to certificates in authentik
|
||||
idp_cert_fingerprint: '4E:1E:CD:67:4A:67:5A:E9:6A:D0:3C:E6:DD:7A:F2:44:2E:76:00:6A',
|
||||
idp_sso_target_url: 'https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/',
|
||||
issuer: 'https://gitlab.company',
|
||||
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
|
||||
attribute_statements: {
|
||||
email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'],
|
||||
first_name: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'],
|
||||
nickname: ['http://schemas.goauthentik.io/2021/02/saml/username']
|
||||
}
|
||||
},
|
||||
label: 'authentik'
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Run `gitlab-ctl reconfigure` or restart the container after making changes.
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="oidc">
|
||||
|
||||
## authentik configuration
|
||||
|
||||
To support the integration of GitLab with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://gitlab.company/users/auth/openid_connect/callback`.
|
||||
- Select any available signing key.
|
||||
- Under **Advanced protocol settings**, set the **Subject mode** to `Based on the User's Email`.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
### GitLab configuration
|
||||
|
||||
Paste the following block in your `/etc/gitlab/gitlab.rb` file:
|
||||
|
||||
```ruby
|
||||
gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
|
||||
gitlab_rails['omniauth_sync_email_from_provider'] = 'openid_connect'
|
||||
gitlab_rails['omniauth_sync_profile_from_provider'] = ['openid_connect']
|
||||
gitlab_rails['omniauth_sync_profile_attributes'] = ['email']
|
||||
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'openid_connect'
|
||||
gitlab_rails['omniauth_block_auto_created_users'] = false
|
||||
gitlab_rails['omniauth_auto_link_user'] = ['openid_connect']
|
||||
gitlab_rails['omniauth_providers'] = [
|
||||
{
|
||||
name: 'openid_connect',
|
||||
label: 'My Company OIDC Login',
|
||||
args: {
|
||||
name: 'openid_connect',
|
||||
scope: ['openid','profile','email'],
|
||||
response_type: 'code',
|
||||
issuer: 'https://authentik.company/application/o/<application_slug>/',
|
||||
discovery: true,
|
||||
client_auth_method: 'query',
|
||||
uid_field: 'preferred_username',
|
||||
send_scope_to_token_endpoint: 'true',
|
||||
pkce: true,
|
||||
client_options: {
|
||||
identifier: '${OIDC_CLIENT_ID}',
|
||||
secret: '${OIDC_CLIENT_SECRET}',
|
||||
redirect_uri: 'https://gitlab.company/users/auth/openid_connect/callback'
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
For further GitLab provider arguments, check the [GitLab docs](https://docs.gitlab.com/ee/integration/openid_connect_provider.html).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
60
docs/integrations/development/gravitee/index.md
Normal file
60
docs/integrations/development/gravitee/index.md
Normal file
@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Integrate with Gravitee
|
||||
sidebar_label: Gravitee
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Gravitee
|
||||
|
||||
> Gravitee.io API Management is a flexible, lightweight and blazing-fast Open Source solution that helps your organization control who, when and how users access your APIs.
|
||||
>
|
||||
> It offers an easy to use GUI to setup proxies for APIs, rate limiting, api keys, caching, OAUTH rules, a portal that can be opened to the public for people to subscribe to APIs, and much more.
|
||||
>
|
||||
> -- https://github.com/gravitee-io/gravitee-api-management
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `gravitee.company` is the FQDN of the Gravitee installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Gravitee with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Add two `Strict` redirect URI and set them to `https://gravitee.company/user/login` and `https://gravitee.company/console/`. Ensure a trailing slash is present at the end of the second redirect URI.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Gravitee configuration
|
||||
|
||||
In the Gravitee Management Console, navigate to _Organizations_ (gravitee.company/console/#!/organization/settings/identities) , under **Console** > **Authentication**. Click _Add an identity provider_, select _OpenID Connect_, and fill in the following:
|
||||
|
||||
:::note
|
||||
Only settings that have been modified from default have been listed.
|
||||
:::
|
||||
|
||||
- **Allow portal authentication to use this identity provider**: enable this
|
||||
- **Client ID**: Enter the Client ID from authentik that you noted in step 1
|
||||
- **Client Secret**: Enter the Client Secret from authentik that you noted in step 1
|
||||
- **Token Endpoint**: `https://authentik.company/application/o/token/`
|
||||
- **Authorize Endpoint**: `https://authentik.company/application/o/authorize/`
|
||||
- **Userinfo Endpoint**: `https://authentik.company/application/o/userinfo/`
|
||||
- **Userinfo Logout Endpoint**: `https://authentik.company/application/o/<application_slug>/end-session/`
|
||||
- **Scopes**: `email openid profile`
|
||||
66
docs/integrations/development/jenkins/index.md
Normal file
66
docs/integrations/development/jenkins/index.md
Normal file
@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Integrate with Jenkins
|
||||
sidebar_label: Jenkins
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Jenkins
|
||||
|
||||
> The leading open source automation server, Jenkins provides hundreds of plugins to support building, deploying and automating any project.
|
||||
>
|
||||
> -- https://www.jenkins.io/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `jenkins.company` is the FQDN of the Service installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Jenkins with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://jenkins.company/securityRealm/finishLogin`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Jenkins configuration
|
||||
|
||||
Navigate to the Jenkins plugin manager: **Manage Jenkins** -> **Plugins** -> **Available plugins**. Search for the plugin `oic-auth` in the search field, and install the plugin. Jenkins must be restarted afterwards to ensure the plugin is loaded.
|
||||
|
||||
After the restart, navigate to **Manage Jenkins** again, and click **Security**.
|
||||
|
||||
Modify the **Security Realm** option to select `Login with Openid Connect`.
|
||||
|
||||
In the **Client id** and **Client secret** fields, enter the Client ID and Client Secret values from the provider you created.
|
||||
|
||||
Set the configuration mode to **Automatic configuration** and set the **Well-known configuration endpoint** to `https://authentik.company/application/o/<application_slug>/.well-known/openid-configuration`
|
||||
|
||||
Check the checkbox **Override scopes** and input the scopes `openid profile email` into the new input field.
|
||||
|
||||
Further down the page, expand the **Advanced** section and input the following values:
|
||||
|
||||
- **User name field name**: `preferred_username`
|
||||
- **Full name field name**: `name`
|
||||
- **Email field name**: `email`
|
||||
- **Groups field name**: `groups`
|
||||
|
||||
We also recommend enabling the option **Enable Proof Key for Code Exchange** further down the page.
|
||||
|
||||
Additionally, as a fallback to regain access to Jenkins in the case of misconfiguration, we recommend configuring the **Configure 'escape hatch' for when the OpenID Provider is unavailable** option below. How to configure this option is beyond the scope of this document, and is explained by the OpenID Plugin.
|
||||
94
docs/integrations/development/node-red/index.md
Normal file
94
docs/integrations/development/node-red/index.md
Normal file
@ -0,0 +1,94 @@
|
||||
---
|
||||
title: Integrate with Node-RED
|
||||
sidebar_label: Node-RED
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Node-RED
|
||||
|
||||
> Node-RED is a programming tool for wiring together hardware devices, APIs and online services in new and interesting ways.
|
||||
>
|
||||
> It provides a browser-based editor that makes it easy to wire together flows using the wide range of nodes in the palette that can be deployed to its runtime in a single-click.
|
||||
>
|
||||
> -- https://nodered.org/
|
||||
|
||||
:::caution
|
||||
This requires modification of the Node-RED settings.js and installing additional Passport-js packages, see [Securing Node-RED](https://nodered.org/docs/user-guide/runtime/securing-node-red#oauthopenid-based-authentication) documentation for further details.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company` is the FQDN of authentik.
|
||||
- `nodred.company` is the FQDN of Node-RED.
|
||||
|
||||
:::note
|
||||
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 Node-RED with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://nodered.company/auth/strategy/callback/`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Note-RED configuration
|
||||
|
||||
### Step 1
|
||||
|
||||
:::note
|
||||
Group based permissions are not implemented in the below example
|
||||
:::
|
||||
|
||||
Use npm to install passport-openidconnect
|
||||
|
||||
Navigate to the node-red `node_modules` directory, this is dependent on your chosen install method. In the official Node-RED docker container the `node_modules` directory is located in the data volume `data/node_modules/`. Alternatively enter the docker container `docker exec -it nodered bash` and `cd /data/node_modules` to utilise npm within the docker container.
|
||||
|
||||
Run the command `npm install passport-openidconnect`
|
||||
|
||||
### Step 2
|
||||
|
||||
Edit the node-red settings.js file `/data/settings.js` to use the external authentication source via passport-openidconnect.
|
||||
|
||||
```js
|
||||
adminAuth: {
|
||||
type:"strategy",
|
||||
strategy: {
|
||||
name: "openidconnect",
|
||||
label: 'Sign in with authentik',
|
||||
icon:"fa-cloud",
|
||||
strategy: require("passport-openidconnect").Strategy,
|
||||
options: {
|
||||
issuer: 'https://authentik.company/application/o/<application_slug>/',
|
||||
authorizationURL: 'https://authentik.company/application/o/authorize/',
|
||||
tokenURL: 'https://authentik.company/application/o/token/',
|
||||
userInfoURL: 'https://authentik.company/application/o/userinfo/',
|
||||
clientID: '<Client ID (Key): Step 2>',
|
||||
clientSecret: '<Client Secret: Step 2>',
|
||||
callbackURL: 'https://nodered.company/auth/strategy/callback/',
|
||||
scope: ['email', 'profile', 'openid'],
|
||||
proxy: true,
|
||||
verify: function(issuer, profile, done) {
|
||||
done(null, profile)
|
||||
}
|
||||
}
|
||||
},
|
||||
users: function(user) {
|
||||
return Promise.resolve({ username: user, permissions: "*" });
|
||||
}
|
||||
},
|
||||
```
|
||||
76
docs/integrations/development/sonar-qube/index.mdx
Normal file
76
docs/integrations/development/sonar-qube/index.mdx
Normal file
@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Integrate with SonarQube
|
||||
sidebar_label: SonarQube
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is SonarQube
|
||||
|
||||
> Self-managed static analysis tool for continuous codebase inspection
|
||||
>
|
||||
> -- https://www.sonarsource.com/products/sonarqube/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `sonarqube.company` is the FQDN of the sonarqube installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
## Terraform provider
|
||||
|
||||
Create an application in authentik. Create a SAML Provider with the following values
|
||||
|
||||
```hcl
|
||||
|
||||
data "authentik_flow" "default-provider-authorization-implicit-consent" {
|
||||
slug = "default-provider-authorization-implicit-consent"
|
||||
}
|
||||
|
||||
data "authentik_property_mapping_saml" "saml-sonar-qube" {
|
||||
managed_list = [
|
||||
"goauthentik.io/providers/saml/email",
|
||||
"goauthentik.io/providers/saml/username",
|
||||
"goauthentik.io/providers/saml/name"
|
||||
]
|
||||
}
|
||||
|
||||
resource "authentik_provider_saml" "provider_sonar-qube" {
|
||||
name = "SonarQube"
|
||||
|
||||
authorization_flow = data.authentik_flow.default-provider-authorization-implicit-consent.id
|
||||
|
||||
acs_url = "https://sonarqube.company/oauth2/callback/saml"
|
||||
issuer = "https://authentik.company/"
|
||||
sp_binding = "post"
|
||||
audience = "https://sonarqube.company/saml2/metadata"
|
||||
|
||||
property_mappings = data.authentik_property_mapping_saml.saml-sonar-qube.ids
|
||||
}
|
||||
|
||||
resource "authentik_application" "application_sonar-qube" {
|
||||
name = "SonarQube"
|
||||
slug = "sonarqube"
|
||||
protocol_provider = authentik_provider_saml.provider_sonar-qube.id
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## SonarQube
|
||||
|
||||
Navigate to Administration -> Configuration -> Authentication -> Saml
|
||||
|
||||
Input these Values
|
||||
|
||||
- Application ID: https://sonarqube.company/saml2/metadata
|
||||
- Provider Name: authentik
|
||||
- Provider ID: https://authentik.company/
|
||||
- SAML login url: https://authentik.company/application/saml/sonarqube/sso/binding/redirect/
|
||||
- Identity provider certificate: Download it from authentik
|
||||
- SAML user login attribute: http://schemas.goauthentik.io/2021/02/saml/username
|
||||
- SAML user name attribute: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
|
||||
- SAML user email attribute: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
|
||||
106
docs/integrations/development/weblate/index.md
Normal file
106
docs/integrations/development/weblate/index.md
Normal file
@ -0,0 +1,106 @@
|
||||
---
|
||||
title: Integrate with Weblate
|
||||
sidebar_label: Weblate
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Weblate
|
||||
|
||||
> Weblate is a copylefted libre software web-based continuous localization system, used by over 2500 libre projects and companies in more than 165 countries.
|
||||
>
|
||||
> -- https://weblate.org/en/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `weblate.company` is the FQDN of the Weblate installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `weblate-slug` is the slug of the Weblate application.
|
||||
|
||||
:::note
|
||||
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 Weblate with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### Create property mappings
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**. Create four **SAML Provider Property Mapping**s with the following settings:
|
||||
- **Full Name Mapping:**
|
||||
- **Name**: Choose a descriptive name
|
||||
- **SAML Attribute Name**: `urn:oid:2.5.4.3`
|
||||
- **Friendly Name**: Leave blank
|
||||
- **Expression**:
|
||||
```python
|
||||
return request.user.name
|
||||
```
|
||||
- **OID_USERID Mapping:**
|
||||
- **Name**: Choose a descriptive name
|
||||
- **SAML Attribute Name**: `urn:oid:0.9.2342.19200300.100.1.1`
|
||||
- **Friendly Name**: Leave blank
|
||||
- **Expression**:
|
||||
```python
|
||||
return request.user.username
|
||||
```
|
||||
- **Username Mapping:**
|
||||
- **Name**: Choose a descriptive name
|
||||
- **SAML Attribute Name**: `username`
|
||||
- **Friendly Name**: Leave blank
|
||||
- **Expression**:
|
||||
```python
|
||||
return request.user.username
|
||||
```
|
||||
- **Email Mapping:**
|
||||
- **Name**: Choose a descriptive name
|
||||
- **SAML Attribute Name**: `email`
|
||||
- **Friendly Name**: Leave blank
|
||||
- **Expression**:
|
||||
```python
|
||||
return request.user.email
|
||||
```
|
||||
|
||||
### 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. Take note of the **slug** as it will be required later.
|
||||
- **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.
|
||||
- Set the **ACS URL** to `https://weblate.company/accounts/complete/saml/`.
|
||||
- Set the **Audience** to `https://weblate.company/accounts/metadata/saml/`.
|
||||
- Set the **Issuer** to `https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, select an available signing certificate. Then, under **Property mappings**, add the ones you just created.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Weblate configuration
|
||||
|
||||
The variables below need to be set, depending on if you deploy in a container or not you can take a look at the following links
|
||||
|
||||
- https://docs.weblate.org/en/latest/admin/config.html#config
|
||||
- https://docs.weblate.org/en/latest/admin/install/docker.html#docker-environment
|
||||
|
||||
Variables to set
|
||||
|
||||
- ENABLE_HTTPS: `1`
|
||||
- SAML_IDP_ENTITY_ID: `https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/`
|
||||
- SAML_IDP_URL: `https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/`
|
||||
- SAML_IDP_X509CERT: `MIIFDjCCAvagAwIBAgIRAJV8hH0wGkhGvbhhDKppWIYwDQYJKoZIhvcNAQELBQAw....F9lT9hHwHhsnA=`
|
||||
|
||||
The `SAML_IDP_X509CERT` is the certificate in the SAML Metadata `X509Certificate` key.
|
||||
|
||||
Should you wish to only allow registration and login through Authentik, you should set the following variables as well.
|
||||
|
||||
- REGISTRATION_OPEN: `0`
|
||||
- REGISTRATION_ALLOW_BACKENDS: `saml`
|
||||
- REQUIRE_LOGIN: `1`
|
||||
- NO_EMAIL_AUTH: `1`
|
||||
|
||||
Should you wish to deploy this in a container prefix all the variables with `WEBLATE_` and set them as environment variables
|
||||
399
docs/integrations/device-management/apple/index.md
Normal file
399
docs/integrations/device-management/apple/index.md
Normal file
@ -0,0 +1,399 @@
|
||||
---
|
||||
title: Integrate with Apple Business Manager
|
||||
sidebar_label: Apple Business Manager
|
||||
support_level: authentik
|
||||
tags:
|
||||
- integration
|
||||
- apple
|
||||
- ssf
|
||||
- backchannel
|
||||
- device-management
|
||||
authentik_version: "2025.2.0"
|
||||
authentik_enterprise: true
|
||||
authentik_preview: true
|
||||
---
|
||||
|
||||
## What is Apple Business Manager?
|
||||
|
||||
> Apple Business Manager is a web-based portal for IT administrators, managers, and procurement professionals to manage devices, and automate device enrollment.
|
||||
>
|
||||
> Organizations using Apple Business Essentials can allow their users to authenticate into their Apple devices using their IdP credentials, typically their company email addresses.
|
||||
>
|
||||
> -- [Apple Business Manager](https://www.apple.com/business/)
|
||||
|
||||
:::info Apple Device Management Platforms
|
||||
|
||||
Apple packages their device management platform into three brands to cater to different audiences:
|
||||
|
||||
- Apple Business Manager: Large organizations
|
||||
- Apple Business Essentials: Small businesses
|
||||
- Apple School Manager: Educational institutions
|
||||
|
||||
While this integration guide focuses on Business Manager, the instructions are applicable to all three platforms with minor changes to the terminology.
|
||||
|
||||
:::
|
||||
|
||||
## Authentication Flow
|
||||
|
||||
This sequence diagram shows a high-level flow between the user's apple device, authentik, and Apple Business Manager.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant User
|
||||
participant authentik
|
||||
participant Apple
|
||||
|
||||
User->>Apple: User sign-in via iCloud
|
||||
Note over Apple: 🔍 Email domain is federated
|
||||
Apple-->>authentik: Redirect to authentik
|
||||
Note over authentik: ✅ Authenticate
|
||||
authentik-->>Apple: Identity verified
|
||||
Apple-->>User: Device enrolled!
|
||||
|
||||
```
|
||||
|
||||
In short, Apple Business Manager recognizes the email domain
|
||||
as a federated identity provider controlled by authentik. When a user signs in with their email address, Apple redirects them to authentik for authentication. Once authenticated, Apple enrolls the user's device and grants access to Apple services.
|
||||
|
||||
## Preparation
|
||||
|
||||
By the end of this integration, your users will be able to enroll their Apple devices using their authentik credentials.
|
||||
|
||||
You'll need to have authentik instance running and accessible on an HTTPS domain, and an Apple Business Manager user with the role of Administrator or People Manager.
|
||||
|
||||
:::warning Caveats
|
||||
|
||||
Be aware that Apple Business Manager imposes the following restrictions on federated authentication:
|
||||
|
||||
- Federated authentication should use the user’s email address as their username. Aliases aren’t supported.
|
||||
- Existing users with an email address in the federated domain will automatically be converted to federated authentication, effectively _taking ownership_ of the account.
|
||||
- User accounts with the role of Administrator, Site Manager, or People Manager can’t sign in using federated authentication; they can only manage the federation process.
|
||||
|
||||
:::
|
||||
|
||||
### Placeholders
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company`: The FQDN of the authentik installation.
|
||||
|
||||
## authentik configuration
|
||||
|
||||
The workflow to configure authentik as an identity provider for Apple Business Manager involves creating scope mappings, signing keys, a Shared Signals Framework provider, and a OIDC provider/application pair.
|
||||
|
||||
Together, these components will handle the authentication flow and backchannel communication between authentik and Apple Business Manager.
|
||||
|
||||
### 1. Create scope mappings
|
||||
|
||||
Apple Business Manager requires that we create three scope mappings for our OIDC provider:
|
||||
|
||||
- User profile information
|
||||
- Read access
|
||||
- Management access
|
||||
|
||||
#### User profile information
|
||||
|
||||
1. From the authentik Admin interface, navigate to **Customization -> Property Mappings** and click **Create**.
|
||||
|
||||
2. Select **Scope Mapping** and use the following values:
|
||||
- **Name**: `Apple Business Manager profile`
|
||||
- **Scope Name**: `profile`
|
||||
- **Description**: _[optional]_ Set to inform user
|
||||
- **Expression**:
|
||||
Apple Business Manager requires both a given name and family name in the OIDC claim. The example expression below assumes that the user's name is formatted with the given name first, followed by the family name, delimited by a space.
|
||||
|
||||
Consider adjusting the expression to match the name format used in your organization.
|
||||
|
||||
```py
|
||||
given_name, _, family_name = request.user.name.partition(" ")
|
||||
|
||||
return {
|
||||
"given_name": given_name,
|
||||
"family_name": family_name,
|
||||
}
|
||||
```
|
||||
|
||||
3. Click **Finish** and confirm that new scope mapping is listed in the **Property Mappings** overview.
|
||||
|
||||
#### Read access
|
||||
|
||||
1. On the **Property Mappings** list, click **Create**.
|
||||
|
||||
2. Select **Scope Mapping** and use the following values:
|
||||
- **Name**: `Apple Business Manager ssf.read`
|
||||
- **Scope Name**: `ssf.read`
|
||||
- **Description**: _[optional]_ Set to inform user
|
||||
- **Expression**: `return {}`
|
||||
|
||||
3. Click **Finish** and confirm that new scope mapping is listed in the **Property Mappings** overview.
|
||||
|
||||
#### Management access
|
||||
|
||||
1. On the **Property Mappings** list, click **Create**.
|
||||
|
||||
2. Select **Scope Mapping** and use the following values:
|
||||
- **Name**: `Apple Business Manager ssf.manage`
|
||||
- **Scope Name**: `ssf.manage`
|
||||
- **Description**: _[optional]_ Set to inform user
|
||||
- **Expression**: `return {}`
|
||||
|
||||
3. Click **Finish** and confirm that new scope mapping is listed in the **Property Mappings** overview.
|
||||
|
||||
### 2. Create signing keys
|
||||
|
||||
You will need to create **Signing Key** to sign Security Event Tokens (SET).
|
||||
This key is used to both sign and verify the SETs that are sent between authentik and Apple Business Manager.
|
||||
|
||||
You can either generate a new key or import an existing one.
|
||||
|
||||
#### Generate a new key
|
||||
|
||||
1. From the Admin interface, navigate to **System -> Certificates**
|
||||
2. Click **Generate**, select **Signing Key**, and use the following values:
|
||||
- **Common Name**: `apple-business-manager`
|
||||
|
||||
3. Click **Generate** and confirm that the new key is listed in the **Certificates** overview.
|
||||
|
||||
#### Import an existing key
|
||||
|
||||
Alternatively, you can use an existing key if you have one available.
|
||||
|
||||
1. From the Admin interface, navigate to **System -> Certificates**.
|
||||
2. Click **Create** and use the following values:
|
||||
- **Name**: `apple-business-manager`
|
||||
- **Certificate**: Paste in your certificate
|
||||
- **Private Key**: _[optional]_ Pastein your private key
|
||||
|
||||
3. Click **Create** and confirm that the new key is listed in the **Certificates** overview.
|
||||
|
||||
### 3. Create OIDC provider
|
||||
|
||||
:::tip Keep your text editor ready
|
||||
|
||||
authentik will automatically generate the **Client ID** and **Client Secret** values for the new provider. You'll need these values when configuring Apple Business Manager.
|
||||
|
||||
You can always find your provider's generated values by navigating to **Providers**, selecting the provider by name, and clicking the **Edit** button.
|
||||
|
||||
:::
|
||||
|
||||
1. From the authentik Admin interface, navigate to **Applications -> Providers** and click **Create**.
|
||||
2. For the **Provider Type** select **OAuth2/OpenID Provider**, click **Next**, and use the following values.
|
||||
- **Name**: `Apple Business Manager`
|
||||
- **Authorization flow**: Select a flow that suits your organization's requirements.
|
||||
- **Protocol settings**:
|
||||
- **Client ID**: Copy the generated value to your text editor.
|
||||
- **Client Secret**: Copy the generated value to your text editor.
|
||||
- **Redirect URIs/Origins**:
|
||||
- `Strict`
|
||||
- **URL**: `https://gsa-ws.apple.com/grandslam/GsService2/acs`
|
||||
- **Signing Key**: Select a certificate to sign the OpenID Connect tokens.
|
||||
- **Advanced protocol settings**:
|
||||
Any fields that can be left as their default values are omitted from the list.
|
||||
- **Scopes**: Add four **Selected Scopes** to the provider.
|
||||
- [x] `Apple Business Manager ssf.manage`
|
||||
- [x] `Apple Business Manager ssf.read`
|
||||
- [x] `Apple Business Manager profile`
|
||||
- [x] `authentik default OAuth Mapping: OpenID 'profile'`
|
||||
|
||||
3. Click **Finish** and confirm that `Apple Business Manager` is listed in the provider overview.
|
||||
|
||||
4. Navigate to **Applications -> Providers** and click `Apple Business Manager`.
|
||||
5. Copy the **OpenID Configuration URL** field to your text editor.
|
||||
|
||||
### 4. Create Shared Signals Framework provider
|
||||
|
||||
While the OIDC provider handles the authentication flow, you'll need to create a [Shared Signals Framework provider](/docs/add-secure-apps/providers/ssf/) to handle the backchannel communication between authentik and Apple Business Manager.
|
||||
|
||||
1. From the authentik Admin interface, navigate to **Applications -> Providers** and click **Create**.
|
||||
2. Select **Shared Signals Framework Provider** and use the following values.
|
||||
Any fields that can be left as their default values are omitted from the list.
|
||||
- **Name** `Apple Business Manager SSF`
|
||||
- **Signing Key**: `[Your Signing Key]`
|
||||
- **Event Retention**: `days=30`
|
||||
|
||||
3. Click **Finish** and confirm that the new SSF provider is listed in the overview.
|
||||
|
||||
:::tip A Blank SSF Config URL is expected
|
||||
|
||||
Keep in mind the **SSF Config URL** will be blank until the SSF provider is assigned to an application as a backchannel provider. We'll return to collect this URL after creating the application.
|
||||
|
||||
:::
|
||||
|
||||
### 5. Assign SSF permissions
|
||||
|
||||
The authentik user you will use to test the stream connection to Apple Business Manager must either have the role of superuser or have permission to add streams to the SSF provider.
|
||||
|
||||
1. From authentik the Admin interface, navigate to **Applications -> Providers** and click the Apple Business Manager SSF provider.
|
||||
|
||||
2. Click the **Permissions** tab, select **User Object Permissions**, and click **Assign to new user**.
|
||||
|
||||
3. In the **User** field, enter the object name of the test user performing the initial connection to Apple Business Manager.
|
||||
|
||||
4. Set the **Add stream to SSF provider** permission toggle to **On**
|
||||
|
||||
5. Click **Assign** and confirm that the user is listed in the **User Object Permissions** list.
|
||||
|
||||
### 6. Create application
|
||||
|
||||
1. From the authentik Admin interface, navigate to **Applications -> Applications**, click **Create**, and use the following values:
|
||||
- **Name**: Apple Business Manager
|
||||
- **Slug**: `abm`
|
||||
- **Provider**: `Apple Business Manager`
|
||||
- **Backchannel Provider:** `Apple Business Manager SSF`
|
||||
|
||||
2. Click **Create** and confirm that the application is listed in the overview page.
|
||||
|
||||
3. Navigate to **Providers -> Apple Business Manager SSF**
|
||||
- On the **Overview** tab copy the `SSF Config URL` value to your text editor.
|
||||
|
||||
### 7. Confirm and modify copied authentik values
|
||||
|
||||
Before proceeding to Apple Business Manager, let's go over the values you've copied from authentik.
|
||||
|
||||
1. Verify that you have all the necessary values in your text editor:
|
||||
- From the `Apple Business Manager` provider:
|
||||
- [x] `Client ID`
|
||||
- [x] `Client Secret`
|
||||
- [x] `OpenID Configuration URL`
|
||||
|
||||
- From the `Apple Business Manager SSF` provider:
|
||||
- [x] `SSF Config URL`
|
||||
|
||||
2. Modify URLs to include the default HTTPS port. Apple requires the port number to be included when providing the URLs in the configuration.
|
||||
- Add port 443 to the SSF Config URL that you copied from the `Apple Business Manager SSF` provider:
|
||||
|
||||
```diff
|
||||
-https://authentik.company/.well-known/ssf-configuration/abm
|
||||
+https://authentik.company:443/.well-known/ssf-configuration/abm
|
||||
```
|
||||
|
||||
- Add port 443 to the OpenID Config URL that you copied from the `Apple Business Manager` provider:
|
||||
|
||||
```diff
|
||||
-https://authentik.company/application/o/abm/.well-known/openid-configuration
|
||||
+https://authentik.company:443/application/o/abm/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
## Apple Business Manager configuration
|
||||
|
||||
With these prerequisites in place, authentik is ready to act as an identity provider for Managed Apple Accounts.
|
||||
|
||||
Similar to a personal Apple account, a _Managed Apple Account_ uses an email address to access Apple services and devices. What makes an Apple account _managed_ is that the domain associated with the email address is owned and verified by an organization through an Apple Business Manager account.
|
||||
|
||||
### 1. Add and verify your domain
|
||||
|
||||
By verifying the domain, Apple Business Manager will delegate ownership of any accounts with a matching email address to the organization, allowing for centralized management of devices, apps, and services.
|
||||
|
||||
1. From the [Apple Business Manager dashboard](https://business.apple.com/), click **your account name** on the sidebar, then select **Preferences**.
|
||||
|
||||
2. From the Preferences page, select **Managed Apple Accounts** tab, click **Add Domain** and then provide your domain name.
|
||||
Apple will generate a DNS TXT record that you'll need to add to your domain's DNS settings.
|
||||
|
||||
3. Wait for DNS propagation and click **Verify** to complete the domain verification process.
|
||||
|
||||
A confirmation dialog will prompt you to lock your domain before you can proceed with the next steps.
|
||||
|
||||
:::warning Locking your domain affects all enrolled users
|
||||
|
||||
Locking your domain ensures that only your organization can use your domain for federated authentication.
|
||||
|
||||
**Once locked, your enrolled users will not be able to access Apple services until you complete the next steps to configure federated authentication.**
|
||||
|
||||
**Only lock your domain when you're ready to proceed with the next steps.**
|
||||
|
||||
:::
|
||||
|
||||
4. In the confirmation dialog, set the **Lock Domain** toggle to **On** and confirm that the domain displays as locked in the **Managed Apple Accounts** tab.
|
||||
|
||||
### 2. Capture all accounts
|
||||
|
||||
Optionally, you may choose to [capture all accounts](https://support.apple.com/guide/apple-business-manager/capture-a-domain-axm512ce43c3/1/web/1), which will convert all existing accounts with an email address in the federated domain to _Managed Apple Accounts_. You can also choose to capture all accounts at a later time when you're ready to manage all users in the domain.
|
||||
|
||||
:::danger Account capture is one-way migration
|
||||
|
||||
Choosing to capture all accounts will affect all users with an email address in the federated domain, regardless of their enrollment status or device ownership.
|
||||
**Once captured, the accounts can't be reverted to personal Apple accounts – even if the domain is unlocked.**
|
||||
|
||||
**Only capture accounts if you're sure that every user in the domain should be managed by Apple Business Manager.**
|
||||
|
||||
:::
|
||||
|
||||
1. From the [Apple Business Manager dashboard](https://business.apple.com/), click **your account name** on the sidebar, then select **Preferences**.
|
||||
|
||||
2. From the Preferences page, select **Managed Apple Accounts** tab, and click **Manage** next to the domain you've verified.
|
||||
|
||||
3. In your domain's management dialog, ensure you understand the implications of capturing all accounts and then click **Capture All Accounts**.
|
||||
|
||||
4. Wait for Apple to complete the account capture process, and confirm that all accounts are now managed by Apple Business Manager.
|
||||
|
||||
### 3. Enable federated authentication
|
||||
|
||||
You're now ready to configure federated authentication with authentik.
|
||||
|
||||
1. From the Apple Business Manager dashboard, click **your account name** on the sidebar, then select **Preferences**.
|
||||
|
||||
2. From the Preferences page, select **Managed Apple Accounts** tab, and click **Get Started** under the "User sign in and directory sync" section.
|
||||
|
||||
3. To define how you want users to sign in, choose **Custom Identity Provider** and click **Continue**.
|
||||
|
||||
4. On the **Set up your Custom Identity Provider** page, use the following values:
|
||||
- **Name**: `authentik`
|
||||
- **Client ID**: _`Your Client ID`_
|
||||
- **Client Secret**: _`Your Client Secret`_
|
||||
- **SSF Config URL**: **_`Your SSF Config URL with 443 port`_**
|
||||
- **OpenID Config URL**: **_`Your OpenID Config URL with 443 port`_**
|
||||
|
||||
5. Click **Continue** to begin Apple's verification of your configuration.
|
||||
6. When prompted to authenticate through your authentik instance, provide your credentials and click **Log In**.
|
||||
|
||||
When the test finishes, click **Done** to complete the configuration.
|
||||
|
||||
#### Troubleshooting connection issues during the test
|
||||
|
||||
If the connection test fails, your configuration may be incorrect. Here are some common issues to check:
|
||||
|
||||
- [x] Ensure that your authentik instance is accessible from the internet from an HTTPS domain.
|
||||
- [x] Verify that the Client ID and Client Secret values are correct.
|
||||
- [x] Verify that scope mappings are created and all assigned to the OIDC provider.
|
||||
- [x] Verify that the SSF provider is assigned to the application.
|
||||
- [x] Ensure that the SSF Config URL and OpenID Configuration URL include the port number `443`.
|
||||
|
||||
If you're still having issues, check your authentik instance's log for any errors that might have occurred during the authentication process. If Apple can reach your authentik instance, you should see logs indicating Apple's attempts to test the authentication flow.
|
||||
|
||||
## Configuration verification
|
||||
|
||||
:::warning Administrators cannot use federated authentication
|
||||
|
||||
Apple Business Manager does not allow users with the role of Administrator, Site Manager, or People Manager to log in using federated authentication.
|
||||
|
||||
When creating test users, ensure that their role is set to Standard (or Student) to test federated authentication with authentik.
|
||||
|
||||
:::
|
||||
|
||||
### 1. Create a test user
|
||||
|
||||
1. From the [Apple Business Manager dashboard](https://business.apple.com/), click **Users** on the sidebar, then click **Add**.
|
||||
2. In the **Add New User** dialog, use the following values:
|
||||
- **First Name**: `Jessie`
|
||||
- **Last Name**: `Lorem`
|
||||
- **Email**: `jessie@authentik.company`
|
||||
- **Role**: `Standard`
|
||||
|
||||
3. Click **Save** to create the user account, and then click **Create Sign-In** in the user's profile.
|
||||
|
||||
4. When prompted to choose a delivery method, select **Create a downloadable PDF and CSV** and click **Continue**. Note the temporary password provided on the next page, optionally downloading the PDF and CSV files for future reference.
|
||||
|
||||
5. Confirm the user is created from the authentik Admin interface by navigating to the **Users** page and searching for the account by their email address. Note that this may take a few minutes to synchronize.
|
||||
|
||||
### 2. Test the authentication flow
|
||||
|
||||
1. Confirmed the test user in synchronized in authentik.
|
||||
2. Open a private browsing window and navigate to the [Apple Business Manager](https://business.apple.com/).
|
||||
3. In the the email field, provide the email address assigned to test user.
|
||||
|
||||
4. Submit the form to trigger the authentication flow.
|
||||
|
||||
You should be redirected to authentik for authentication and then back to Apple Business Manager to manage the test user's account.
|
||||
|
||||
If the test is successful, you'll be able to enroll the test user's device and access Apple services.
|
||||
143
docs/integrations/device-management/fleet/index.md
Normal file
143
docs/integrations/device-management/fleet/index.md
Normal file
@ -0,0 +1,143 @@
|
||||
---
|
||||
title: Integrate with Fleet
|
||||
sidebar_label: Fleet
|
||||
support_level: authentik
|
||||
tags:
|
||||
- integration
|
||||
- device-management
|
||||
authentik_preview: true
|
||||
---
|
||||
|
||||
## What is Fleet
|
||||
|
||||
> Fleet is an open source device management (MDM) platform for vulnerability reporting, detection engineering, device health monitoring, posture-based access control, managing unused software licenses, and more.
|
||||
>
|
||||
> -- [Fleet](https://fleetdm.com/)
|
||||
|
||||
## Preparation
|
||||
|
||||
By the end of this integration, your users will be able to log into Fleet using their authentik credentials.
|
||||
|
||||
Your authentik and Fleet instances must both be running and accessible on an HTTPS domain.
|
||||
|
||||
### Placeholders
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company`: The FQDN of the authentik installation.
|
||||
- `fleet.company`: The FQDN of the Fleet installation.
|
||||
|
||||
## authentik configuration
|
||||
|
||||
The workflow to configure authentik as a single sign-on for Fleet involves creating an application and SAML provider pair. Following this configuration process will generate the necessary metadata you will use to configure Fleet to trust authentik as an identity provider.
|
||||
|
||||
### Create an application and provider
|
||||
|
||||
1. From the authentik Admin interface, navigate to **Applications -> Applications** and click **Create with Provider** to create an application and provider pair.
|
||||
|
||||
2. For the **App name** enter `Fleet` and click **Next**.
|
||||
|
||||
3. For the **Provider Type** select **SAML**, click **Next**, and use the following values.
|
||||
- **Name**: `Fleet`
|
||||
- **Authorization flow**: Select a flow that suits your organization's requirements.
|
||||
- **Protocol settings**:
|
||||
- **Assertion Consumer Service URL**: `https://fleet.company/api/v1/fleet/sso/callback`
|
||||
|
||||
:::info Requiring an End User License Agreement
|
||||
|
||||
If you require end users to agree to an end user license agreement (EULA) before they can use their device, you will need to modify the **Assertion Consumer Service URL**.
|
||||
|
||||
```diff
|
||||
- https://fleet.company/api/v1/fleet/sso/callback
|
||||
+ https://fleet.company/api/v1/fleet/mdm/sso/callback
|
||||
```
|
||||
|
||||
You will also need to configure Fleet with additional settings to enable the EULA. For more information, refer to Fleet's [end user authentication guide](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#end-user-authentication-and-eula).
|
||||
:::
|
||||
|
||||
- **Issuer**: `authentik`
|
||||
This value is used to identify authentik as the identity provider to Fleet. It can be any string, but it must be unique and used consistently across both authentik and Fleet configurations.
|
||||
- **Service Provider Binding**: `Post`
|
||||
- **Audience**: `https://fleet.company`
|
||||
- **Advanced protocol settings**:
|
||||
(Any fields that can be left as their default values are omitted from the list below).
|
||||
- **Signing Certificate**: Select a certificate enable **Sign assertions** and **Sign responses**.
|
||||
- **NameID Property Mapping**: `authentik default SAML Mapping: Email`
|
||||
|
||||
4. Click **Next**, review the configuration details, and click **Submit**.
|
||||
|
||||
### Retrieve provider metadata
|
||||
|
||||
1. From the authentik Admin interface, navigate to **Applications -> Providers** and click the Fleet SAML provider.
|
||||
|
||||
2. In the **Related Objects** section, click **Copy download URL** to copy the metadata URL to your clipboard. Paste this URL to a text editor as you will need it when configuring Fleet.
|
||||
|
||||
:::tip Downloading the metadata file
|
||||
|
||||
If you prefer to download the metadata file, clicking **Download** will save an XML file to your local machine. The choice to download or copy the metadata URL will have no impact on the configuration process in Fleet.
|
||||
|
||||
:::
|
||||
|
||||
## Fleet configuration
|
||||
|
||||
With these prerequisites in place, authentik is now configured to act as a single sign-on provider for Fleet. The next step is to configure Fleet to trust authentik as an identity provider.
|
||||
|
||||
1. From the Fleet dashboard, click your avatar in the page header and select **Settings**.
|
||||
|
||||
2. In the **Organization settings** tab, click **Single sign-on options**.
|
||||
|
||||
3. Check the box next to **Enable single sign-on** and use the following values:
|
||||
- **Identity provider name**: `authentik`
|
||||
- **Entity ID**: `authentik`
|
||||
|
||||
- **Metadata/Metadata URL**
|
||||
|
||||
Fleet's SSO configuration form will include two fields: **Metadata URL** and **Metadata**.
|
||||
Only one of these fields is required, but you must provide at least one of them.
|
||||
- If you copied the **Metadata URL** from authentik, paste the URL you copied earlier into the **Metadata URL** field.
|
||||
|
||||
- If you downloaded the metadata file from authentik, paste the contents of the XML file into the **Metadata** field.
|
||||
|
||||
- **Allow SSO login initiated by identity provider**: Check this box to allow users to log in to Fleet using the authentik login page.
|
||||
|
||||
4. Click **Save** to apply the changes.
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To verify that authentik and Fleet are correctly configured, you can test the SSO flow with a user account.
|
||||
|
||||
### Create a test user
|
||||
|
||||
1. From the authentik Admin interface, navigate to **Directory -> Users** and click **Create**.
|
||||
2. Enter the following details for the test user. All other fields can be left as their default values.
|
||||
- **Name**: `Jessie Lorem`
|
||||
- **Email**: `jessie@authentik.company`
|
||||
|
||||
3. Click **Create** and verify that the user is listed in the **Users** table.
|
||||
|
||||
4. From the Fleet Admin interface, navigate to **Settings -> Users** and click **Add user**.
|
||||
|
||||
5. Enter the following details for the test user. All other fields can be left as their default values.
|
||||
- **Full Name**: `Jessie Lorem`
|
||||
- **Email**: `jessie@authentik.company`
|
||||
- **Authentication**: `Single sign-on`
|
||||
- **Role**: `Observer`
|
||||
|
||||
6. Click **Add** and verify that the user is listed in the **Users** table.
|
||||
|
||||
### Test the SSO flow
|
||||
|
||||
1. In a private browsing window, navigate to your Fleet instance and click **Sign on with authentik**.
|
||||
2. After being redirected to the authentik login page, enter the test user's email address and password.
|
||||
|
||||
After you are authenticated, you should be redirected back to the Fleet and logged in as the test user. This confirms that the SSO flow is working as expected.
|
||||
|
||||
#### Troubleshooting
|
||||
|
||||
If the SSO authentication fails, your configuration may be incorrect. Here are some common issues to check:
|
||||
|
||||
- [x] Verify that your authentik instance is accessible from the internet from an HTTPS domain.
|
||||
- [x] Verify that the Fleet instance is accessible from the internet from an HTTPS domain.
|
||||
- [x] Ensure that your test user is not the default super-admin user.
|
||||
- [x] Check that your test user has a matching email address in both authentik and Fleet.
|
||||
- [x] Check that the test user has Single sign-on authentication enabled in Fleet.
|
||||
67
docs/integrations/device-management/meshcentral/index.md
Normal file
67
docs/integrations/device-management/meshcentral/index.md
Normal file
@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Integrate with MeshCentral
|
||||
sidebar_label: MeshCentral
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is MeshCentral
|
||||
|
||||
> MeshCentral is a free, open source, web-based platform for remote device management.
|
||||
>
|
||||
> -- https://meshcentral.com
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `meshcentral.company` is the FQDN of the MeshCentral installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 MeshCentral with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://meshcentral.company/auth-oidc-callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## MeshCentral configuration
|
||||
|
||||
Edit the `config.json` file for your MeshCentral deployment, and add the following code in the `domains:` subsection:
|
||||
|
||||
:::info
|
||||
For Docker deployments, the `config.json` should be located in the directory on the host machine you mapped to `/opt/meshcentral/meshcentral-data`.
|
||||
:::
|
||||
|
||||
:::info
|
||||
If you need to enable advanced OIDC configurations, please refer to the [Using the OpenID Connect Strategy](https://ylianst.github.io/MeshCentral/meshcentral/openidConnectStrategy/) section in the MeshCentral documentation for detailed instructions.
|
||||
:::
|
||||
|
||||
```json
|
||||
"domains": {
|
||||
"authStrategies": {
|
||||
"oidc": {
|
||||
"issuer": "https://authentik.company/application/o/meshcentral/",
|
||||
"clientid": "<Client ID>",
|
||||
"clientsecret": "<Client Secret>",
|
||||
"newAccounts": true
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
To ensure everything is setup correctly, restart your MeshCentral instance and visit the main page. You should be greeted with a new button to allow signing in with OIDC.
|
||||
135
docs/integrations/documentation/bookstack/index.mdx
Normal file
135
docs/integrations/documentation/bookstack/index.mdx
Normal file
@ -0,0 +1,135 @@
|
||||
---
|
||||
title: Integrate with BookStack
|
||||
sidebar_label: BookStack
|
||||
support_level: community
|
||||
---
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
## What is BookStack
|
||||
|
||||
> BookStack is a free and open-source wiki software aimed for a simple, self-hosted, and easy-to-use platform. It uses the ideas of books to organise pages and store information. BookStack is multilingual and available in over thirty languages. For the simplicity, BookStack is considered as suitable for smaller businesses or freelancers.
|
||||
>
|
||||
> -- https://bookstackapp.com
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `bookstack.company` is the FQDN of the BookStack installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
## Configuration methods
|
||||
|
||||
You can configure Bookstack to use either OIDC or SAML, and this guide explains both options.
|
||||
|
||||
<Tabs
|
||||
defaultValue="oidc"
|
||||
values={[
|
||||
{ label: "Log in with OIDC", value: "oidc" },
|
||||
{ label: "Log in with SAML", value: "saml" },
|
||||
]}>
|
||||
<TabItem value="oidc">
|
||||
|
||||
## authentik configuration
|
||||
|
||||
To support the integration of BookStack with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://bookstack.company/oidc/callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Bookstack configuration
|
||||
|
||||
Once that's done, the next step is to update your `.env` file to include the following variables:
|
||||
|
||||
```yaml showLineNumbers
|
||||
AUTH_METHOD=oidc
|
||||
AUTH_AUTO_INITIATE=false # Set this to "true" to automatically redirect the user to authentik.
|
||||
OIDC_NAME=authentik # The display name shown on the login page.
|
||||
OIDC_DISPLAY_NAME_CLAIMS=name # Claim(s) for the user's display name. Can have multiple attributes listed, separated with a '|' in which case those values will be joined with a space.
|
||||
OIDC_CLIENT_ID=<Client ID from authentik>
|
||||
OIDC_CLIENT_SECRET=<Client Secret from authentik>
|
||||
OIDC_ISSUER=https://authentik.company/application/o/<application_slug>
|
||||
OIDC_ISSUER_DISCOVER=true
|
||||
OIDC_END_SESSION_ENDPOINT=true
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="saml">
|
||||
|
||||
## authentik configuration
|
||||
|
||||
To support the integration of BookStack with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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. Take note of the **slug** as it will be required later.
|
||||
- **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.
|
||||
- Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later.
|
||||
- Set the **ACS URL** to `https://bookstack.company/saml2/acs`.
|
||||
- Set the **Issuer** to `https://authentik.company`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Set the **Audience** to `https://bookstack.company/saml2/metadata`.
|
||||
- Under **Advanced protocol settings**, set **Signing Certificate** to use any available certificate.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
### Obtain the SAML metadata URL
|
||||
|
||||
### Get metadata URL
|
||||
|
||||
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 (e.g. `Provider for bookstack`).
|
||||
3. Under **Related objects** > **Metadata**, click on **Copy download URL**. This is your authentik metadata URL and it will be required in the next section.
|
||||
|
||||
## Bookstack configuration
|
||||
|
||||
Once that's done, the next step is to update your `.env` file to include the following variables:
|
||||
|
||||
```yaml showLineNumbers
|
||||
AUTH_METHOD=saml2
|
||||
AUTH_AUTO_INITIATE=true # Set this to "true" to automatically redirect the user to authentik.
|
||||
SAML2_NAME=authentik # The display name shown on the login page.
|
||||
SAML2_EMAIL_ATTRIBUTE=email
|
||||
SAML2_EXTERNAL_ID_ATTRIBUTE=uid
|
||||
SAML2_USER_TO_GROUPS=true
|
||||
SAML2_GROUP_ATTRIBUTE=http://schemas.xmlsoap.org/claims/Group
|
||||
SAML2_DISPLAY_NAME_ATTRIBUTES=http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname
|
||||
SAML2_IDP_ENTITYID=<authentik metadata URL>
|
||||
SAML2_AUTOLOAD_METADATA=true
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is properly configured with BookStack, visit your BookStack installation, and click **Login with authentik**.
|
||||
|
||||
## Resources
|
||||
|
||||
- [BookStack Administrator Documentation for OpenID Connect](https://www.bookstackapp.com/docs/admin/oidc-auth/)
|
||||
- [Bookstack Administrator Documentation for SAML2](https://www.bookstackapp.com/docs/admin/saml2-auth/)
|
||||
- [PeerTube video detailing a setup with authentik (OpenID Connect)](https://foss.video/w/a744K8GxFF1LqBFSadAsuV)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
85
docs/integrations/documentation/dokuwiki/index.md
Normal file
85
docs/integrations/documentation/dokuwiki/index.md
Normal file
@ -0,0 +1,85 @@
|
||||
---
|
||||
title: Integrate with DokuWiki
|
||||
sidebar_label: DokuWiki
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is DokuWiki
|
||||
|
||||
> DokuWiki is an open source wiki application licensed under GPLv2 and written in the PHP programming language. It works on plain text files and thus does not need a database. Its syntax is similar to the one used by MediaWiki and it is often recommended as a more lightweight, easier to customize alternative to MediaWiki.
|
||||
>
|
||||
> -- https://en.wikipedia.org/wiki/DokuWiki
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `dokuwiki.company` is the FQDN of the DokiWiki installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 DocuWiki with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID** and **Client Secret** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://docuwiki.company/doku.php`.
|
||||
- Select any available signing key.
|
||||
- Under **Advanced Protocol Settings**, add the following OAuth mapping under **Scopes**: `authentik default OAuth Mapping: OpenID 'offline_access'`
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## DokuWiki configuration
|
||||
|
||||
From the **Administration** interface of your DocuWiki installation, navigate to **Extension Manager** and install the following extensions:
|
||||
|
||||
- https://www.dokuwiki.org/plugin:oauth
|
||||
- https://www.dokuwiki.org/plugin:oauthgeneric
|
||||
|
||||
Then, under the **Configuration Settings** section, update the **oauth** and **oauthgeneric** options:
|
||||
|
||||
For **oauth**: - Select the following option: `plugin»oauth»register-on-auth`
|
||||
|
||||
:::warning
|
||||
When using `preferred_username` as the user identifier, ensure that the [Allow users to change username setting](https://docs.goauthentik.io/docs/sys-mgmt/settings#allow-users-to-change-username) is disabled to prevent authentication issues. You can configure DocuWiki to use either the `sub` or `preferred_username` as the UID field under `plugin»oauthgeneric»json-user`. The `sub` option uses a unique, stable identifier for the user, while `preferred_username` uses the username configured in authentik.
|
||||
:::
|
||||
|
||||
For **oauthgeneric**:
|
||||
|
||||
- Set `plugin»oauthgeneric»key` to the Client ID from authentik
|
||||
- Set `plugin»oauthgeneric»secret` to the Client Secret from authentik
|
||||
- Set `plugin»oauthgeneric»authurl` to `https://authentik.company/application/o/authorize/`
|
||||
- Set `plugin»oauthgeneric»tokenurl` to `https://authentik.company/application/o/token/`
|
||||
- Set `plugin»oauthgeneric»userurl` to `https://authentik.company/application/o/userinfo/`
|
||||
- Set `plugin»oauthgeneric»authmethod` to `Bearer Header`
|
||||
- Set `plugin»oauthgeneric»scopes` to `email, openid, profile, offline_access`
|
||||
- Select `plugin»oauthgeneric»needs-state`
|
||||
- Set `plugin»oauthgeneric»json-user` to `preferred_username`
|
||||
- Set `plugin»oauthgeneric»json-name` to `name`
|
||||
- Set `plugin»oauthgeneric»json-mail` to `email`
|
||||
- Set `plugin»oauthgeneric»json-grps` to`groups`
|
||||
|
||||
|
||||
|
||||
Once that is done, navigate to the **Authentication** sub-section of the **Administration** interface's **Configuration Settings** section and enable **oauth** under **Authentication backend**.
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To verify that authentik is correctly configured with DocuWiki, log out and log back in through authentik. You should notice a new button on the login page.
|
||||
|
||||
## Resources
|
||||
|
||||
- [DocuWiki OAuth plugin](https://www.dokuwiki.org/plugin:oauth)
|
||||
- [DocuWiki plugin for generic OAuth](https://www.dokuwiki.org/plugin:oauthgeneric)
|
||||
60
docs/integrations/documentation/karakeep/index.md
Normal file
60
docs/integrations/documentation/karakeep/index.md
Normal file
@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Integrate with Karakeep
|
||||
sidebar_label: Karakeep
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Karakeep
|
||||
|
||||
> A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full-text search.
|
||||
>
|
||||
> -- https://karakeep.app/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `karakeep.company` is the FQDN of the Karakeep installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Karakeep with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://karakeep.company/api/auth/callback/custom`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Karakeep configuration
|
||||
|
||||
In Karakeep, you'll need to add these environment variables:
|
||||
|
||||
```sh
|
||||
NEXTAUTH_URL=https://karakeep.company
|
||||
OAUTH_CLIENT_ID=<Client ID from authentik>
|
||||
OAUTH_CLIENT_SECRET=<Client secret from authentik>
|
||||
OAUTH_WELLKNOWN_URL=https://authentik.company/application/o/karakeep/.well-known/openid-configuration
|
||||
OAUTH_PROVIDER_NAME=authentik
|
||||
OAUTH_ALLOW_DANGEROUS_EMAIL_ACCOUNT_LINKING=true
|
||||
# Optional: You can add this if you only want to allow login with Authentik
|
||||
# DISABLE_PASSWORD_AUTH=true
|
||||
# Optional but highly recommended:
|
||||
# DISABLE_SIGNUPS=true
|
||||
```
|
||||
|
||||
Finally, restart the Karakeep server and test your configuration.
|
||||
70
docs/integrations/documentation/mealie/index.md
Normal file
70
docs/integrations/documentation/mealie/index.md
Normal file
@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Integrate with Mealie
|
||||
sidebar_label: Mealie
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Mealie
|
||||
|
||||
> Mealie is a self hosted recipe manager and meal planner. Easily add recipes by providing the url and Mealie will automatically import the relevant data or add a family recipe with the UI editor.
|
||||
>
|
||||
> -- https://mealie.io/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `mealie.company` is the FQDN of the Mealie installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Mealie with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**, **Client Secret**, , and **slug** values because they will be required later.
|
||||
- Create two `Strict` redirect URIs and set to `https://mealie.company/login` and `https://mealie.company/login?direct=1`.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
### Create the users and administrators groups
|
||||
|
||||
Using the authentik Admin interface, navigate to **Directory** -> **Groups** and click **Create** to create two groups, with names of your choosing, one for **Users** (ex: `mealie-users`) and one for **Admins** (ex: `mealie-admins`).
|
||||
|
||||
After creating the groups, select a group, navigate to **Directory** > **Users**, and manage its members by using the **Add existing user** and **Create user** buttons as needed. An admin will need to be added as a member to both groups to function properly.
|
||||
|
||||
## Mealie configuration
|
||||
|
||||
To enable OIDC login with Mealie, update your environment variables to include the following:
|
||||
|
||||
```yaml showLineNumbers
|
||||
OIDC_AUTH_ENABLED=true
|
||||
OIDC_PROVIDER_NAME=authentik
|
||||
OIDC_CONFIGURATION_URL=https://authentik.company/application/o/<application_slug>/.well-known/openid-configuration
|
||||
OIDC_CLIENT_ID=<Client ID from authentik>
|
||||
OIDC_CLIENT_SECRET=<Client secret from authentik>
|
||||
OIDC_SIGNUP_ENABLED=true
|
||||
OIDC_USER_GROUP=<Your users group created in authentik>
|
||||
OIDC_ADMIN_GROUP=<Your admins group created in authentik>
|
||||
OIDC_AUTO_REDIRECT=true # Optional: The login page will be bypassed and you will be sent directly to your Identity Provider.
|
||||
OIDC_REMEMBER_ME=true # Optional: By setting this value to true, a session will be extended as if "Remember Me" was checked.
|
||||
```
|
||||
|
||||
Restart the Mealie service for the changes to take effect.
|
||||
|
||||
## Configuration verification
|
||||
|
||||
1. To confirm that authentik is properly configured with Mealie, log out and log back in via authentik.
|
||||
2. In Mealie click on the user profile icon in the top left. Then click on **Members**, confirm the admins set in your authentik group are an **Admin** in Mealie as expected.
|
||||
244
docs/integrations/documentation/netbox/index.md
Normal file
244
docs/integrations/documentation/netbox/index.md
Normal file
@ -0,0 +1,244 @@
|
||||
---
|
||||
title: Integrate with NetBox
|
||||
sidebar_label: NetBox
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is NetBox
|
||||
|
||||
> NetBox is the leading solution for modeling and documenting modern networks.
|
||||
>
|
||||
> -- https://github.com/netbox-community/netbox
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `netbox.company` is the FQDN of the NetBox installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 NetBox with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://netbox.company/oauth/complete/oidc/`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## NetBox
|
||||
|
||||
:::info
|
||||
This setup was tested and developed with NetBox Docker. For a non-Docker installation, the Docker part must be disabled and the non-docker part must be used.
|
||||
:::
|
||||
|
||||
The following Docker env vars are required for the configuration.
|
||||
|
||||
```env
|
||||
# Enable python-social-auth
|
||||
REMOTE_AUTH_ENABLED='true'
|
||||
REMOTE_AUTH_BACKEND='social_core.backends.open_id_connect.OpenIdConnectAuth'
|
||||
|
||||
# python-social-auth config
|
||||
SOCIAL_AUTH_OIDC_OIDC_ENDPOINT='https://authentik.company/application/o/<application_slug>/'
|
||||
SOCIAL_AUTH_OIDC_KEY='<Client ID>'
|
||||
SOCIAL_AUTH_OIDC_SECRET='<Client Secret>'
|
||||
SOCIAL_AUTH_OIDC_SCOPE=openid profile email roles
|
||||
LOGOUT_REDIRECT_URL='https://authentik.company/application/o/<application_slug>/end-session/'
|
||||
```
|
||||
|
||||
The Netbox configuration needs to be extended, for this you can create a new file in the configuration folder, for example `authentik.py`.
|
||||
|
||||
```py
|
||||
from os import environ
|
||||
|
||||
#############
|
||||
# Docker
|
||||
#############
|
||||
|
||||
# python-social-auth configuration
|
||||
SOCIAL_AUTH_OIDC_OIDC_ENDPOINT = environ.get('SOCIAL_AUTH_OIDC_OIDC_ENDPOINT')
|
||||
SOCIAL_AUTH_OIDC_KEY = environ.get('SOCIAL_AUTH_OIDC_KEY')
|
||||
SOCIAL_AUTH_OIDC_SECRET = environ.get('SOCIAL_AUTH_OIDC_SECRET')
|
||||
SOCIAL_AUTH_OIDC_SCOPE = environ.get('SOCIAL_AUTH_OIDC_SCOPE').split(' ')
|
||||
LOGOUT_REDIRECT_URL = environ.get('LOGOUT_REDIRECT_URL')
|
||||
|
||||
|
||||
#############
|
||||
# non Docker
|
||||
#############
|
||||
|
||||
# NetBox settings
|
||||
#REMOTE_AUTH_ENABLED = True
|
||||
#REMOTE_AUTH_BACKEND = 'social_core.backends.open_id_connect.OpenIdConnectAuth'
|
||||
|
||||
# python-social-auth configuration
|
||||
#SOCIAL_AUTH_OIDC_ENDPOINT = 'https://authentik.company/application/o/<Application
|
||||
#SOCIAL_AUTH_OIDC_KEY = '<Client ID>'
|
||||
#SOCIAL_AUTH_OIDC_SECRET = '<Client Secret>'
|
||||
#LOGOUT_REDIRECT_URL = 'https://authentik.company/application/o/<application_slug>/end-session/
|
||||
```
|
||||
|
||||
### Groups
|
||||
|
||||
To manage groups in NetBox custom social auth pipelines are required. To create them you have to create the `custom_pipeline.py` file in the NetBox directory with the following content.
|
||||
|
||||
:::info
|
||||
From Netbox version 4.0.0 Netbox add the custom `Group` models. The following code is compatible with Netbox 4.0.0 and above. For Netbox versions below 4.0.0, the import statement and group adding / deleting of user lines must be changed.
|
||||
:::
|
||||
|
||||
```python
|
||||
# from django.contrib.auth.models import Group # For Netbox < 4.0.0
|
||||
from netbox.authentication import Group # For Netbox >= 4.0.0
|
||||
|
||||
class AuthFailed(Exception):
|
||||
pass
|
||||
|
||||
def add_groups(response, user, backend, *args, **kwargs):
|
||||
try:
|
||||
groups = response['groups']
|
||||
except KeyError:
|
||||
pass
|
||||
|
||||
# Add all groups from oAuth token
|
||||
for group in groups:
|
||||
group, created = Group.objects.get_or_create(name=group)
|
||||
# group.user_set.add(user) # For Netbox < 4.0.0
|
||||
user.groups.add(group) # For Netbox >= 4.0.0
|
||||
|
||||
def remove_groups(response, user, backend, *args, **kwargs):
|
||||
try:
|
||||
groups = response['groups']
|
||||
except KeyError:
|
||||
# Remove all groups if no groups in oAuth token
|
||||
user.groups.clear()
|
||||
pass
|
||||
|
||||
# Get all groups of user
|
||||
user_groups = [item.name for item in user.groups.all()]
|
||||
# Get groups of user which are not part of oAuth token
|
||||
delete_groups = list(set(user_groups) - set(groups))
|
||||
|
||||
# Delete non oAuth token groups
|
||||
for delete_group in delete_groups:
|
||||
group = Group.objects.get(name=delete_group)
|
||||
# group.user_set.remove(user) # For Netbox < 4.0.0
|
||||
user.groups.remove(group) # For Netbox >= 4.0.0
|
||||
|
||||
|
||||
def set_roles(response, user, backend, *args, **kwargs):
|
||||
# Remove Roles temporary
|
||||
user.is_superuser = False
|
||||
user.is_staff = False
|
||||
try:
|
||||
groups = response['groups']
|
||||
except KeyError:
|
||||
# When no groups are set
|
||||
# save the user without Roles
|
||||
user.save()
|
||||
pass
|
||||
|
||||
# Set roles is role (superuser or staff) is in groups
|
||||
user.is_superuser = True if 'superusers' in groups else False
|
||||
user.is_staff = True if 'staff' in groups else False
|
||||
user.save()
|
||||
```
|
||||
|
||||
The path of the file in the Official Docker image is: `/opt/netbox/netbox/netbox/custom_pipeline.py`
|
||||
|
||||
To enable the pipelines, add the pipelines section to the netbox configuration file from above
|
||||
|
||||
```python
|
||||
SOCIAL_AUTH_PIPELINE = (
|
||||
###################
|
||||
# Default pipelines
|
||||
###################
|
||||
|
||||
# Get the information we can about the user and return it in a simple
|
||||
# format to create the user instance later. In some cases the details are
|
||||
# already part of the auth response from the provider, but sometimes this
|
||||
# could hit a provider API.
|
||||
'social_core.pipeline.social_auth.social_details',
|
||||
|
||||
# Get the social uid from whichever service we're authing thru. The uid is
|
||||
# the unique identifier of the given user in the provider.
|
||||
'social_core.pipeline.social_auth.social_uid',
|
||||
|
||||
# Verifies that the current auth process is valid within the current
|
||||
# project, this is where emails and domains whitelists are applied (if
|
||||
# defined).
|
||||
'social_core.pipeline.social_auth.auth_allowed',
|
||||
|
||||
# Checks if the current social-account is already associated in the site.
|
||||
'social_core.pipeline.social_auth.social_user',
|
||||
|
||||
# Make up a username for this person, appends a random string at the end if
|
||||
# there's any collision.
|
||||
'social_core.pipeline.user.get_username',
|
||||
|
||||
# Send a validation email to the user to verify its email address.
|
||||
# Disabled by default.
|
||||
# 'social_core.pipeline.mail.mail_validation',
|
||||
|
||||
# Associates the current social details with another user account with
|
||||
# a similar email address. Disabled by default.
|
||||
# 'social_core.pipeline.social_auth.associate_by_email',
|
||||
|
||||
# Create a user account if we haven't found one yet.
|
||||
'social_core.pipeline.user.create_user',
|
||||
|
||||
# Create the record that associates the social account with the user.
|
||||
'social_core.pipeline.social_auth.associate_user',
|
||||
|
||||
# Populate the extra_data field in the social record with the values
|
||||
# specified by settings (and the default ones like access_token, etc).
|
||||
'social_core.pipeline.social_auth.load_extra_data',
|
||||
|
||||
# Update the user record with any changed info from the auth service.
|
||||
'social_core.pipeline.user.user_details',
|
||||
|
||||
|
||||
###################
|
||||
# Custom pipelines
|
||||
###################
|
||||
# Set authentik Groups
|
||||
'netbox.custom_pipeline.add_groups',
|
||||
'netbox.custom_pipeline.remove_groups',
|
||||
# Set Roles
|
||||
'netbox.custom_pipeline.set_roles'
|
||||
)
|
||||
|
||||
```
|
||||
|
||||
### Roles
|
||||
|
||||
In netbox, there are two special user roles `superuser` and `staff`. To set them, add your users to the `superusers` or `staff` group in authentik.
|
||||
|
||||
To use custom group names, the following scope mapping example can be used. In the example, the group `netbox_admins` is used for the `superusers` and the group `netbox_staff` for the `staff` users.
|
||||
|
||||
Name: `Netbox roles`
|
||||
Scope name: `roles`
|
||||
|
||||
Expression:
|
||||
|
||||
```python
|
||||
return {
|
||||
"groups": ["superusers" if group.name == "netbox_admin" else "staff" if group.name == "netbox_staff" else group.name for group in request.user.ak_groups.all()],
|
||||
}
|
||||
```
|
||||
|
||||
This scope mapping must also be selected in the _OAuth2/OpenID Provider_ created above.
|
||||
60
docs/integrations/documentation/outline/index.md
Normal file
60
docs/integrations/documentation/outline/index.md
Normal file
@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Integrate with Outline
|
||||
sidebar_label: Outline
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Outline
|
||||
|
||||
> Your team's knowledge base.
|
||||
> Lost in a mess of Docs? Never quite sure who has access? Colleagues requesting the same information repeatedly in chat? It’s time to get your team’s knowledge organized.
|
||||
>
|
||||
> -- https://www.getoutline.com
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `outline.company` is the FQDN of the Outline installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Outline with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://outline.company/auth/oidc.callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Outline configuration
|
||||
|
||||
You need to set the following `env` variables for Docker-based installations.
|
||||
|
||||
1. Set the following values:
|
||||
|
||||
```yaml
|
||||
OIDC_CLIENT_ID=
|
||||
OIDC_CLIENT_SECRET=
|
||||
OIDC_AUTH_URI=https://authentik.company/application/o/authorize/
|
||||
OIDC_TOKEN_URI=https://authentik.company/application/o/token/
|
||||
OIDC_USERINFO_URI=https://authentik.company/application/o/userinfo/
|
||||
OIDC_LOGOUT_URI=https://authentik.company/application/o/<application_slug>/end-session/
|
||||
OIDC_USERNAME_CLAIM=preferred_username
|
||||
OIDC_DISPLAY_NAME=authentik
|
||||
OIDC_SCOPES=openid profile email
|
||||
```
|
||||
76
docs/integrations/documentation/paperless-ng/index.md
Normal file
76
docs/integrations/documentation/paperless-ng/index.md
Normal file
@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Integrate with Paperless-ng
|
||||
sidebar_label: Paperless-ng
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Paperless-ng
|
||||
|
||||
> Paperless-ng is an application that indexes your scanned documents and allows you to easily search for documents and store metadata alongside your documents. It was a fork from the original Paperless that is no longer maintained.
|
||||
>
|
||||
> -- https://github.com/jonaswinkler/paperless-ng
|
||||
|
||||
:::caution
|
||||
This setup uses HTTP headers to log you in simply by providing your username as a header. Your authentik username and Paperless username MUST match. If you intend for this to be accessed externally, this requires careful setup of your reverse proxy server to not forward these headers from other sources.
|
||||
|
||||
The author of Paperless-ng recommends you do not expose Paperless outside your network, as it was not designed for that. Instead, they "recommend that if you do want to use it, run it locally on a server in your own home."
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `paperless.company` is the FQDN of the Paperless-ng installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
Also set up your proxy server to use forward auth with paperless.company: https://goauthentik.io/docs/providers/proxy/forward_auth
|
||||
|
||||
## Paperless
|
||||
|
||||
Start by adding the following environment variables to your Paperless-ng setup. If you are using docker-compose, then add the following to your docker-compose.env file:
|
||||
|
||||
```
|
||||
PAPERLESS_ENABLE_HTTP_REMOTE_USER=TRUE
|
||||
PAPERLESS_HTTP_REMOTE_USER_HEADER_NAME=HTTP_X_AUTHENTIK_USERNAME
|
||||
```
|
||||
|
||||
Authentik automatically sets this header when we use a proxy outpost.
|
||||
|
||||
Now restart your container:
|
||||
`docker compose down && docker compose up -d`
|
||||
|
||||
## authentik
|
||||
|
||||
**Provider**
|
||||
In authentik, go to the Admin Interface and click _Applications/Providers_.
|
||||
|
||||
Create a Proxy Provider. Give it a name (e.g. `Paperless Proxy`), then choose explicit or implicit consent (whether you want authentik to show a button to proceed to Paperless after login, or to just go there).
|
||||
|
||||
Choose Forward Auth (single application), then add the External host: `https://paperless.company`
|
||||
|
||||
Click Create to finish creating the provider.
|
||||
|
||||
**Application**
|
||||
|
||||
Now go to _Applications/Applications_ and create a new application.
|
||||
|
||||
Give it a name, this one is displayed to users. E.g. `Paperless`.
|
||||
|
||||
Set the slug, let's use `paperless`.
|
||||
|
||||
Now select the provider we created earlier, e.g. `Paperless Proxy`.
|
||||
|
||||
Click Create to create the application.
|
||||
|
||||
**Outpost**
|
||||
|
||||
Now go to _Applications/Outposts_ and click the edit button for _"authentik Embedded Outpost"_.
|
||||
|
||||
Under Applications, click Paperless to select it (use ctrl+click to select multiple), then click Update at the bottom.
|
||||
|
||||
## Finished
|
||||
|
||||
Now you can access Paperless-ng by logging in with authentik. Note that your authentik username and your Paperless username MUST match.
|
||||
111
docs/integrations/documentation/paperless-ngx/index.mdx
Normal file
111
docs/integrations/documentation/paperless-ngx/index.mdx
Normal file
@ -0,0 +1,111 @@
|
||||
---
|
||||
title: Integrate with Paperless-ngx
|
||||
sidebar_label: Paperless-ngx
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Paperless-ngx
|
||||
|
||||
> Paperless-ngx is an application that indexes your scanned documents and allows you to easily search for documents and store metadata alongside your documents. It was a fork from Paperless-ng, in turn a fork from the original Paperless, neither of which are maintained any longer.
|
||||
>
|
||||
> -- https://github.com/paperless-ngx/paperless-ngx
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `paperless.company` is the FQDN of the Paperless-ngx installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Paperless-ngx with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://paperless.company/accounts/oidc/authentik/login/callback/`.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
- **Advanced protocol settings**:
|
||||
- **Selected Scopes**: Add the following
|
||||
- `authentik default OAuth Mapping: OpenID 'openid'`
|
||||
- `authentik default OAuth Mapping: OpenID 'email'`
|
||||
- `authentik default OAuth Mapping: OpenID 'profile'`
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Paperless Configuration
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
<Tabs
|
||||
defaultValue="docker"
|
||||
values={[
|
||||
{label: 'Docker', value: 'docker'},
|
||||
{label: 'Standalone', value: 'standalone'},
|
||||
]}>
|
||||
<TabItem value="docker">
|
||||
If you have Paperless-ngx setup in Docker, add the following environment variables to your Paperless-ngx compose file:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
PAPERLESS_APPS: allauth.socialaccount.providers.openid_connect
|
||||
PAPERLESS_SOCIALACCOUNT_PROVIDERS: >
|
||||
{
|
||||
"openid_connect": {
|
||||
"APPS": [
|
||||
{
|
||||
"provider_id": "authentik",
|
||||
"name": "Authentik",
|
||||
"client_id": "<Client ID>",
|
||||
"secret": "<Client Secret>",
|
||||
"settings": {
|
||||
"server_url": "https://authentik.company/application/o/<application_slug>/.well-known/openid-configuration"
|
||||
}
|
||||
}
|
||||
],
|
||||
"OAUTH_PKCE_ENABLED": "True"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now restart your container:
|
||||
`docker compose down && docker compose up -d`
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="standalone">
|
||||
|
||||
You need to update your `paperless.conf` configuration file. Paperless will search for this configuration file in the following locations and use the first one it finds:
|
||||
|
||||
- The environment variable `PAPERLESS_CONFIGURATION_PATH`
|
||||
- `/path/to/paperless/paperless.conf`
|
||||
- `/etc/paperless.conf`
|
||||
- `/usr/local/etc/paperless.conf`
|
||||
|
||||
Edit your `paperless.conf` and add the following:
|
||||
|
||||
```ini
|
||||
PAPERLESS_ENABLE_ALLAUTH=true
|
||||
PAPERLESS_APPS=allauth.socialaccount.providers.openid_connect
|
||||
PAPERLESS_SOCIALACCOUNT_PROVIDERS={"openid_connect":{"OAUTH_PKCE_ENABLED":true,"APPS":[{"provider_id":"authentik","name":"authentik","client_id":"<Client ID>","secret":"<Client Secret>","settings":{"server_url":"https://authentik.company/application/o/paperless/.well-known/openid-configuration"}}]}}
|
||||
```
|
||||
|
||||
Now restart your Paperless services using `sudo systemctl restart paperless-*`
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
## Finished
|
||||
|
||||
Now you can access Paperless-ngx by logging in with authentik.
|
||||
|
||||
To add authentik authentication to an existing user, log in to Paperless with local authentication, click the profile icon in the top-right, click My Profile, then Connect new social account.
|
||||
159
docs/integrations/documentation/snipe-it/index.md
Normal file
159
docs/integrations/documentation/snipe-it/index.md
Normal file
@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Integrate with Snipe-IT
|
||||
sidebar_label: Snipe-IT
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Snipe-IT
|
||||
|
||||
> A free open source IT asset/license management system.
|
||||
>
|
||||
> -- https://snipeitapp.com
|
||||
|
||||
:::caution
|
||||
This setup assumes you will be using HTTPS as Snipe-It dynamically generates the ACS and other settings based on the complete URL.
|
||||
:::
|
||||
|
||||
:::caution
|
||||
In case something goes wrong with the configuration, you can use the URL `http://inventory.company/login?nosaml` to log in using the
|
||||
built-in authentication.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `inventory.company` is the FQDN of the snipe-it installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `snipeit-user` is the name of the authentik service account we will create.
|
||||
- `DC=ldap,DC=authentik,DC=io` is the Base DN of the LDAP Provider (default)
|
||||
|
||||
:::note
|
||||
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
|
||||
|
||||
### Step 1 - Service account
|
||||
|
||||
In authentik, create a service account (under _Directory/Users_) for Snipe-IT to use as the LDAP Binder and take note of the password generated.
|
||||
|
||||
In this example, we'll use `snipeit-user` as the Service account's username
|
||||
|
||||
:::note
|
||||
If you didn't keep the password, you can copy it from _Directory/Tokens & App password_.
|
||||
:::
|
||||
|
||||
### Step 2 - LDAP Provider
|
||||
|
||||
In authentik, create a LDAP Provider (under _Applications/Providers_) with these settings :
|
||||
|
||||
- Name : Snipe IT-LDAP
|
||||
- Bind DN : `DC=ldap,DC=goauthentik,DC=io`
|
||||
- Certificate : `authentik Self-signed Certificate`
|
||||
|
||||
### Step 3 - Application
|
||||
|
||||
In authentik, create an application (under _Resources/Applications_) with these settings :
|
||||
|
||||
- Name: Snipe IT-LDAP
|
||||
- Slug: snipe-it-ldap
|
||||
- Provider: Snipe IT-LDAP
|
||||
|
||||
### Step 4 - Outpost
|
||||
|
||||
In authentik, create an outpost (under _Applications/Outposts_) of type `LDAP` that uses the LDAP Application you created in _Step 3_.
|
||||
|
||||
- Name: LDAP
|
||||
- Type: LDAP
|
||||
|
||||
## Snipe-IT LDAP Setup
|
||||
|
||||
Configure Snipe-IT LDAP settings by going to settings (he gear icon), and selecting `LDAP`
|
||||
|
||||
Change the following fields
|
||||
|
||||
- LDAP Integration: **ticked**
|
||||
- LDAP Password Sync: **ticked**
|
||||
- Active Directory : **unticked**
|
||||
- LDAP Client-Side TLS Key: (taken from authentik)
|
||||
- LDAP Server: `ldap://authentik.company`
|
||||
- Use TLS : **unticked**
|
||||
- LDAP SSL certificate validation : **ticked**
|
||||
- Bind credentials:
|
||||
- LDAP Bind USername: `cn=snipeit-user,ou=users,dc=ldap,dc=goauthentik,dc=io`
|
||||
- LDAP Bind Password: `<snipeit-user password from step 2>`
|
||||
- Base Bind DN: `ou=users,DC=ldap,DC=goauthentik,DC=io`
|
||||
:::note
|
||||
ou=users is the default OU for users. If you are using authentik's virtual groups, or have your users in a different organizational unit (ou), change accordingly.
|
||||
:::
|
||||
- LDAP Filter: &(objectClass=user)
|
||||
- Username Field: mail
|
||||
:::note
|
||||
Setting the Username field to mail is recommended in order to ensure the usernameisunique. See https://snipe-it.readme.io/docs/ldap-sync-login
|
||||
:::
|
||||
- Allow unauthenticated bind: **unticked**
|
||||
- Last Name: sn
|
||||
- LDAP First Name: givenname
|
||||
- LDAP AUthentication query: cn=
|
||||
- LDAP Email: mail
|
||||
|
||||
:::note
|
||||
authentik does not support other LDAP attributes like Employee Number, Department, etc out of the box. If you need these fields, you will need to setup custom attributes.
|
||||
:::
|
||||
|
||||
Save your config, then click on Test LDAP Synchorization. This does not import any users, just verifies everything is working and the account can search the directory.
|
||||
|
||||
To test your settings, enter a username and password and click Test LDAP.
|
||||
|
||||
## Snipe-IT LDAP Sync
|
||||
|
||||
You must sync your LDAP database with Snipe-IT. Go to People on the sidebar menu.
|
||||
|
||||
- CLick `LDAP Sync`
|
||||
- Select your Location
|
||||
- Click Synchronize
|
||||
:::note
|
||||
Snipe-IT will only import users with both a first and last name set. You need to create user attributes with first and last names.
|
||||
:::
|
||||
|
||||
## authentik SAML Config
|
||||
|
||||
### Step 1
|
||||
|
||||
Create another application in authentik and note the slug you choose, as this will be used later. In the Admin Interface, go to Applications ->Providers. Create a SAML provider with the following parameters:
|
||||
|
||||
- ACS URL: `https://inventory.company/saml/acs`
|
||||
- Issuer: `https://inventory.company`
|
||||
- Service Provider Binding: `Post`
|
||||
- Audience: `https://inventory.company`
|
||||
- Signing certificate: Select any certificate you have.
|
||||
- Property mappings: Select all Managed mappings.
|
||||
- NamedID Property Mapping: authentik default SAML Mapping: Email
|
||||
:::note
|
||||
This is to match setting the username as **mail**. If you are using another field as the username, set it here.
|
||||
:::
|
||||
|
||||
### Step 2
|
||||
|
||||
After saving your new Application and Provider, go to _Applications/Providers_ and select your newly created Provider.
|
||||
|
||||
Either copy the information under SAML Metadata, or click the Download button under SAML Metadata
|
||||
|
||||
## Snipe-IT SAML Config
|
||||
|
||||
Configure Snipe-IT SAML settings by going to settings (he gear icon), and selecting `SAML`
|
||||
|
||||
- SAML enabled: **ticked**
|
||||
- SAML IdP Metadata: (paste information copied in Step 2 above -or-
|
||||
- Click `Select File`and select the file you downloaded in Step 2
|
||||
- Attribute Mapping - Username: mail
|
||||
- SAML Force Login: **ticked**
|
||||
- SAML Single Log Out: **ticked**
|
||||
|
||||
All other field can be left blank.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- https://snipe-it.readme.io/docs/ldap-sync-login
|
||||
- https://snipe-it.readme.io/docs/saml
|
||||
56
docs/integrations/documentation/tandoor/index.md
Normal file
56
docs/integrations/documentation/tandoor/index.md
Normal file
@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Integrate with Tandoor
|
||||
sidebar_label: Tandoor
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Tandoor
|
||||
|
||||
> Application for managing recipes, planning meals and building shopping lists.
|
||||
>
|
||||
> -- https://github.com/TandoorRecipes/recipes
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `tandoor.company` is the FQDN of the tandoor installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Tandoor with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://tandoor.company/accounts/oidc/authentik/login/callback/`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Tandoor configuration
|
||||
|
||||
Add the following environment variables to your tandoor configuration. Make sure to fill in the client ID, client secret and OpenID Connect well-known URL from your authentik instance.
|
||||
|
||||
```sh
|
||||
SOCIAL_PROVIDERS=allauth.socialaccount.providers.openid_connect
|
||||
SOCIALACCOUNT_PROVIDERS='{"openid_connect":{"APPS":[{"provider_id":"authentik","name":"authentik","client_id":"<Client ID from authentik>","secret":"<Client Secret from authentik>","settings":{"server_url":"https://authentik.company/application/o/<application_slug>/.well-known/openid-configuration"}}]}}'
|
||||
```
|
||||
|
||||
Restart the Tandoor service for the changes to take effect.
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is properly configured with Tandoor, log out of Tandoor, locate the "Sign in with authentik" button on the login page, click on it, and ensure you can successfully log in using Single Sign-On.
|
||||
75
docs/integrations/documentation/wiki-js/index.md
Normal file
75
docs/integrations/documentation/wiki-js/index.md
Normal file
@ -0,0 +1,75 @@
|
||||
---
|
||||
title: Integrate with Wiki.js
|
||||
sidebar_label: Wiki.js
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Wiki.js
|
||||
|
||||
> Wiki.js is a wiki engine running on Node.js and written in JavaScript. It is free software released under the Affero GNU General Public License. It is available as a self-hosted solution or using "single-click" install on the DigitalOcean and AWS marketplace.
|
||||
>
|
||||
> -- https://en.wikipedia.org/wiki/Wiki.js
|
||||
|
||||
:::note
|
||||
This is based on authentik 2022.11 and Wiki.js 2.5. Instructions may differ between versions.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `wiki.company` is the FQDN of Wiki.js installation.
|
||||
- `authentik.company` is the FQDN of authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
## Wiki.js pre-configuration
|
||||
|
||||
In Wiki.js, navigate to the _Authentication_ section in the _Administration_ interface.
|
||||
|
||||
Add a _Generic OpenID Connect / OAuth2_ strategy and take note of the _Callback URL / Redirect URI_ in the _Configuration Reference_ section at the bottom.
|
||||
|
||||
## authentik configuration
|
||||
|
||||
To support the integration of Wiki.js with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://wiki.company/login/id-from-wiki/callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Wiki.js configuration
|
||||
|
||||
In Wiki.js, configure the authentication strategy with these settings:
|
||||
|
||||
- Client ID: Client ID from the authentik provider.
|
||||
- Client Secret: Client Secret from the authentik provider.
|
||||
- Authorization Endpoint URL: https://authentik.company/application/o/authorize/
|
||||
- Token Endpoint URL: https://authentik.company/application/o/token/
|
||||
- User Info Endpoint URL: https://authentik.company/application/o/userinfo/
|
||||
- Issuer: https://authentik.company/application/o/wikijs/
|
||||
- Logout URL: https://authentik.company/application/o/wikijs/end-session/
|
||||
- Allow self-registration: Enabled
|
||||
- Assign to group: The group to which new users logging in from authentik should be assigned.
|
||||
|
||||
|
||||
|
||||
:::note
|
||||
You do not have to enable "Allow self-registration" and select a group to which new users should be assigned, but if you don't you will have to manually provision users in Wiki.js and ensure that their emails match the email they have in authentik.
|
||||
:::
|
||||
|
||||
:::note
|
||||
If you're using self-signed certificates for authentik, you need to set the root certificate of your CA as trusted in WikiJS by setting the NODE_EXTRA_CA_CERTS variable as explained here: https://github.com/Requarks/wiki/discussions/3387.
|
||||
:::
|
||||
BIN
docs/integrations/documentation/wiki-js/wiki-js_strategy.png
Normal file
BIN
docs/integrations/documentation/wiki-js/wiki-js_strategy.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 187 KiB |
74
docs/integrations/documentation/youtrack/index.md
Normal file
74
docs/integrations/documentation/youtrack/index.md
Normal file
@ -0,0 +1,74 @@
|
||||
---
|
||||
title: Integrate with YouTrack
|
||||
sidebar_label: YouTrack
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is YouTrack
|
||||
|
||||
> YouTrack is a proprietary, commercial browser-based bug tracker, issue tracking system, and project management software developed by JetBrains.
|
||||
>
|
||||
> -- https://www.jetbrains.com/youtrack/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `youtrack.company` is the FQDN of the YouTrack installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 YouTrack with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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.
|
||||
- Take note of the **slug** value as it will be required later.
|
||||
- Set the **ACS URL** to `https://placeholder.com`.
|
||||
- Set the **Entity ID** to `https://youtrack.company/admin/hub/`.
|
||||
- Set the **Service Provider Binding** to `Post`.
|
||||
- Under **Advanced protocol settings**, set an available signing key and make sure **Sign assertions** is toggled.
|
||||
- Then, also under **Advanced protocol settings**, make sure **NameID Property Mapping** is set to `authentik default SAML Mapping: username`. Make sure the [Allow users to change username](https://docs.goauthentik.io/docs/sys-mgmt/settings#allow-users-to-change-username) setting is disabled to prevent authentication issues.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
### Get the certificate's SHA-256 fingerprint
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **System** > **Certificates**, expand the certificate chosen in the previous section, and take note of the **Certificate Fingerprint (SHA256)**.
|
||||
|
||||
## YouTrack configuration
|
||||
|
||||
1. To integrate YouTrack with authentik, log in as a _Low-level Admin or higher_, click the **Administration** cog near the bottom of the page, hover over **Access Management**, and then select **Auth Modules**.
|
||||
2. Click **New module**, then select **SAML 2.0**.
|
||||
3. Fill out the form with the following information:
|
||||
- **Name**: Set an appropriate name (e.g. `authentik`)
|
||||
- **SAML SSO URL**: `https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/`
|
||||
- **IdP entity ID**: `https://youtrack.company/admin/hub/`
|
||||
- **Certificate fingerprint**: Set to the SHA-256 fingerprint retrieved in the previous step.
|
||||
4. Click **Create** to submit the form and take note of the **ACS URL**.
|
||||
|
||||
### Update the authentik provider
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Applications** > **Providers** > **_application name_**, then click **Edit**.
|
||||
3. Replace the placeholder value for the **ACS URL** with the value copied from the previous section.
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To confirm that authentik is properly configured with YouTrack, log out and attempt to log back in. You should be redirected to authentik to complete authentication.
|
||||
|
||||
## Resources
|
||||
|
||||
- [YouTrack SAML 2.0 Auth Module Documentation](https://www.jetbrains.com/help/youtrack/server/saml-authentication-module.html)
|
||||
1
docs/integrations/docusaurus.config.cjs
Normal file
1
docs/integrations/docusaurus.config.cjs
Normal file
@ -0,0 +1 @@
|
||||
module.exports = import("./docusaurus.config.esm.mjs").then(($) => $.default);
|
||||
87
docs/integrations/docusaurus.config.esm.mjs
Normal file
87
docs/integrations/docusaurus.config.esm.mjs
Normal file
@ -0,0 +1,87 @@
|
||||
/**
|
||||
* @file Docusaurus Integrations config.
|
||||
*
|
||||
* @import { Config } from "@docusaurus/types";
|
||||
* @import { UserThemeConfig, UserThemeConfigExtra } from "@goauthentik/docusaurus-config";
|
||||
* @import { Options as DocsPluginOptions } from "@docusaurus/plugin-content-docs";
|
||||
*/
|
||||
import { createDocusaurusConfig } from "@goauthentik/docusaurus-config";
|
||||
import { CommonConfig, CommonDocsPluginOptions } from "@goauthentik/docusaurus-theme/config";
|
||||
import { remarkLinkRewrite } from "@goauthentik/docusaurus-theme/remark";
|
||||
|
||||
import { GlobExcludeDefault } from "@docusaurus/utils";
|
||||
import { deepmerge } from "deepmerge-ts";
|
||||
import { createRequire } from "node:module";
|
||||
import { resolve } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const require = createRequire(import.meta.url);
|
||||
const __dirname = fileURLToPath(new URL(".", import.meta.url));
|
||||
|
||||
//#region Configuration
|
||||
|
||||
/**
|
||||
* Documentation site configuration for Docusaurus.
|
||||
* @satisfies {Partial<Config>}
|
||||
*/
|
||||
const config = {
|
||||
staticDirectories: [
|
||||
// ---
|
||||
resolve(__dirname, "..", "static"),
|
||||
"static",
|
||||
],
|
||||
|
||||
themes: ["@goauthentik/docusaurus-theme"],
|
||||
|
||||
themeConfig: /** @type {UserThemeConfig & UserThemeConfigExtra} */ ({
|
||||
navbarReplacements: {
|
||||
INTEGRATIONS_URL: "/",
|
||||
},
|
||||
algolia: {
|
||||
externalUrlRegex: /^(?:https?:\/\/)(integrations|api).?(goauthentik.io)/.source,
|
||||
},
|
||||
}),
|
||||
|
||||
plugins: [
|
||||
[
|
||||
"@docusaurus/theme-classic",
|
||||
{
|
||||
customCss: [
|
||||
"./custom.css",
|
||||
require.resolve("@goauthentik/docusaurus-config/css/index.css"),
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
//#region Documentation
|
||||
[
|
||||
"@docusaurus/plugin-content-docs",
|
||||
deepmerge(
|
||||
CommonDocsPluginOptions,
|
||||
/** @type {DocsPluginOptions} */ ({
|
||||
id: "docs",
|
||||
routeBasePath: "/",
|
||||
path: ".",
|
||||
exclude: [...GlobExcludeDefault],
|
||||
include: ["**/*.mdx", "**/*.md"],
|
||||
sidebarPath: "./sidebar.mjs",
|
||||
showLastUpdateTime: false,
|
||||
editUrl:
|
||||
"https://github.com/goauthentik/authentik/edit/main/docs/topics/integrations/",
|
||||
|
||||
//#region Docs Plugins
|
||||
|
||||
beforeDefaultRemarkPlugins: [
|
||||
remarkLinkRewrite([
|
||||
// ---
|
||||
["/api", "https://api.goauthentik.io"],
|
||||
["/docs", "https://docs.goauthentik.io"],
|
||||
]),
|
||||
],
|
||||
}),
|
||||
),
|
||||
],
|
||||
],
|
||||
};
|
||||
|
||||
export default /** @type {Config} */ (deepmerge(CommonConfig, createDocusaurusConfig(config)));
|
||||
10
docs/integrations/eslint.config.mjs
Normal file
10
docs/integrations/eslint.config.mjs
Normal file
@ -0,0 +1,10 @@
|
||||
import { DefaultIgnorePatterns, createESLintPackageConfig } from "@goauthentik/eslint-config";
|
||||
|
||||
export default createESLintPackageConfig({
|
||||
ignorePatterns: [
|
||||
// ---
|
||||
...DefaultIgnorePatterns,
|
||||
".docusaurus/",
|
||||
"./build",
|
||||
],
|
||||
});
|
||||
@ -0,0 +1,71 @@
|
||||
---
|
||||
title: Integrate with Portainer
|
||||
sidebar_label: Portainer
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Portainer
|
||||
|
||||
> Portainer is a powerful, GUI-based Container-as-a-Service solution that helps organizations manage and deploy cloud-native applications easily and securely.
|
||||
>
|
||||
> -- https://www.portainer.io/
|
||||
|
||||
:::note
|
||||
This is based on authentik 2021.7.3 and Portainer 2.6.x-CE. Portainer 2.6 supports OAuth without additional licenses, 1.x Series requires a paid license for OAuth.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `portainer.company` is the FQDN of Portainer installation.
|
||||
- `authentik.company` is the FQDN of authentik installation.
|
||||
|
||||
:::note
|
||||
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 Portainer with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://portainer.company/`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Portainer configuration
|
||||
|
||||
In Portainer, under _Settings_, _Authentication_, Select _OAuth_ and _Custom_
|
||||
|
||||
- Client ID: The 'Client ID' from the authentik provider
|
||||
- Client Secret: The 'Client secret' from the authentik provider
|
||||
- Authorization URL: `https://authentik.company/application/o/authorize/`
|
||||
- Access Token URL: `https://authentik.company/application/o/token/`
|
||||
- Resource URL: `https://authentik.company/application/o/userinfo/`
|
||||
- Redirect URL: `https://portainer.company/`
|
||||
- Logout URL: `https://authentik.company/application/o/portainer/end-session/`
|
||||
- User Identifier: `preferred_username` (Or `email` if you want to use email addresses as identifiers)
|
||||
- Scopes: `email openid profile`
|
||||
|
||||
:::note
|
||||
Portainer by default shows commas between each item in the Scopes field. Do **NOT** use commas. Use a _space_
|
||||
:::
|
||||
|
||||
|
||||
|
||||
## Notes
|
||||
|
||||
:::note
|
||||
Portainer Reference link: https://documentation.portainer.io/v2.0/auth/oauth/
|
||||
:::
|
||||
BIN
docs/integrations/hypervisors-orchestrators/portainer/port1.png
Normal file
BIN
docs/integrations/hypervisors-orchestrators/portainer/port1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 99 KiB |
@ -0,0 +1,86 @@
|
||||
---
|
||||
title: Integrate with Proxmox VE
|
||||
sidebar_label: Proxmox VE
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Proxmox VE
|
||||
|
||||
> Proxmox Virtual Environment is an open source server virtualization management solution based on QEMU/KVM and LXC. You can manage virtual machines, containers, highly available clusters, storage, and networks with an integrated, easy-to-use web interface or via CLI. Proxmox VE code is licensed under the GNU Affero General Public License, version 3. The project is developed and maintained by Proxmox Server Solutions GmbH.
|
||||
>
|
||||
> -- https://pve.proxmox.com/wiki/Main_Page
|
||||
|
||||
:::caution
|
||||
Requires Proxmox VE 7.0 or newer.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `proxmox.company` is the FQDN of the Proxmox VE server installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Proxmox with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://proxmox.company:8006`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Proxmox VE configuration (using the web interface)
|
||||
|
||||
1. Log in to the Proxmox VE web interface using an administrative account.
|
||||
|
||||
2. Navigate to authentication source settings.
|
||||
- Go to **Datacenter** > **Permissions** > **Realms**.
|
||||
- Click **Add** and select **Realm** to open the Add Realm dialog.
|
||||
|
||||
3. Fill out the OpenID Connect settings.
|
||||
- In the dialog that appears, fill in the following details:
|
||||
- **Issuer URL**: Enter the Issuer URL from authentik (found in your provider's overview tab), e.g., `https://authentik.company/application/o/proxmox/`.
|
||||
- **Realm**: Enter a name for this authentication source, such as `authentik`.
|
||||
- **Client ID**: Enter the Client ID found on the provider overview page.
|
||||
- **Client Key**: Enter the Client Secret. (To find this value click **Edit** on the Provider overview page.)
|
||||
- **Username claim**: Set this to `username`.
|
||||
- **Autocreate users**: Check this box if you want Proxmox to automatically create users upon first login. If checked, users will appear in Proxmox with the format `<authentik username>@authentik`.
|
||||
- **Default**: Check this if you want OpenID Connect to be pre-selected as the default on the login screen.
|
||||
|
||||
**Example configuration**:
|
||||
|
||||
|
||||
|
||||
4. **Save the configuration**.
|
||||
- Click **Add** to save the settings.
|
||||
|
||||
5. **Assign permissions**
|
||||
- After setting up the authentication source, go to **Permissions** to assign roles and permissions for each user as needed.
|
||||
|
||||
6. **Logging in**
|
||||
- Users can select this authentication method from the Proxmox login screen, or if set as default, it will be automatically selected.
|
||||
|
||||
|
||||
|
||||
## Proxmox VE configuration (using CLI)
|
||||
|
||||
To configure OpenID Connect authentication via the CLI, SSH into any Proxmox cluster node and use the following command:
|
||||
|
||||
```bash
|
||||
pveum realm add authentik --type openid --issuer-url https://authentik.company/application/o/proxmox/ --client-id xxx --client-key xxx --username-claim username --autocreate 1
|
||||
```
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 7.4 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
61
docs/integrations/hypervisors-orchestrators/rancher/index.md
Normal file
61
docs/integrations/hypervisors-orchestrators/rancher/index.md
Normal file
@ -0,0 +1,61 @@
|
||||
---
|
||||
title: Integrate with Rancher
|
||||
sidebar_label: Rancher
|
||||
support_level: authentik
|
||||
---
|
||||
|
||||
## What is Rancher
|
||||
|
||||
> An enterprise platform for managing Kubernetes Everywhere
|
||||
> Rancher is a platform built to address the needs of the DevOps teams deploying applications with Kubernetes, and the IT staff responsible for delivering an enterprise-critical service.
|
||||
>
|
||||
> -- https://rancher.com/products/rancher
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `rancher.company` is the FQDN of the Rancher installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
Under _Customization_ -> _Property Mappings_, create a _SAML Property Mapping_. Give it a name like "SAML Rancher User ID". Set the SAML name to `rancherUidUsername` and the expression to the following
|
||||
|
||||
```python
|
||||
return f"{user.pk}-{user.username}"
|
||||
```
|
||||
|
||||
Create an application in authentik. Set the Launch URL to `https://rancher.company`, as Rancher does not currently support IdP-initiated logins.
|
||||
|
||||
Create a SAML provider with the following parameters:
|
||||
|
||||
- ACS URL: `https://rancher.company/v1-saml/adfs/saml/acs`
|
||||
- Audience: `https://rancher.company/v1-saml/adfs/saml/metadata`
|
||||
- Issuer: `authentik`
|
||||
- Service Provider Binding: `Post`
|
||||
- Property mappings: Select all default mappings and the mapping you've created above.
|
||||
- Signing Certificate: Select the authentik self-signed certificate.
|
||||
|
||||
You can of course use a custom signing certificate, and adjust durations.
|
||||
|
||||
## Rancher
|
||||
|
||||
In Rancher, navigate to _Global_ -> _Security_ -> _Authentication_, and select ADFS.
|
||||
|
||||
Fill in the fields
|
||||
|
||||
- Display Name Field: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
|
||||
- User Name Field: `http://schemas.goauthentik.io/2021/02/saml/username`
|
||||
- UID Field: `rancherUidUsername`
|
||||
- Groups Field: `http://schemas.xmlsoap.org/claims/Group`
|
||||
|
||||
For the private key and certificate, you can either generate a new pair (in authentik, navigate to _Identity & Cryptography_ -> _Certificates_ and select Generate), or use an existing pair.
|
||||
|
||||
Copy the metadata from authentik, and paste it in the metadata field.
|
||||
|
||||
Click on save to test the authentication.
|
||||
|
||||
|
||||
BIN
docs/integrations/hypervisors-orchestrators/rancher/rancher.png
Normal file
BIN
docs/integrations/hypervisors-orchestrators/rancher/rancher.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 162 KiB |
@ -0,0 +1,89 @@
|
||||
---
|
||||
title: Integrate with VMware vCenter
|
||||
sidebar_label: VMware vCenter
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is vCenter
|
||||
|
||||
> vCenter Server is the centralized management utility for VMware, and is used to manage virtual machines, multiple ESXi hosts, and all dependent components from a single centralized location. VMware vMotion and svMotion require the use of vCenter and ESXi hosts.
|
||||
>
|
||||
> -- https://en.wikipedia.org/wiki/VCenter
|
||||
|
||||
:::caution
|
||||
Integration with authentik requires VMware vCenter 8.03 or newer.
|
||||
:::
|
||||
|
||||
The following placeholders will be used in the examples below:
|
||||
|
||||
- `vcenter.company` is the FQDN of the vCenter server.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 vCenter with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://vcenter.company/ui/login/oauth2/authcode`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## vCenter configuration
|
||||
|
||||
1. Log in to vCenter with your local Administrator account. Using the menu in the left navigation bar, navigate to **Administration -> Single Sign-on -> Configuration**.
|
||||
|
||||
2. Click **Change Provider** in the top-right corner, and then select **Okta** from the drop-down list.
|
||||
|
||||
3. In the wizard, click **Run Prechecks**, select the confirmation box, and then click **Next**
|
||||
- Enter the **Directory Name**. For example `authentik` or any other name.
|
||||
- Add a **Domain Name**. For example `authentik.company`.
|
||||
- Click on the Plus (+) sign to show the default domain name.
|
||||
|
||||
4. Click **Next**.
|
||||
|
||||
5. On the OpenID Connect page, enter the following values:
|
||||
- Set **Identity Provider Name** to `authentik`.
|
||||
- Set **Client Identifier** to the client ID from authentik.
|
||||
- Set **Shared secret** to the client secret from authentik.
|
||||
- Set **OpenID Address** to the _OpenID Configuration URL_ from authentik.
|
||||
|
||||
6. Click **Next**, and then **Finish**.
|
||||
|
||||
7. On the **Single Sign On -> Configuration** page, in the **User Provisioning** area, take the following steps:
|
||||
- Copy the **Tenant URL** and save to a safe place.
|
||||
- Click on **Generate** to generate a SCIM token.
|
||||
- Click **Generate** in the newly opened modal box.
|
||||
- Copy the token and save to a safe place.
|
||||
|
||||
8. Return to the authentik Admin interface.
|
||||
- Create a SCIM provider with the name `vcenter-scim`.
|
||||
- Paste the Tenant URL into **URL** field for the provider.
|
||||
- Paste the token you saved into the **Token** field.
|
||||
- If your vCenter certificate is self-signed (which is the default), toggle **Verify SCIM server's certificates** to be off.
|
||||
- Configure options under `User filtering` to your needs.
|
||||
- Save the provider.
|
||||
- Edit the application that you created earlier and select this newly created SCIM provider as the backchannel provider.
|
||||
- Navigate to the provider and trigger a sync.
|
||||
|
||||
9. Return to vCenter.
|
||||
- Navigate to **Administration -> Access Control -> Global Permissions**.
|
||||
- Click **Add**.
|
||||
- Select the Domain created above from the dropdown.
|
||||
- Enter the name of the group to which you want to assign permissions.
|
||||
- Select the role.
|
||||
|
||||
10. Click **Save**.
|
||||
@ -0,0 +1,69 @@
|
||||
---
|
||||
title: Integrate with Xen Orchestra
|
||||
sidebar_label: Xen Orchestra
|
||||
support_level: community
|
||||
---
|
||||
|
||||
## What is Xen Orchestra
|
||||
|
||||
> Xen Orchestra provides a user friendly web interface for every Xen based hypervisor (XenServer, xcp-ng, etc.).
|
||||
>
|
||||
> -- https://xen-orchestra.com/
|
||||
|
||||
:::note
|
||||
Xen Orchestra offers authentication plugins for OpenID Connect, SAML and LDAP. This guide is using the OpenID Connect plugin.
|
||||
If you are using the Xen Orchestra Appliance, the OIDC Plugin should be present. If you are using Xen Orchestra compiled from sources, make sure the plugin `auth-oidc` is installed.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `xenorchestra.company` is the FQDN of the Xen Orchestra instance.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Xen Orchestra with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://xenorchestra.company/signin/oidc/callback`.
|
||||
- Select any available signing key.
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Xen Orchestra configuration
|
||||
|
||||
Xen Orchestra allows the configuration of the OpenID Connect authentication in the plugin-section.
|
||||
All of the URLs mentioned below can be copied & pasted from authentik (_Applications -> Providers -> *the provider created earlier*_).
|
||||
|
||||
1. Navigate to Settings -> Plugins
|
||||
2. Scroll to **auth-oidc** and click on the **+** icon on the right hand side.
|
||||
3. Configure the auth-oidc plugin with the following configuration values:
|
||||
|
||||
- Set the `Auto-discovery URL` to `https://authentik.company/application/o/xenorchestra/.well-known/openid-configuration`.
|
||||
- Set the `Client identifier (key)` to the Client ID from your notes.
|
||||
- Set the `Client secret` to the Client Secret from your notes.
|
||||
- Check the `Fill information (optional)`-Checkbox to open the advanced menu.
|
||||
- Set the `Username field` to `username`
|
||||
- Set the `Scopes` to `openid profile email`
|
||||
|
||||
4. Enable the `auth-oidc`-Plugin by toggling the switch above the configuration.
|
||||
5. You should be able to login with OIDC.
|
||||
|
||||
:::note
|
||||
The first time a user signs in, Xen Orchesta will create a new user with the same username used in authentik. If you want to map the users by their e-mail-address instead of their username, you have to set the `Username field` to `email` in the Xen Orchestra plugin configuration.
|
||||
:::
|
||||
24
docs/integrations/index.mdx
Normal file
24
docs/integrations/index.mdx
Normal file
@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Integrations overview
|
||||
sidebar_label: Overview
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
## What is an integration?
|
||||
|
||||
An integration is a how authentik connects to third-party applications, directories, and other identity providers.
|
||||
Integrations are categorized into two categories: **Applications** and **Sources**.
|
||||
|
||||
### Applications
|
||||
|
||||
Applications include vendor tools such as Google Workspace, GitHub, Slack, or AWS. These applications can be integrated with authentik to provide single sign-on capabilities to securely authenticate users.
|
||||
|
||||
If you want to integrate an application that isn't listed, authentik can be configured to work with most applications that support authentication protocols such as [SAML](/docs/add-secure-apps/providers/saml), [OAuth and OpenID Connect](/docs/add-secure-apps/providers/oauth2).
|
||||
|
||||
To learn more, refer to the [Applications](./applications.mdx) page.
|
||||
|
||||
### Federated and social sources
|
||||
|
||||
Sources are a way for authentik to use external user credentials for authentication. Supported integrations with external sources via authentik include federated directories like Active Directory and social logins such as Facebook, Twitter, etc. These integrations support all major protocols, including [LDAP](/docs/users-sources/sources/protocols/ldap/index.md), [SCIM](/docs/users-sources/sources/protocols/scim/index.md), [SAML](/docs/users-sources/sources/protocols/saml/index.md), and [OAuth and OpenID Connect](/docs/users-sources/sources/protocols/oauth/index.mdx)
|
||||
|
||||
To learn more, refer to the [Sources](/docs/users-sources/sources/index.md) page.
|
||||
197
docs/integrations/infrastructure/apache-guacamole/index.mdx
Normal file
197
docs/integrations/infrastructure/apache-guacamole/index.mdx
Normal file
@ -0,0 +1,197 @@
|
||||
---
|
||||
title: Integrate with Apache Guacamole™
|
||||
sidebar_label: Apache Guacamole™
|
||||
support_level: authentik
|
||||
---
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
## What is Apache Guacamole™
|
||||
|
||||
> Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH.
|
||||
>
|
||||
> -- https://guacamole.apache.org/
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `guacamole.company` is the FQDN of the Guacamole installation.
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
|
||||
:::note
|
||||
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 Apache Guacamole with authentik, you need to create an application/provider pair in authentik.
|
||||
|
||||
### 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 **OAuth2/OpenID Connect** 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.
|
||||
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
|
||||
- Set a `Strict` redirect URI to `https://guacamole.company/`. If you have configured [Apache Tomcat](https://tomcat.apache.org/) to run Apache Guacamole on a subpath, you will need to update this value accordingly.
|
||||
- Select any available signing key.
|
||||
- Note that Apache Guacamole does not support session tokens longer than 300 minutes (5 hours).
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
||||
|
||||
3. Click **Submit** to save the new application and provider.
|
||||
|
||||
## Apache Guacamole Configuration
|
||||
|
||||
It is recommended to create an admin account in Guacamole before configuring Single Sign-On to simplify the process. Create a user in Guacamole using the same username as in authentik and grant them admin permissions. This step is important to avoid losing access to the Guacamole admin settings, as you may need to revert your changes without it.
|
||||
|
||||
:::warning
|
||||
You can configure Apache Guacamole to use either the `sub` or `preferred_username` as the UID field under `user-name-attribute`. When using `preferred_username` as the user identifier, ensure that the [**Allow users to change username** setting](https://docs.goauthentik.io/docs/sys-mgmt/settings#allow-users-to-change-username) is disabled to prevent authentication issues. The `sub` option uses a unique, stable identifier for the user, while `preferred_username` uses the username configured in authentik.
|
||||
:::
|
||||
|
||||
<Tabs
|
||||
defaultValue="docker"
|
||||
values={[
|
||||
{ label: 'Docker', value: 'docker' },
|
||||
{ label: 'Standalone', value: 'standalone' },
|
||||
]}>
|
||||
<TabItem value="docker">
|
||||
Docker containers are typically configured using environment variables. To ensure proper integration, add the following variables to your `.env` file:
|
||||
|
||||
```yaml showLineNumbers
|
||||
OPENID_AUTHORIZATION_ENDPOINT=https://authentik.company/application/o/authorize/
|
||||
OPENID_CLIENT_ID=<Client ID from authentik>
|
||||
OPENID_ISSUER=https://authentik.company/application/o/<application_slug>/
|
||||
OPENID_JWKS_ENDPOINT=https://authentik.company/application/o/<application_slug>/jwks/
|
||||
OPENID_REDIRECT_URI=https://guacamole.company/
|
||||
OPENID_USERNAME_CLAIM_TYPE=preferred_username
|
||||
```
|
||||
|
||||
Additionally, ensure your `guacamole.properties` file (typically located in `/etc/guacamole/`) includes the following line. This setting allows environment variables to be evaluated before static configuration files:
|
||||
|
||||
```yaml
|
||||
enable-environment-properties: true
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="standalone">
|
||||
To set up Apache Guacamole in a standalone environment, you'll need to adjust the settings in the `guacamole.properties` file, usually found in the `/etc/guacamole/` directory. Add the following settings:
|
||||
|
||||
```yaml showLineNumbers title="/etc/guacamole/guacamole.properties"
|
||||
openid-authorization-endpoint=https://authentik.company/application/o/authorize/
|
||||
openid-client-id=<Client ID from authentik>
|
||||
openid-issuer=https://authentik.company/application/o/<application_slug>/
|
||||
openid-jwks-endpoint=https://authentik.company/application/o/<application_slug>/jwks/
|
||||
openid-redirect-uri=https://guacamole.company/
|
||||
openid-username-claim-type=preferred_username
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Self Signed Certificates
|
||||
|
||||
When using a self-signed certificate, it is necessary to incorporate the certificate of the corresponding Certificate Authority into both the `/etc/ssl/certs/ca-certificates.crt` file and the `/opt/java/openjkd/jre/lib/security/cacerts` keystore on your Apache Guacamole host. This ensures that the self-signed certificate is trusted by both the system and the Java runtime environment used by Guacamole.
|
||||
|
||||
#### Adding Certificate Authority certificate as trusted in `/etc/ssl/certs/ca-certificates.crt`
|
||||
|
||||
:::note
|
||||
This section depends on the operating system hosting Apache Guacamole.
|
||||
:::
|
||||
|
||||
##### For _Debian_ based operating systems:
|
||||
|
||||
1. Copy the certificate of the Certificate Authority (e.g. `<CA_certificate>.crt`) to the `/usr/local/share/ca-certificates/` directory on the Apache Guacamole host. Ensure that the file extension is `.crt`.
|
||||
|
||||
2. To add the certificate as trusted in `/etc/ssl/certs/ca-certificates.crt`, use the following command:
|
||||
|
||||
```shell
|
||||
update-ca-certificates
|
||||
```
|
||||
|
||||
##### For _Synology_ systems:
|
||||
|
||||
1. Copy the certificate of the Certificate Authority (e.g. `<CA_certificate>.crt`) to the `/usr/syno/etc/security-profile/ca-bundle-profile/ca-certificates/` directory on the Synology host. Ensure that the filetype is `.crt`.
|
||||
|
||||
2. To add the certificate as trusted in `/etc/ssl/certs/ca-certificates.crt`, use the following command:
|
||||
|
||||
```shell
|
||||
update-ca-certificates.sh
|
||||
```
|
||||
|
||||
#### Adding Certificate Authority certificate to `/opt/java/openjkd/jre/lib/security/cacerts`
|
||||
|
||||
1. To export the certificate of the Certificate Authority, use the following command on the Certificate Authority host:
|
||||
|
||||
```shell
|
||||
openssl pkcs12 -export -in <CA_certificate>.crt -inkey <CA_certificate>.key -out <CA_certificate>.p12 -passout pass:<password>
|
||||
```
|
||||
|
||||
2. To import the certificate to the `/opt/java/openjdk/jre/lib/security/cacerts` keystore on the Apache Guacamole host, use the following command:
|
||||
|
||||
```shell
|
||||
keytool -importkeystore -srckeystore <CA_certificate>.p12 -srcstoretype PKCS12 -keystore /opt/java/openjdk/jre/lib/security/cacerts -deststorepass <destination_store_password> -nopromt -srcstorepass <password>
|
||||
```
|
||||
|
||||
:::note
|
||||
More information on the keytool command can be found in the [Oracle documentation.](https://docs.oracle.com/en/java/javase/21/docs/specs/man/keytool.html)
|
||||
:::
|
||||
|
||||
### Self Signed Certificates
|
||||
|
||||
When using a self-signed certificate, it is necessary to incorporate the certificate of the corresponding Certificate Authority into both the `/etc/ssl/certs/ca-certificates.crt` file and the `/opt/java/openjkd/jre/lib/security/cacerts` keystore on your Apache Guacamole host. This ensures that the self-signed certificate is trusted by both the system and the Java runtime environment used by Guacamole.
|
||||
|
||||
#### Adding Certificate Authority certificate as trusted in `/etc/ssl/certs/ca-certificates.crt`
|
||||
|
||||
:::note
|
||||
This section depends on the operating system hosting Apache Guacamole.
|
||||
:::
|
||||
|
||||
##### For _Debian_ based operating systems:
|
||||
|
||||
1. Copy the certificate of the Certificate Authority (e.g. `<CA_certificate>.crt`) to the `/usr/local/share/ca-certificates/` directory on the Apache Guacamole host. Ensure that the file extension is `.crt`.
|
||||
|
||||
2. To add the certificate as trusted in `/etc/ssl/certs/ca-certificates.crt`, use the following command:
|
||||
|
||||
```shell
|
||||
update-ca-certificates
|
||||
```
|
||||
|
||||
##### For _Synology_ systems:
|
||||
|
||||
1. Copy the certificate of the Certificate Authority (e.g. `<CA_certificate>.crt`) to the `/usr/syno/etc/security-profile/ca-bundle-profile/ca-certificates/` directory on the Synology host. Ensure that the filetype is `.crt`.
|
||||
|
||||
2. To add the certificate as trusted in `/etc/ssl/certs/ca-certificates.crt`, use the following command:
|
||||
|
||||
```shell
|
||||
update-ca-certificates.sh
|
||||
```
|
||||
|
||||
#### Adding Certificate Authority certificate to `/opt/java/openjkd/jre/lib/security/cacerts`
|
||||
|
||||
1. To export the certificate of the Certificate Authority, use the following command on the Certificate Authority host:
|
||||
|
||||
```shell
|
||||
openssl pkcs12 -export -in <CA_certificate>.crt -inkey <CA_certificate>.key -out <CA_certificate>.p12 -passout pass:<password>
|
||||
```
|
||||
|
||||
2. To import the certificate to the `/opt/java/openjdk/jre/lib/security/cacerts` keystore on the Apache Guacamole host, use the following command:
|
||||
|
||||
```shell
|
||||
keytool -importkeystore -srckeystore <CA_certificate>.p12 -srcstoretype PKCS12 -keystore /opt/java/openjdk/jre/lib/security/cacerts -deststorepass <destination_store_password> -nopromt -srcstorepass <password>
|
||||
```
|
||||
|
||||
:::note
|
||||
More information on the keytool command can be found in the [Oracle documentation.](https://docs.oracle.com/en/java/javase/21/docs/specs/man/keytool.html)
|
||||
:::
|
||||
|
||||
## Configuration verification
|
||||
|
||||
To verify that authentik is correctly configured with Apache Guacamole, log out and log back in through authentik. You should notice a new button appearing at the bottom left of the login page.
|
||||
|
||||
## Resources
|
||||
|
||||
- [Apache Guacamole official documentation on OpenID Connect integrations](https://guacamole.apache.org/doc/gug/openid-auth.html#configuring-guacamole-for-single-sign-on-with-openid-connect)
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user