Github/authentik
1
0
Fork 0
mirror of https://github.com/goauthentik/authentik.git synced 2026-08-30 18:51:39 -07:00
Code Issues Packages Projects Releases Wiki Activity

website: Merge branch (#21684)

Browse Source 
Co-authored-by: Codex <codex@openai.com>
Co-authored-by: Dewi Roberts <dewi@goauthentik.io>
This commit is contained in:
Dominic R
2026-04-22 21:46:10 -04:00
committed by GitHub
parent b4c9ac57e0
commit 028ec05a8b
8 changed files with 315 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
website/docs/add-secure-apps/bindings-overview/index.md
View File

@@ -2,21 +2,45 @@
title: authentik bindings
---
A binding is, simply put, a connection between two components. The use of a binding adds additional functionality to one the existing components; for example, a policy binding can cause a new stage to be presented within a flow to a specific user or group.
A binding is a connection between two components. In practice, a binding adds behavior to an existing authentik object by telling authentik where to evaluate a policy, user, or group, or where to insert a stage into a flow.
A policy answers a question like "should this pass?" A binding decides where authentik asks that question.
A policy answers the question "should this pass?" A binding decides where authentik asks that question.
:::info
For information about creating and managing bindings, refer to [Work with bindings](./work-with-bindings.md).
:::
Bindings are an important part of authentik; the majority of configuration options are defined in bindings.
Bindings are used throughout authentik. Many access and execution decisions are configured through bindings. The two binding types that you will work with most often are:
It's important to remember that bindings are instantiated objects themselves, and conceptually can be considered as a "connector" between two components. This is why you might read about "binding a binding", because technically, a binding is "spliced" into another binding, in order to intercept and enforce the criteria defined in the second binding. Note that stage-bindings are the only type of binding that you can add (or splice) another binding to.
- **Policy bindings**, which attach a policy, user, or group to an object that supports bindings.
- **Flow-stage bindings**, which attach a stage to a flow in a specific order.
## Relations with bindings
## Types of bindings
This diagram shows the relationships that bindings have between components. The primary components are _policy_, _user_, and _group_; these three objects can be bound to an application, application entitlement, flow, flow-stage binding, source, device, device access group, notification rule, or endpoint.
The two most common types of bindings in authentik are policy bindings and flow-stage bindings. They solve different problems:
- Use a policy binding when you want to control whether a target is allowed, denied, or shown.
- Use a flow-stage binding when you want to place a stage into a flow and decide when it should run.
## Where bindings are used
The policy binding system is shared by several authentik objects. As of the current implementation, you can bind policies, users, and groups to these targets:
- flows
- flow-stage bindings
- applications
- application entitlements
- sources
- devices
- device access groups
- notification rules
- RAC endpoints
Stages themselves are not policy binding targets. A stage is attached to a flow through a flow-stage binding, so when you bind a policy to a stage in a flow, you are binding it to that flow-stage binding.
Because of this, the same stage can be reused in multiple flows, and each flow can apply different policies to that stage.
## Relationships
```mermaid
@@ -73,45 +97,76 @@ flowchart TD
policy_binding --> flow_stage_binding
```
## Types of bindings
## Policy bindings
The two most common types of bindings in authentik are:
A policy binding attaches one of the following to a target:
- policy bindings (which can also bind to users and groups)
- flow-stage bindings
- a policy object
- a user
- a group
### Policy bindings
User and group bindings are simple membership checks. A user binding passes when the current user matches that user. A group binding passes when the current user is a member of that group.
A _policy binding_ connects a specific policy (a policy object) to a flow or stage binding. With the policy binding, the flow (or specifically the stage within the flow) will now have additional content (i.e. the rules of the policy).
This is useful when you want a direct allow or deny rule without creating a separate policy object.
With policy bindings, you can also bind groups and users to another component (an application, a source, a flow, etc.). For example you can bind a specific group to an application, and then only that group (and/or other groups also bound to it, depending on the [policy engine mode](../applications/manage_apps.mdx#use-bindings-to-control-access)), can access the application.
Policy bindings are commonly used with applications, sources, flows, flow-stage bindings, and [application entitlements](../applications/manage_apps.mdx#application-entitlements). For example, you can bind a group directly to an application so that only members of that group can view and launch it.
When you bind a policy to a stage binding, this task is done _per flow_, and does not carry across to other flows that use this same stage. That is, you will need to go to the **Stage Bindings** tab for the specific flow, and add a policy to the stage.
Bindings are evaluated according to the target's **Policy engine mode**:
Bindings are also used for [Application Entitlements](../../add-secure-apps/applications/manage_apps.mdx#application-entitlements), where you can bind specific users or groups to an application as a way to manage who has access to certain areas _within an application_.
- `Any`: the target passes when any binding passes.
- `All`: the target passes only when every binding passes.
:::info
Be aware that any policy binding bound directly to the entire flow (not to a stage within the flow) are evaluated _before_ the flow executes, so if the user has not been identified, the flow will not be accessible. This is due to bindings relying on user information that isn't available yet.
:::
authentik evaluates enabled bindings in ascending order. The order is most noticeable when you are reading logs or combining multiple policies that return messages.
### Flow-stage bindings
Bindings also support these options:
:::info
Be aware that depending on context, user and group policy bindings are not evaluated (i.e. ignored). For example, if you are not authenticated or if authentik has not yet identified the user, a policy binding that depends on knowing who the user is cannot be evaluated.
:::
- **Negate**, which flips the pass or fail result of the binding.
- **Timeout**, which limits how long authentik waits for policy execution.
- **Failure result**, which controls whether a policy error is treated as pass or fail.
Flow-stage bindings (also called stage bindings) are analyzed by authentik's Flow Plan, which starts with the flow, then assesses all of the bound policies, and then runs them in order to build out the plan.
Policy bindings attached directly to a flow are evaluated before the flow starts. In authentication and enrollment flows, that usually means that user- and group-based checks on the flow itself cannot pass until the user has already been identified elsewhere.
A _flow-stage binding_ connects a stage to a flow in a specified order, so that the stage is executed at the desired point within the flow.
If a target has no applicable bindings, authentik treats the result as passing by default.
For example, you can create a binding for a specific group, and then [bind that to a stage binding](../flows-stages/stages/index.md#bind-users-and-groups-to-a-flows-stage-binding), with the result that everyone in that group now will see that stage (and any policies bound to that stage) as part of their flow. Or more specifically, and going one step deeper, you can also _bind a binding to a binding_.
## Flow-stage bindings
Flow-stage bindings can have policy bindings bound to them; this can be used to conditionally run or skip stages within a flow. There are two settings in a flow-stage binding that configure _when_ these policies are executed:
A flow-stage binding attaches a stage to a flow and defines the order in which that stage runs.
- **Evaluate when flow is planned**
Policies are evaluated when authentik creates a flow plan that contains a reference to all of the stages that the user will need to go through to complete the flow. In this case, user-specific attributes are only available if the user is already authenticated before beginning the flow.
Flow-stage bindings are also called stage bindings. authentik uses them while building the flow plan that determines which stages a user will see and in what order.
- **Evaluate when the stage is run**
Policies bound to a flow-stage binding are evaluated before the stage is run (i.e. after the flow has started but before the stage is reached in the flow). Therefore, the context with which policy bindings to the flow-stage binding are evaluated reflects the current state of the flow.
This matters because stages are reusable objects. The same stage can appear in multiple flows, but each flow-stage binding can have its own policies, users, groups, order, and evaluation settings. When you bind a policy to a stage in a specific flow, you are binding it to that flow-stage binding, not to the reusable stage definition itself.
For example, when configuring an authentication flow with an identification stage bound to it, and a user bound to a Captcha flow-stage binding, with this setting (**Evaluate when stage is run**) enabled authentik can check against the user who has identified themselves previously.
### When authentik evaluates stage-binding policies
Flow-stage bindings have two evaluation settings:
- **Evaluate when flow is planned**: authentik evaluates the binding while it is building the flow plan. If the binding does not pass at planning time, the stage is not added to the plan.
- **Evaluate when the stage is run**: authentik adds the stage to the flow plan, then evaluates the binding again immediately before the stage is shown. If the binding no longer passes, authentik removes that stage from the flow plan.
The second option is useful when the decision depends on context that is only available later in the flow. For example, after an identification stage completes, a subsequent stage binding can assess the identified user and then trigger a CAPTCHA or Deny stage as needed.
In other words:
- use **Evaluate when flow is planned** when the decision can already be made before the user reaches the stage
- use **Evaluate when the stage is run** when the decision depends on flow context that is created by an earlier stage
## What to remember
- Stages are attached to flows through flow-stage bindings.
- Policies, users, and groups can all be bound through the same policy binding system.
- The same stage can behave differently in different flows because each flow-stage binding has its own settings and bindings.
- A policy bound directly to a flow is evaluated earlier than a policy bound to a flow-stage binding.
## Common examples
### Restrict an application
By default, applications are accessible to all users. Bind a group or policy to an application when you want to limit access to specific users.
### Run a stage only for some users
Bind a policy, user, or group to the flow-stage binding when a stage should appear only for certain users in that flow. For example, only require an MFA stage for certain users.
### Scope access inside an application
Use [application entitlements](../applications/manage_apps.mdx#application-entitlements) when you need to control access to parts of an application after the user already has access to the application itself. For example, control which users have access to certain administrator functions within an application.

56
website/docs/add-secure-apps/flows-stages/stages/authenticator_validate/index.mdx
View File

@@ -24,6 +24,62 @@ Keep in mind that when using Code-based devices (TOTP, Static and SMS), values l
### Options
#### Require more than one MFA method
To require users to enroll more than one MFA method and validate with each method on every login, add multiple **Authenticator Validation** stages to the same authentication flow.
Configure each authenticator validation stage with a different set of allowed **Device classes**, and set **Not configured action** to **Configure**.
#### Example: require both TOTP and WebAuthn
To require both TOTP and WebAuthn:
1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Create a TOTP setup stage and a WebAuthn setup stage if you do not already have them.
3. Navigate to **Flows and Stages** > **Stages** and create an **Authenticator Validation** stage for TOTP:
- Set **Device classes** to `totp`.
- Set **Not configured action** to **Configure**.
- Set **Configuration stages** to your TOTP setup stage.
4. Create a second **Authenticator Validation** stage for WebAuthn:
- Set **Device classes** to `webauthn`.
- Set **Not configured action** to **Configure**.
- Set **Configuration stages** to your WebAuthn setup stage.
5. Navigate to **Flows and Stages** > **Flows** and open your authentication flow.
6. On the **Stage Bindings** tab, bind both validation stages to the flow in the order that you want users to enroll them.
On first sign-in, users who do not yet have one of the required methods are prompted to configure it before the flow continues. On later sign-ins, each validation stage checks only the device classes configured on that stage.
#### Require at least two enrolled MFA methods of any type
If you want to require users to enroll at least two different MFA methods, regardless of which types they choose, use an [Expression Policy](../../../../customize/policies/types/expression/index.mdx) to count the enrolled device classes for the user.
To enforce this requirement:
1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Customization** > **Policies** and create an **Expression Policy**.
3. Add an expression like the following to count the user's confirmed authenticator types:
```python
from authentik.stages.authenticator import devices_for_user
pending_user = request.context.get("pending_user")
if not pending_user or not pending_user.pk:
return False
device_types = {
device.__class__.__name__.lower().replace("device", "")
for device in devices_for_user(pending_user, confirmed=True)
}
return len(device_types) >= 2
```
4. Bind the policy to the flow or stage binding that controls whether the user can continue without enrolling another authenticator.
#### Allow users to choose from multiple enrollment methods
If you select multiple **Configuration stages** on a single validation stage, users can choose which authenticator to enroll for that requirement.
#### Less-frequent validation
You can configure this stage to only ask for MFA validation if the user hasn't authenticated themselves within a defined time period. To configure this, set _Last validation threshold_ to any non-zero value. Any of the user's devices within the selected classes are checked.

45
website/docs/add-secure-apps/flows-stages/stages/password/index.md
View File

@@ -31,29 +31,62 @@ If you create a service account, that account has an automatically generated App
## Passwordless login
There are two different ways to configure passwordless authentication;
There are two different ways to configure passwordless authentication:
- allow users to directly authenticate with their authenticator (only supported for WebAuthn devices), by following [these instructions](../authenticator_validate/index.mdx#passwordless-authentication).
- dynamically skip a Password stage (depending on the user's device), as documented on this page.
If you want users to be able to pick a passkey from the browser's passkey/autofill UI without entering a username first, configure **Passkey autofill (WebAuthn conditional UI)** in the [Identification stage](../identification/index.mdx#passkey-autofill-webauthn-conditional-ui). This is separate from configuring a dedicated passwordless flow, and can be used alongside normal identification flows.
Depending on what kind of device you want to require the user to have:
### Dynamically skip a Password stage
This setup keeps a normal identification flow, but skips the Password stage for users who already have a supported authenticator configured.
To configure this setup:
1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Customization** > **Policies** and create an [Expression Policy](../../../../customize/policies/types/expression/index.mdx).
3. Configure the expression so that it returns `True` only when the Password stage should run. Use one of the expressions below, depending on the authenticator type.
4. Navigate to **Flows and Stages** > **Flows** and open your authentication flow.
5. Open the **Stage Bindings** tab, expand the Password stage binding, and bind the Expression Policy there. Do not bind it to the flow itself or directly to the stage object. For more background, see [Bind a policy to a stage binding](../../../../customize/policies/working_with_policies.md#bind-a-policy-to-a-stage-binding).
6. On the Password stage binding, enable **Evaluate when stage is run**. Disable **Evaluate when flow is planned** unless the user is already known before the flow starts.
#### WebAuthn
```python
from authentik.stages.authenticator_webauthn.models import WebAuthnDevice
return WebAuthnDevice.objects.filter(user=request.context['pending_user'], confirmed=True).exists()
pending_user = request.context.get("pending_user")
if not pending_user:
return True
return not WebAuthnDevice.objects.filter(user=pending_user, confirmed=True).exists()
```
#### Duo
```python
from authentik.stages.authenticator_duo.models import DuoDevice
return DuoDevice.objects.filter(user=request.context['pending_user'], confirmed=True).exists()
pending_user = request.context.get("pending_user")
if not pending_user:
return True
return not DuoDevice.objects.filter(user=pending_user, confirmed=True).exists()
```
Afterwards, bind the policy you've created to the stage binding of the password stage.
Because the expression already returns whether the Password stage should run, you do not need to enable **Negate result** on the policy binding.
Make sure to uncheck _Evaluate when flow is planned_ and check _Evaluate when stage is run_, otherwise an invalid result will be cached.
If the Password stage binding has more than one policy attached, review its **Policy engine mode** carefully:
- With only this policy attached, either mode works.
- If multiple policies are attached, `all` requires every policy to pass before the Password stage runs.
- If multiple policies are attached, `any` runs the Password stage when any bound policy passes.
#### Default authentication flow
The built-in `default-authentication-flow` already includes a policy binding on its Password stage, `default-authentication-flow-password-stage`, which controls whether the Password stage should appear.
If you add a second policy to that same Password stage binding, set the stage binding's **Policy engine mode** to `all` so both the built-in policy and your Expression Policy must pass before the Password stage runs.
Keep **Evaluate when stage is run** enabled on that binding. In the default blueprint, this is already configured.

43
website/docs/add-secure-apps/outposts/embedded/embedded.mdx
View File

@@ -4,44 +4,51 @@ title: Embedded Outpost
authentik includes an embedded outpost to simplify deployments that use the Proxy provider.
The embedded outpost runs in the main `server` container, and is managed by authentik itself. The embedded outpost authenticates itself via the secret key.
The embedded outpost runs as part of the main authentik server deployment and is managed by authentik itself. It authenticates to the authentik API by using the secret key.
You can access the embedded outpost on the same ports as authentik itself, 9000 and 9443.
You can access the embedded outpost on the same ports as authentik itself, `9000` and `9443`.
If the embedded outpost doesn't make sense for your deployment, you can simply ignore it.
## When to use the embedded outpost
### Configuration
Use the embedded outpost when you are using the proxy provider and want the simplest deployment model. It is a good fit when authentik is already behind a reverse proxy and you want proxy provider traffic to be handled by the same authentik deployment, without a separate outpost deployment.
Since authentik doesn't know its own "primary" URL, there might be some configuration required.
Use a [managed outpost](../index.mdx) instead when you want authentik to deploy and update a separate outpost through the [Docker](../integrations/docker.md) or [Kubernetes](../integrations/kubernetes.md) integrations, or when you want the outpost lifecycle to be separate from the core server.
By default, when opening the admin dashboard on a fresh install, authentik will automatically configure the outpost to use the same URL as was used to access authentik.
If the embedded outpost does not fit your deployment, you can ignore it and use a [managed outpost](../index.mdx) instead.
If this isn't correct, or needs to be changed, click the edit button on the right of the outpost, and set the value of `authentik_host` to the URL you want to log in with.
Make sure to set it to a full URL; only configuring a hostname or FQDN will not work.
## Configuration
Additionally, most of the other configuration options can be used as with any other outpost, except for items that are marked as "non-embedded".
Because authentik does not know its own primary URL, you might need to configure the embedded outpost after installation.
By default, when you open the Admin interface on a fresh install, authentik automatically configures the outpost to use the same URL that was used to access authentik.
If this is not correct, navigate to **Applications** > **Outposts**, edit **authentik Embedded Outpost**, and set `authentik_host` to the correct URL.
Make sure that you set a full URL. A hostname or FQDN by itself does not work.
Most other outpost configuration options also apply to the embedded outpost, except for items that are marked as `non-embedded`.
import Configuration from "../_config.md";
<Configuration />
### Routing
## Routing
Routing is handled like this:
Requests are routed as follows:
1. Paths starting with `/static`, `/media` and `/help` return packaged CSS/JS files, and user-uploaded media files.
1. Paths starting with `/static`, `/media`, and `/help` return packaged CSS and JavaScript files, and user-uploaded media files.
2. Paths starting with `/outpost.goauthentik.io` are sent to the embedded outpost.
3. Any hosts configured in the providers assigned to the embedded outpost are sent to the outpost.
4. Everything remaining is sent to the authentik backend server.
### Differences
## How the embedded outpost differs from managed outposts
There are a few more differences between managed outposts and the embedded outpost, mainly due to the fact that authentik can't fully manage the containers.
There are a few differences between managed outposts and the embedded outpost because authentik cannot fully manage the main authentik server deployment in the same way that it manages a separate outpost deployment.
1. (Docker-only) No automatic traefik labels are added to the server container.
1. Docker only: no automatic Traefik labels are added to the server container.
When you deploy a managed outpost on docker, the container has several labels to automatically configure traefik. This is not done for the embedded outpost.
When you deploy a managed outpost on Docker, the container includes labels that can configure Traefik automatically. The embedded outpost does not add those labels to the server container.
2. (Kubernetes-only) An additional service is created.
2. Kubernetes only: an additional Service is created.
Since authentik does not know what the normal authentik Service is called, another one is created with a common set of labels that is always set.
Because authentik does not know the name of the primary authentik Service, it creates another Service with a common set of labels that is always present.

24
website/integrations/chat-communication-collaboration/sharepoint-se/index.md
View File

@@ -117,7 +117,10 @@ return {
"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.groups.all()], # The set of roles that were assigned to the user who is logging in.
"roles": [
entitlement.name
for entitlement in request.user.app_entitlements(provider.application)
], # The set of role entitlements that were assigned to the user who is logging in.
}
```
@@ -151,6 +154,7 @@ From the authentik Admin Dashboard:
The minimum is 15 minutes, otherwise SharePoint backend will consider the access token expired.
:::
- **Scopes**: select default email, SPopenid and SPprofile
- Under **Advanced protocol settings** > **Selected Scopes**, add `authentik default OAuth Mapping: OpenID 'entitlements'`.
- **Subject mode**: Based on the User's hashed ID
5. Click **Finish**.
@@ -168,6 +172,22 @@ From the authentik Admin Dashboard:
- (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 3b: Create application entitlements in authentik
Use [application entitlements](/docs/add-secure-apps/applications/manage_apps/#application-entitlements) to define the values that authentik sends in the `roles` claim for this SharePoint Server SE application.
From the authentik Admin Dashboard:
1. Open **Applications > Applications** from the sidebar.
2. Open the application `auth.applicationName`.
3. Click the **Application entitlements** tab.
4. Create the entitlements that SharePoint should receive in the `roles` claim.
5. Open each entitlement and bind the users or groups that should receive it.
:::tip Entitlement role names
For this integration, entitlement names should exactly match the role values that your SharePoint configuration expects in the incoming `roles` claim. This keeps SharePoint-specific authorization scoped to the SharePoint application instead of relying on global authentik group names.
:::
### Step 4: Setup OIDC authentication in SharePoint Server
#### Pre-requisites
@@ -250,7 +270,7 @@ $idClaim = New-SPClaimTypeMapping "http://schemas.microsoft.com/identity/claims/
## User claims mappings
$claims = @(
$idClaim
## User Roles (Group membership)
## User Roles (application entitlements sent in the roles claim)
,(New-SPClaimTypeMapping ([System.Security.Claims.ClaimTypes]::Role) -IncomingClaimTypeDisplayName "Role" -SameAsIncoming)
## User email
,(New-SPClaimTypeMapping ([System.Security.Claims.ClaimTypes]::Email) -IncomingClaimTypeDisplayName "Email" -SameAsIncoming)

39
website/integrations/cloud-providers/aws-classic/index.mdx
View File

@@ -43,7 +43,7 @@ SCIM Provisioning is only supported in conjunction with [IAM Identity Center](..
## authentik configuration
To support the integration of AWS with authentik via the Classic IAM method, you need to create two property mappings and an application/provider pair in authentik.
To support the integration of AWS with authentik via the Classic IAM method, you need to create two property mappings, an application/provider pair, and application entitlements for the AWS roles that users can assume.
### Create property mappings
@@ -61,24 +61,16 @@ To support the integration of AWS with authentik via the Classic IAM method, you
return "arn:aws:iam::<aws_account_ID>:role/authentik-admin,arn:aws:iam::<aws_account_ID>:saml-provider/<provider_name>"
```
**For role assignment based on group membership** (recommended):
**For role assignment based on application entitlements** (recommended):
```python
ACCOUNT_ID = "<aws_account_ID>"
PROVIDER_NAME = "<provider_name>"
PREFIX = "AWS:"
# Collect the user's groups
group_names = list(user.groups.values_list("name", flat=True))
# Filter for groups starting with the prefix
roles = [
g[len(PREFIX):].strip()
for g in group_names
if g and g.casefold().startswith(PREFIX.casefold())
entitlement.name
for entitlement in request.user.app_entitlements(provider.application)
]
# Build entries. AWS expects a list of strings in this format where each line contains the role, then the provider name:
return [
f"arn:aws:iam::{ACCOUNT_ID}:role/{r},arn:aws:iam::{ACCOUNT_ID}:saml-provider/{PROVIDER_NAME}"
for r in roles
@@ -86,7 +78,7 @@ To support the integration of AWS with authentik via the Classic IAM method, you
```
:::tip
With the group-based approach, create groups in authentik with names like `AWS:authentik-admin`, `AWS:authentik-read-only`, etc. Users assigned to these groups will automatically receive the corresponding AWS roles.
With the entitlement-based approach, create application entitlements with names like `AWS:authentik-admin` and `AWS:authentik-read-only`, then bind the appropriate users or groups to those entitlements. Create these entitlements after you create the application, as described later in this guide. Users receive the corresponding AWS roles when they access the AWS application.
:::
**For multiple static roles:**
@@ -121,7 +113,8 @@ To support the integration of AWS with authentik via the Classic IAM method, you
- Set the **Issuer** to `urn:amazon:webservices`
- Set the **Audience** to `urn:amazon:webservices`
- Set **Service Provider Binding** to `Post`
- Under **Advanced protocol settings**, select an available **Signing Certificate**, ensure both **Signing Assertions** and **Signing Responses** are enabled, then add, under **Property Mappings**, both property mappings you created in the previous section
- Under **Advanced protocol settings**, select an available **Signing Certificate**, ensure both **Signing Assertions** and **Signing Responses** are enabled, then add, under **Property Mappings**, both property mappings you created in the previous section.
- Set **NameID Property Mapping** to `authentik default SAML Mapping: Email`.
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/bindings-overview/) (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.
@@ -130,6 +123,19 @@ To support the integration of AWS with authentik via the Classic IAM method, you
AWS Classic IAM uses the email-formatted NameID. The default authentik SAML email mapping is automatically included and does not need to be added manually.
:::
### Create application entitlements for AWS roles
Use [application entitlements](/docs/add-secure-apps/applications/manage_apps/#application-entitlements) to represent the AWS IAM roles this application should expose.
1. Open the AWS application that you just created in the authentik Admin interface.
2. Click the **Application entitlements** tab.
3. Create one entitlement for each AWS IAM role that users should be able to assume, such as `authentik-admin` or `authentik-read-only`.
4. Bind the appropriate users or groups to each entitlement.
:::tip
For this integration, the entitlement name should match the AWS IAM role name exactly. This keeps AWS-specific authorization scoped to the AWS application instead of relying on global group names such as `AWS:authentik-admin`.
:::
### Download metadata file
1. Log into authentik as an administrator and open the authentik Admin interface.
@@ -152,7 +158,7 @@ You will be redirected to the **Identity providers** home page.
### Create IAM roles for SAML federation
For each role that users can assume via SAML (e.g., `authentik-admin`, `authentik-read-only`), you need to create a corresponding IAM role in AWS. The role names must match those specified in your authentik property mappings.
For each role that users can assume via SAML (for example, `authentik-admin` or `authentik-read-only`), you need to create a corresponding IAM role in AWS. The role names must match the entitlement names that you created in authentik.
1. Still in the IAM console, navigate to **Access management** > **Roles**.
2. Click **Create role**.
@@ -167,7 +173,7 @@ For each role that users can assume via SAML (e.g., `authentik-admin`, `authenti
7. Click **Next**.
8. Select one or more policies that define the permissions for this role (e.g., `AdministratorAccess`, `ReadOnlyAccess`, or custom policies).
9. Click **Next**.
10. Set the **Role name** to match the role name in your property mapping (e.g., `authentik-admin`). This name must exactly match what you specified in the authentik property mappings.
10. Set the **Role name** to match the entitlement name in authentik (e.g., `authentik-admin`). This name must exactly match the entitlement name.
11. Optionally add a description and tags.
12. Click **Create role**.
@@ -268,6 +274,7 @@ To support the integration of AWS with authentik using OIDC, you need to create
- Note the **Client ID** and **slug** values because they will be required later.
- Set a `Strict` redirect URI to match the AWS resource that you want to access via OIDC.
- Select any available signing key.
- Under **Advanced protocol settings** > **Selected Scopes**, add `authentik default OAuth Mapping: OpenID 'entitlements'`.
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/bindings-overview/) (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.

55
website/integrations/cloud-providers/digitalocean/index.md
View File

@@ -22,7 +22,7 @@ This documentation lists only the settings that you need to change from their de
## authentik configuration
To support the integration of DigitalOcean with authentik, you need to create a scope mapping as well as an application/provider pair in authentik.
To support the integration of DigitalOcean with authentik, you need to create a scope mapping, an application/provider pair, and application entitlements for the DigitalOcean roles that users should receive.
### Create a scope mapping
@@ -34,22 +34,31 @@ To support the integration of DigitalOcean with authentik, you need to create a
- **Expression**:
```py
# Extract the names of all groups the user belongs to
group_names = user.groups.values_list("name", flat=True)
# Get the role names from the application's entitlements
do_roles = [
entitlement.name
for entitlement in request.user.app_entitlements(provider.application)
]
# From the group names, filter out those that start with "do:"
# Strip off the "do:" prefix so we’re left with just the role name
do_roles = [n[3:] for n in group_names if n and n[:3].casefold() == "do:"]
# DigitalOcean team roles must match a valid predefined or custom role name.
# Predefined roles are Owner, Biller, Billing Viewer, Modifier, Member,
# and Resource Viewer.
priority = [
"Owner",
"Biller",
"Billing Viewer",
"Modifier",
"Member",
"Resource Viewer",
]
# You can find all predefined roles at: https://docs.digitalocean.com/platform/teams/roles/predefined/
# You can find documentation for custom roles at: https://docs.digitalocean.com/platform/teams/roles/custom/
priority = ["Owner", "Admin", "Member"]
# Pick the first matching role based on priority order
# (e.g. if user has both "do:Admin" and "do:Member", they'll get "Admin")
# Pick the first matching predefined role based on priority order.
# If no predefined role matches, fall back to the first custom role name.
chosen = next((r for p in priority for r in do_roles if r == p), None)
if not chosen and do_roles:
chosen = sorted(do_roles)[0]
# Return a dict with the team role if one was chosen, otherwise return an empty dict
# Return a dict with the team role if one was chosen, otherwise return an empty dict.
return {"team_role": [chosen]} if chosen else {}
```
@@ -67,10 +76,28 @@ To support the integration of DigitalOcean with authentik, you need to create a
- Select any available signing key.
- Under **Advanced protocol settings**:
- Add the `profile` scope created in the previous section. Do not remove authentik’s `authentik default OAuth Mapping: OpenID 'profile'`, as claims such as `name` are required by DigitalOcean.
- Under **Advanced protocol settings** > **Selected Scopes**, add `authentik default OAuth Mapping: OpenID 'entitlements'`.
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/bindings-overview/) (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 application entitlements for DigitalOcean roles
Use [application entitlements](/docs/add-secure-apps/applications/manage_apps/#application-entitlements) to represent the DigitalOcean roles that this application should assign.
1. Open the DigitalOcean application that you just created in the authentik Admin interface.
2. Click the **Application entitlements** tab.
3. Create one entitlement for each DigitalOcean role that users should be able to receive.
4. Bind the appropriate users or groups to each entitlement.
:::tip Entitlement role names
For this integration, each entitlement name must exactly match a valid DigitalOcean team role name. This can be one of the predefined team roles, such as `Owner`, `Biller`, `Billing Viewer`, `Modifier`, `Member`, or `Resource Viewer`, or the exact name of a custom role that you created for the same DigitalOcean team. This keeps the role assignment scoped to the DigitalOcean application instead of relying on global group names such as `do:Owner`.
:::
:::info Single role mapping
The sample scope mapping returns a single `team_role` value. In most deployments, each user should receive only one DigitalOcean role entitlement at a time. If multiple matching entitlements are assigned, the example prefers predefined roles in the priority order shown above and otherwise falls back to the first custom role name alphabetically.
:::
## DigitalOcean configuration
1. Log in to the [DigitalOcean control panel](https://cloud.digitalocean.com/) as an administrator.
@@ -96,4 +123,4 @@ To support the integration of DigitalOcean with authentik, you need to create a
## Configuration verification
To verify the integration of authentik with DigitalOcean, navigate to the authentik User interface and click the DigitalOcean application to initiate a Single Sign-On login. Upon successful login, you should be redirected to the DigitalOcean dashboard and have the appropriate permissions set by your authentik groups.
To verify the integration of authentik with DigitalOcean, navigate to the authentik User interface and click the DigitalOcean application to initiate a Single Sign-On login. Upon successful login, you should be redirected to the DigitalOcean dashboard and have the appropriate permissions set by your application entitlements.

49
website/integrations/development/gitea/index.md
View File

@@ -36,6 +36,7 @@ To support the integration of Gitea with authentik, you need to create an applic
- 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.
- Under **Advanced protocol settings** > **Selected Scopes**, add `authentik default OAuth Mapping: OpenID 'entitlements'`.
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/bindings-overview/) (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.
@@ -59,33 +60,25 @@ To support the integration of Gitea with authentik, you need to create an applic
### Claims for authorization management (optional)
:::info
This step is _optional_ and shows how to set claims to control the permissions of users in Gitea by adding them to groups.
:::
This optional section shows how to set claims to control the permissions of users in Gitea by assigning them application entitlements.
#### Create groups
#### Create application entitlements
The following groups will be created:
The following application entitlements will be created:
- `gituser`: normal Gitea users.
- `gitadmin`: Gitea users with administrative permissions.
- `gitrestricted`: restricted Gitea users.
:::info
Users who are in none of these groups will not be able to log in to Gitea.
:::
Users who are assigned none of these entitlements 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 users that need Gitea access, and click **Add**.
7. Repeat steps 5 and 6 for the two additional groups.
:::info
You can add users to the groups at any point.
:::
2. Navigate to **Applications** > **Applications** and open the Gitea application.
3. Click the **Application entitlements** tab.
4. Click **New Entitlement**, set the name to `gituser`, and then click **Create**.
5. Repeat step 4 to create two additional entitlements named `gitadmin` and `gitrestricted`.
6. Open an entitlement and bind the users or groups that need Gitea access to it.
7. Repeat step 6 for the two additional entitlements.
#### Create custom property mapping
@@ -96,14 +89,18 @@ You can add users to the groups at any point.
- **Expression**:
```python showLineNumbers
entitlement_names = {
entitlement.name
for entitlement in request.user.app_entitlements(provider.application)
}
gitea_claims = {}
if request.user.groups.filter(name="gituser").exists():
gitea_claims["gitea"]= "user"
if request.user.groups.filter(name="gitadmin").exists():
gitea_claims["gitea"]= "admin"
if request.user.groups.filter(name="gitrestricted").exists():
gitea_claims["gitea"]= "restricted"
if "gituser" in entitlement_names:
gitea_claims["gitea"] = "user"
if "gitadmin" in entitlement_names:
gitea_claims["gitea"] = "admin"
if "gitrestricted" in entitlement_names:
gitea_claims["gitea"] = "restricted"
return gitea_claims
```
@@ -139,8 +136,8 @@ For this to function, the Gitea `ENABLE_AUTO_REGISTRATION: true` variable must b
4. Click **Update Authentication Source**.
:::info
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.
Users who are assigned none of the defined entitlements will be denied login access.
In contrast, users assigned the `gitadmin` entitlement will have full administrative privileges, while users assigned the `gitrestricted` entitlement will have limited access.
:::
### Helm Chart Configuration