Palmr/apps/docs/content/docs/3.2-beta/oidc-authentication/authentik.mdx

---
title: Authentik
icon: Key
---

import { ZoomableImage } from "@/components/ui/zoomable-image";

Authentik is one of Palmr's officially supported OIDC providers, offering enterprise-grade authentication through Authentik's identity platform. This integration allows users to sign in to Palmr using Authentik's comprehensive authentication system, making it perfect for enterprise organizations, applications requiring advanced security features, and teams that need centralized identity management with complete control over their authentication infrastructure.

<ZoomableImage src="/assets/v3/oidc/authentik/sign-in-with-authentik.png" alt="Sign in with Authentik" />

## Why use Authentik authentication?

Authentik authentication provides several advantages for enterprise and security-focused organizations:

- **Complete self-hosted control** - Full control over your authentication infrastructure and data
- **Enterprise-grade security** - Advanced security features like MFA, adaptive authentication, and threat detection
- **Centralized identity management** - Single platform to manage users across multiple applications
- **Compliance ready** - Built-in compliance with GDPR, SOC 2, and other enterprise standards
- **Advanced customization** - Policies, flows, and custom branding capabilities

---

## Prerequisites

Before configuring Authentik authentication, ensure you have:

- **Authentik instance** - Self-hosted Authentik installation running and accessible
- **Admin privileges in Palmr** - Required to configure OIDC settings
- **Domain configuration** - For production deployments with custom domains

> **Note:** Authentik is pre-configured as an official provider in Palmr, which means the technical configuration is handled automatically. You only need to provide your OAuth credentials.

---

## Setting up Authentik OAuth2/OpenID Provider

### Creating an Authentik OAuth2/OpenID Provider

To get started with Authentik authentication, you'll need to create an OAuth2/OpenID Provider in your Authentik Admin Interface.

1. **Navigate to Authentik Admin Interface**: Go to your Authentik instance URL (e.g., `https://your-authentik-domain.com`)

<ZoomableImage src="/assets/v3/oidc/authentik/authentik-admin.png" alt="Authentik Admin Interface" />

2. **Create new OAuth2/OpenID Provider**: Click **"Applications"** in the left sidebar, then click **"Providers"** and click **"+ Create"**

<ZoomableImage src="/assets/v3/oidc/authentik/create-provider.png" alt="Authentik Create Provider" />

3. **Select provider type**: Choose **"OAuth2/OpenID Provider"** for OIDC authentication and click on **"Next"** button.

<ZoomableImage
  src="/assets/v3/oidc/authentik/provider-type.png"
  alt="Authentik Provider Type Selection"
  legend="This is a fake application, you have to use your own."
/>

### Configuring provider settings

1. **Enter provider details**:
   - **Name**: Enter a descriptive name like "Palmr File Sharing"
   - **Authorization Flow**: select **default-provider-authorization-explicit-consent (Authorize Application)**
   - **Protocol Settings (Client type)**: select **Confidential**
   - **Protocol Settings (Client ID)**: Copy the Client ID from Authentik field (You can edit it if you want) - `(Copy this value and save it for later use)`
   - **Protocol Settings (Client Secret)**: Copy the Client Secret from Authentik field (You can edit it if you want) - `(Copy this value and save it for later use)`
   - **Protocol Settings (Redirect URIs/Origins (RegEx))**: Select 'Strict' and add the redirect URI for your application (e.g. `https://your-palmr-domain.com/api/auth/providers/authentik/callback`) you can see below the field the example of the redirect URI.
   - **Protocol Settings (Signing key)**: select **"authentik Self-signed Certificate"**

<ZoomableImage
  src="/assets/v3/oidc/authentik/provider-settings-1.png"
  alt="Authentik Provider Settings"
  legend="This is a fake application, you have to use your own."
/>

<ZoomableImage
  src="/assets/v3/oidc/authentik/provider-settings-2.png"
  alt="Authentik Provider Settings"
  legend="This is a fake application, you have to use your own."
/>

2. **Configure provider URLs**:

You'll need to configure several URLs in your Authentik provider settings. Here's what to add for each environment:

### Redirect URIs

| Environment | URL                                                                 |
| ----------- | ------------------------------------------------------------------- |
| Production  | `https://yourdomain.com/api/auth/providers/authentik/callback`      |
| Development | `http://localhost:3000/api/auth/providers/authentik/callback`       |
| Custom Port | `https://yourdomain.com:5487/api/auth/providers/authentik/callback` |

> **Note:** Replace `yourdomain.com` with your actual domain name in all production and custom port URLs.
> **Note:** You can add multiple redirect URIs for different environments (development, staging, production).

**Save changes**: Click **"Finish"** to apply your configuration.

> **Note:** You can configure other settings for provider if you want, but the necessary settings are already configured in this step.

After clicking on **"Finish"** you will see your provider listed in the provider list, but with an warning message like this: ' Warning: Provider not assigned to any application.'.

<ZoomableImage
  src="/assets/v3/oidc/authentik/warning-message.png"
  alt="Authentik Provider Warning Message"
  legend="This is a fake application, you have to use your own."
/>

### Creating application with created provider

After creating your provider, you need to create an application with the created provider. To do this, you need to click on the **"Applications"** in the left sidebar, then click on **"+ Create"**.

<ZoomableImage
  src="/assets/v3/oidc/authentik/applications-page.png"
  alt="Authentik Applications Page"
  legend="This is a fake application, you have to use your own."
/>

1. **Configure application**:

- **Name**: Enter a descriptive name like "Palmr File Sharing"
- **Slug**: Enter a unique identifier (e.g., `palmr-file-sharing`)
- **Provider**: Select the provider you just created from the list of providers.

<ZoomableImage
  src="/assets/v3/oidc/authentik/application-modal.png"
  alt="Authentik Application Modal"
  legend="This is a fake application, you have to use your own."
/>

The other fields are not important for now, you can leave them as they are. But if you want to change something, you can change them.

2. **Save application**: Click on **"Create"** to save the application.

<ZoomableImage
  src="/assets/v3/oidc/authentik/application-modal.png"
  alt="Authentik Application Modal"
  legend="This is a fake application, you have to use your own."
/>

### Final Authentik step

The last step in Authentik is grab your instance URL. You can find it clicking on the **"providers"** in the side menu on tab **"overview"**.

<ZoomableImage
  src="/assets/v3/oidc/authentik/provider-overview.png"
  alt="Authentik Instance URL"
  legend="This is a fake application, you have to use your own."
/>

You don't need copy the complete URL, just the domain name and protocol and port if you are using a custom port.
For example: `https://your-authentik-domain.com`.

> **Note:** In Authentik we finish the configuration. Let's go to Palmr to configure the provider. Remember you need `Client ID`, `Client Secret` and `Instance URL` to configure the provider in Palmr.

---

## Configuring Palmr

### Accessing OIDC settings

To configure Authentik authentication in Palmr, you need administrator access to the settings panel.

1. **Login as administrator**: Sign in to Palmr with an admin account

2. **Access settings**: Click your profile picture in the header and select **Settings**

3. **Navigate to authentication**: Find and click on the **Authentication Providers** configuration section

<ZoomableImage src="/assets/v3/oidc/auth-providers.png" alt="Palmr Authentication Providers" />

### Enabling Authentik provider

Authentik comes pre-configured as an official provider, so the setup process is streamlined.

1. **Locate Authentik provider**: Find Authentik in the list of available providers

2. **Enable the provider**: Toggle the status to **Enabled**

<ZoomableImage src="/assets/v3/oidc/authentik/enabled-authentik.png" alt="Palmr Authentik Provider Enabled" />

After enabling the provider, click on the pen icon to configure the provider.

3. **Configure credentials**:
   - **Provider URL**: Paste your Authentik instance URL (e.g., `https://your-authentik-domain.com`)
   - **Client ID**: Paste the Client ID from Authentik provider
   - **Client Secret**: Paste the Client Secret from Authentik provider
   - **Scopes**: Add the scopes you want to use. The default scopes are `openid`, `profile`, and `email`. You don't need change this if you are not sure.

<ZoomableImage
  src="/assets/v3/oidc/authentik/edit-authentik.png"
  alt="Edit Authentik Provider"
  legend="This is a fake application, you have to use your own."
/>

### Advanced configuration options

Configure additional settings to customize the authentication behavior:

**Auto Registration**: Enable this to automatically create user accounts when someone authenticates for the first time.

**Sort Order**: Control where the Authentik login button appears relative to other authentication providers.

**Icon**: you can choose the icon you want to use for the Authentik login button (default is `FaShieldAlt`).

<ZoomableImage src="/assets/v3/oidc/authentik/authentik-icon.png" alt="Authentik Icon" />

---

## Account linking

By default, if a user is already registered in Palmr with their Authentik email, they will be automatically linked to their Palmr account.

> **Note:** You can't disable account linking. If you want to unlink a user from their Authentik account, you need to delete the user from Palmr.

---

## Technical configuration

Authentik's technical configuration is handled automatically, but understanding the setup can help with troubleshooting:

```yaml
Provider Type: OAuth 2.0 with OIDC Discovery
Issuer URL: https://your-authentik-domain.com
Authorization Endpoint: /application/o/authorize
Token Endpoint: /application/o/token
UserInfo Endpoint: /application/o/userinfo
Scopes: openid profile email
```

### Field mappings

Palmr automatically maps Authentik user information to local user accounts:

- **User ID**: Maps from Authentik's `sub` field
- **Email**: Maps from Authentik's `email` field
- **Full Name**: Maps from Authentik's `name` field
- **First Name**: Maps from Authentik's `given_name` field
- **Last Name**: Maps from Authentik's `family_name` field
- **Avatar**: Maps from Authentik's `picture` field
- **Username**: Maps from Authentik's `preferred_username` field

### Authentik-specific features

- **Custom Claims**: Can include custom user metadata and app metadata
- **Policies Support**: Can customize authentication flow with custom policies
- **Multi-factor Authentication**: Supports Authentik's MFA features
- **Enterprise SSO**: Integrates with SAML, LDAP, and other enterprise systems
- **Self-hosted Only**: Complete control over your authentication infrastructure

---

## Testing the configuration

### Verifying the setup

After configuring Authentik authentication, test the integration to ensure everything works correctly.

1. **Check login page**: Navigate to your Palmr login page and verify the "Sign in with Authentik" button appears

2. **Test authentication flow**: Click the Authentik sign-in button and complete the authentication process

3. **Verify user creation**: Confirm that a new user account is created (if auto-registration is enabled)

### Login flow verification

The complete authentication process should work as follows:

1. **User clicks "Sign in with Authentik"**: The browser redirects to Authentik's authorization page
2. **User authenticates**: User completes authentication through Authentik (login, MFA, etc.)
3. **Authentik redirects back to Palmr**: User returns to Palmr with authentication tokens
4. **Palmr creates or updates user**: User account is automatically managed with Authentik information
5. **User accesses Palmr**: User is logged in with their Authentik identity

---

## Troubleshooting common issues

### Redirect URI mismatch error

**Error message**: `invalid_redirect_uri`

**Cause**: The redirect URI in your request doesn't match what's configured in Authentik provider.

**Solution**:

1. Check the exact URL in the error message
2. Add this exact URL to your Authentik provider's redirect URIs
3. Ensure you include the correct protocol (http/https) and port
4. Remove any trailing slashes unless they're in the callback URL

### Access denied error

**Error message**: `access_denied`

**Cause**: User denied permissions or the provider isn't properly configured.

**Solution**:

1. Verify that your Authentik provider requests the correct scopes
2. Check that users are granting permissions during the authorization flow
3. Ensure your provider is not restricted or disabled
4. Verify the provider has proper permissions set up

### Invalid client error

**Error message**: `invalid_client`

**Cause**: Incorrect Client ID, Client Secret, or Instance URL.

**Solution**:

1. Double-check that you've copied the credentials correctly from Authentik
2. Ensure there are no extra spaces or characters in the credentials
3. Verify you're using the correct instance URL format
4. Generate a new Client Secret if necessary

### Instance URL configuration issues

**Error message**: Instance not found or invalid

**Cause**: Incorrect Authentik instance URL or instance configuration.

**Solution**:

1. Verify your Authentik instance URL is correct
2. Check that your Authentik instance is active and accessible
3. Ensure you're using the correct protocol (https://)
4. Verify DNS resolution for your Authentik instance

### Self-hosted connectivity issues

**Cause**: Network connectivity problems with self-hosted Authentik instance.

**Solution**:

1. Check server firewall and network connectivity
2. Verify DNS resolution from your server to the Authentik instance
3. Ensure the Authentik instance is properly configured and running
4. Check SSL certificate validity for the Authentik instance

---

## Security best practices

### Credential management

- **Never expose secrets**: Keep your Client Secret secure and never commit it to version control
- **Rotate credentials regularly**: Generate new Client Secrets periodically for enhanced security
- **Use environment variables**: Store sensitive configuration in environment variables, not config files
- **Monitor access logs**: Regularly review authentication logs for suspicious activity

### Scope and permission management

- **Minimal scopes**: Only request `openid`, `profile`, and `email` scopes as required by Palmr
- **User consent**: Ensure users understand what permissions they're granting
- **Regular audits**: Review which users have connected their Authentik accounts
- **Access reviews**: Periodically check user access and remove inactive accounts

### Production considerations

- **Use HTTPS**: Always use HTTPS in production environments
- **Configure proper domains**: Use production domains in Authentik provider settings
- **Test thoroughly**: Verify the complete authentication flow before going live
- **Plan for failures**: Have fallback authentication methods available

---

## Next steps

With Authentik authentication configured, you might want to:

- **Configure additional providers**: Set up other OIDC providers for more authentication options
- **Customize user management**: Fine-tune auto-registration and admin assignment rules
- **Review security settings**: Ensure your authentication setup meets your security requirements
- **Monitor usage**: Keep track of authentication patterns and user activity

For more information about OIDC authentication in Palmr, see the [OIDC Authentication overview](/docs/3.2-beta/oidc-authentication).

## Useful resources

- [Authentik Documentation](https://goauthentik.io/docs)
- [Authentik OAuth2/OpenID Provider](https://goauthentik.io/docs/providers/oauth2)
- [Authentik Installation Guide](https://goauthentik.io/docs/installation)
- [Authentik Admin Interface](https://goauthentik.io/docs/administration)