Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

website/integrations: Update to Wizard and Styling Guide #12919

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

website/integrations: Update to Wizard and Styling Guide #12919

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
46691f4
update to Wizard and Styling Guide
nicedevil007 Feb 2, 2025
c3d2879
Ready for PR
nicedevil007 Feb 2, 2025
826716c
remove changes on actual budget
nicedevil007 Feb 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 0 additions & 95 deletions website/integrations/services/engomo/index.md
View file
Open in desktop

This file was deleted.

87 changes: 87 additions & 0 deletions website/integrations/services/engomo/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
Copy link
Contributor

@dominic-r dominic-r Feb 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the engomo documentation renamed to use a mdx file? No React components are being used. It doesn't really matter that much as it shows up in the UI the same, I'm just curious. I'll be sure to outline this in the style guide!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thought this is the right format nowadays, so I used the update to get to this file extension as well. Was the one I took on most of my other PRs as well. Just to be honest, I never thought about it what is the right or wrong one. Just wanted to make everything similar 🙈

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makese sense 🤣

title: Integrate with engomo
sidebar_label: engomo
---

# Integrate with engomo

<span class="badge badge--secondary">Support level: Community</span>

## 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.
- `engomo.mapping` is the name of the Scope Mapping.

:::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

In authentik, create a new scope mapping. To do so, log in and navigate to the Admin interface, then go to **Customization --> Property Mapping** and click **Create**.

- `engomo.mapping` is the value of the Mapping's name.
- `profile` is the value for the Scope name.
- `return {"preferred_username": request.user.email}` is the value for the Expression.

[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:

1. In the authentik Admin interface, navigate to **Applications** -> **Applications**.
2. Use the wizard to create a new application and provider. During this process:
- Note the **Client ID**, **Client Secret**, and **slug** values for later use.
- Select implicit or explicit authorization flow as desired.
- Set Client type to `Public`.
- Set the redirect URI to <kbd>https://<em>engomo.company</em>/auth</kbd> and <kbd>com.engomo.engomo://callback/</kbd>.
- Select any available signing key.
- Add the `engomo.mapping` scope in addition to the default values.

:::note
Redirect URIs => write the values line by line.
:::

## engomo configuration

Navigate to <kbd>https://<em>engomo.company</em>/composer</kbd> 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 <kbd>https://<em>authentik.company</em>/application/o/<em>engomo</em></kbd>.
- 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 <kbd>https://<em>engomo.company</em>/composer</kbd> 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 <kbd>https://<em>engomo.company</em></kbd>.
- 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 <kbd>https://<em>engomo.company</em>/composer</kbd> URL.
- If you are redirected back to the <kbd>https://<em>engomo.company</em>/composer</kbd> 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.
:::
35 changes: 18 additions & 17 deletions website/integrations/services/rustdesk-pro/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ sidebar_label: RustDesk Server Pro
> Ideal for businesses, it provides full control over data while ensuring scalable and reliable remote access.
>
> -- https://rustdesk.com/
>
> This guide explains how to configure Rustdesk Server Pro to use authentik as the OAuth provider for logging in to the Web GUI.
Copy link
Contributor

@dominic-r dominic-r Feb 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This added sentence is not part of the integration template.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was a line on all my other docs why I added it here now as well. As I started making docs for authentik I just copied anyone else others doc from a different app and started from this point 😂

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

haha yea I get it. I can't say I never did the same with some stuff. I'm just trying to standardize existing documentation to get a good base. That means a lot of cleanup, yes, but I think it's for the good. The sentence itself is a good idea, but I feel like it's already implied if you get what I mean

Copy link
Contributor Author

@nicedevil007 nicedevil007 Feb 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So if the most recent template is the best I can start; then I can start from scratch before you review the rest from here and then having to review it again. I'm absolutely on your side on standardizing stuff. That was sometimes a problem here for me. Started first PRs with fortigate stuff here then I copy pasted my old Fortigate guide and used it as my template for next PR, then stuff told me to use on FGT wasn't good anymore 😂 will do my best to keep this docs here as you want 👌


## Preparation

Expand All @@ -28,39 +30,38 @@ This documentation lists only the settings that you need to change from their de

## 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:

1. In the authentik Admin interface, navigate to **Applications** -> **Applications**.
2. Use the wizard to create a new application and provider. During this process:
- Note the **Client ID**, **Client Secret**, and **slug** values for later use.
- Set the redirect URI to https://_rustdesk.company_/api/oidc/callback.
- Select implicit or explicit authorization flow as desired.
- Set the redirect URI to <kbd>https://<em>rustdesk.company</em>/api/oidc/callback</kbd>.
- Select any available signing key.

## RustDesk Server Pro configuration

1. Sign in to RustDesk Server Pro using a browser.

2. In the left menu, select **Settings** and then **OIDC**.

3. Click **+ New Auth Provider**.

4. In the popup window, select **custom** as the **Auth Type** and click **OK**.

5. Configure the following values using information from the authentik provider:
- **Name**: _SSO-Login_
- **Client ID**: _client-id_
- **Client Secret**: _client-secret_
- **Issuer**: https://_authentik.company_/application/o/_slug_/
- **Authorization Endpoint**: https://_authentik.company_/application/o/authorize/
- **Token Endpoint**: https://_authentik.company_/application/o/token/
- **Userinfo Endpoint**: https://_authentik.company_/application/o/userinfo/
- **JWKS Endpoint**: https://_authentik.company_/application/o/_slug_/jwks/
- Set **Name** to `authentik`
- Set **Client ID** to the Client ID copied from authentik.
- Set **Client secret** to the Client Secret copied from authentik.
- Set **Issuer** to <kbd>https://<em>authentik.company</em>/application/o/<em>slug</em>/</kbd>
- Set **Authorization Endpoint** to <kbd>https://<em>authentik.company</em>/application/o/authorize/</kbd>
- Set **Token Endpoint** to <kbd>https://<em>authentik.company</em>/application/o/token/</kbd>
- Set **Userinfo Endpoint** to <kbd>https://<em>authentik.company</em>/application/o/userinfo/</kbd>
- Set **JWKS Endpoint** to <kbd>https://<em>authentik.company</em>/application/o/<em>slug</em>/jwks/</kbd>

:::info
Users are created automatically on login. Permissions must be assigned by an administrator after user creation.
:::

## Test the Login

- Open a browser and navigate to https://_rustdesk.company_.
- Click **Continue with SSO-Login**.
- You should be redirected to authentik (with the login flows you configured). After logging in, authentik will redirect you back to https://_rustdesk.company_.
- If you are redirected back to https://_rustdesk.company_ and can read the username in the top right corner, the setup was successful.
- Open a browser and navigate to <kbd>https://<em>rustdesk.company</em></kbd>.
- Click **Continue with authentik**.
- You should be redirected to authentik (with the login flows you configured). After logging in, authentik will redirect you back to <kbd>https://<em>rustdesk.company</em></kbd>.
- If you are redirected back to <kbd>https://<em>rustdesk.company</em></kbd> and can read the username in the top right corner, the setup was successful.
37 changes: 11 additions & 26 deletions website/integrations/services/semaphore/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,27 +28,14 @@ This documentation lists only the settings that you need to change from their de

## authentik configuration

Start the wizard for adding a new application.
[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:

**1. Application:**

- Name: `Semaphore UI`
- Slug: `semaphore`

**2. Choose a Provider**

Select `OAuth2/OpenID Provider`

**3. Configure Provider**

Select implicit or explicit authorization flow as desired.

Take note of the Client ID and Client Secret, you'll need to give them to Semaphore UI later.

- Redirect URIs/Origins (RegEx): `https://semaphore.company/api/auth/oidc/authentik/redirect/`
- Signing Key: `authentik Self-signed Certificate`

Leave the rest as default values.
1. In the authentik Admin interface, navigate to **Applications** -> **Applications**.
2. Use the wizard to create a new application and provider. During this process:
- Note the **Client ID**, **Client Secret**, and **slug** values for later use.
- Select implicit or explicit authorization flow as desired.
- Set the redirect URI to <kbd>https://<em>semaphore.company</em>/api/auth/oidc/authentik/redirect/</kbd>.
- Select any available signing key.

## Semaphore UI configuration

Expand All @@ -60,7 +47,7 @@ Add the `oidc_providers` configuration:
{
"oidc_providers": {
"authentik": {
"display_name": "Sign in with Authentik",
"display_name": "Sign in with authentik",
"provider_url": "https://authentik.company/application/o/<slug>/",
"client_id": "<client-id>",
"client_secret": "<client-secret>",
Expand Down Expand Up @@ -89,14 +76,12 @@ SEMAPHORE_WEB_ROOT: /

More information on this can be found in the Semaphore documentation https://docs.semaphoreui.com/administration-guide/openid/authentik/.

Leave the rest as default.

## Test the login

- Open a browser of your choice and open the URL `https://semaphore.company`.
- Open a browser of your choice and open the URL <kbd>https://<em>semaphore.company</em></kbd>.
- Click on the SSO-Login button.
- You should be redirected to authentik (with the login flows you created) and then authentik should redirect you back to `https://semaphore.company` URL.
- If you are redirected back to the `https://semaphore.company` URL you did everything correct.
- You should be redirected to authentik (with the login flows you created) and then authentik should redirect you back to <kbd>https://<em>semaphore.company</em></kbd> URL.
- If you are redirected back to the <kbd>https://<em>semaphore.company</em></kbd> URL you did everything correct.

:::info
Users are created upon logging in with authentik. They will not have the rights to create anything initially. These permissions must be assigned later by the local admin created during the first login to the Semaphore UI.
Expand Down
Loading