diff --git a/website/integrations/services/actual-budget/index.md b/website/integrations/services/actual-budget/index.md new file mode 100644 index 000000000000..518714fab856 --- /dev/null +++ b/website/integrations/services/actual-budget/index.md @@ -0,0 +1,65 @@ +--- +title: Integrate with Actual Budget +sidebar_label: Actual Budget +--- + +# Actual Budget + +Support level: Community + +## What is Actual Budget + +> Actual Budget is a web-based financial management software. It helps users track and manage their income, expenses, and budgets in real time. The software compares actual spending with planned budgets to improve financial decisions. +> +> -- https://actualbudget.org/ + +## Preparation + +The following placeholders are used in this guide: + +- `actual.company` is the FQDN of the Actual Budget installation. +- `authentik.company` is the FQDN of the authentik installation. + +:::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 + +1. From the **authentik Admin interface**, navigate to **Applications** -> **Applications**. +2. Use the [wizard](https://docs.goauthentik.io/docs/add-secure-apps/applications/manage_apps#add-new-applications) to create a new application and a **OAuth2/OpenID Connect provider**. During this process: + - Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later. + - Set a `Strict` redirect URI to https://actual.company/openid/callback/. + - Select any available signing key. + +:::info +Actual Budget only supports the RS256 algorithm. Be aware of this when choosing the appropriate signing key. +::: + +## Actual Budget configuration + +1. Sign in to Actual Budget and select your budget by clicing its name. +2. In the top-left corner, click your budget name to open the dropdown and choose **Settings**. +3. Scroll down and select **Show advanced settings**, then enable **I understand the risks, show experimental features**. +4. Enable **OpenID authentication method**. +5. Scroll up and click **Start using OpenID** under the **Authentication method** section. +6. Fill in the following values: + - **OpenID Provider**: authentik + - **OpenID provider URL**: https://authentik.company/application/o/your-application-slug/ + - **Client ID**: Enter the **Client ID** from authentik + - **Client Secret**: Enter the **Client Secret** from authentik + +:::warning +The first user to log into Actual Budget via OpenID will become the owner and administrator with the highest privileges for the budget. For more information on how to create additional users, see the Note below. +::: + +:::info +Users are not created automatically in Actual Budget. The owner must manually add users. To do this, go to **Server online** > **User Directory**, and create users matching their authentik usernames. Then, grant access to the budget via **User Access**. +::: + +## Test the login + +1. Open a browser and navigate to https://actual.company/. +2. Select the OpenID login method in the dropdown menu and click **Sign in with OpenID**. +3. You will be redirected to authentik to complete the login process, then back to Actual Budget. +4. If you reach the budget selection page, the integration is successful. diff --git a/website/integrations/services/actual-budget/index.mdx b/website/integrations/services/actual-budget/index.mdx deleted file mode 100644 index 33644c828165..000000000000 --- a/website/integrations/services/actual-budget/index.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Integrate with Actual Budget -sidebar_label: Actual Budget ---- - -# Actual Budget - -Support level: Community - -## What is Actual Budget - -> Actual Budget is a web-based financial management software. It helps users track and manage their income, expenses, and budgets in real time. -> The software compares actual spending with planned budgets to improve financial decisions. -> -> -- https://actualbudget.org/ -> -> This guide explains how to configure Actual Budget to use authentik as the OAuth provider for logging in to the Web GUI. - -## Preparation - -The following placeholders are used in this guide: - -- `actual.company` is the FQDN of the Actual Budget installation. -- `authentik.company` is the FQDN of the authentik installation. - -## authentik configuration - -[Create](https://docs.goauthentik.io/docs/add-secure-apps/applications/manage_apps#add-new-applications) an OAuth2/OpenID provider and an application in authentik. Use the following parameters for the OAuth2/OpenID provider: - -**Provider:** - -- Name: _SP-actual_ -- Client type: _Confidential_ -- Redirect URIs/Origins (RegEx): https://_actual.company_/openid/callback -- Signing Key: Select any available signing keys. - -:::info -Actual Budget supports the RS256 algorithm. Be aware of this when choosing the appropriate signing key. -::: - -Take note of the Client ID and Client Secret; you will need to provide them to Actual Budget in the last step. - -Leave the remaining values as default. Durations can be adjusted as needed. - -**Application:** - -- Name: _Actual Budget_ -- Slug: _actual_ -- Launch URL: https://_actual.company_/ - -## Actual Budget configuration - -1. Sign in to Actual Budget with a browser of your choice and access your budget by clicking on its name. - -2. Click your budget in the top-left corner to open the dropdown menu and select **Settings**. - -3. Scroll to the bottom and select **Show advanced settings**. Scroll again and select **I understand the risks, show experimental features**. - -4. To enable the option **OpenID authentication method** select the checkbox next to it. - -5. Scroll up to the new option **Authentication method...** and click **Start using OpenID**. - -6. Set the following values from the authentik provider: - - Set **OpenID Provider** to **authentik** - - Set **OpenID provider URL** to https://_authentik.company_/application/o/_actual_/ - - Set **Client ID** to _client-id_ - - Set **Client secret** to _client-secret_ - -:::warning -The first user to log into Actual Budget via OpenID will become the owner and administrator with the highest privileges for the budget. For more information on how to create additional users, see the Note below. -::: - -## Test the login - -- Open a browser of your choice and navigate to https://_actual.company_. -- Select the OpenID login method in the dropdown menu and click **Sign in with OpenID**. -- You should be redirected to authentik (with the login flows you created), and then authentik will redirect you back to the https://_actual.company_ URL. -- If you are redirected back to the https://_actual.company_ URL and can see the budget file selection page, the setup was successful. - -:::info -Users are not automatically created when logging in with authentik. The owner must manually create each user in Actual Budget. To do so, click **Server online** at the top next to your name and select **User Directory**. Add a new user. The `Username` must match the one in authentik. You can now grant the new user access to your budget by clicking **Server online** next to your name at the top and selecting **User Access**. -::: diff --git a/website/integrations/services/apache-guacamole/index.mdx b/website/integrations/services/apache-guacamole/index.mdx index 97d78664c286..aa90868561c4 100644 --- a/website/integrations/services/apache-guacamole/index.mdx +++ b/website/integrations/services/apache-guacamole/index.mdx @@ -13,6 +13,10 @@ sidebar_label: Apache Guacamole™ > > -- https://guacamole.apache.org/ +:::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. +::: + ## Preparation The following placeholders are used in this guide: @@ -20,22 +24,21 @@ 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. -Create an OAuth2/OpenID provider with the following parameters: - -- **Client Type**: `Confidential` -- **Redirect URIs**: `https://guacamole.company/` (depending on your Tomcat setup, you might have to add `/guacamole/` if the application runs in a subfolder) -- **Scopes**: OpenID, Email, and Profile +## authentik configuration -Under **Advanced protocol settings**, set the following: +1. From the **authentik Admin interface**, navigate to **Applications** -> **Applications**. +2. Use the [wizard](https://docs.goauthentik.io/docs/add-secure-apps/applications/manage_apps#add-new-applications) to create a new application and a **OAuth2/OpenID provider**. During this process: + - 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 in a subfolder, you will need to update this value accordingly. + - Select any available signing key. -- **Token validity**: Any value to configure how long the session should last. Guacamole will not accept any tokens valid longer than 300 Minutes. -- **Signing Key**: Set the key as `authentik Self-signed Certificate` +## Apache Guacamole Configuration -Note the Client ID value. Create an application, using the provider you've created above. +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. -## Guacamole - -It is recommended you configure an admin account in Guacamole before setting up SSO to make things easier. Create a user in Guacamole using the username of your user in authentik and give them admin permissions. Without this, you might lose access to the Guacamole admin settings and have to revert the settings below. +:::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. +::: import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; @@ -47,29 +50,43 @@ import TabItem from "@theme/TabItem"; { label: 'Standalone', value: 'standalone' }, ]}> - The Docker containers are configured via environment variables. The following variables are required: + Docker containers are often configured through environment variables. The following variables are required: + + + OPENID_AUTHORIZATION_ENDPOINT=https://authentik.company/application/o/authorize/ + +OPENID_CLIENT_ID=Client ID from authentik + +OPENID_ISSUER=https://authentik.company/application/o/your-slug/ + +OPENID_JWKS_ENDPOINT=https://authentik.company/application/o/your-slug/jwks/ + +OPENID_REDIRECT_URI=https://guacamole.company/ # This must match the Redirect URI set in authentik (including trailing slash). -```yaml -OPENID_AUTHORIZATION_ENDPOINT: https://authentik.company/application/o/authorize/ -OPENID_CLIENT_ID: # client ID from above -OPENID_ISSUER: https://authentik.company/application/o/*Slug of the application from above*/ -OPENID_JWKS_ENDPOINT: https://authentik.company/application/o/*Slug of the application from above*/jwks/ -OPENID_REDIRECT_URI: https://guacamole.company/ # This must match the redirect URI above -OPENID_USERNAME_CLAIM_TYPE: preferred_username -``` +OPENID_USERNAME_CLAIM_TYPE=preferred_username + + - Standalone Guacamole is configured using the `guacamole.properties` file. Add the following settings: + 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: + + + openid-authorization-endpoint=https://authentik.company/application/o/authorize/ openid-client-id=Client ID from authentik + + openid-issuer=https://authentik.company/application/o/your-slug/ + + openid-jwks-endpoint=https://authentik.company/application/o/your-slug/jwks/ -``` -openid-authorization-endpoint=https://authentik.company/application/o/authorize/ -openid-client-id=# client ID from above -openid-issuer=https://authentik.company/application/o/*Slug of the application from above*/ -openid-jwks-endpoint=https://authentik.company/application/o/*Slug of the application from above*/jwks/ -openid-redirect-uri=https://guacamole.company/ # This must match the redirect URI above -openid-username-claim-type=preferred_username -``` + openid-redirect-uri=https://guacamole.company/ # This must match the Redirect URI set in authentik (Including trailing slash). + + openid-username-claim-type=preferred_username + + + +## Configuration verification + +To confirm that authentik is properly configured with Apache Guacamole, log out and log back in via authentik. A new button should have appeared on the bottom left of the login page. diff --git a/website/integrations/services/argocd/index.md b/website/integrations/services/argocd/index.md index 88f248f01b3f..970d39a6a8df 100644 --- a/website/integrations/services/argocd/index.md +++ b/website/integrations/services/argocd/index.md @@ -13,6 +13,10 @@ sidebar_label: ArgoCD > > -- https://argoproj.github.io/cd/ +:::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. +::: + ## Preparation The following placeholders are used in this guide: @@ -26,42 +30,19 @@ Only settings that have been modified from default have been listed. ## authentik Configuration -### Step 1 - Provider creation - -In authentik, create an _OAuth2/OpenID Provider_ (under _Applications/Providers_) with these settings: - -- Name: ArgoCD -- Client Type: `Confidential` -- Signing Key: Select any available key -- Redirect URIs: - -``` -https://argocd.company/api/dex/callback -http://localhost:8085/auth/callback -``` - -After creating the provider, take note of the `Client ID` and `Client Secret`, you'll need to give them to ArgoCD in the _ArgoCD Configuration_ field. - -### Step 2 - Application creation - -Create a new _Application_ (under _Applications/Applications_) with these settings: - -- Name: ArgoCD -- Provider: ArgoCD -- Slug: argocd -- Launch URL: https://argocd.company/auth/login - -### Step 3 - ArgoCD Group creation +### Wizard configuration -Create a new _Group_ (under _Directory/Groups_) that'll be used as the admin group for ArgoCD (if you already have an "admin" group, you can skip this part!) +1. From the **authentik Admin interface**, navigate to **Applications** -> **Applications**. +2. Use the wizard to create a new application and with an **OAuth2/OpenID** provider. During this process: + - Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later. + - Add two `Strict` redirect URIs and set them to `https://argocd.company/api/dex/callback` and `http://localhost:8085/auth/callback`. + - Select any available signing key. -- Name: ArgoCD Admins -- Members: Add your user and/or any user that should be an ArgoCD admin +### ArgoCD group creation -You can create another group for read-only access to ArgoCD as well if desired: +Using the **authentik Admin interface**, go to **Directory** -> **Groups** and click **Create**. ArgoCD lets you to set up administrator users and read-only users by creating groups named `ArgoCD Admins` and `ArgoCD Viewers`. -- Name: ArgoCD Viewers -- Members: Any user that should have ArgoCD read-only access +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. ## Terraform provider diff --git a/website/integrations/services/aruba-orchestrator/index.md b/website/integrations/services/aruba-orchestrator/index.md index a77f65e44051..0da7bb87ac28 100644 --- a/website/integrations/services/aruba-orchestrator/index.md +++ b/website/integrations/services/aruba-orchestrator/index.md @@ -19,39 +19,27 @@ The following placeholders are used in this guide: - `arubaorchestrator.company` is the FQDN of the Aruba Orchestrator installation. - `authentik.company` is the FQDN of the authentik installation. -- `SSL Certificate` is the name of the SSL certificate used to sign outgoing responses. ## authentik Configuration -1. Log in to authentik as an admin, and go to the Admin interface. -2. Create a new SAML Property Mapping under **Customisation** -> **Property Mappings**: - - - **Name**: `Aruba Orchestrator RBAC` - - **SAML Attribute Name**: `sp-roles` - - **Expression**: Use the expression below but amend the group name as desired. - - ``` - if ak_is_group_member(request.user, name="authentik Admins"): - result = "superAdmin" - return result - ``` - - - Save the settings. - -3. Create a new SAML Provider under **Applications** -> **Providers** using the following settings: - - **Name**: Aruba Orchestrator - - **Authentication Flow**: Use your preferred authentication flow (e.g., default-authentication-flow`) - - **Authorization Flow ID**: `default-provider-authorization-explicit-consent (Authorize Application)` - - Protocol settings: - - - **ACS URL**: `https://arubaorchestrator.company/gms/rest/authentication/saml2/consume` - - - **Issuer**: `https://arubaorchestrator.company/gms/rest/authentication/saml2/consume` - - - **Service Provider Binding**: Post - - Advanced protocol settings: - - - **Signing Certificate**:`SSL Certificate` - - - **Property Mappings**:`default` + `sp-roles` - - Leave everything else as default and save the settings. -4. Download the signing certificate under **Applications** -> **Providers** -> **Aruba Orchestrator** . -5. Create a new application under **Applications** -> **Applications**, pick a name and a slug, and assign the provider that you have just created. +1. From the **authentik Admin interface** and go to **Customization** -> **Property Mappings**, then click **Create**. +2. Choose **SAML Provider Property Mapping**, and click **Next**. +3. Configure the following: + - Set **Name** to `Aruba Orchestrator RBAC`. + - Set **SAML Attribute Name** to `sp-roles`. + - Add the expression below, modifying the group name if necessary: + ```python + if ak_is_group_member(request.user, name="authentik Admins"): + result = "superAdmin" + return result + ``` +4. When satisfied with the expression, click **Create**. +5. Navigate to **Applications** -> **Applications** in the **authentik Admin interface**, and create a new application with a **SAML** provider using the wizard. During the setup: + - Set the **ACS URL** and **Issuer** to `https://arubaorchestrator.company/gms/rest/authentication/saml2/consume`. + - Choose `Post` for the **Service Provider Binding**. + - Under **Advanced protocol settings**, select an available signing certificate. + - Add the `sp-roles` property mapping under the **Proprety Mappins** section of **Advanced protocol settings**. +6. Go to **Applications** -> **Providers** -> **Provider for _Your application name_**, and download the signing certificate. ## Aruba Orchestrator Configuration diff --git a/website/integrations/services/aws/index.md b/website/integrations/services/aws/index.md index c031e19a45f6..b18ab382a3b0 100644 --- a/website/integrations/services/aws/index.md +++ b/website/integrations/services/aws/index.md @@ -13,138 +13,105 @@ sidebar_label: Amazon Web Services > > -- https://www.aboutamazon.com/what-we-do/amazon-web-services -## Select your method +## Choose Your Integration Method -There are two ways to perform the integration: the classic IAM SAML way, or the 'newer' IAM Identity Center way. This all depends on your preference and needs. +There are two primary methods to integrate authentik with AWS: -## Method 1: Classic IAM +1. **Classic IAM (SAML)** – The traditional method of integrating using SAML-based authentication. +2. **IAM Identity Center (AWS SSO)** – A newer, simplified method for managing user access. -### Preparation +## Method 1: Classic IAM (SAML Integration) -Create an application in authentik and note the slug, as this will be used later. Create a SAML provider with the following parameters: +### authentik Configuration -- **ACS URL**: `https://signin.aws.amazon.com/saml` -- **Issuer**: `authentik` -- **Binding**: `Post` -- **Audience**: `urn:amazon:webservices` +1. **Create an Application**: Create an application in authentik and note the **slug**, which will be used later. +2. **Create a SAML Provider**: Set up a SAML provider with these configurations: -You can use a custom signing certificate and adjust durations as needed. + - **ACS URL**: `https://signin.aws.amazon.com/saml` + - **Issuer**: `authentik` + - **Binding**: `Post` + - **Audience**: `urn:amazon:webservices` + You can choose a custom signing certificate and adjust duration settings as necessary. !!!!!TODO WIZARD -### AWS - -Create a role with the permissions you desire, and note the ARN. - -After configuring the Property Mappings, add them to the SAML Provider in AWS. - -Create an application, assign policies, and assign this provider. - -Export the metadata from authentik and create a new Identity Provider [here](https://console.aws.amazon.com/iam/home#/providers). +3. **Configure Property Mappings**: Customize property mappings as needed for your AWS integration. #### Role Mapping -The Role mapping specifies the AWS ARN(s) of the identity provider, and the role the user should assume ([see](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_role-attribute)). +!!!!!TODO: WHERE/HOW -This Mapping needs to have the SAML Name field set to `https://aws.amazon.com/SAML/Attributes/Role`. +The **Role Mapping** specifies the AWS ARN(s) of the identity provider and the role the user should assume. Set the **SAML Name** field to `https://aws.amazon.com/SAML/Attributes/Role`. Below are several examples for role mapping: -As expression, you can return a static ARN like so +- **Static ARN Mapping**: -```python -return "arn:aws:iam::123412341234:role/saml_role,arn:aws:iam::123412341234:saml-provider/authentik" -``` + ```python + return "arn:aws:iam::123412341234:role/saml_role,arn:aws:iam::123412341234:saml-provider/authentik" + ``` -Or, if you want to assign AWS Roles based on Group membership, you can add a custom attribute to the Groups, for example "aws_role", and use this snippet below. Groups are sorted by name and later groups overwrite earlier groups' attributes. +- **Role Mapping 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" -``` - -If you want to allow a user to choose from multiple roles, use this snippet - -```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", -] -``` + ```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" + ``` -### RoleSessionName Mapping +- **Multiple Role Mapping**: -The RoleSessionMapping specifies what identifier will be shown at the top of the Management Console ([see](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_role-session-attribute)). + ```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", + ] + ``` -This mapping needs to have the SAML Name field set to `https://aws.amazon.com/SAML/Attributes/RoleSessionName`. +#### Role Session Name Mapping -To use the user's username, use this snippet +The **RoleSessionName Mapping** defines the name shown in the AWS Management Console. Set the **SAML Name** field to `https://aws.amazon.com/SAML/Attributes/RoleSessionName`. To use the user's username, use this expression: ```python return user.username ``` -## Method 2: IAM Identity Center - -### Preparation - -- A certificate to sign SAML assertions is required. You can use authentik's default certificate, or provide/generate one yourself. -- You may pre-create an AWS application. - -### How to integrate with AWS - -In AWS: - -- In AWS, navigate to: **IAM Identity Center -> Settings -> Identity Source (tab)** -- On the right side, click **Actions** -> **Change identity source** -- Select **External Identity Provider** -- Under **Service Provider metadata** download the metadata file. +### AWS Configuration -Now go to your authentik instance, and perform the following steps. +1. **Create a Role**: In AWS, create a role with the desired permissions, and note its **ARN**. !!!!!TODO: HOW +2. **Identity Provider**: Export the metadata from authentik and create a new Identity Provider in AWS by visiting [IAM Providers](https://console.aws.amazon.com/iam/home#/providers). +3. **Property Mappings**: After creating the role, ensure that the property mappings from authentik are applied correctly in AWS. -- Under **Providers**, create a new **SAML Provider from metadata**. Give it a name, and upload the metadata file AWS gave you. -- Click **Next**. Give it a name, and close the file. -- If you haven't done so yet, create an application for AWS and connect the provider to it. -- Navigate to the provider you've just created, and then select **Edit** -- Copy the **Issuer URL** to the **Audience** field. -- Under **Advanced Protocol Settings** set a **Signing Certificate** -- Save and Close. -- Under **Related Objects**, download the **Metadata file** and the **Signing Certificate** +For further instructions, refer to the [AWS IAM Documentation on SAML](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html). -Now go back to your AWS instance +## Method 2: IAM Identity Center (AWS SSO) -- Under **Identity provider metadata**, upload both the **Metadata** file and **Signing Certificate** that authentik gave you. -- Click **Next**. -- In your settings pane, under the tab **Identity Source**, click **Actions** -> **Manage Authentication**. -- Note the AWS access portal sign-in URL (especially if you have customized it). +### authentik Configuration -Now go back to your authentik instance. +1. **Create a SAML Provider**: In authentik, navigate to **Providers**, click **Create**, and select **SAML Provider from metadata**. Upload the metadata file provided by AWS. +2. **Configure the Provider**: Set the **Audience** field to the **Issuer URL** from AWS. Under **Advanced Protocol Settings**, configure the **Signing Certificate**. +3. **Download Metadata and Certificate**: After setting up, download the **Metadata file** and **Signing Certificate**. !!!!!TODO WIZARD -- Navigate to the Application that you created for AWS and click **Edit**. -- Under **UI Settings** make sure the **Start URL** matches the **AWS access portal sign-in URL**. +For more detailed steps, refer to [AWS IAM Identity Center Federation Setup](https://docs.aws.amazon.com/singlesignon/latest/userguide/federation.html). -:::::info +### AWS Configuration -- Ensure users already exist in AWS for authentication through authentik. AWS will throw an error if the user is unrecognized. -- In case you're stuck, you can see the SSO logs in Amazon CloudTrail -> Event History. Look for `ExtenalIdPDirectoryLogin`. - ::::: +1. **Change Identity Source**: In AWS, !!!!!TODO FROM THE MAIN DASH go to **IAM Identity Center -> Settings -> Identity Source (tab)**. Click **Actions** -> **Change identity source** and choose **External Identity Provider**. +2. **Upload Metadata and Certificate**: Upload both the **Metadata file** and **Signing Certificate** from authentik into AWS. +3. **Authentication Settings**: In AWS, under **IAM Identity Center -> Settings**, click **Manage Authentication**. Note the AWS access portal sign-in URL. -## Optional: Automated provisioning with SCIM +For more on configuring AWS, refer to [AWS IAM Identity Center Documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/identity-source.html). -Some people may opt to use the automatic provisioning feature called SCIM (System for Cross-domain Identity Management). -SCIM allows you to synchronize (part of) your directory to AWS's IAM, saving you the hassle of having to create users by hand. -To do so, take the following steps in your AWS Identity Center: +## Optional: SCIM for Automated Provisioning -- In your **Settings** pane, locate the **Automatic Provisioning** information box. Click **Enable**. -- AWS provides an SCIM Endpoint and an Access Token. Note these values. +SCIM (System for Cross-domain Identity Management) allows you to automate the synchronization of users, groups, and attributes between authentik and AWS. -Go back to your authentik instance +### authentik Configuration -- Navigate to **Providers** -> **Create** +Navigate to **Providers** -> **Create** - Select **SCIM Provider** - Give it a name, under **URL** enter the **SCIM Endpoint**, and then under **Token** enter the **Access Token** AWS provided you with. - Optionally, change the user filtering settings to your liking. Click **Finish** - Go to **Customization -> Property Mappings** - Click **Create -> SCIM Mapping** -- Make sure to give the mapping a name that's lexically lower than `authentik default`, for example `AWS SCIM User mapping` +- Make sure to give the mapping a name that's lexically lower THE WHAT? than `authentik default`, for example `AWS SCIM User mapping` - As the expression, enter: ```python @@ -154,13 +121,25 @@ return { "photos": None, } ``` +1. **Enable SCIM**: In AWS, navigate to **Settings** and enable **Automatic Provisioning**. AWS will provide the **SCIM Endpoint** and **Access Token**. +2. **Sync Users**: Once configured, the SCIM provider will automatically sync users and groups between authentik and AWS IAM. You can trigger manual sync by going to the SCIM provider and clicking **Run sync again**. - Click **Save**. Navigate back to your SCIM provider, click **Edit** - Under **User Property Mappings** select the default mapping and the mapping that you just created. - Click **Update** +For more on SCIM, refer to the [AWS SCIM Documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/scim.html). -- Navigate to your application, click **Edit**. -- Under **Backchannel providers** add the SCIM provider that you created. -- Click **Update** +### AWS Configuration + +1. **Enable SCIM**: In AWS, navigate to **Settings** and enable **Automatic Provisioning**. AWS will provide the **SCIM Endpoint** and **Access Token**. +2. **Sync Users**: Once configured, the SCIM provider will automatically sync users and groups between authentik and AWS IAM. You can trigger manual sync by going to the SCIM provider and clicking **Run sync again**. + +For more on SCIM, refer to the [AWS SCIM Documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/scim.html). + +:::info +Ensure users already exist in AWS for successful authentication via authentik. AWS will throw an error if the user is not found. !!!!!TODO THIS IS TECHNICALLY A DIFFERENT THING For troubleshooting, check Amazon CloudTrail logs for `ExternalIdPDirectoryLogin`. +::: + +!!!!!TODO VERIFICIATION STEP -The SCIM provider syncs automatically whenever you create/update/remove users, groups, or group membership. You can manually sync by going to your SCIM provider and clicking **Run sync again**. After the SCIM provider has synced, you should see the users and groups in your AWS IAM center. +ADD The SCIM provider syncs automatically whenever you create/update/remove users, groups, or group membership. You can manually sync by going to your SCIM provider and clicking **Run sync again**. After the SCIM provider has synced, you should see the users and groups in your AWS IAM center. diff --git a/website/integrations/services/fortimanager/index.md b/website/integrations/services/fortimanager/index.md index a5a239e2340a..22ac07731a16 100644 --- a/website/integrations/services/fortimanager/index.md +++ b/website/integrations/services/fortimanager/index.md @@ -9,9 +9,7 @@ sidebar_label: FortiManager ## What is FortiManager -> FortiManager supports network operations use cases for centralized management, best practices compliance, and workflow automation to provide better protection against breaches. -> -> FortiManager is a paid enterprise product. +> FortiManager is an enterprise solution that enables centralized network management, ensures compliance with best practices, and automates workflows to enhance breach protection. > > -- https://www.fortinet.com/products/management/fortimanager @@ -19,41 +17,27 @@ sidebar_label: FortiManager The following placeholders are used in this guide: -- `fgm.company` is the FQDN of the FortiManager installation. +- `fortimanager.company` is the FQDN of the FortiManager installation. - `authentik.company` is the FQDN of the authentik installation. -Create an application and Provider in authentik, note the slug, as this will be used later. Create a SAML provider with the following parameters: - -Provider: - -- ACS URL: `https://fgm.company/saml/?acs` -- Issuer: `https://authentik.company/application/saml/fgm/sso/binding/redirect/` -- Service Provider Binding: Post - -You can of course use a custom signing certificate, and adjust durations. +## authentik Configuration -Application: - -- Launch URL: 'https://fgm.company/p/sso_sp/' +1. From the **authentik Admin interface**, navigate to **Applications** -> **Applications**. +2. Use the [wizard](https://docs.goauthentik.io/docs/add-secure-apps/applications/manage_apps#add-new-applications) to create a new application and a **SAML provider**. During this process: + - Note the **slug** as it will be required later. + - Set the **ACS URL** to https://fortimanager.company/saml/?acs. + - Set the **Issuer** to https://authentik.company/application/saml/application-slug/sso/binding/redirect/. + - Set the **Service Provider Binding** to `Post`. ## FortiManager Configuration -Navigate to `https://fgm.company/p/app/#!/sys/sso_settings` and select SAML SSO settings to configure SAML. - -Select 'Service Provider (SP)' under Single Sign-On Mode to enable SAML authentication. - -Set the Field 'SP Address' to the FortiManager FQDN 'fgm.company'. (This gives you the URLs to configure in authentik) - -Set the Default Login Page to either 'Normal' or 'Single-Sign On'. (Normal allows both local and SAML authentication vs only SAML SSO) - -FortiManager create a new user by default if one does not exist so you will need to set the Default Admin Profile to the permissions you want any new users to have. (We created a no_permissions profile to assign by default) - -Set the Field 'IdP Type' to 'Custom' - -Set the Field `IdP entity ID` to `https://authentik.company/application/saml/fgm/sso/binding/redirect/`. - -Set the Field `IdP Login URL` to `https://authentik.company/application/saml/fgm/sso/binding/redirect/`. - -Set the Field `IdP Logout URL` to `https://authentik.company/` - -For the Field 'IdP Certificate" Import your authentik cert. (Self Signed or real) +1. Navigate to https://fortimanager.company/p/app/#!/sys/sso_settings and select **SAML SSO Settings** to configure SAML. +2. Under **Single Sign-On Mode**, choose **Service Provider (SP)** to enable SAML authentication. +3. Set the **SP Address** field to the FortiManager FQDN, fortimanager.company. This provides the URLs needed for configuration in authentik. +4. Choose the **Default Login Page** as either **Normal** or **Single Sign-On**. Selecting **Normal** allows both local and SAML authentication, while **Single Sign-On** restricts login to SAML only. +5. By default, FortiManager creates a new user if one does not exist. Set the **Default Admin Profile** to assign the desired permissions to new users. A `no_permissions` profile is created by default for this purpose. +6. Set the **IdP Type** field to **Custom**. +7. For the **IdP Entity ID** field, enter: https://authentik.company/application/saml/application-slug/sso/binding/redirect/ +8. Set the **IdP Login URL** to: https://authentik.company/application/saml/application-slug/sso/binding/redirect/ +9. Set the **IdP Logout URL** to: https://authentik.company/ +10. In the **IdP Certificate** field, import your authentik certificate (either self-signed or valid). diff --git a/website/integrations/services/frappe/index.md b/website/integrations/services/frappe/index.md index 1a671615b67f..7f036077d973 100644 --- a/website/integrations/services/frappe/index.md +++ b/website/integrations/services/frappe/index.md @@ -25,65 +25,63 @@ The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. - `provider` is the name for the social login provider in Frappe. -## authentik configuration +:::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. +::: -1. Log in to authentik as an admin, and go to the Admin interface. -2. Create a new OAuth2/OpenID Provider under **Applications** -> **Providers** using the following settings: +## authentik configuration - - **Name**: Frappe - - **Client type**: Confidential - - **Client ID**: Use the auto-populated ID - - **Client Secret**: Use the auto-populated secret - - **Redirect URIs/Origins (RegEx)**: - - `https://frappe.company/api/method/frappe.integrations.oauth2_logins.custom/provider` - - **Scopes**: `email`, `openid`, `profile` - - **Subject mode**: `Based on the Users's username` - - **Include claims in id_token**: `True` - - Leave everything else as default +1. From the **authentik Admin interface**, navigate to **Applications** -> **Applications**. +2. Use the [wizard](https://docs.goauthentik.io/docs/add-secure-apps/applications/manage_apps#add-new-applications) to create a new application and a **OAuth2/OpenID Connect provider**. During this process: + - 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`. - Take note of **Client ID** and **Client Secret** as you will need them later. +## Frappe configuration -3. Create a new application under **Applications** -> **Applications**, pick a name and a slug, and assign the provider that you have just created. +1. **Navigate to Integrations** -## Frappe configuration + - From the Frappe main menu, go to **Integrations** and then select **Social Login Key**. -1. From the Frappe main menu, navigate to **Integrations**, then to **Social Login Key**. +2. **Add a New Social Login Key** -Add a new Social login Key using the black button on top right. -![](./frappe1.png) + - Click the black **+ New** button in the top-right corner. + ![](./frappe1.png) -2. Enter the following settings: +3. **Enter the Required Settings** - - In the **Client Credentials** section: - - Enable Social Login: Turn the checkmark to the _on_ position. - - Client ID: _client-id-from-authentik_ - - Client Secret: _client-secret-from-authentik_ + - **Client Credentials** - - In the **Configuration** section: - - Sign ups: Allow + - **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. - ![](./frappe2.png) + - **Configuration** - - In the **Identity Details** section: - - Base URL: `https://authentik.company/` - - In Client URLs section: - - 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/` + - **Sign-ups**: Set to **Allow**. + ![](./frappe2.png) - ![](./frappe3.png) + - **Identity Details** - - In the **Client Information** section: - - Auth URL Data: `{"response_type": "code", "scope": "email profile openid"}` + - **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/` + ![](./frappe3.png) - ![](./frappe4.png) + - **Client Information** + - **Auth URL Data**: + ```json + { "response_type": "code", "scope": "email profile openid" } + ``` + ![](./frappe4.png) -3. Press the black **Save** button on the top right. +4. **Save the Configuration** + - Click the black **Save** button in the top-right corner to complete the setup. ## Verification -1. Go to `https://frappe.company` from Incognito mode. -2. Click **Login with provider** on the login screen. -3. Authorize with authentik. -4. You will be redirected to home screen of Frappe application. +First, open an incognito browser window and go to `https://frappe.company`. On the login screen, click **Login with Provider**. You will be redirected to authentik to enter your credentials and to authorize the application. Once that's done, you will be redirected to the home screen of the Frappe application, confirming the successful login. diff --git a/website/integrations/services/freshrss/index.md b/website/integrations/services/freshrss/index.md index 0937c6173a5d..32d30c52367e 100644 --- a/website/integrations/services/freshrss/index.md +++ b/website/integrations/services/freshrss/index.md @@ -18,52 +18,43 @@ sidebar_label: FreshRSS The following placeholders are used in this guide: - `freshrss.company` is the FQDN of the FreshRSS installation. -- `port` is the port on which the FreshRSS install is running (usually 443) - `authentik.company` is the FQDN of the authentik installation. +:::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 -1. Create an **OAuth2/OpenID Provider** under **Applications** > **Providers** using the following settings: - - - **Name**: FreshRSS - - **Authorization flow**: default-provider-authorization-explicit-consent - - **Protocol Settings**: - - **Client Type**: Confidential - - **Client ID**: Either create your own Client ID or use the auto-populated ID - - **Client Secret**: Either create your own Client Secret or use the auto-populated secret - :::note - Take note of the `Client ID` and `Client Secret`, you'll need them later. - ::: - - **Redirect URIs/Origins**: - - `https://freshrss.company/i/oidc/` - - `https://freshrss.company:port/i/oidc` - - **Signing Key**: Any of your signing keys - - Leave everything else as default - -2. Create an **Application** under **Applications** > **Applications** using the following settings: - - **Name**: FreshRSS - - **Slug**: freshrss - - **Provider**: FreshRSS _(the provider you created in step 1)_ - - Leave everything else as default +1. From the **authentik Admin interface**, navigate to **Applications** -> **Applications**. +2. Use the [wizard](https://docs.goauthentik.io/docs/add-secure-apps/applications/manage_apps#add-new-applications) to create a new application and a **OAuth2/OpenID Connect provider**. During this process: + - 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://freshrss.company/i/oidc/ and https://freshrss.company:443/i/oidc/. If FreshRSS is exposed on a port other than `443`, update the second redirect URI accordingly. + - Select any available signing key. ## FreshRSS configuration -:::info -This integration only works with the Docker or Kubernetes install of FreshRSS, using [FreshRSS docker image](https://hub.docker.com/r/freshrss/freshrss/), on x86_64 systems and without the Alpine version of the image. More information can be found on [this issue on FreshRSS GitHub](https://github.com/FreshRSS/FreshRSS/issues/5722) +:::info +This integration is compatible only with Docker or Kubernetes installations of FreshRSS that use the [FreshRSS Docker image](https://hub.docker.com/r/freshrss/freshrss/) on x86_64 systems. Note that the Alpine version of the image is not supported. For more details, see [this issue on the FreshRSS GitHub repository](https://github.com/FreshRSS/FreshRSS/issues/5722). ::: -Add those environment variables to your _Docker_ image : +To enable OIDC login with FreshRSS, update your `.env` file with the following variables: -- `OIDC_ENABLED` : `1` -- `OIDC_PROVIDER_METADATA_URL` : `https://authentik.company/application/o//.well-known/openid-configuration` replacing `` with the slug of your created application -- `OIDC_CLIENT_ID` : the client ID of your provider -- `OIDC_CLIENT_SECRET` : the client secret of your provider -- `OIDC_X_FORWARDED_HEADERS` : `X-Forwarded-Port X-Forwarded-Proto X-Forwarded-Host` -- `OIDC_SCOPES` : `openid email profile` +``` +OIDC_ENABLED=1 +OIDC_PROVIDER_METADATA_URL=https://authentik.company/application/o/application-slug/.well-known/openid-configuration +OIDC_CLIENT_ID=Your Client ID +OIDC_CLIENT_SECRET=Your Client Secret +OIDC_X_FORWARDED_HEADERS=X-Forwarded-Port X-Forwarded-Proto X-Forwarded-Host +OIDC_SCOPES=openid email profile +``` + +:::warning +Before restarting your Docker container, ensure that at least one Admin user in your FreshRSS instance has a username that matches an authentik user. +::: -Before restarting your Docker container, ensure that one of the Admin users of your FreshRSS instance has the same login as one of your Authentik user. +Restart your FreshRSS container, then log in as a user that exists in both FreshRSS and authentik. -Restart your FreshRSS container, and login as a user that exists on both FreshRSS and your Authentik. -Navigate to _Settings_ > _Authentication_ in your FreshRSS instance, and choose as an authentication method _HTTP (for advanced users with HTTPS)_ +Go to **Settings** -> **Authentication** in your FreshRSS instance and set the authentication method to **HTTP**. -You can find additional information on [FreshRSS documentation](https://freshrss.github.io/FreshRSS/en/admins/16_OpenID-Connect.html) +Additional configuration options can be found in the [FreshRSS documentation for OpenID Connect](https://freshrss.github.io/FreshRSS/en/admins/16_OpenID-Connect.html). diff --git a/website/integrations/services/gatus/index.md b/website/integrations/services/gatus/index.md index 2d90ecff73cc..6f7bb6d7b598 100644 --- a/website/integrations/services/gatus/index.md +++ b/website/integrations/services/gatus/index.md @@ -9,7 +9,7 @@ sidebar_label: Gatus ## What is Gatus? -> Gatus is a free and open source project for endpoint monitoring. It allows many types of monitoring from pings or http requests to DNS checking and certification expiration. This is all done through yaml files. +> Gatus is a developer-oriented health dashboard that gives you the ability to monitor your services using HTTP, ICMP, TCP, and even DNS queries as well as evaluate the result of said queries by using a list of conditions on values like the status code, the response time, the certificate expiration, the body and many others. The icing on top is that each of these health checks can be paired with alerting via Slack, Teams, PagerDuty, Discord, Twilio and many more. > > -- https://github.com/TwiN/gatus @@ -20,29 +20,31 @@ The following placeholders are used in this guide: - `gatus.company` is the FQDN of the Gatus installation. - `authentik.company` is the FQDN of the authentik installation. -## authentik configuration - -Create an OIDC provider with the following settings: +:::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. +::: -- Name: 'gatus' -- Redirect URL: 'https://gatus.company/authorization-code/callback' +## authentik configuration -Everything else is up to you and what you want, just don't forget to grab the client ID and secret! +1. From the **authentik Admin interface**, navigate to **Applications** -> **Applications**. +2. Use the [wizard](https://docs.goauthentik.io/docs/add-secure-apps/applications/manage_apps#add-new-applications) to create a new application and a **OAuth2/OpenID Connect provider**. During this process: + - Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later. + - Set a `Strict` redirect URI to https://gatus.company/authorization-code/callback/. ## Gatus configuration -In the `config.yaml` file of Gatus, add the following: +To enable OIDC in Gatus, add the following configuration to the `config.yaml` file. This file is usually located at `/config/config.yaml` or in the path specified by the `GATUS_CONFIG_PATH` environment variable: ```yml security: oidc: - issuer-url: https://authentik.company/application/o/gatus/ - client-id: "CLIENT_ID" - client-secret: "CLIENT_SECRET" - redirect-url: https://gatus.company/authorization-code/callback + issuer-url: https://authentik.company/application/o/your-slug/ + client-id: "Your Client ID" + client-secret: "Your Client Secret" + redirect-url: https://gatus.company/authorization-code/callback scopes: [openid] ``` :::note -Gatus auto-updates the configuration about every 30 seconds. However, if it does not pick up the changes, just restart the instance. +Gatus automatically updates its configuration approximately every 30 seconds. If the changes are not reflected, restart the instance to ensure the changes are applied. ::: diff --git a/website/integrations/services/zulip/index.md b/website/integrations/services/zulip/index.md index 389e1ba302ef..3a9756c7017d 100644 --- a/website/integrations/services/zulip/index.md +++ b/website/integrations/services/zulip/index.md @@ -9,8 +9,7 @@ sidebar_label: Zulip ## What is Zulip -> **Zulip**: Chat for distributed teams. Zulip combines the immediacy of real-time chat with an email threading model. -> With Zulip, you can catch up on important conversations while ignoring irrelevant ones. +> 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 @@ -19,7 +18,7 @@ sidebar_label: Zulip The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -- `zulip.company` is the FQDN of the Zulip instance. +- `zulip.company` is the FQDN of the Zulip installation. Create an application in authentik and note the slug, as this will be used later. Create a SAML provider with the following parameters: