website: Flesh out docs split.
website: Copy files during build. website: Allow for mixed env builds. website: Reduce build size. website: Expose build. website: Add build memory debugging. WIP: Disable broken links check to compare memory usage. website: Update deps. website: Clean up API paths. website: Flesh out 3.8 fixes. Format. website: Update ignore paths. Website: Clean up integrations build. website: Fix paths. website: Optimize remark. website: Update deps. website: Format. website: Remove linking. website: Fix paths. wip: Attempt API only build. Prep. Migrate render to runtime. Tidy sidebar. Clean up templates. docs: Move directory. WIP docs: Flesh out split. website: Fix issue where routes have collisions.
This commit is contained in:
Teffen Ellis
40
docs/topics/add-secure-apps/applications/index.md
Normal file
40
docs/topics/add-secure-apps/applications/index.md
Normal file
@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Applications
|
||||
---
|
||||
|
||||
Applications, as defined in authentik, are used to configure and separate the authorization/access control and the appearance of a specific software application in the **My applications** page.
|
||||
|
||||
When a user logs into authentik, they see a list of the applications for which authentik is configured to provide authentication and authorization (the applications that that they are authorized to use).
|
||||
|
||||
Applications are the "other half" of providers. They typically exist in a 1-to-1 relationship; each application needs a provider and every provider can be used with one application. Applications can, however, use specific, additional providers to augment the functionality of the main provider. For more information, see [Backchannel providers](./manage_apps.mdx#backchannel-providers).
|
||||
|
||||
Furthermore, the [RAC (Remote Access Control)](../providers/rac/index.md) feature uses a single application and a single provider, but multiple "endpoints". An endpoint defines each remote machine.
|
||||
|
||||
:::info
|
||||
For information about creating and managing applications, refer to [Manage applications](./manage_apps.mdx).
|
||||
:::
|
||||
|
||||
## Appearance
|
||||
|
||||
Applications are displayed to users when:
|
||||
|
||||
- The user has access defined via policies (or the application has no policies bound)
|
||||
- A valid Launch URL is configured/could be guessed, this consists of URLs starting with http:// and https://
|
||||
|
||||
The following options can be configured:
|
||||
|
||||
- _Name_: This is the name shown for the application card
|
||||
- _Launch URL_: The URL that is opened when a user clicks on the application. When left empty, authentik tries to guess it based on the provider
|
||||
|
||||
You can use placeholders in the launch url to build them dynamically based on the logged in user. For example, you can set the Launch URL to `https://goauthentik.io/%(username)s`, which will be replaced with the currently logged in user's username.
|
||||
|
||||
Only applications whose launch URL starts with `http://` or `https://` or are relative URLs are shown on the users' **My applications** page. This can also be used to hide applications that shouldn't be visible on the **My applications** page but are still accessible by users, by setting the _Launch URL_ to `blank://blank`.
|
||||
|
||||
- _Icon (URL)_: Optionally configure an Icon for the application
|
||||
|
||||
If the authentik server does not have a volume mounted under `/media`, you'll get a text input. This accepts absolute URLs. If you've mounted single files into the container, you can reference them using `https://authentik.company/media/my-file.png`.
|
||||
|
||||
If there is a mount under `/media` or if [S3 storage](../../sys-mgmt/ops/storage-s3.md) is configured, you'll instead see a field to upload a file.
|
||||
|
||||
- _Publisher_: Text shown below the application
|
||||
- _Description_: Subtext shown on the application card below the publisher
|
||||
98
docs/topics/add-secure-apps/applications/manage_apps.mdx
Normal file
98
docs/topics/add-secure-apps/applications/manage_apps.mdx
Normal file
@ -0,0 +1,98 @@
|
||||
---
|
||||
title: Manage applications
|
||||
---
|
||||
|
||||
Managing the applications that your team uses involves several tasks, from initially adding the application and provider, to controlling access and visibility of the application, to providing access URLs.
|
||||
|
||||
### Instructions
|
||||
|
||||
To add an application to authentik and have it display on users' **My applications** page, follow these steps:
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
|
||||
2. Navigate to **Applications -> Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can create only an application, without a provider, by clicking **Create.)**
|
||||
|
||||
3. In the **New application** box, define the application details, the provider type and configuration settings, and bindings for the application.
|
||||
- **Application**: provide a name, an optional group for the type of application, the policy engine mode, and optional UI settings.
|
||||
|
||||
- **Choose a Provider**: select the provider types for this application.
|
||||
|
||||
- **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and any additional required configurations.
|
||||
|
||||
- **Configure Bindings**: to manage the listing and access to applications on a user's **My applications** page, you can optionally create a [binding](../flows-stages/bindings/index.md) between the application and a specific policy, group, or user. Note that if you do not define any bindings, then all users have access to the application. For more information about user access, refer to our documentation about [authorization](#policy-driven-authorization) and [hiding an application](#hide-applications).
|
||||
|
||||
4. On the **Review and Submit Application** panel, review the configuration for the new application and its provider, and then click **Submit**.
|
||||
|
||||
## Policy-driven authorization
|
||||
|
||||
To use a [policy](../../customize/policies/index.md) to control which users or groups can access an application, click on an application in the applications list and then select the **Policy/Group/User Bindings** tab. There you can bind users/groups/policies to grant them access. When nothing is bound, everyone has access. Binding a policy restricts access to specific Users or Groups, or by other custom policies such as restriction to a set time-of-day or a geographic region.
|
||||
|
||||
By default, all users can access applications when no policies are bound.
|
||||
|
||||
When multiple policies/groups/users are attached, you can configure the _Policy engine mode_ to either:
|
||||
|
||||
- Require users to pass all bindings/be member of all groups (ALL), or
|
||||
- Require users to pass either binding/be member of either group (ANY)
|
||||
|
||||
## Application Entitlements
|
||||
|
||||
<div className="badge-group">
|
||||
|
||||
:ak-version[2024.12]
|
||||
:ak-preview
|
||||
|
||||
</div>
|
||||
|
||||
Application entitlements can be used through authentik to manage authorization within an application (what areas of the app users or groups can access). Entitlements are scoped to a single application and can be bound to multiple users and/or groups (binding policies is not currently supported), giving them access to the entitlement. An application can either check for the name of the entitlement (via the `entitlements` scope), or via attributes stored in entitlements.
|
||||
|
||||
An authentik admin can create an entitlement [in the Admin interface](#create-an-application-entitlement) or using the [authentik API](/api).
|
||||
|
||||
Because entitlements exist within an application, names of entitlements must be unique within an application. This also means that entitlements are deleted when an application is deleted.
|
||||
|
||||
### Using entitlements
|
||||
|
||||
Entitlements to which a user has access can be retrieved using the `user.app_entitlements()` function in property mappings/policies. This function needs to be passed the specific application for which to get the entitlements. For example:
|
||||
|
||||
```python
|
||||
entitlements = [entitlement.name for entitlement in request.user.app_entitlements(provider.application)]
|
||||
return {
|
||||
"entitlements": entitlements,
|
||||
}
|
||||
```
|
||||
|
||||
### Attributes
|
||||
|
||||
Each entitlement can store attributes similar to user and group attributes. These attributes can be accessed in property mappings and passed to applications via `user.app_entitlements_attributes`. For example:
|
||||
|
||||
```python
|
||||
attrs = request.user.app_entitlements(provider.application)
|
||||
return {
|
||||
"my_attr": attrs.get("my_attr")
|
||||
}
|
||||
```
|
||||
|
||||
### Create an application entitlement
|
||||
|
||||
1. Open the Admin interface and navigate to **Applications -> Applications**.
|
||||
2. Click the name of the application for which you want to create an entitlement.
|
||||
3. Click the **Application entitlements** tab at the top of the page, and then click **Create entitlement**. Provide a name for the entitlement, enter any optional **Attributes**, and then click **Create**.
|
||||
4. In the list locate the entitlement to which you want to bind a user or group, and then **click the caret (>) to expand the entitlement details.**
|
||||
5. In the expanded area, click **Bind existing Group/User**.
|
||||
6. In the **Create Binding** box, select either the tab for **Group** or **User**, and then in the drop-down list, select the group or user.
|
||||
7. Optionally, configure additional settings for the binding, and then click **Create** to create the binding and close the box.
|
||||
|
||||
## Hide applications
|
||||
|
||||
To hide an application without modifying its policy settings or removing it, you can simply set the _Launch URL_ to `blank://blank`, which will hide the application from users.
|
||||
|
||||
Keep in mind that users still have access, so they can still authorize access when the login process is started from the application.
|
||||
|
||||
## Launch URLs
|
||||
|
||||
To give users direct links to applications, you can now use a URL like `https://authentik.company/application/launch/<slug>/`. If the user is already logged in, they will be redirected to the application automatically. Otherwise, they'll be sent to the authentication flow and, if successful, forwarded to the application.
|
||||
|
||||
## Backchannel providers
|
||||
|
||||
Backchannel providers can augment the functionality of applications by using additional protocols. The main provider of an application provides the SSO protocol that is used for logging into the application. Then, additional backchannel providers can be used for protocols such as [SCIM](../providers/scim/index.md) and [LDAP](../providers/ldap/index.md) to provide directory syncing.
|
||||
|
||||
Access restrictions that are configured on an application apply to all of its backchannel providers.
|
||||
33
docs/topics/add-secure-apps/flows-stages/bindings/index.md
Normal file
33
docs/topics/add-secure-apps/flows-stages/bindings/index.md
Normal file
@ -0,0 +1,33 @@
|
||||
---
|
||||
title: Bindings
|
||||
---
|
||||
|
||||
A binding is, simply put, a connection between two components (a flow, stage, policy, user, or group). The use of a binding adds additional functionality to one those existing components; for example, a policy binding can cause a new stage to be presented within a flow to a specific user or group.
|
||||
|
||||
:::info
|
||||
For information about creating and managing bindings, refer to [Working with bindings](./work_with_bindings.md).
|
||||
:::
|
||||
|
||||
Bindings are an important part of authentik; the majority of configuration options are set in bindings.
|
||||
|
||||
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.
|
||||
|
||||
The two most common types of bindings in authentik are:
|
||||
|
||||
- stage bindings
|
||||
- policy bindings
|
||||
- user and group bindings
|
||||
|
||||
A _stage binding_ connects a stage to a flow. The "additional content" (i.e. the content in the stage) is now added to the flow.
|
||||
|
||||
A _policy binding_ connects a specific policy to a flow or to a stage. With the binding, the flow (or stage) will now have additional content (i.e. the policy rules).
|
||||
|
||||
You can also bind groups and users to another component (a policy, a stage, a flow, etc.). For example, you can create a binding for a specific group, and then [bind that to a stage binding](../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_.
|
||||
|
||||
Bindings are also used for [Application Entitlements](../../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 the application.
|
||||
|
||||
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.
|
||||
|
||||
:::info
|
||||
Be aware that some stages and flows do not allow user or group bindings, because in certain scenarios (authentication or enrollment), the flow plan doesn't yet know who the user or group is.
|
||||
:::
|
||||
@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Work with bindings
|
||||
---
|
||||
|
||||
As covered in the [overview](./index.md), bindings interact with many other components.
|
||||
|
||||
For instructions to create a binding, refer to the documentation for the specific components:
|
||||
|
||||
- [Bind a stage to a flow](../stages/index.md#bind-a-stage-to-a-flow)
|
||||
- [Bind a policy to a flow or stage](../../../customize/policies/working_with_policies.md#bind-a-policy-to-a-flow-or-stage)
|
||||
- [Bind users or groups to a specific application with an Application Entitlement](../../applications/manage_apps.mdx#application-entitlements)
|
||||
- [Bind a policy to a specific application when you create a new application and provider](../../applications/manage_apps.mdx#instructions)
|
||||
- [Bind users and groups to a stage binding, to define whether or not that stage is shown](../stages/index.md#bind-users-and-groups-to-a-flows-stage-binding)
|
||||
229
docs/topics/add-secure-apps/flows-stages/flow/context/index.mdx
Normal file
229
docs/topics/add-secure-apps/flows-stages/flow/context/index.mdx
Normal file
@ -0,0 +1,229 @@
|
||||
---
|
||||
title: Flow Context
|
||||
toc_max_heading_level: 5
|
||||
---
|
||||
|
||||
Each flow execution has an independent _context_. This context holds all of the arbitrary data about that specific flow, data which can then be used and transformed by stages and policies.
|
||||
|
||||
## Managing data in a flow context
|
||||
|
||||
You create and manage the data for a context by configuring policies, stages, and bindings. As you plan your flow, and set up the required stages, etc. you are creating the context data for that flow.
|
||||
|
||||
For example, in the Identification Stage (part of the default login flow), you can define whether users will be prompted to enter an email address, a username, or both. All such information about the flow's configuration makes up the context.
|
||||
|
||||
Any data can be stored in the flow context, however there are some reserved keys in the context dictionary that are used by authentik stages.
|
||||
|
||||
To manage flow context on a more granular level, see [Setting flow context keys](../../../../customize/policies/expression/managing_flow_context_keys.md).
|
||||
|
||||
## Context dictionary and reserved keys
|
||||
|
||||
This section describes the data (the context) that are used in authentik, and provides a list of keys, what they are used for and when they are set.
|
||||
|
||||
:::warning
|
||||
Keys prefixed with `goauthentik.io` are used internally by authentik and are subject to change without notice, and should not be modified in policies in most cases.
|
||||
:::
|
||||
|
||||
### Common keys
|
||||
|
||||
#### `pending_user` ([User object](../../../../users-sources/user/user_ref.mdx#object-properties))
|
||||
|
||||
`pending_user` is used by multiple stages. In the context of most flow executions, it represents the data of the user that is executing the flow. This value is not set automatically, it is set via the [Identification stage](../../stages/identification/index.mdx).
|
||||
|
||||
Stages that require a user, such as the [Password stage](../../stages/password/index.md), the [Authenticator validation stage](../../stages/authenticator_validate/index.mdx) and others will use this value if it is set, and fallback to the request's users when possible.
|
||||
|
||||
#### `prompt_data` (Dictionary)
|
||||
|
||||
`prompt_data` is primarily used by the [Prompt stage](../../stages/prompt/index.md). The value of any field within a prompt stage is written to the `prompt_data` dictionary. For example, given a field with the _Field key_ `email` that was submitted with the value `foo@bar.baz` will result in the following context:
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt_data": {
|
||||
"email": "foo@bar.baz"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This data can be modified with policies. The data is also used by stages like [User write](../../stages/user_write.md), which takes data in `prompt_data` and writes it to `pending_user`.
|
||||
|
||||
#### `redirect` (string)
|
||||
|
||||
Stores the final redirect URL that the user's browser will be sent to after the flow is finished executing successfully. This is set when an un-authenticated user attempts to access a secured application, and when a user authenticates/enrolls with an external source.
|
||||
|
||||
#### `pending_user_identifier` (string)
|
||||
|
||||
If _Show matched user_ is disabled, this key will hold the user identifier entered by the user in the identification stage.
|
||||
|
||||
Stores the final redirect URL that the user's browser will be sent to after the flow is finished executing successfully. This is set when an un-authenticated user attempts to access a secured application, and when a user authenticates/enrolls with an external source.
|
||||
|
||||
#### `application` (Application object)
|
||||
|
||||
When an unauthenticated user attempts to access a secured resource, they are redirected to an authentication flow. The application they attempted to access will be stored in the key attached to this object. For example: `application.github`, with `application` being the key and `github` the value.
|
||||
|
||||
#### `source` (Source object)
|
||||
|
||||
When a user authenticates/enrolls via an external source, this will be set to the source they are using.
|
||||
|
||||
#### `outpost` (dictionary):ak-version[2024.10]
|
||||
|
||||
When a flow is executed by an Outpost (for example the [LDAP](../../../providers/ldap/index.md) or [RADIUS](../../../providers/radius/index.mdx)), this will be set to a dictionary containing the Outpost instance under the key `"instance"`.
|
||||
|
||||
### Scenario-specific keys
|
||||
|
||||
#### `is_sso` (boolean)
|
||||
|
||||
This key is set to `True` when the flow is executed from an "SSO" context. For example, this is set when a flow is used during the authentication or enrollment via an external source, and if a flow is executed to authorize access to an application.
|
||||
|
||||
#### `is_restored` (Token object)
|
||||
|
||||
This key is set when a flow execution is continued from a token. This happens for example when an [Email stage](../../stages/email/index.mdx) is used and the user clicks on the link within the email. The token object contains the key that was used to restore the flow execution. This field is also used by the [Source stage](../../stages/source/index.md) when returning back to the initial flow the Source stage was run on.
|
||||
|
||||
#### `is_redirected` (Flow object):ak-version[2024.12]
|
||||
|
||||
This key is set when the current flow was reached through a [Redirect stage](../../stages/redirect/index.md) in Flow mode.
|
||||
|
||||
### Stage-specific keys
|
||||
|
||||
#### Autosubmit stage
|
||||
|
||||
The autosubmit stage is an internal stage type that is not configurable via the API/Web interface. It is used in certain situations, where a POST request is sent from the browser, such as with SAML POST bindings. This works by using an HTML form that is submitted automatically.
|
||||
|
||||
##### `title` (string)
|
||||
|
||||
Optional title of the form shown to the user. Automatically set when this stage is used by the backend.
|
||||
|
||||
##### `url` (string)
|
||||
|
||||
URL that the form will be submitted to.
|
||||
|
||||
##### `attrs` (dictionary)
|
||||
|
||||
Key-value pairs of the data that is included in the form and will be submitted to `url`.
|
||||
|
||||
#### Captcha stage:ak-version[2024.6]
|
||||
|
||||
##### `captcha` (dictionary)
|
||||
|
||||
When `error_on_invalid_score` (TODO) is set to false on a captcha stage, after the execution of the captcha stage, this object will be set in the flow context.
|
||||
|
||||
It contains two keys, `response` which is the raw response from the specified captcha verification URL, and `stage`, which is a reference to the captcha stage that executed the test.
|
||||
|
||||
#### Consent stage
|
||||
|
||||
##### `consent_header` (string)
|
||||
|
||||
The title of the consent prompt shown. Set automatically when the consent stage is used with a OAuth2, Proxy or SAML provider.
|
||||
|
||||
##### `consent_permissions` (List of PermissionDict)
|
||||
|
||||
An optional list of all permissions that will be given to the application by granting consent. Not supported with SAML. When used with an OAuth2 or Proxy provider, this will be set based on the configured scopes.
|
||||
|
||||
#### Deny stage
|
||||
|
||||
##### `deny_message` (string)
|
||||
|
||||
Optionally overwrite the deny message shown, has a higher priority than the message configured in the stage.
|
||||
|
||||
#### User write stage
|
||||
|
||||
##### `groups` (List of [Group objects](../../../../users-sources/groups/index.mdx))
|
||||
|
||||
See [Group](../../../../users-sources/groups/index.mdx). If set in the flow context, the `pending_user` will be added to all the groups in this list.
|
||||
|
||||
If set, this must be a list of group objects and not group names.
|
||||
|
||||
##### `user_path` (string)
|
||||
|
||||
Path the `pending_user` will be written to. If not set in the flow, falls back to the value set in the user_write stage, and otherwise to the `users` path.
|
||||
|
||||
##### `user_type` (string)
|
||||
|
||||
Type the `pending_user` will be created as. Must be one of `internal`, `external` or `service_account`.
|
||||
|
||||
#### Password stage
|
||||
|
||||
##### `user_backend` (string)
|
||||
|
||||
Set by the [Password stage](../../stages/password/index.md) after successfully authenticating in the user. Contains a dot-notation to the authentication backend that was used to successfully authenticate the user.
|
||||
|
||||
##### `auth_method` (string)
|
||||
|
||||
Set by the [Password stage](../../stages/password/index.md), the [Authenticator validation stage](../../stages/authenticator_validate/index.mdx), the [OAuth2 Provider](../../../providers/oauth2/index.mdx), and the API authentication depending on which method was used to authenticate.
|
||||
|
||||
Possible options:
|
||||
|
||||
- `password` (Authenticated via the password in authentik's database)
|
||||
- `token` (Authenticated via API token)
|
||||
- `ldap` (Authenticated via LDAP bind from an LDAP source)
|
||||
- `auth_mfa` (Authentication via MFA device without password)
|
||||
- `auth_webauthn_pwl` (Passwordless authentication via WebAuthn with Passkeys)
|
||||
- `jwt` ([M2M](../../../providers/oauth2/client_credentials.mdx) authentication via an existing JWT)
|
||||
- `mtls` (Authentication via Certificate, see [Mutual TLS Stage](../../stages/mtls/index.md))
|
||||
|
||||
##### `auth_method_args` (dictionary)
|
||||
|
||||
Additional arguments used during the authentication. Value varies depending on `auth_method`.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
// List of the MFA device objects used during authentication
|
||||
// applies for `auth_method` `auth_mfa`
|
||||
"mfa_devices": [],
|
||||
// MFA device used for passwordless authentication, applies to
|
||||
// `auth_method` `auth_webauthn_pwl`
|
||||
"device": null,
|
||||
// the token identifier when `auth_method` `token` was used
|
||||
"identifier": "",
|
||||
// JWT information when `auth_method` `jwt` was used
|
||||
"jwt": {},
|
||||
"source": null,
|
||||
"provider": null,
|
||||
// Certificate used for authentication
|
||||
// applies for `auth_method` `mtls`
|
||||
"certificate": {}
|
||||
}
|
||||
```
|
||||
|
||||
#### Email stage
|
||||
|
||||
##### `email_sent` (boolean)
|
||||
|
||||
Boolean set to true after the email form the email stage has been sent.
|
||||
|
||||
##### `email` (string)
|
||||
|
||||
Optionally override the email address that the email will be sent to. If not set, defaults to the email of `pending_user`.
|
||||
|
||||
#### Identification stage
|
||||
|
||||
##### `pending_user_identifier` (string)
|
||||
|
||||
If _Show matched user_ is disabled, this key will be set to the user identifier entered by the user in the identification stage.
|
||||
|
||||
#### Redirect stage
|
||||
|
||||
##### `redirect_stage_target` (string):ak-version[2024.12]
|
||||
|
||||
[Set this key](../../../../customize/policies/expression/managing_flow_context_keys.md) in an Expression Policy to override [Redirect stage](../../stages/redirect/index.md) to force it to redirect to a certain URL or flow. This is useful when a flow requires that the redirection target be decided dynamically.
|
||||
|
||||
Use the format `ak-flow://{slug}` to use the Redirect stage in Flow mode. Any other format will result in the Redirect stage running in Static mode.
|
||||
|
||||
#### Mutual TLS Stage
|
||||
|
||||
##### `certificate` (dictionary):ak-version[2025.6]
|
||||
|
||||
This key is set by the Mutual TLS Stage during enrollment and contains data about the certificate supplied by the browser.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"serial_number": "1234",
|
||||
"subject": "CN=client",
|
||||
"issuer": "CN=authentik Test CA, O=authentik, OU=Self-signed",
|
||||
"fingerprint_sha256": "08:D4:A4:79:25:CA:C3:51:28:88:BB:30:C2:96:C3:44:5A:EB:18:07:84:CA:B4:75:27:74:61:19:8A:6A:AF:FC",
|
||||
"fingerprint_sha1": "5D:14:0D:5F:A2:7E:14:B0:F1:1D:6F:CD:E3:4B:81:68:71:24:1A:70",
|
||||
"raw": "-----BEGIN CERTIFICATE-----...."
|
||||
}
|
||||
```
|
||||
BIN
docs/topics/add-secure-apps/flows-stages/flow/create-flow.png
Normal file
BIN
docs/topics/add-secure-apps/flows-stages/flow/create-flow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 113 KiB |
@ -0,0 +1,11 @@
|
||||
---
|
||||
title: Default flows
|
||||
---
|
||||
|
||||
When you create a new provider, you can select certain default flows that will be used with the provider and its associated application. For example, you can [create a custom flow](../index.md#create-a-custom-flow) that override the defaults configured on the brand.
|
||||
|
||||
If no default flow is selected when the provider is created, to determine which flow should be used authentik will first check if there is a default flow configured in the active [**Brand**](../../../../sys-mgmt/brands.md). If no default is configured there, authentik will go through all flows with the matching designation, sorted by `slug` and evaluate policies bound directly to the flows, and the first flow whose policies allow access will be picked.
|
||||
|
||||
import DefaultFlowList from "../../flow/flow_list/\_defaultflowlist.mdx";
|
||||
|
||||
<DefaultFlowList />
|
||||
@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Example flows
|
||||
---
|
||||
|
||||
:::info
|
||||
You can apply these flows multiple times to stay updated, however this will discard all changes you've made.
|
||||
:::
|
||||
|
||||
:::info
|
||||
The example flows provided below will **override** the default flows, please review the contents of the example flow before importing and consider exporting the affected existing flows first.
|
||||
:::
|
||||
|
||||
## Enrollment (2 Stage)
|
||||
|
||||
Flow: right-click [here](/blueprints/example/flows-enrollment-2-stage.yaml) and save the file.
|
||||
|
||||
Sign-up flow for new users, which prompts them for their username, email, password and name. No verification is done. Users are also immediately logged on after this flow.
|
||||
|
||||
## Enrollment with email verification
|
||||
|
||||
Flow: right-click [here](/blueprints/example/flows-enrollment-email-verification.yaml) and save the file.
|
||||
|
||||
Same flow as above, with an extra email verification stage.
|
||||
|
||||
You'll probably have to adjust the Email stage and set your connection details.
|
||||
|
||||
## Two-factor Login
|
||||
|
||||
Flow: right-click [here](/blueprints/example/flows-login-2fa.yaml) and save the file.
|
||||
|
||||
Login flow which follows the default pattern (username/email, then password), but also checks for the user's OTP token, if they have one configured.
|
||||
|
||||
You can force two-factor authentication by editing the _Not configured action_ in the Authenticator Validation Stage.
|
||||
|
||||
## Login with conditional Captcha
|
||||
|
||||
Flow: right-click [here](/blueprints/example/flows-login-conditional-captcha.yaml) and save the file.
|
||||
|
||||
Login flow which conditionally shows the users a captcha, based on the reputation of their IP and Username.
|
||||
|
||||
By default, the captcha test keys are used. You can get a proper key [here](https://www.google.com/recaptcha/intro/v3.html).
|
||||
|
||||
## Recovery with email verification
|
||||
|
||||
Flow: right-click [here](/blueprints/example/flows-recovery-email-verification.yaml) and save the file.
|
||||
|
||||
Recovery flow, the user is sent an email after they've identified themselves. After they click on the link in the email, they are prompted for a new password and immediately logged on.
|
||||
|
||||
## User deletion
|
||||
|
||||
Flow: right-click [here](/blueprints/example/flows-unenrollment.yaml) and save the file.
|
||||
|
||||
Flow for users to delete their account.
|
||||
|
||||
:::warning
|
||||
This is done without any warning.
|
||||
:::
|
||||
@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Example policy snippets for flows
|
||||
---
|
||||
|
||||
### Redirect current flow to another URL
|
||||
|
||||
```python
|
||||
plan = request.context.get("flow_plan")
|
||||
if not plan:
|
||||
return False
|
||||
plan.redirect("https://foo.bar")
|
||||
return False
|
||||
```
|
||||
|
||||
This policy should be bound to the stage after your redirect should happen. For example, if you have an identification and a password stage, and you want to redirect after identification, bind the policy to the password stage. Make sure the stage binding's option _Evaluate when stage is run_ is enabled.
|
||||
|
||||
### Deny flow when user is authenticated
|
||||
|
||||
```python
|
||||
return not request.user.is_authenticated
|
||||
```
|
||||
|
||||
When used with authentik 2022.7 or later, set the flow _Denied action_ to _CONTINUE_. This will redirect already authenticated users to the default interface if they try to use the respective flow.
|
||||
@ -0,0 +1,11 @@
|
||||
---
|
||||
title: Headless
|
||||
---
|
||||
|
||||
The headless flow executor is used by clients that don't have access to the web interface. It is currently used by the LDAP and Radius outposts to authenticate users.
|
||||
|
||||
The following stages are supported:
|
||||
|
||||
- [**Identification stage**](../../stages/identification/index.mdx)
|
||||
- [**Password stage**](../../stages/password/index.md)
|
||||
- [**Authenticator Validation Stage**](../../stages/authenticator_validate/index.mdx)
|
||||
@ -0,0 +1,33 @@
|
||||
---
|
||||
title: Default
|
||||
---
|
||||
|
||||
This is the default, web-based environment that flows are executed in. All stages are compatible with this environment and no limitations are imposed.
|
||||
|
||||
:::info
|
||||
All flow executors use the same [API](/api/docs/flow-executor), which allows for the implementation of custom flow executors.
|
||||
:::
|
||||
|
||||
## Layouts
|
||||
|
||||
Starting with authentik 2022.5, the layout of the default flow executor can be changed. Below are examples for the available options:
|
||||
|
||||
### Stacked (default)
|
||||
|
||||
|
||||
|
||||
### Content besides logo (left)
|
||||
|
||||
|
||||
|
||||
### Content besides logo (right)
|
||||
|
||||
|
||||
|
||||
### Sidebar (left)
|
||||
|
||||
|
||||
|
||||
### Sidebar (right)
|
||||
|
||||
|
||||
@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Simplified flow executor
|
||||
authentik_version: "2024.6.1"
|
||||
---
|
||||
|
||||
A simplified web-based flow executor that authentik automatically uses for older browsers that do not support modern web technologies.
|
||||
|
||||
Currently this flow executor is automatically used for the following browsers:
|
||||
|
||||
- Internet Explorer
|
||||
- Microsoft Edge (up to and including version 18)
|
||||
|
||||
The following stages are supported:
|
||||
|
||||
- [**Identification stage**](../../stages/identification/index.mdx)
|
||||
|
||||
:::info
|
||||
Only user identifier and user identifier + password stage configurations are supported; sources and passwordless configurations are not supported.
|
||||
:::
|
||||
|
||||
- [**Password stage**](../../stages/password/index.md)
|
||||
- [**Authenticator Validation Stage**](../../stages/authenticator_validate/index.mdx)
|
||||
|
||||
Compared to the [default flow executor](./if-flow.md), this flow executor does _not_ support the following features:
|
||||
|
||||
- Localization
|
||||
- Theming (Dark / light themes)
|
||||
- Theming (Custom CSS)
|
||||
- Stages not listed above
|
||||
- Flow inspector
|
||||
@ -0,0 +1,9 @@
|
||||
---
|
||||
title: User settings
|
||||
---
|
||||
|
||||
The user interface (/if/user/) uses a specialized flow executor to allow individual users to customize their profile. A user's profile consists of key/value fields, so this executor only supports Prompt or User Write stages. If the configured flow contains another stage, a button will be shown to open the default executor.
|
||||
|
||||
Because the stages in a flow can change during its execution, be aware that configuring this executor to use any stage type other than Prompt or User Write will automatically trigger a redirect to the standard executor.
|
||||
|
||||
An admin can customize which fields can be changed by the user by updating the default-user-settings-flow, or copying it to create a new flow with a Prompt Stage and a User Write Stage. Different variants of your flow can be applied to different [Brands](../../../../sys-mgmt/brands.md) on the same authentik instance.
|
||||
BIN
docs/topics/add-secure-apps/flows-stages/flow/flow-inspector.png
Normal file
BIN
docs/topics/add-secure-apps/flows-stages/flow/flow-inspector.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 564 KiB |
@ -0,0 +1,13 @@
|
||||
- **Authentication**: this option designates a flow to be used for authentication. The authentication flow should always contain a [**User Login**](../../stages/user_login/index.md) stage, which attaches the staged user to the current session.
|
||||
|
||||
- **Authorization**: designates a flow to be used for authorization of an application. Can be used to add additional verification steps before the user is allowed to access an application. This flow is defined per provider, when the provider is created, to state whether implicit or explicit authorization is required.
|
||||
|
||||
- **Enrollment**: designates a flow for enrollment. This flow can contain any amount of verification stages, such as [**Email**](../../stages/email/index.mdx) or **Captcha**. At the end, to create the user, you can use the [**User Write**](../../stages/user_write.md) stage, which either updates the currently staged user, or if none exists, creates a new one.
|
||||
|
||||
- **Invalidation**: designates a default flow to be used to invalidate a session. Use `default-invalidation-flow` for invalidation from authentik itself, or use `default-provider-invalidation-flow` to invalidate when the session of an application ends. When you use the `default-invalidation-flow` as a global invalidation flow, it should contain a [**User Logout**](../../stages/user_logout.md) stage. When you use the `default-provider-invalidation-flow` (supported with OIDC, SAML, Proxy, and RAC providers), you can configure this default flow to present users log-off options such as "log out of the app but remain logged in to authentik" or "return to the **My Applications** page", or "log out completely". (Alternatively, you can create a custom invalidation flow, with a branded background image.)
|
||||
|
||||
- **Recovery**: designates a flow for recovery. This flow normally contains an [**Identification**](../../stages/identification/index.mdx) stage to find the user. It can also contain any amount of verification stages, such as [**Email**](../../stages/email/index.mdx) or [**CAPTCHA**](../../stages/captcha/index.md). Afterwards, use the [**Prompt**](../../stages/prompt/index.md) stage to ask the user for a new password and the [**User Write**](../../stages/user_write.md) stage to update the password.
|
||||
|
||||
- **Stage configuration**: designates a flow for general setup. This designation doesn't have any constraints in what you can do. For example, by default this designation is used to configure authenticators, like change a password and set up TOTP.
|
||||
|
||||
- **Unenrollment**: designates a flow for unenrollment. This flow can contain any amount of verification stages, such as [**email**](../../stages/email/index.mdx) or [**Captcha**](../../stages/captcha/index.md). As a final stage, to delete the account, use the [**user_delete**](../../stages/user_delete.md) stage.
|
||||
90
docs/topics/add-secure-apps/flows-stages/flow/index.md
Normal file
90
docs/topics/add-secure-apps/flows-stages/flow/index.md
Normal file
@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Flows
|
||||
---
|
||||
|
||||
Flows are a major component in authentik. In conjunction with stages and [policies](../../../customize/policies/index.md), flows are at the heart of our system of building blocks, used to define and execute the workflows of authentication, authorization, enrollment, and user settings.
|
||||
|
||||
There are over a dozen default, out-of-the box flows available in authentik. Users can decide if they already have everything they need with the [default flows](../flow/examples/default_flows.md) or if they want to [create](#create-a-custom-flow) their own custom flow, using the Admin interface, Terraform, or via the API.
|
||||
|
||||
A flow is a method of describing a sequence of stages. A stage represents a single verification or logic step. By connecting a series of stages within a flow (and optionally attaching policies as needed) you can build a highly flexible process for authenticating users, enrolling them, and more.
|
||||
|
||||
For example a standard login flow would consist of the following stages:
|
||||
|
||||
- **Identification stage**: user identifies themselves via a username or email address
|
||||
- **Password stage**: the user's password is checked against the hash in the database
|
||||
- **Login stage**: this stage attaches a currently pending user to the current session
|
||||
|
||||
When these stages are successfully completed, authentik logs in the user.
|
||||
|
||||
|
||||
|
||||
By default, policies are evaluated dynamically, right before the stage (to which a policy is bound) is presented to the user. This flexibility allows the login process to continue, change, or stop, based on the success or failure of each policy.
|
||||
|
||||
This default behaviour can be altered by enabling the **Evaluate when flow is planned** option on the stage binding. With this setting a _flow plan_ containing all stages is generated upon flow execution. This means that all attached policies are evaluated upon execution. For more information about flow plans, read our [flow context documentation](./context/index.mdx).
|
||||
|
||||
## Permissions
|
||||
|
||||
Flows can have [policies](../stages/index.md) assigned to them. These policies determine if the current user is allowed to see and use this flow.
|
||||
|
||||
Keep in mind that in certain circumstances, policies cannot match against users and groups as there is no authenticated user yet.
|
||||
|
||||
## Import & Export
|
||||
|
||||
Flows can be imported and exported to share with other people, the community, and for troubleshooting. Flows can be imported to apply new functionality and apply existing workflows.
|
||||
|
||||
Download our [Example flows](./examples/flows.md) and then import them into your authentik instance.
|
||||
|
||||
Starting with authentik 2022.8, flows will be exported as YAML, but JSON-based flows can still be imported.
|
||||
|
||||
## Create a custom flow
|
||||
|
||||
To create a flow, follow these steps:
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
2. In the Admin interface, navigate to **Flows and Stages -> Flows**.
|
||||
3. Click **Create**, define the flow using the [configuration settings](#flow-configuration-options) described below, and then click **Finish**.
|
||||
|
||||
After creating the flow, you can then [bind specific stages](../stages/index.md#bind-a-stage-to-a-flow) to the flow and [bind policies](../../../customize/policies/working_with_policies.md) to the flow to further customize the user's log in and authentication process.
|
||||
|
||||
To determine which flow should be used, authentik will first check which default authentication flow is configured in the active [**Brand**](../../../sys-mgmt/brands.md). If no default is configured there, the policies in all flows with the matching designation are checked, and the first flow with matching policies sorted by `slug` will be used.
|
||||
|
||||
## Flow configuration options
|
||||
|
||||
When creating or editing a flow in the UI of the Admin interface, you can set the following configuration options.
|
||||
|
||||
|
||||
|
||||
**Name**: Enter a descriptive name. This is the name that will appear on the list of flows in the Admin interface.
|
||||
|
||||
**Title**: This is the title that will appear on the flow as the end-user logs in and encounters the flow.
|
||||
|
||||
**Slug**: The slug will be used, and appear, in the URL when the flow is in use.
|
||||
|
||||
**Designation**: Flows are designated for a single purpose. This designation changes when a flow is used. The following designations are available:
|
||||
|
||||
import Defaultflowlist from "../flow/flow_list/\_defaultflowlist.mdx";
|
||||
|
||||
<Defaultflowlist />
|
||||
|
||||
**Authentication**: Using this option, you can configure whether the the flow requires initial authentication or not, whether the user must be a superuser, if the flow can only be started after being redirected by a [Redirect stage](../stages/redirect/index.md), or if the flow requires an outpost.
|
||||
|
||||
**Behavior settings**:
|
||||
|
||||
- **Compatibility mode**: Toggle this option on to increase compatibility with password managers and mobile devices. Password managers like [1Password](https://1password.com/), for example, don't need this setting to be enabled, when accessing the flow from a desktop browser. However accessing the flow from a mobile device might necessitate this setting to be enabled.
|
||||
|
||||
The technical reasons for this settings' existence is due to the JavaScript libraries we're using for the default flow interface. These interfaces are implemented using [Lit](https://lit.dev/), which is a modern web development library. It uses a web standard called ["Shadow DOMs"](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM), which makes encapsulating styles simpler. Due to differences in Browser APIs, many password managers are not compatible with this technology.
|
||||
|
||||
When the compatibility mode is enabled, authentik uses a polyfill which emulates the Shadow DOM APIs without actually using the feature, and instead a traditional DOM is rendered. This increases support for password managers, especially on mobile devices.
|
||||
|
||||
- **Denied action**: Configure what happens when access to a flow is denied by a policy. By default, authentik will redirect to a `?next` parameter if set, and otherwise show an error message.
|
||||
- `MESSAGE_CONTINUE`: Show a message if no `?next` parameter is set, otherwise redirect.
|
||||
- `MESSAGE`: Always show error message.
|
||||
- `CONTINUE`: Always redirect, either to `?next` if set, otherwise to the default interface.
|
||||
|
||||
- **Policy engine mode**: Configure the flow to succeed in _any_ policy passes, or only if _all_ policies pass.
|
||||
|
||||
**Appearance Settings**:
|
||||
|
||||
- **Layout**: select how the UI displays the flow when it is executed; with stacked elements, content left or right, and sidebar left or right.
|
||||
|
||||
- **Background**: optionally, select a background image for the UI presentation of the flow. This overrides any default background image configured in the [Branding settings](../../../sys-mgmt/brands.md#branding-settings).
|
||||
63
docs/topics/add-secure-apps/flows-stages/flow/inspector.md
Normal file
63
docs/topics/add-secure-apps/flows-stages/flow/inspector.md
Normal file
@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Flow Inspector
|
||||
---
|
||||
|
||||
The flow inspector, introduced in 2021.10, allows administrators to visually determine how custom flows work, inspect the current [flow context](./context/index.mdx), and investigate issues.
|
||||
|
||||
As shown in the screenshot below, the flow inspector displays next to the selected flow (in this case, "Change Password"), with [information](#flow-inspector-details) about that specific flow and flow context.
|
||||
|
||||
|
||||
|
||||
## Access the Flow Inspector
|
||||
|
||||
:::info
|
||||
Be aware that when running a flow with the inspector enabled, the flow is still executed normally. This means that for example, a [User write](../stages/user_write.md) stage _will_ write user data.
|
||||
:::
|
||||
|
||||
The inspector is accessible to users that have been granted the [permission](../../../users-sources/access-control/permissions.md) **Can inspect a Flow's execution**, either directly or through a role. Superusers can always inspect flow executions.
|
||||
|
||||
When developing authentik with the debug mode enabled, the inspector is enabled by default and can be accessed by both unauthenticated users and standard users. However the debug mode should only be used for the development of authentik. So unless you are a developer and need the more verbose error information, the best practice for using the flow inspector is to assign the permission, not use debug mode.
|
||||
|
||||
Starting with authentik 2025.2, for users with appropriate permissions to access the inspector a button is shown in the top right of the [default flow executor](./executors/if-flow.md) which opens the flow inspector.
|
||||
|
||||
### Manually running a flow with the inspector
|
||||
|
||||
1. To access the inspector, open the Admin interface and navigate to **Flows and Stages -> Flows**.
|
||||
|
||||
2. Select the specific flow that you want to inspect by clicking its name in the list.
|
||||
|
||||
3. On the Flow's detail page, on the left side under **Execute Flow**, click **with inspector**.
|
||||
|
||||
4. The selected flow will launch in a new browser tab, with the flow inspector displayed to the right.
|
||||
|
||||
Alternatively, a user with the correct permission can launch the inspector by adding the query parameter `?inspector` to the URL when the URL opens on a flow.
|
||||
|
||||
:::info
|
||||
Troubleshooting:
|
||||
|
||||
- If the flow inspector does not launch and a "Bad request" error displays, this is likely either because you selected a flow that has a policy bound directly to it that prevents access (so the inspector won't open because the flow can't be executed) or because you do not have view permission on that specific flow.
|
||||
:::
|
||||
|
||||
### Flow Inspector Details
|
||||
|
||||
The following information is shown in the inspector:
|
||||
|
||||
#### Next stage
|
||||
|
||||
This is the currently planned next stage. If you have stage bindings configured to `Evaluate when flow is planned`\_`, then you will see the result here. If, however, you have them configured to re-evaluate (`Evaluate when stage is run`), then this will not show up here, since the results will vary based on your input.
|
||||
|
||||
Shown is the name and kind of the stage, as well as the unique ID.
|
||||
|
||||
#### Plan history
|
||||
|
||||
Here you can see an overview of which stages have run, which is currently active, and which is planned to come next. Same caveats as above apply.
|
||||
|
||||
#### Current plan context
|
||||
|
||||
This shows you the current context. This will contain fields depending on the same, after an identification stage for example you would see "pending_user" defined.
|
||||
|
||||
This data is not cleaned, so if your flow involves inputting a password, it will be shown here too.
|
||||
|
||||
#### Session ID
|
||||
|
||||
The unique ID for the currently used session. This can be used to debug issues with flows restarting/losing state.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 2.8 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 2.8 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 2.2 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 2.3 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 2.8 MiB |
BIN
docs/topics/add-secure-apps/flows-stages/flow/simple_stages.png
Normal file
BIN
docs/topics/add-secure-apps/flows-stages/flow/simple_stages.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Duo Authenticator Setup stage
|
||||
---
|
||||
|
||||
This stage configures a Duo authenticator. To get the API Credentials for this stage, open your Duo Admin dashboard.
|
||||
|
||||
Go to Applications, click on Protect an Application and search for "Auth API". Click on Protect.
|
||||
|
||||
Copy all of the integration key, secret key and API hostname, and paste them in the Stage form.
|
||||
|
||||
Devices created reference the stage they were created with, since the API credentials are needed to authenticate. This also means when the stage is deleted, all devices are removed.
|
||||
|
||||
## Importing users
|
||||
|
||||
:::info
|
||||
Due to the way the Duo API works, authentik can only automatically import existing Duo users when a Duo MFA or higher license is active.
|
||||
:::
|
||||
|
||||
To import a device, open the Stages list in the authentik Admin interface. On the right next to the import button you'll see an import button, with which you can import Duo devices to authentik users.
|
||||
|
||||
The Duo username can be found by navigating to your Duo Admin dashboard and selecting _Users_ in the sidebar. Optionally if you have multiple users with the same username, you can click on a User and copy their ID from the URL, and use that to import the device.
|
||||
|
||||
### Older versions
|
||||
|
||||
You can call the `/api/v3/stages/authenticator/duo/{stage_uuid}/import_devices/` endpoint ([see here](https://goauthentik.io/api/#post-/stages/authenticator/duo/-stage_uuid-/import_devices/)) using the following parameters:
|
||||
|
||||
- `duo_user_id`: The Duo User's ID. This can be found in the Duo Admin Portal, navigating to the user list and clicking on a single user. Their ID is shown in th URL.
|
||||
- `username`: The authentik user's username to assign the device to.
|
||||
|
||||
Additionally, you need to pass `stage_uuid` which is the `authenticator_duo` stage, in which you entered your API credentials.
|
||||
@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Email Authenticator Setup stage
|
||||
authentik_version: "2025.2"
|
||||
---
|
||||
|
||||
This stage configures an email-based authenticator that sends a one-time code to a user's email address for authentication.
|
||||
|
||||
When a user goes through a flow that includes this stage, they are prompted for their email address (if not already set). The user then receives an email with a one-time code, which they enter into the authentik Login panel.
|
||||
|
||||
The email address will be saved and can be used with the [Authenticator validation](../authenticator_validate/index.mdx) stage for future authentications.
|
||||
|
||||
## Flow integration
|
||||
|
||||
To use the Email Authenticator Setup stage in a flow, follow these steps:
|
||||
|
||||
1. [Create](../../flow/index.md#create-a-custom-flow) a new flow or edit an existing one.
|
||||
2. On the flow's **Stage Bindings** tab, click **Create and bind stage** to create and add the Email Authenticator Setup stage. (If the stage already exists, click **Bind existing stage**.)
|
||||
3. Configure the stage settings as described below.
|
||||
- **Name**: provide a descriptive name, such as Email Authenticator Setup.
|
||||
- **Authenticator type name**: define the display name for this stage.
|
||||
- **Use global connection settings**: the stage can be configured in two ways: global settings or stage-specific settings.
|
||||
- Enable (toggle on) the **Use global connection settings** option to use authentik's global email configuration. Note that you must already have configured your environment variables to use the global settings. See instructions for [Docker Compose](../../../../install-config/install/docker-compose#email-configuration-optional-but-recommended) and for [Kubernetes](../../../../install-config/install/kubernetes#optional-step-configure-global-email-credentials).
|
||||
|
||||
- If you need different email settings for this stage, disable (toggle off) **Use global connection settings** and configure the following options:
|
||||
|
||||
- **Connection settings**:
|
||||
- **SMTP Host**: SMTP server hostname (default: localhost)
|
||||
- **SMTP Port**: SMTP server port number(default: 25)
|
||||
- **SMTP Username**: SMTP authentication username (optional)
|
||||
- **SMTP Password**: SMTP authentication password (optional)
|
||||
- **Use TLS**: Enable TLS encryption
|
||||
- **Use SSL**: Enable SSL encryption
|
||||
- **Timeout**: Connection timeout in seconds (default: 10)
|
||||
- **From Address**: Email address that messages are sent from (default: system@authentik.local)
|
||||
|
||||
- **Stage-specific settings**:
|
||||
- **Subject**: Email subject line (default: "authentik Sign-in code")
|
||||
- **Token Expiration**: Time in minutes that the sent token is valid (default: 30)
|
||||
- **Configuration flow**: select the flow to which you are binding this stage.
|
||||
|
||||
4. Click **Update** to complete the creation and binding of the stage to the flow.
|
||||
|
||||
The new Email Authenticator Setup stage now appears on the **Stage Bindings** tab for the flow.
|
||||
@ -0,0 +1,75 @@
|
||||
---
|
||||
title: Endpoint Authenticator Google Device Trust Connector Stage
|
||||
authentik_version: "2024.10"
|
||||
authentik_preview: true
|
||||
authentik_enterprise: true
|
||||
---
|
||||
|
||||
With this stage, authentik can validate users' Chrome browsers and ensure that users' devices are compliant and up-to-date.
|
||||
|
||||
:::info
|
||||
This stage only works with Google Chrome, as it relies on the [Chrome Verified Access API](https://developers.google.com/chrome/verified-access).
|
||||
:::
|
||||
|
||||
## Configuration
|
||||
|
||||
The main steps to set up your Google workspace are as follows:
|
||||
|
||||
- [Configuration](#configuration)
|
||||
- [Create a Google cloud project](#create-a-google-cloud-project)
|
||||
- [Create a service account](#create-a-service-account)
|
||||
- [Set credentials for the service account](#set-credentials-for-the-service-account)
|
||||
- [Create the stage](#create-the-stage)
|
||||
|
||||
For detailed instructions, refer to Google documentation.
|
||||
|
||||
### Create a Google cloud project
|
||||
|
||||
1. Open the Google Cloud Console (https://cloud.google.com/cloud-console).
|
||||
2. In upper left, click the drop-down box to open the **Select a project** box, and then select **New Project**.
|
||||
3. Create a new project and give it a name like "authentik GWS".
|
||||
4. Use the search bar at the top of your new project page to search for "API Library".
|
||||
5. On the **API Library** page, use the search bar again to find "Chrome Verified Access API".
|
||||
6. On the **Chrome Verified Access API** page, click **Enable**.
|
||||
|
||||
### Create a service account
|
||||
|
||||
1. After the new Chrome Verified Access API is enabled (it might take a few minutes), return to the Google Cloud console home page (click on **Google Cloud** in upper left).
|
||||
2. Use the search bar to find and navigate to the **IAM** page.
|
||||
3. On the **IAM** page, click **Service Accounts** in the left navigation pane.
|
||||
4. At the top of the **Service Accounts** page, click **Create Service Account**.
|
||||
|
||||
- Under **Service account details** page, define the **Name** and **Description** for the new service account, and then click **Create and Continue**.
|
||||
- Under **Grant this service account access to project** you do not need to define a role, so click **Continue**.
|
||||
- Under **Grant users access to project** you do not need to define a role, so click **Done** to complete the creation of the service account.
|
||||
|
||||
### Set credentials for the service account
|
||||
|
||||
1. On the **Service accounts** page, click the account that you just created.
|
||||
2. Click the **Keys** tab at top of the page, the click **Add Key -> Create new key**.
|
||||
3. In the Create box, select JSON as the key type, and then click **Create**.
|
||||
A pop-up displays with the private key, and the key is saved to your computer as a JSON file.
|
||||
Later, when you create the stage in authentik, you will add this key in the **Credentials** field.
|
||||
4. On the service account page, click the **Details** tab, and expand the **Advanced settings** area.
|
||||
5. Log in to the Admin Console, and then navigate to **Chrome browser -> Connectors**.
|
||||
6. Click on **New Provider Configuration**.
|
||||
7. Under Universal Device Trust, click "Set up".
|
||||
8. Enter a name.
|
||||
9. Enter the URL: https://authentik.company/endpoint/gdtc/chrome/
|
||||
10. Under Service accounts, enter the full name of the service account created above, for example `authentik-gdtc-docs@authentik-enterprise-dev.iam.gserviceaccount.com`.
|
||||
|
||||
### Create the stage
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
|
||||
2. In the Admin interface, navigate to **Flows -> Stages**.
|
||||
|
||||
3. Click **Create**, and select **Endpoint Authenticator Google Device Trust Connector Stage**, and in the **New stage** box, define the following fields:
|
||||
- **Name**: define a descriptive name, such as "chrome-device-trust".
|
||||
|
||||
- **Google Verified Access API**
|
||||
- **Credentials**: paste the contents of the JSON file (the key) that you downloaded earlier.
|
||||
|
||||
4. Click **Finish**.
|
||||
|
||||
After creating the stage, it can be used in any flow. Compared to other Authenticator stages, this stage does not require enrollment. Instead of adding an [Authenticator Validation Stage](../authenticator_validate/index.mdx), this stage only verifies the users' browser.
|
||||
@ -0,0 +1,80 @@
|
||||
---
|
||||
title: SMS Authenticator Setup stage
|
||||
---
|
||||
|
||||
This stage configures an SMS-based authenticator using either Twilio, or a generic HTTP endpoint.
|
||||
|
||||
## Providers
|
||||
|
||||
#### Twilio
|
||||
|
||||
Navigate to https://console.twilio.com/, and log in to your existing account, or create a new one.
|
||||
|
||||
In the sidebar, navigate to _Explore Products_, then _Messaging_, and _Services_ below that.
|
||||
|
||||
Click on _Create Messaging Service_ to create a new set of API credentials.
|
||||
|
||||
Give the service a Name, and select _Verify users_ as a use-case.
|
||||
|
||||
In the next step, add an address from your Sender Pool. Instructions on how to create numbers are not covered here, please check the Twilio documentation [here](https://www.twilio.com/docs).
|
||||
|
||||
The other two steps can be skipped using the _Skip setup_ button.
|
||||
|
||||
Navigate back to the root of your Twilio console, and copy the Auth token. This is the value for the _Twilio Auth Token_ field in authentik. Copy the value of **Account SID**. This is the value for the _Twilio Account SID_ field in authentik.
|
||||
|
||||
#### Generic
|
||||
|
||||
For the generic provider, a POST request will be sent to the URL you have specified in the _External API URL_ field. The request payload looks like this
|
||||
|
||||
```json
|
||||
{
|
||||
"From": "<value of the *From number* field>",
|
||||
"To": "<the phone number of the user's device>",
|
||||
"Body": "<the token that the user needs to authenticate>,
|
||||
}
|
||||
```
|
||||
|
||||
Authentication can either be done as HTTP Basic, or via a Bearer Token. Any response with status 400 or above is counted as failed, and will prevent the user from proceeding.
|
||||
|
||||
Starting with authentik 2022.10, a custom webhook mapping can be specified to freely customize the payload of the request. For example:
|
||||
|
||||
```python
|
||||
return {
|
||||
"from": stage.from_number,
|
||||
"to": device.phone_number,
|
||||
"body": f"foo bar baz {token}".
|
||||
}
|
||||
```
|
||||
|
||||
## Verify only
|
||||
|
||||
To only verify the validity of a users' phone number, without saving it in an easily accessible way, you can enable this option. Phone numbers from devices enrolled through this stage will only have their hashed phone number saved. These devices can also not be used with the [Authenticator validation](../authenticator_validate/index.mdx) stage.
|
||||
|
||||
## Limiting phone numbers
|
||||
|
||||
To limit phone numbers (for example to a specific region code), you can create an expression policy to validate the phone number, and use a prompt stage for input.
|
||||
|
||||
### Expression policy
|
||||
|
||||
Create an expression policy to check the phone number:
|
||||
|
||||
```python
|
||||
# Trim all whitespace in and around the user input
|
||||
phone_number = regex_replace(request.context["prompt_data"]["phone"], r'\s+', '')
|
||||
|
||||
# Only allow a specific region code
|
||||
if phone_number.startswith("+1234"):
|
||||
return True
|
||||
ak_message("Invalid phone number or missing region code")
|
||||
return False
|
||||
```
|
||||
|
||||
### Prompt stage
|
||||
|
||||
Create a text prompt field with the _field key_ set to `phone`. Make sure it is selected as a required field.
|
||||
|
||||
Create a prompt stage with the phone field you created above, and select the expression policy created above as validation policy.
|
||||
|
||||
### Flow
|
||||
|
||||
Create a new flow to enroll SMS devices. Bind the prompt stage created above as first stage, and create/bind a _SMS Authenticator Setup Stage_, and bind it to the flow as second stage. This stage will see the `phone` field in the flow's context's `prompt_data`, and not prompt the user for a phone number.
|
||||
@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Static Authenticator Setup stage
|
||||
---
|
||||
|
||||
This stage configures static Tokens, which can be used as a backup method to time-based OTP tokens.
|
||||
|
||||
You can configure how many tokens are shown to the user.
|
||||
@ -0,0 +1,9 @@
|
||||
---
|
||||
title: TOTP Authenticator Setup stage
|
||||
---
|
||||
|
||||
This stage configures a time-based OTP Device, such as Google Authenticator or Authy.
|
||||
|
||||
You can configure how many digits should be used for the OTP Token.
|
||||
|
||||
The Config URL's Issuer is set based on the currently active brand's branding title. The default setup can cause issues if the same username is used on multiple authentik issues within the same authenticator app, so changing the brand title is recommended.
|
||||
@ -0,0 +1,82 @@
|
||||
---
|
||||
title: Authenticator Validation stage
|
||||
---
|
||||
|
||||
This stage validates an already configured Authenticator Device. This device has to be configured using any of the other authenticator stages:
|
||||
|
||||
- [Duo authenticator stage](../authenticator_duo/index.mdx)
|
||||
- [Email authenticator stage](../authenticator_email/index.md)
|
||||
- [SMS authenticator stage](../authenticator_sms/index.mdx)
|
||||
- [Static authenticator stage](../authenticator_static/index.md)
|
||||
- [TOTP authenticator stage](../authenticator_totp/index.md)
|
||||
- [WebAuthn authenticator stage](../authenticator_webauthn/index.mdx)
|
||||
|
||||
You can select which type of device classes are allowed.
|
||||
|
||||
Using the `Not configured action`, you can choose what happens when a user does not have any matching devices.
|
||||
|
||||
- Skip: Validation is skipped and the flow continues
|
||||
- Deny: Access is denied, the flow execution ends
|
||||
- Configure: This option requires a _Configuration stage_ to be set. The validation stage will be marked as successful, and the configuration stage will be injected into the flow.
|
||||
|
||||
By default, authenticator validation is required every time the flow containing this stage is executed. To only change this behavior, set _Last validation threshold_ to a non-zero value. (Requires authentik 2022.5)
|
||||
Keep in mind that when using Code-based devices (TOTP, Static and SMS), values lower than `seconds=30` cannot be used, as with the way TOTP devices are saved, there is no exact timestamp.
|
||||
|
||||
### Options
|
||||
|
||||
#### 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 users devices within the selected classes are checked.
|
||||
|
||||
#### Passwordless authentication
|
||||
|
||||
:::caution
|
||||
Firefox has some known issues regarding TouchID (see https://bugzilla.mozilla.org/show_bug.cgi?id=1536482)
|
||||
:::
|
||||
|
||||
Passwordless authentication currently only supports WebAuthn devices, which provides for the use of passkeys, security keys and biometrics. For an alternate passwordless setup, see [Password stage](../password/index.md#passwordless-login), which supports other types.
|
||||
|
||||
To configure passwordless authentication, create a new Flow with the designation set to _Authentication_.
|
||||
|
||||
As first stage, add an _Authenticator validation_ stage, with the WebAuthn device class allowed.
|
||||
After this stage you can bind any additional verification stages.
|
||||
As final stage, bind a _User login_ stage.
|
||||
|
||||
Users can either access this flow directly via its URL, or you can modify any Identification stage's _Passwordless flow_ setting to add a direct link to this flow.
|
||||
|
||||
#### Logging
|
||||
|
||||
Logins which used Passwordless authentication have the _auth_method_ context variable set to `auth_webauthn_pwl`, and the device used is saved in the arguments. Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"auth_method": "auth_webauthn_pwl",
|
||||
"http_request": {
|
||||
"args": {
|
||||
"query": ""
|
||||
},
|
||||
"path": "/api/v3/flows/executor/test/",
|
||||
"method": "GET"
|
||||
},
|
||||
"auth_method_args": {
|
||||
"device": {
|
||||
"pk": 1,
|
||||
"app": "authentik_stages_authenticator_webauthn",
|
||||
"name": "test device",
|
||||
"model_name": "webauthndevice"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### WebAuthn Device type restrictions:ak-version[2024.4]
|
||||
|
||||
Optionally restrict which WebAuthn device types can be used to authenticate.
|
||||
|
||||
When no restriction is set, all WebAuthn devices a user has registered are allowed.
|
||||
|
||||
These restrictions only apply to WebAuthn devices created with authentik 2024.4 or later.
|
||||
|
||||
#### Automatic device selection
|
||||
|
||||
If the user has more than one device, the user is prompted to select which device they want to use for validation. After the user successfully authenticates with a certain device, that device is marked as "last used". In subsequent prompts by the Authenticator validation stage, the last used device is automatically selected for the user. Should they wish to use another device, the user can return to the device selection screen.
|
||||
@ -0,0 +1,31 @@
|
||||
---
|
||||
title: WebAuthn / FIDO2 / Passkeys Authenticator setup stage
|
||||
---
|
||||
|
||||
This stage configures an authenticator stage for using WebAuthn, FIDO2, Passkeys. This stage supports:
|
||||
|
||||
- **Security Keys**: Physical devices like YubiKey, Google Titan, etc.
|
||||
- **Platform Authenticators**: Built-in authenticators like Windows Hello, Touch ID, Face ID
|
||||
- **Mobile Devices**: Using device biometrics or security keys via mobile browsers
|
||||
|
||||
### Options
|
||||
|
||||
#### User verification
|
||||
|
||||
Configure if authentik should require, prefer or discourage user verification for the authenticator. For example when using a virtual authenticator like Windows Hello, this setting controls if a PIN is required.
|
||||
|
||||
#### Resident key requirement
|
||||
|
||||
Configure if the created authenticator is stored in the encrypted memory on the device or in persistent memory. When configuring [passwordless login](../identification/index.mdx#passwordless-flow), this should be set to either _Preferred_ or _Required_, otherwise the authenticator cannot be used for passwordless authentication.
|
||||
|
||||
#### Authenticator Attachment
|
||||
|
||||
Configure if authentik will require either a removable device (like a YubiKey, Google Titan, etc) or a non-removable device (like Windows Hello, TouchID or password managers), or not send a requirement.
|
||||
|
||||
#### Device type restrictions:ak-version[2024.4]
|
||||
|
||||
Optionally restrict the types of devices allowed to be enrolled. This option can be used to ensure users are only able to enroll FIPS-compliant devices for example.
|
||||
|
||||
When no restrictions are selected, all device types are allowed.
|
||||
|
||||
As authentik does not know of all possible device types, it is possible to select the special option `authentik: Unknown devices` to allow unknown devices.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Captcha stage
|
||||
---
|
||||
|
||||
This stage adds a form of verification using [Google's reCAPTCHA](https://www.google.com/recaptcha/intro/v3.html) or compatible services.
|
||||
|
||||
Currently supported implementations:
|
||||
|
||||
- [Google reCAPTCHA](#google-recaptcha)
|
||||
- [hCaptcha](#hcaptcha)
|
||||
- [Cloudflare Turnstile](#cloudflare-turnstile)
|
||||
|
||||
## Captcha provider configuration
|
||||
|
||||
### Google reCAPTCHA
|
||||
|
||||
This stage has two required fields: Public key and private key. These can both be acquired at https://www.google.com/recaptcha/admin.
|
||||
|
||||
|
||||
|
||||
#### Configuration options
|
||||
|
||||
- Interactive: Enabled when using reCAPTCHA v3
|
||||
- Score minimum threshold: `0.5`
|
||||
- Score maximum threshold: `1`
|
||||
- JS URL: `https://www.recaptcha.net/recaptcha/api.js`
|
||||
- API URL: `https://www.recaptcha.net/recaptcha/api/siteverify`
|
||||
|
||||
### hCaptcha
|
||||
|
||||
See https://docs.hcaptcha.com/switch
|
||||
|
||||
#### Configuration options
|
||||
|
||||
- Interactive: Enabled
|
||||
- JS URL: `https://js.hcaptcha.com/1/api.js`
|
||||
- API URL: `https://api.hcaptcha.com/siteverify`
|
||||
|
||||
**Score options only apply to hCaptcha Enterprise**
|
||||
|
||||
- Score minimum threshold: `0`
|
||||
- Score maximum threshold: `0.5`
|
||||
|
||||
### Cloudflare Turnstile
|
||||
|
||||
See https://developers.cloudflare.com/turnstile/get-started/migrating-from-recaptcha
|
||||
|
||||
#### Configuration options
|
||||
|
||||
- Interactive: Enabled if the Turnstile instance is configured as visible or managed
|
||||
- JS URL: `https://challenges.cloudflare.com/turnstile/v0/api.js`
|
||||
- API URL: `https://challenges.cloudflare.com/turnstile/v0/siteverify`
|
||||
|
||||
**Score options do not apply when using with turnstile**
|
||||
10
docs/topics/add-secure-apps/flows-stages/stages/deny.md
Normal file
10
docs/topics/add-secure-apps/flows-stages/stages/deny.md
Normal file
@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Deny stage
|
||||
---
|
||||
|
||||
This stage stops the execution of a flow. This can be used to conditionally deny users access to a flow,
|
||||
even if they are not signed in (and permissions can't be checked via groups).
|
||||
|
||||
:::caution
|
||||
To effectively use this stage, make sure _Evaluate when flow is planned_ is **disable** on the Stage binding.
|
||||
:::
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 208 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
164
docs/topics/add-secure-apps/flows-stages/stages/email/index.mdx
Normal file
164
docs/topics/add-secure-apps/flows-stages/stages/email/index.mdx
Normal file
@ -0,0 +1,164 @@
|
||||
---
|
||||
title: Email stage
|
||||
---
|
||||
|
||||
This stage can be used for email verification. authentik's background worker will send an email using the specified connection details. When an email can't be delivered, delivery is automatically retried periodically.
|
||||
|
||||
|
||||
|
||||
## Behaviour
|
||||
|
||||
By default, the email is sent to the currently pending user. To override this, you can set `email` in the plan's context to another email address, which will override the user's email address (the user won't be changed).
|
||||
|
||||
For example, create this expression policy and bind it to the email stage:
|
||||
|
||||
```python
|
||||
request.context["flow_plan"].context["email"] = "foo@bar.baz"
|
||||
# Or get it from a prompt
|
||||
# request.context["flow_plan"].context["email"] = request.context["prompt_data"]["email"]
|
||||
# Or another user attribute
|
||||
# request.context["flow_plan"].context["email"] = request.context["pending_user"].attributes.get("otherEmail")
|
||||
return True
|
||||
```
|
||||
|
||||
## Custom Templates
|
||||
|
||||
You can also use custom email templates, to use your own design or layout.
|
||||
|
||||
:::info
|
||||
Starting with authentik 2024.2, it is possible to create `.txt` files with the same name as the `.html` template. If a matching `.txt` file exists, the email sent will be a multipart email with both the text and HTML template.
|
||||
:::
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
<Tabs
|
||||
defaultValue="docker-compose"
|
||||
values={[
|
||||
{label: 'docker-compose', value: 'docker-compose'},
|
||||
{label: 'Kubernetes', value: 'kubernetes'},
|
||||
]}>
|
||||
<TabItem value="docker-compose">
|
||||
Place any custom templates in the `custom-templates` Folder, which is in the same folder as your docker-compose file. Afterwards, you'll be able to select the template when creating/editing an Email stage.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="kubernetes">
|
||||
Create a ConfigMap with your email templates:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: authentik-templates
|
||||
namespace: authentik
|
||||
data:
|
||||
my-template.html: |
|
||||
<tr>...
|
||||
```
|
||||
|
||||
Then, in the helm chart add this to your `values.yaml` file:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- name: email-templates
|
||||
configMap:
|
||||
name: authentik-templates
|
||||
volumeMounts:
|
||||
- name: email-templates
|
||||
mountPath: /templates
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::info
|
||||
If you've add the line and created a file, and can't see if, check the worker logs using `docker compose logs -f worker` or `kubectl logs -f deployment/authentik-worker`.
|
||||
:::
|
||||
|
||||
|
||||
|
||||
### Example template
|
||||
|
||||
Templates are rendered using Django's templating engine. The following variables can be used:
|
||||
|
||||
- `url`: The full URL for the user to click on
|
||||
- `user`: The pending user object.
|
||||
- `expires`: The timestamp when the token expires.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
```html
|
||||
{# This is how you can write comments which aren't rendered. #}
|
||||
{# Extend this template from the base email template, which includes base layout and CSS. #}
|
||||
{% extends "email/base.html" %}
|
||||
{# Load the internationalization module to translate strings, and humanize to show date-time #}
|
||||
{% load i18n %}
|
||||
{% load humanize %}
|
||||
{# The email/base.html template uses a single "content" block #}
|
||||
{% block content %}
|
||||
<tr>
|
||||
<td class="alert alert-success">
|
||||
{% blocktrans with username=user.username %} Hi {{ username }},
|
||||
{% endblocktrans %}
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="content-wrap">
|
||||
<table width="100%" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td class="content-block">
|
||||
{% trans 'You recently requested to change your password for you authentik account. Use the button below to set a new password.' %}
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="content-block">
|
||||
<table
|
||||
role="presentation"
|
||||
border="0"
|
||||
cellpadding="0"
|
||||
cellspacing="0"
|
||||
class="btn btn-primary"
|
||||
>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<table
|
||||
role="presentation"
|
||||
border="0"
|
||||
cellpadding="0"
|
||||
cellspacing="0"
|
||||
>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<a
|
||||
id="confirm"
|
||||
href="{{ url }}"
|
||||
rel="noopener noreferrer"
|
||||
target="_blank"
|
||||
>{% trans 'Reset Password' %}</a
|
||||
>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="content-block">
|
||||
{% blocktrans with expires=expires|naturaltime %}
|
||||
If you did not request a password change, please ignore this Email. The link above is valid for {{ expires }}.
|
||||
{% endblocktrans %}
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Identification stage
|
||||
---
|
||||
|
||||
This stage provides a ready-to-go form for users to identify themselves.
|
||||
|
||||
## User Fields
|
||||
|
||||
Select which fields the user can use to identify themselves. Multiple fields can be selected. If no fields are selected, only sources will be shown.
|
||||
|
||||
- Username
|
||||
- Email
|
||||
- UPN
|
||||
|
||||
UPN will attempt to identify the user based on the `upn` attribute, which can be imported with an [LDAP Source](../../../../users-sources/sources/protocols/ldap/index.md)
|
||||
|
||||
## Password stage
|
||||
|
||||
To prompt users for their password on the same step as identifying themselves, a Password stage can be selected here. If a Password stage is selected in the Identification stage, the Password stage should not be bound to the flow.
|
||||
|
||||
## CAPTCHA stage
|
||||
|
||||
:::warning
|
||||
The CAPTCHA stage you use must be configured to use the "Invisible" mode, otherwise the widget will be rendered incorrectly.
|
||||
:::
|
||||
|
||||
To run a CAPTCHA process in the background while the user is entering their identification, a CAPTCHA stage can be selected here. If a CAPTCHA stage is selected in the Identification stage, the CAPTCHA stage should not be bound to the flow.
|
||||
|
||||
## Enrollment/Recovery Flow
|
||||
|
||||
These fields specify if and which flows are linked on the form. The enrollment flow is linked as `Need an account? Sign up.`, and the recovery flow is linked as `Forgot username or password?`.
|
||||
|
||||
## Pretend user exists:ak-version[2024.2]
|
||||
|
||||
When enabled, any user identifier will be accepted as valid (as long as they match the correct format, i.e. when [User fields](#user-fields) is set to only allow Emails, then the identifier still needs to be an Email). The stage will succeed and the flow will continue to the next stage. Stages like the [Password stage](../password/index.md) and [Email stage](../email/index.mdx) are aware of this "pretend" user and will behave the same as if the user would exist.
|
||||
|
||||
## Enable "Remember me on this device":ak-version[2025.4]
|
||||
|
||||
When enabled, users will be given the option at login of having their username stored on the device. If selected, on future logins this stage will automatically fill in the username and fast-forward to the password field. Users will still have the options of clicking "Not you?" and going back to provide a different username or disable this feature.
|
||||
|
||||
## Source settings
|
||||
|
||||
Some sources (like the [OAuth Source](../../../../users-sources/sources/protocols/oauth/index.mdx) and [SAML Source](../../../../users-sources/sources/protocols/saml/index.md)) require user interaction. To make these sources available to users, they can be selected in the Identification stage settings, which will show them below the selected [user field](#user-fields).
|
||||
|
||||
By default, sources are only shown with their icon, which can be changed with the _Show sources' labels_ option.
|
||||
|
||||
Furthermore, it is also possible to deselect any [user field option](#user-fields) for an Identification stage, which will result in users only being able to use currently configured sources.
|
||||
|
||||
:::info
|
||||
Starting with authentik 2023.5, when no user fields are selected and only one source is selected, authentik will automatically redirect the user to that source. This only applies when the **Passwordless flow** option is _not_ configured.
|
||||
:::
|
||||
|
||||
## Flow settings
|
||||
|
||||
### Passwordless flow
|
||||
|
||||
See [Passwordless authentication](../authenticator_validate/index.mdx#passwordless-authentication).
|
||||
|
||||
### Enrollment flow
|
||||
|
||||
Optionally can be set to a flow with the designation of _Enrollment_, which will allow users to sign up.
|
||||
|
||||
### Recovery flow
|
||||
|
||||
Optionally can be set to a flow with the designation of _Recovery_, which will allow users to recover their credentials.
|
||||
77
docs/topics/add-secure-apps/flows-stages/stages/index.md
Normal file
77
docs/topics/add-secure-apps/flows-stages/stages/index.md
Normal file
@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Stages
|
||||
---
|
||||
|
||||
Stages are one of the fundamental building blocks in authentik, along with [flows](../flow/index.md) and [policies](../../../customize/policies/index.md).
|
||||
|
||||
A stage represents a single verification or logic step within a flow. You can bind one or more stages to a flow to create a customized, flexible login and authentication process.
|
||||
|
||||
In the following diagram of the `default-authentication-flow`, you see multiple stages, or steps, in the authentication process for a user. Policies are bound to some stages; this provides for dynamic application of a specific stage _if_ the policy criteria is met.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
flow_pre[["Pre-flow policies"]]
|
||||
flow_pre --Binding 10--> flow_policy_0{{"Policy (Event Matcher Policy)
|
||||
default-match-update"}}
|
||||
flow_policy_0 --Policy denied--> done[["End of the flow"]]
|
||||
flow_policy_0 --> flow_start[["Flow
|
||||
Welcome to authentik!"]]
|
||||
stage_0_policy_0 --Policy passed--> stage_0(["Stage (Identification Stage)
|
||||
default-authentication-identification"])
|
||||
stage_1_policy_0 --Policy passed--> stage_1(["Stage (Password Stage)
|
||||
default-authentication-password"])
|
||||
--> stage_2(["Stage (Authenticator Validation Stage)
|
||||
default-authentication-mfa-validation"])
|
||||
--> stage_3(["Stage (User Login Stage)
|
||||
default-authentication-login"])
|
||||
flow_start --> stage_0_policy_0{{"Policy (Event Matcher Policy)
|
||||
default-match-configuration-error"}}
|
||||
stage_0 --> stage_1_policy_0{{"Policy (Expression Policy)
|
||||
default-authentication-flow-password-stage"}}
|
||||
stage_0_policy_0 --Policy denied--> stage_1(["Stage (Password Stage)
|
||||
default-authentication-password"])
|
||||
stage_1_policy_0 --Policy denied--> stage_2(["Stage (Authenticator Validation Stage)
|
||||
default-authentication-mfa-validation"])
|
||||
stage_3 --> done[["End of the flow"]]
|
||||
```
|
||||
|
||||
## Create a Stage
|
||||
|
||||
To create a stage, follow these steps:
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
2. In the Admin interface, navigate to **Flows and Stages -> Stages**.
|
||||
3. Click **Create**, define the flow using the configuration settings, and then click **Finish**.
|
||||
|
||||
After creating the stage, you can then [bind the stage to a flow](#bind-a-stage-to-a-flow) or [bind a policy to the stage](../../../customize/policies/working_with_policies.md) (the policy determines whether or not the stage will be implemented in the flow).
|
||||
|
||||
## Bind a stage to a flow
|
||||
|
||||
To bind a stage to a flow, follow these steps:
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
2. In the Admin interface, navigate to **Flows and Stages -> Flows**.
|
||||
3. In the list of flows, click the name of the flow to which you want to bind one or more stages.
|
||||
4. On the Flow page, click the **Stage Bindings** tab at the top.
|
||||
5. Here, you can decide if you want to create a new stage and bind it to the flow (**Create and bind Stage**), or if you want to select an existing stage and bind it to the flow (**Bind existing stage**).
|
||||
|
||||
## Bind users and groups to a flow's stage binding
|
||||
|
||||
You can use bindings to determine whether or not a stage is presented to a single user or any users within a group. You do this by binding the user or group to a stage binding within a specific flow. For example, if you have a flow that contains a stage that prompts the user for multi-factor authentication, but you only want certain users to see this stage (and fulfill the MFA prompt), then you would bind the appropriate group (or single user) to the stage binding for that flow.
|
||||
|
||||
To bind a user or a group to a stage binding for a specific flow, follow these steps:
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
2. In the Admin interface, navigate to **Flows and Stages -> Flows**.
|
||||
3. In the list of flows, click the name of the flow to which you want to bind one or more stages.
|
||||
4. On the Flow page, click the **Stage Bindings** tab at the top.
|
||||
5. Locate the stage binding to which you want to bind a user or group, and then **click the caret (>) to expand the stage binding details.**
|
||||
|
||||
|
||||
|
||||
6. In the expanded area, click **Bind existing policy/group/user**.
|
||||
7. In the **Create Binding** box, select either the tab for **Group** or **User**.
|
||||
8. In the drop-down list, select the group or user.
|
||||
9. Optionally, configure additional settings for the binding, and then click **Create** to create the binding and close the box.
|
||||
|
||||
Learn more about [bindings](../bindings/index.md) and [working with them](../bindings/work_with_bindings.md).
|
||||
@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Invitation stage
|
||||
---
|
||||
|
||||
This stage can be used to invite users. You can use this to enroll users with preset values.
|
||||
|
||||
If the option `Continue Flow without Invitation` is enabled, this stage will continue even when no invitation token is present.
|
||||
|
||||
To check if a user has used an invitation within a policy, you can check `request.context.get("invitation_in_effect", False)`.
|
||||
|
||||
To use an invitation, use the URL `https://authentik.tld/if/flow/your-enrollment-flow/?itoken=invitation-token`.
|
||||
|
||||
You can also prompt the user for an invite by using the [_Prompt stage_](../prompt/index.md) by using a field with a field key of `token`.
|
||||
121
docs/topics/add-secure-apps/flows-stages/stages/mtls/index.md
Normal file
121
docs/topics/add-secure-apps/flows-stages/stages/mtls/index.md
Normal file
@ -0,0 +1,121 @@
|
||||
---
|
||||
title: Mutual TLS stage
|
||||
authentik_version: "2025.6"
|
||||
authentik_preview: true
|
||||
authentik_enterprise: true
|
||||
toc_max_heading_level: 5
|
||||
---
|
||||
|
||||
The Mutual TLS stage enables authentik to use client certificates to enroll and authenticate users. These certificates can be local to the device or available via PIV Smart Cards, Yubikeys, etc.
|
||||
|
||||
Management of client certificates is out of the scope of this document.
|
||||
|
||||
## Reverse-proxy configuration
|
||||
|
||||
Using the Mutual TLS stage requires special configuration of any reverse proxy that is used in front of authentik, because the reverse-proxy interacts directly with the browser.
|
||||
|
||||
- nginx
|
||||
- [Standalone nginx](#nginx-standalone)
|
||||
- [nginx kubernetes ingress](#nginx-ingress)
|
||||
- Traefik
|
||||
- [Standalone Traefik](#traefik-standalone)
|
||||
- [Traefik kubernetes ingress](#traefik-ingress)
|
||||
- [envoy](#envoy)
|
||||
- [No reverse proxy](#no-reverse-proxy)
|
||||
|
||||
#### nginx Standalone
|
||||
|
||||
Add this configuration snippet in your authentik virtual host:
|
||||
|
||||
```nginx
|
||||
# server {
|
||||
ssl_client_certificate /etc/ssl/path-to-my-ca.pem;
|
||||
ssl_verify_client on;
|
||||
|
||||
# location / {
|
||||
proxy_set_header ssl-client-cert $ssl_client_escaped_cert;
|
||||
# }
|
||||
# }
|
||||
```
|
||||
|
||||
See [nginx documentation](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_client_certificate) for reference.
|
||||
|
||||
#### nginx Ingress
|
||||
|
||||
Add these annotations to your authentik ingress object:
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
|
||||
# This secret needs to contain `ca.crt` which is the certificate authority to validate against.
|
||||
nginx.ingress.kubernetes.io/auth-tls-secret: namespace/secretName
|
||||
```
|
||||
|
||||
See [ingress-nginx documentation](https://kubernetes.github.io/ingress-nginx/examples/auth/client-certs/) for reference.
|
||||
|
||||
#### Traefik Standalone
|
||||
|
||||
Add this snippet to your traefik configuration:
|
||||
|
||||
```yaml
|
||||
tls:
|
||||
options:
|
||||
default:
|
||||
clientAuth:
|
||||
# in PEM format. each file can contain multiple CAs.
|
||||
caFiles:
|
||||
- tests/clientca1.crt
|
||||
- tests/clientca2.crt
|
||||
clientAuthType: RequireAndVerifyClientCert
|
||||
```
|
||||
|
||||
See the [Traefik mTLS documentation](https://doc.traefik.io/traefik/https/tls/#client-authentication-mtls) for reference.
|
||||
|
||||
#### Traefik Ingress
|
||||
|
||||
Create a middleware object with these options:
|
||||
|
||||
```yaml
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-passtlsclientcert
|
||||
spec:
|
||||
passTLSClientCert:
|
||||
pem: true
|
||||
```
|
||||
|
||||
See the [Traefik PassTLSClientCert documentation](https://doc.traefik.io/traefik/middlewares/http/passtlsclientcert/) for reference.
|
||||
|
||||
#### Envoy
|
||||
|
||||
See the [Envoy mTLS documentation](https://www.envoyproxy.io/docs/envoy/latest/start/quick-start/securing#use-mutual-tls-mtls-to-enforce-client-certificate-authentication) and [Envoy header documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-client-cert) for configuration.
|
||||
|
||||
#### No reverse proxy
|
||||
|
||||
When using authentik without a reverse proxy, select the certificate authorities in the corresponding [brand](../../../../sys-mgmt/brands.md#client-certificates) for the domain, under **Other global settings**.
|
||||
|
||||
## Stage configuration
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
|
||||
2. In the Admin interface, navigate to **System -> Certificates**
|
||||
|
||||
3. Create a new certificate for the Certificate Authority used to sign client certificates.
|
||||
|
||||
4. In the Admin interface, navigate to **Flows -> Stages**.
|
||||
|
||||
5. Click **Create**, and select **Mutual TLS Stage**, and in the **New stage** box, define the following fields:
|
||||
- **Name**: define a descriptive name, such as "chrome-device-trust".
|
||||
|
||||
- **Stage-specific settings**
|
||||
- **Mode**: Configure the mode this stage operates in.
|
||||
- **Certificate optional**: When no certificate is provided by the user or the reverse proxy, the flow will continue to the next stage.
|
||||
- **Certificate required**: When no certificate is provided, the flow ends with an error message.
|
||||
|
||||
- **Certificate authorities**: Select the certificate authorities used to sign client certificates.
|
||||
|
||||
- **Certificate attribute**: Select the attribute of the certificate to be used to find a user for authentication.
|
||||
|
||||
- **User attribute**: Select the attribute of the user the certificate should be compared against.
|
||||
|
||||
6. Click **Finish**.
|
||||
@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Password stage
|
||||
---
|
||||
|
||||
This is a generic password prompt which authenticates the current `pending_user`. This stage allows the selection of the source the user is authenticated against.
|
||||
|
||||
## Passwordless login
|
||||
|
||||
There are two different ways to configure passwordless authentication; you can follow the instructions [here](../authenticator_validate/index.mdx#passwordless-authentication) to allow users to directly authenticate with their authenticator (only supported for WebAuthn devices), or dynamically skip the password stage depending on the users device, which is documented here.
|
||||
|
||||
Depending on what kind of device you want to require the user to have:
|
||||
|
||||
#### WebAuthn
|
||||
|
||||
```python
|
||||
from authentik.stages.authenticator_webauthn.models import WebAuthnDevice
|
||||
return WebAuthnDevice.objects.filter(user=request.context['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()
|
||||
```
|
||||
|
||||
Afterwards, bind the policy you've created to the stage binding of the password stage.
|
||||
|
||||
Make sure to uncheck _Evaluate when flow is planned_ and check _Evaluate when stage is run_, otherwise an invalid result will be cached.
|
||||
113
docs/topics/add-secure-apps/flows-stages/stages/prompt/index.md
Normal file
113
docs/topics/add-secure-apps/flows-stages/stages/prompt/index.md
Normal file
@ -0,0 +1,113 @@
|
||||
---
|
||||
title: Prompt stage
|
||||
---
|
||||
|
||||
This stage is used to show the user arbitrary prompts.
|
||||
|
||||
## Prompt
|
||||
|
||||
The prompt can be any of the following types:
|
||||
|
||||
| Type | Description |
|
||||
| --------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| Text | Arbitrary text. No client-side validation is done. |
|
||||
| Text (Read only) | Same as above, but cannot be edited. |
|
||||
| Text Area | Arbitrary multiline text. No client-side validation is done. |
|
||||
| Text Area (Read only) | Same as above, but cannot be edited. |
|
||||
| Username | Same as text, except the username is validated to be unique. |
|
||||
| Email | Text input, ensures the value is an email address (validation is only done client-side). |
|
||||
| Password | Same as text, shown as a password field client-side, and custom validation (see below). |
|
||||
| Number | Numerical textbox. |
|
||||
| Checkbox | Simple checkbox. |
|
||||
| Radio Button Group | Similar to checkboxes, but allows selecting a value from a set of predefined values. |
|
||||
| Dropdown | A simple dropdown menu filled with predefined values. |
|
||||
| Date | Same as text, except the client renders a date-picker |
|
||||
| Date-time | Same as text, except the client renders a date-time-picker |
|
||||
| File | Allow users to upload a file, which will be available as base64-encoded data in the flow . |
|
||||
| Separator | Passive element to group surrounding elements |
|
||||
| Hidden | Hidden input field. Allows for the pre-setting of default values. |
|
||||
| Static | Display arbitrary value as is |
|
||||
| authentik: Locale | Display a list of all locales authentik supports. |
|
||||
|
||||
:::note
|
||||
`TextArea`, `TextArea (Read only)`, `Radio Button Group` and `Dropdown` options require authentik 2023.4+
|
||||
:::
|
||||
|
||||
Some types have special behaviors:
|
||||
|
||||
- _Username_: Input is validated against other usernames to ensure a unique value is provided.
|
||||
- _Password_: All prompts with the type password within the same stage are compared and must be equal. If they are not equal, an error is shown
|
||||
- _Hidden_ and _Static_: Their initial values are defaults and are not user-changeable.
|
||||
- _Radio Button Group_ and _Dropdown_: Only allow the user to select one of a set of predefined values.
|
||||
|
||||
A prompt has the following attributes:
|
||||
|
||||
### `field_key`
|
||||
|
||||
The field name used for the prompt. This key is also used to later retrieve the data in expression policies:
|
||||
|
||||
```python
|
||||
request.context.get('prompt_data').get('<field_key>')
|
||||
```
|
||||
|
||||
### `label`
|
||||
|
||||
The label used to describe the field. Depending on the selected template, this may not be shown.
|
||||
|
||||
### `required`
|
||||
|
||||
A flag which decides whether or not this field is required.
|
||||
|
||||
### `placeholder`
|
||||
|
||||
A field placeholder, shown within the input field.
|
||||
|
||||
By default, the placeholder is interpreted as-is. If you enable _Interpret placeholder as expression_, the placeholder
|
||||
will be evaluated as a Python expression. This happens in the same environment as [_Policies_](../../../../customize/policies/expression.mdx).
|
||||
|
||||
In the case of `Radio Button Group` and `Dropdown` prompts, this field defines all possible values (choices). When interpreted as-is, only one value will be allowed (the placeholder string). When interpreted as expression, a list of values can be returned to define multiple choices. For example, `return ["first option", 42, "another option"]` defines 3 possible values.
|
||||
|
||||
You can access both the HTTP request and the user as with a mapping. Additionally, you can access `prompt_context`, which is a dictionary of the current state of the prompt stage's data.
|
||||
|
||||
For `Radio Button Group` and `Dropdown` prompts, if a key with the same name as the prompt's `field_key` and a suffix of `__choices` (`<field_key>__choices`) is present in the `prompt_context` dictionary, its value will be returned directly, even if _Interpret placeholder as expression_ is enabled.
|
||||
|
||||
### `initial_value`
|
||||
|
||||
The prompt's initial value. It can also be left empty, in which case the field will not have a pre-filled value.
|
||||
|
||||
With the `hidden` prompt, the initial value will also be the actual value, because the field is hidden to the user.
|
||||
|
||||
By default, the initial value is interpreted as-is. If you enable _Interpret initial value as expression_, the initial value
|
||||
will be evaluated as a Python expression. This happens in the same environment as [_Policies_](../../../../customize/policies/expression.mdx).
|
||||
|
||||
In the case of `Radio Button Group` and `Dropdown` prompts, this field defines the default choice. When interpreted as-is, the default choice will be the initial value string. When interpreted as expression, the default choice will be the returned value. For example, `return 42` defines `42` as the default choice.
|
||||
|
||||
:::note
|
||||
The default choice defined for any fixed choice field **must** be one of the valid choices specified in the prompt's placeholder.
|
||||
:::
|
||||
|
||||
You can access both the HTTP request and the user as with a mapping. Additionally, you can access `prompt_context`, which is a dictionary of the current state of the prompt stage's data. If a key with the same name as the prompt's `field_key` is present in the `prompt_context` dictionary, its value will be returned directly, even if _Interpret initial value as expression_ is enabled.
|
||||
|
||||
### `order`
|
||||
|
||||
The numerical index of the prompt. This applies to all stages which this prompt is a part of.
|
||||
|
||||
# Validation
|
||||
|
||||
Further validation of prompts can be done using policies.
|
||||
|
||||
To validate that two password fields are identical, create the following expression policy:
|
||||
|
||||
```python
|
||||
if request.context.get('prompt_data').get('password') == request.context.get('prompt_data').get('password_repeat'):
|
||||
return True
|
||||
|
||||
ak_message("Passwords don't match.")
|
||||
return False
|
||||
```
|
||||
|
||||
This policy expects you to have two password fields with `field_key` set to `password` and `password_repeat`.
|
||||
|
||||
Afterwards, bind this policy to the prompt stage you want to validate.
|
||||
|
||||
Before 2021.12, any policy was required to pass for the result to be considered valid. This has been changed, and now all policies are required to be valid.
|
||||
@ -0,0 +1,18 @@
|
||||
---
|
||||
title: Redirect stage
|
||||
authentik_version: "2024.12"
|
||||
---
|
||||
|
||||
This stage's main purpose is to redirect the user to a new Flow while keeping flow context. For convenience, it can also redirect the user to a static URL.
|
||||
|
||||
## Redirect stage modes
|
||||
|
||||
### Static mode
|
||||
|
||||
When the user reaches this stage, they are redirected to a static URL.
|
||||
|
||||
### Flow mode
|
||||
|
||||
When the user reaches this stage, they are redirected to a specified flow, retaining all [flow context](../../flow/context/index.mdx).
|
||||
|
||||
Optionally, untoggle the "Keep flow context" switch. If this is untoggled, all flow context is cleared with the exception of the [is_redirected](../../flow/context#is_redirected-flow-object) key.
|
||||
@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Source stage
|
||||
authentik_version: "2024.4"
|
||||
authentik_enterprise: true
|
||||
---
|
||||
|
||||
The source stage injects an [OAuth](../../../../users-sources/sources/protocols/oauth/index.mdx) or [SAML](../../../../users-sources/sources/protocols/saml/index.md) Source into the flow execution. This allows for additional user verification, or to dynamically access different sources for different user identifiers (username, email address, etc).
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant u as User
|
||||
participant ak as authentik
|
||||
participant eidp as External IDP
|
||||
|
||||
u->>ak: User initiates flow
|
||||
ak->>u: User reaches Source Stage
|
||||
|
||||
u->>eidp: User is redirected to external IDP
|
||||
eidp->>ak: User has authenticated with external IDP
|
||||
|
||||
alt User is connected to external IDP (auth)
|
||||
ak->>u: Source's authentication flow is started
|
||||
u->>ak: User finishes source's authentication flow
|
||||
else User has not been connected to external IDP (enroll)
|
||||
ak->>u: Source's enrollment flow is started
|
||||
u->>ak: User finishes source's enrollment flow
|
||||
end
|
||||
|
||||
ak->>u: Execution of the previous flow is resumed
|
||||
```
|
||||
|
||||
### Considerations
|
||||
|
||||
It is very important that the configured source's authentication and enrollment flows (when set; they can be left unselected to prevent authentication or enrollment with the source) do **not** have a [User login stage](../user_login/index.md) bound to them.
|
||||
|
||||
This is because the Source stage works by appending a [dynamic in-memory](../../../../core/terminology.md#dynamic-in-memory-stage) stage to the source's flow, so having a [User login stage](../user_login/index.md) bound will cause the source's flow to not resume the original flow it was started from, and instead directly authenticating the pending user.
|
||||
|
||||
### Example use case
|
||||
|
||||
This stage can be used to leverage an external OAuth/SAML identity provider.
|
||||
|
||||
For example, you can authenticate users by routing them through a custom device-health solution.
|
||||
|
||||
Another use case is to route users to authenticate with your legacy (Okta, etc) IdP and then use the returned identity and attributes within authentik as part of an authorization flow, for example as part of an IdP migration. For authentication/enrollment this is also possible with an [OAuth](../../../../users-sources/sources/protocols/oauth/index.mdx)/[SAML](../../../../users-sources/sources/protocols/saml/index.md) source by itself.
|
||||
|
||||
### Options
|
||||
|
||||
#### Source
|
||||
|
||||
The source the user is redirected to. Must be a web-based source, such as [OAuth](../../../../users-sources/sources/protocols/oauth/index.mdx) or [SAML](../../../../users-sources/sources/protocols/saml/index.md). Sources like [LDAP](../../../../users-sources/sources/protocols/ldap/index.md) are _not_ compatible.
|
||||
|
||||
#### Resume timeout
|
||||
|
||||
Because the execution of the current flow is suspended before the user is redirected to the configured source, this option configures how long the suspended flow is saved. If this timeout is exceeded, upon return from the configured source, the suspended flow will restart from the beginning.
|
||||
@ -0,0 +1,11 @@
|
||||
---
|
||||
title: User delete stage
|
||||
---
|
||||
|
||||
:::danger
|
||||
This stage deletes the `pending_user` without any confirmation. You have to make sure the user is aware of this.
|
||||
:::
|
||||
|
||||
This stage is intended for an unenrollment flow. It deletes the currently pending user.
|
||||
|
||||
The pending user is also removed from the current session.
|
||||
@ -0,0 +1,83 @@
|
||||
---
|
||||
title: User login stage
|
||||
---
|
||||
|
||||
This stage attaches a currently pending user to the current session.
|
||||
|
||||
It can be used after `user_write` during an enrollment flow, or after a `password` stage during an authentication flow.
|
||||
|
||||
## User login stage configuration options
|
||||
|
||||
When creating or editing this stage in the UI of the Admin interface, you can set the following configuration options.
|
||||
|
||||
**Name**: enter a descriptive name for the stage.
|
||||
|
||||
**Stage-specific settings**
|
||||
|
||||
- **Session duration**: By default, the authentik session expires when you close your browser (_seconds=0_).
|
||||
|
||||
:::warning
|
||||
Different browsers handle session cookies differently, and might not remove them even when the browser is closed. See [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#expiresdate) for more info.
|
||||
:::
|
||||
|
||||
You can set the session to expire after any duration using the syntax of `hours=1,minutes=2,seconds=3`. The following keys are allowed:
|
||||
- Microseconds
|
||||
- Milliseconds
|
||||
- Seconds
|
||||
- Minutes
|
||||
- Hours
|
||||
- Days
|
||||
- Weeks
|
||||
|
||||
All values accept floating-point values.
|
||||
|
||||
- **Stay signed in offset**: When this is set to a higher value than the default _seconds=0_, the user logging in is shown a prompt, allowing the user to choose if their session should be extended or not. The same syntax as for _Session duration_ applies.
|
||||
|
||||
|
||||
|
||||
- **Network binding and GeoIP binding**
|
||||
|
||||
When configured, all sessions authenticated by this stage will be bound to the selected network and/or GeoIP criteria.
|
||||
|
||||
Sessions that break this binding will be terminated on use. The created [`logout`](../../../../sys-mgmt/events/index.md#logout) event will contain additional data related to what caused the binding to be broken:
|
||||
|
||||
```json
|
||||
{
|
||||
"asn": {
|
||||
"asn": 6805,
|
||||
"as_org": "Telefonica Germany",
|
||||
"network": "5.4.0.0/14"
|
||||
},
|
||||
"geo": {
|
||||
"lat": 51.2993,
|
||||
"city": "",
|
||||
"long": 9.491,
|
||||
"country": "DE",
|
||||
"continent": "EU"
|
||||
},
|
||||
"binding": {
|
||||
"reason": "network.missing",
|
||||
"new_value": {
|
||||
"asn": 6805,
|
||||
"as_org": "Telefonica Germany",
|
||||
"network": "5.4.0.0/14"
|
||||
},
|
||||
"previous_value": {}
|
||||
},
|
||||
"ip": {
|
||||
"previous": "1.2.3.4",
|
||||
"new": "5.6.7.8"
|
||||
},
|
||||
"http_request": {
|
||||
"args": {},
|
||||
"path": "/if/admin/",
|
||||
"method": "GET",
|
||||
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
|
||||
},
|
||||
"logout_reason": "Session binding broken"
|
||||
}
|
||||
```
|
||||
|
||||
- **Terminate other sessions**
|
||||
|
||||
When enabled, previous sessions of the user logging in will be revoked. This has no affect on OAuth refresh tokens.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 142 KiB |
@ -0,0 +1,5 @@
|
||||
---
|
||||
title: User logout stage
|
||||
---
|
||||
|
||||
Opposite stage of [User Login Stages](./user_login/index.md). It removes the user from the current session.
|
||||
@ -0,0 +1,27 @@
|
||||
---
|
||||
title: User write stage
|
||||
---
|
||||
|
||||
This stages writes data from the current flow context to a user.
|
||||
|
||||
Newly created users can be created as inactive and can be assigned to a selected group.
|
||||
|
||||
### Dynamic groups
|
||||
|
||||
Starting with authentik 2022.5, users can be added to dynamic groups. To do so, simply set `groups` in the flow plan context before this stage is run, for example
|
||||
|
||||
```python
|
||||
from authentik.core.models import Group
|
||||
group, _ = Group.objects.get_or_create(name="some-group")
|
||||
# ["groups"] *must* be set to an array of Group objects, names alone are not enough.
|
||||
request.context["flow_plan"].context["groups"] = [group]
|
||||
return True
|
||||
```
|
||||
|
||||
### User creation
|
||||
|
||||
By default, this stage will create a new user when none is present in the flow context.
|
||||
|
||||
Starting with authentik 2022.12, the stage can by default not create new users to prevent users from creating new accounts without authorization.
|
||||
|
||||
Starting with authentik 2023.1, this option has been expanded to allow user creation, forbid it or force user creation.
|
||||
94
docs/topics/add-secure-apps/outposts/_config.md
Normal file
94
docs/topics/add-secure-apps/outposts/_config.md
Normal file
@ -0,0 +1,94 @@
|
||||
```yaml
|
||||
# Log level that the outpost will set
|
||||
# Allowed levels: trace, debug, info, warning, error
|
||||
# Applies to: non-embedded
|
||||
log_level: debug
|
||||
# Interval at which the outpost will refresh the providers
|
||||
# from authentik. For caching outposts (such as LDAP), the
|
||||
# cache will also be invalidated at that interval.
|
||||
# (Format: hours=1;minutes=2;seconds=3).
|
||||
refresh_interval: minutes=5
|
||||
########################################
|
||||
# The settings below are only relevant when using a managed outpost
|
||||
########################################
|
||||
# URL that the outpost uses to connect back to authentik
|
||||
authentik_host: https://authentik.tld/
|
||||
# Disable SSL Validation for the authentik connection
|
||||
authentik_host_insecure: false
|
||||
# Optionally specify a different URL used for user-facing interactions
|
||||
# Applies to: proxy outposts
|
||||
authentik_host_browser:
|
||||
# Template used for objects created (deployments/containers, services, secrets, etc)
|
||||
object_naming_template: ak-outpost-%(name)s
|
||||
# Use a specific docker image for this outpost rather than the default. This also applies to Kubernetes
|
||||
# outposts.
|
||||
# Applies to: non-embedded
|
||||
container_image:
|
||||
########################################
|
||||
# Docker outpost specific settings
|
||||
########################################
|
||||
# Network the outpost container should be connected to
|
||||
# Applies to: non-embedded
|
||||
docker_network: null
|
||||
# Optionally disable mapping of ports to outpost container, may be useful when using docker networks
|
||||
# (Available with 2021.9.4+)
|
||||
# Applies to: non-embedded
|
||||
docker_map_ports: true
|
||||
# Optionally additional labels for docker containers
|
||||
# (Available with 2022.1.2)
|
||||
# Applies to: non-embedded
|
||||
docker_labels: null
|
||||
########################################
|
||||
# Kubernetes outpost specific settings
|
||||
########################################
|
||||
# Replica count for the deployment of the outpost
|
||||
# Applies to: non-embedded
|
||||
kubernetes_replicas: 1
|
||||
# Namespace to deploy in, defaults to the same namespace authentik is deployed in (if available)
|
||||
kubernetes_namespace: authentik
|
||||
# Any additional annotations to add to the ingress object, for example cert-manager
|
||||
kubernetes_ingress_annotations: {}
|
||||
# Name of the secret that is used for TLS connections, leave empty to disable TLS
|
||||
kubernetes_ingress_secret_name: authentik-outpost-tls
|
||||
# Service kind created, can be set to LoadBalancer for LDAP outposts for example
|
||||
kubernetes_service_type: ClusterIP
|
||||
# Disable any components of the kubernetes integration, can be any of
|
||||
# - 'secret'
|
||||
# - 'deployment'
|
||||
# - 'service'
|
||||
# - 'prometheus servicemonitor'
|
||||
# - 'ingress'
|
||||
# - 'traefik middleware'
|
||||
kubernetes_disabled_components: []
|
||||
# If the above docker image is in a private repository, use these secrets to pull.
|
||||
# NOTE: The secret must be created manually in the namespace first.
|
||||
# Applies to: non-embedded
|
||||
kubernetes_image_pull_secrets: []
|
||||
# Optionally configure an ingress class name. If not set, the ingress will use the cluster's
|
||||
# default ingress class
|
||||
# (Available with 2022.11.0+)
|
||||
# Applies to: proxy outposts
|
||||
kubernetes_ingress_class_name: null
|
||||
# Optionally apply an RFC 6902 compliant patch to the Kubernetes objects.
|
||||
# For an understanding of how this works, refer to the link below:
|
||||
# https://github.com/kubernetes-sigs/kustomize/blob/master/examples/jsonpatch.md
|
||||
#
|
||||
# This value expects a mapping where the key represents
|
||||
# the Kubernetes component that shall be patched.
|
||||
# It can be any of the same values supported by `kubernetes_disabled_components`.
|
||||
#
|
||||
# For example use this patch to add custom resource requests and limits
|
||||
# to the outpost deployment:
|
||||
#
|
||||
# deployment:
|
||||
# - op: add
|
||||
# path: "/spec/template/spec/containers/0/resources"
|
||||
# value:
|
||||
# requests:
|
||||
# cpu: 2000m
|
||||
# memory: 2000Mi
|
||||
# limits:
|
||||
# cpu: 4000m
|
||||
# memory: 8000Mi
|
||||
kubernetes_json_patches: null
|
||||
```
|
||||
47
docs/topics/add-secure-apps/outposts/embedded/embedded.mdx
Normal file
47
docs/topics/add-secure-apps/outposts/embedded/embedded.mdx
Normal file
@ -0,0 +1,47 @@
|
||||
---
|
||||
title: Embedded Outpost
|
||||
---
|
||||
|
||||
Starting with 2021.8.1, authentik comes with an embedded outpost. This has been added to simplify deployment for users using 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.
|
||||
|
||||
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.
|
||||
|
||||
### Configuration
|
||||
|
||||
Since authentik doesn't know it's own "primary" URL, there might be some configuration required.
|
||||
|
||||
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 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 login with.
|
||||
Make sure to set it to full URL, only configuring a hostname or FQDN will not work.
|
||||
|
||||
Additionally, most of the other configuration options can be used as with any other outpost, except from items which are marked as "non-embedded"
|
||||
|
||||
import Configuration from "../_config.md";
|
||||
|
||||
<Configuration />
|
||||
|
||||
### Routing
|
||||
|
||||
Routing is handled like this:
|
||||
|
||||
1. Paths starting with `/static`, `/media` and `/help` return packaged CSS/JS 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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
68
docs/topics/add-secure-apps/outposts/index.mdx
Normal file
68
docs/topics/add-secure-apps/outposts/index.mdx
Normal file
@ -0,0 +1,68 @@
|
||||
---
|
||||
title: Outposts
|
||||
---
|
||||
|
||||
An outpost is a single deployment of an authentik component, essentially a service, that can be deployed anywhere that allows for a connection to the authentik API.
|
||||
|
||||
An outpost is required if you use any of the following types of providers with your application:
|
||||
|
||||
- [LDAP Provider](../providers/ldap/index.md)
|
||||
- [Proxy Provider](../providers/proxy/index.md)
|
||||
- [RADIUS Provider](../providers/radius/index.mdx)
|
||||
- [RAC Provider](../providers/rac/index.md)
|
||||
|
||||
These types of providers use an outpost for increased flexibility and speed. Instead of the provider logic being implemented in authentik Core, these providers use an outpost to handle the logic, which provides improved performance.
|
||||
|
||||
An additional advantage of using an outpost is that outposts, like authentik itself, do not require access to the wider internet. Transactions between the application, the provider, and the outpost occur via the authentik API, and support single sign-on operations in firewalled or airgapped deployments and offline connections to remote machines that are not on the internet.
|
||||
|
||||
An outpost is given permissions to access the authentik API using a service account and token, both of which are auto-generated when you create a new outpost. The outpost is granted rights to only the application/provider pairs configured (and other necessary related objects such as certificates).
|
||||
|
||||
Any change made to the outpost's associated app or provider immediately triggers an event to update the configuration data stored on the outpost, via websockets. Websockets are used also by the outpost to send healthchecks to the authentik Core.
|
||||
|
||||
## Create and configure an outpost
|
||||
|
||||
1. To create a new outpost, log in to authentik as an administrator, and open to the Admin interface.
|
||||
|
||||
2. Navigate to **Applications --> Outposts** and then click **Create**.
|
||||
|
||||
|
||||
|
||||
3. Define the following values:
|
||||
|
||||
- **Name**: a name for the new outpost
|
||||
- **Type**: select the provider type (Proxy, LDAP, Radius, RAC)
|
||||
- **Integration** (_optional_): select either your [Docker or Kubernetes connection](#more-about-outpost-integrations)
|
||||
- **Applications**: select the applications that you want the outpost to serve
|
||||
- **Advanced settings** (*optional*): For further optional configuration settings, refer to [Configuration](#configuration) below.
|
||||
|
||||
4. Click **Create** to save your new outpost settings and close the box.
|
||||
|
||||
Upon creation, a service account and a token is generated. The service account only has permissions to read the outpost and provider configuration. This token is used by the outpost to connect to authentik.
|
||||
|
||||
### More about outpost integrations
|
||||
|
||||
authentik can manage the deployment, updating, and general lifecycle of an outpost. To communicate with the underlying platforms on which the outpost is deployed, authentik has several built-in integrations.
|
||||
|
||||
- If you've deployed authentik on Docker Compose, authentik automatically creates an integration for the local docker socket (See [Docker](./integrations/docker.md)).
|
||||
- If you've deployed authentik on Kubernetes, with `kubernetesIntegration` set to true (default), authentik automatically creates an integrations for the local Kubernetes Cluster (see [Kubernetes](./integrations/kubernetes.md)).
|
||||
|
||||
To deploy an outpost with these integrations, select them during the creation of an outpost. A background task is started, which creates the container/deployment. The outpost deployment can be monitored from the **Dashboards -> System Tasks** page in the Admin interface.
|
||||
|
||||
To deploy an outpost manually, see:
|
||||
|
||||
- [Kubernetes](./manual-deploy-kubernetes.md)
|
||||
- [Docker Compose](./manual-deploy-docker-compose.md)
|
||||
|
||||
### Configuration
|
||||
|
||||
Outposts fetch their configuration from authentik. Below are all the options you can set, and how they influence the outpost.
|
||||
|
||||
import Configuration from "./_config.md";
|
||||
|
||||
<Configuration />
|
||||
|
||||
## Prometheus Metrics
|
||||
|
||||
Each authentik outpost has a Prometheus metrics endpoint accessible under port `:9300/metrics`. This endpoint is not mapped via Docker, as the endpoint doesn't have any authentication.
|
||||
|
||||
For the embedded outpost, the metrics of the outpost and the metrics of the core authentik server are both returned under the same endpoint.
|
||||
91
docs/topics/add-secure-apps/outposts/integrations/docker.md
Normal file
91
docs/topics/add-secure-apps/outposts/integrations/docker.md
Normal file
@ -0,0 +1,91 @@
|
||||
---
|
||||
title: Docker
|
||||
---
|
||||
|
||||
The Docker integration automatically deploys and manages outpost containers using the Docker HTTP API.
|
||||
|
||||
This integration has the advantage over manual deployments of automatic updates that whenever authentik is upgraded to a later version, it also upgrades the outposts.
|
||||
|
||||
The following outpost settings are used:
|
||||
|
||||
- `object_naming_template`: Configures how the container is called.
|
||||
- `container_image`: Optionally overwrites the standard container image (see [Configuration](../../../install-config/configuration/configuration.mdx#authentik_outposts) to configure the global default).
|
||||
- `docker_network`: The Docker network the container should be added to. This needs to be modified if you plan to connect to authentik using the internal hostname.
|
||||
- `docker_map_ports`: Enable/disable the mapping of ports. When using a proxy outpost with Traefik for example, you might not want to bind ports as they are routed through Traefik.
|
||||
- `docker_labels`: Optional additional labels that can be applied to the container.
|
||||
|
||||
The container is created with the following hardcoded properties:
|
||||
|
||||
- Labels
|
||||
- `io.goauthentik.outpost-uuid`: Used by authentik to identify the container, and to allow for name changes.
|
||||
|
||||
Additionally, the proxy outposts have the following extra labels to add themselves into Traefik automatically.
|
||||
- `traefik.enable`: "true"
|
||||
- `traefik.http.routers.ak-outpost-<outpost-name>-router.rule`: `Host(...)`
|
||||
- `traefik.http.routers.ak-outpost-<outpost-name>-router.service`: `ak-outpost-<outpost-name>-service`
|
||||
- `traefik.http.routers.ak-outpost-<outpost-name>-router.tls`: "true"
|
||||
- `traefik.http.services.ak-outpost-<outpost-name>-service.loadbalancer.healthcheck.path`: "/outpost.goauthentik.io/ping"
|
||||
- `traefik.http.services.ak-outpost-<outpost-name>-service.loadbalancer.healthcheck.port`: "9300"
|
||||
- `traefik.http.services.ak-outpost-<outpost-name>-service.loadbalancer.server.port`: "9000"
|
||||
|
||||
## Permissions
|
||||
|
||||
authentik requires the following permissions from the Docker API:
|
||||
|
||||
- Images/Pull: authentik tries to pre-pull the custom image if one is configured, otherwise falling back to the default image.
|
||||
- Containers/Read: Gather infos about currently running container
|
||||
- Containers/Create: Create new containers
|
||||
- Containers/Kill: Cleanup during upgrades
|
||||
- Containers/Remove: Removal of outposts
|
||||
- System/Info: Gather information about the version of Docker running
|
||||
|
||||
## Docker Socket Proxy
|
||||
|
||||
Mapping the Docker socket to a container comes with some inherent security risks. Applications inside these containers have unfettered access to the full Docker API, which can be used to gain unauthorized access to sensitive Docker functions.
|
||||
|
||||
It can also result in possible root escalation on the host system.
|
||||
|
||||
To prevent this, many people use projects like [docker-socket-proxy](https://docs.linuxserver.io/images/docker-socket-proxy/), which limit access to the Docker socket by filtering and restricting API calls that these applications can make.
|
||||
|
||||
See [permissions](#permissions) for the list of APIs that authentik needs access to.
|
||||
|
||||
Note: Connections from authentik to Docker socket proxy must be made over HTTP, not TCP, e.g. `http://<docker-socket-proxy hostname/container name>:<port>`.
|
||||
|
||||
## Remote hosts (TLS)
|
||||
|
||||
To connect remote hosts, follow this guide from Docker [Use TLS (HTTPS) to protect the Docker daemon socket](https://docs.docker.com/engine/security/protect-access/#use-tls-https-to-protect-the-docker-daemon-socket) to configure Docker.
|
||||
|
||||
Afterwards, create two certificate-keypairs in authentik:
|
||||
|
||||
- `Docker CA`, with the contents of `~/.docker/ca.pem` as Certificate
|
||||
- `Docker Cert`, with the contents of `~/.docker/cert.pem` as the certificate and `~/.docker/key.pem` as the private key.
|
||||
|
||||
Create an integration with `Docker CA` as _TLS Verification Certificate_ and `Docker Cert` as _TLS Authentication Certificate_.
|
||||
|
||||
## Remote hosts (SSH)
|
||||
|
||||
authentik can connect to remote Docker hosts using SSH. To configure this, create a new SSH keypair using these commands:
|
||||
|
||||
```
|
||||
# Generate the keypair itself, using RSA keys in the PEM format
|
||||
ssh-keygen -t rsa -f authentik -N "" -m pem
|
||||
# Generate a certificate from the private key, required by authentik.
|
||||
# The values that openssl prompts you for are not relevant
|
||||
openssl req -x509 -sha256 -nodes -days 365 -out certificate.pem -key authentik
|
||||
```
|
||||
|
||||
You'll end up with three files:
|
||||
|
||||
- `authentik.pub` is the public key, this should be added to the `~/.ssh/authorized_keys` file on the target host and user.
|
||||
- `authentik` is the private key, which should be imported into a Keypair in authentik.
|
||||
- `certificate.pem` is the matching certificate for the keypair above.
|
||||
|
||||
Modify/create a new Docker integration, and set your _Docker URL_ to `ssh://hostname`, and select the keypair you created above as _TLS Authentication Certificate/SSH Keypair_.
|
||||
|
||||
The _Docker URL_ field include a user, if none is specified authentik connects with the user `authentik`.
|
||||
|
||||
#### Advanced SSH config
|
||||
|
||||
With the above configuration, authentik will create and manage an `~/.ssh/config` file. If you need advanced configuration, for example SSH Certificates, you can mount a custom SSH Config file.
|
||||
|
||||
Mount the config file into `/authentik/.ssh/config`, and mount any other relevant files into a directory under `/opt`. Afterwards, create an integration using `ssh://hostname`, and don't select a keypair.
|
||||
@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Kubernetes
|
||||
---
|
||||
|
||||
The kubernetes integration will automatically deploy outposts on any Kubernetes Cluster.
|
||||
|
||||
This integration has the advantage over manual deployments of automatic updates (whenever authentik is updated, it updates the outposts), and authentik can (in a future version) automatically rotate the token that the outpost uses to communicate with the core authentik server.
|
||||
|
||||
This integration creates the following objects:
|
||||
|
||||
- Deployment for the outpost container
|
||||
- Service
|
||||
- Secret to store the token
|
||||
- Prometheus ServiceMonitor (if the Prometheus Operator is installed in the target cluster)
|
||||
- Ingress (only Proxy outposts)
|
||||
- HTTPRoute (only Proxy outposts, when the Gateway API resources are installed in the target cluster, and the `kubernetes_httproute_parent_refs` setting is set, see below)
|
||||
- Traefik Middleware (only Proxy outposts with forward auth enabled)
|
||||
|
||||
The following outpost settings are used:
|
||||
|
||||
- `object_naming_template`: Configures how the container is called
|
||||
- `container_image`: Optionally overwrites the standard container image (see [Configuration](../../../install-config/configuration/configuration.mdx) to configure the global default)
|
||||
- `kubernetes_replicas`: Replica count for the deployment of the outpost
|
||||
- `kubernetes_namespace`: Namespace to deploy in, defaults to the same namespace authentik is deployed in (if available)
|
||||
- `kubernetes_ingress_annotations`: Any additional annotations to add to the ingress object, for example cert-manager
|
||||
- `kubernetes_ingress_secret_name`: Name of the secret that is used for TLS connections, can be empty to disable TLS config
|
||||
- `kubernetes_ingress_class_name`: Optionally set the ingress class used for the generated ingress, requires authentik 2022.11.0
|
||||
- `kubernetes_httproute_parent_refs`: Define which Gateways the HTTPRoute wants to be attached to.
|
||||
- `kubernetes_httproute_annotations`: Any additional annotations to add to the HTTPRoute object
|
||||
- `kubernetes_service_type`: Service kind created, can be set to LoadBalancer for LDAP outposts for example
|
||||
- `kubernetes_disabled_components`: Disable any components of the kubernetes integration, can be any of
|
||||
- 'secret'
|
||||
- 'deployment'
|
||||
- 'service'
|
||||
- 'prometheus servicemonitor'
|
||||
- 'ingress'
|
||||
- 'traefik middleware'
|
||||
- 'httproute'
|
||||
- `kubernetes_image_pull_secrets`: If the above docker image is in a private repository, use these secrets to pull. (NOTE: The secret must be created manually in the namespace first.)
|
||||
- `kubernetes_json_patches`: Applies an RFC 6902 compliant JSON patch to the Kubernetes objects.
|
||||
|
||||
## Permissions
|
||||
|
||||
The permissions required for this integration are documented in the helm chart. See [Cluster-level](https://github.com/goauthentik/helm/blob/main/charts/authentik-remote-cluster/templates/clusterrolebinding.yaml) and [Namespace-level](https://github.com/goauthentik/helm/blob/main/charts/authentik-remote-cluster/templates/rolebinding.yaml).
|
||||
|
||||
## Remote clusters
|
||||
|
||||
To add a remote cluster, you can simply install this helm chart in the target cluster and namespace: https://artifacthub.io/packages/helm/goauthentik/authentik-remote-cluster
|
||||
|
||||
After installation, the helm chart outputs an example kubeconfig file, that you can enter in authentik to connect to the cluster.
|
||||
@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Manual Outpost deployment in docker-compose
|
||||
---
|
||||
|
||||
To deploy an outpost with docker-compose, use this snippet in your docker-compose file.
|
||||
|
||||
You can also run the outpost in a separate docker-compose project, you just have to ensure that the outpost container can reach your application container.
|
||||
|
||||
### Proxy outpost
|
||||
|
||||
```yaml
|
||||
services:
|
||||
authentik_proxy:
|
||||
image: ghcr.io/goauthentik/proxy
|
||||
# Optionally specify which networks the container should be
|
||||
# might be needed to reach the core authentik server
|
||||
# networks:
|
||||
# - foo
|
||||
ports:
|
||||
- 9000:9000
|
||||
- 9443:9443
|
||||
environment:
|
||||
AUTHENTIK_HOST: https://your-authentik.tld
|
||||
AUTHENTIK_INSECURE: "false"
|
||||
AUTHENTIK_TOKEN: token-generated-by-authentik
|
||||
# Starting with 2021.9, you can optionally set this too
|
||||
# when authentik_host for internal communication doesn't match the public URL
|
||||
# AUTHENTIK_HOST_BROWSER: https://external-domain.tld
|
||||
```
|
||||
|
||||
### LDAP outpost
|
||||
|
||||
```yaml
|
||||
services:
|
||||
authentik_ldap:
|
||||
image: ghcr.io/goauthentik/ldap
|
||||
# Optionally specify which networks the container should be
|
||||
# might be needed to reach the core authentik server
|
||||
# networks:
|
||||
# - foo
|
||||
ports:
|
||||
- 389:3389
|
||||
- 636:6636
|
||||
environment:
|
||||
AUTHENTIK_HOST: https://your-authentik.tld
|
||||
AUTHENTIK_INSECURE: "false"
|
||||
AUTHENTIK_TOKEN: token-generated-by-authentik
|
||||
```
|
||||
|
||||
### RADIUS outpost
|
||||
|
||||
```yaml
|
||||
services:
|
||||
radius_outpost:
|
||||
image: ghcr.io/goauthentik/radius
|
||||
# Optionally specify which networks the container should be
|
||||
# might be needed to reach the core authentik server
|
||||
# networks:
|
||||
# - foo
|
||||
ports:
|
||||
- 1812:1812/udp
|
||||
environment:
|
||||
AUTHENTIK_HOST: https://your-authentik.tld
|
||||
AUTHENTIK_INSECURE: "false"
|
||||
AUTHENTIK_TOKEN: token-generated-by-authentik
|
||||
```
|
||||
104
docs/topics/add-secure-apps/outposts/manual-deploy-kubernetes.md
Normal file
104
docs/topics/add-secure-apps/outposts/manual-deploy-kubernetes.md
Normal file
@ -0,0 +1,104 @@
|
||||
---
|
||||
title: Manual Outpost deployment on Kubernetes
|
||||
---
|
||||
|
||||
Use the following manifest, replacing all values surrounded with `__`.
|
||||
|
||||
Afterwards, configure the proxy provider to connect to `<service name>.<namespace>.svc.cluster.local`, and update your Ingress to connect to the `authentik-outpost` service.
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/instance: __OUTPOST_NAME__
|
||||
app.kubernetes.io/name: authentik-outpost
|
||||
name: authentik-outpost-api
|
||||
type: Opaque
|
||||
stringData:
|
||||
AUTHENTIK_HOST: "__AUTHENTIK_URL__"
|
||||
AUTHENTIK_INSECURE: "true"
|
||||
AUTHENTIK_TOKEN: "__AUTHENTIK_TOKEN__"
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/instance: __OUTPOST_NAME__
|
||||
app.kubernetes.io/name: authentik-outpost
|
||||
name: authentik-outpost
|
||||
spec:
|
||||
ports:
|
||||
- name: http
|
||||
port: 9000
|
||||
protocol: TCP
|
||||
targetPort: http
|
||||
- name: https
|
||||
port: 9443
|
||||
protocol: TCP
|
||||
targetPort: https
|
||||
type: ClusterIP
|
||||
selector:
|
||||
app.kubernetes.io/instance: __OUTPOST_NAME__
|
||||
app.kubernetes.io/name: authentik-outpost
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/instance: __OUTPOST_NAME__
|
||||
app.kubernetes.io/name: authentik-outpost
|
||||
name: authentik-outpost
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app.kubernetes.io/instance: __OUTPOST_NAME__
|
||||
app.kubernetes.io/name: authentik-outpost
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/instance: __OUTPOST_NAME__
|
||||
app.kubernetes.io/name: authentik-outpost
|
||||
spec:
|
||||
containers:
|
||||
- image: ghcr.io/goauthentik/proxy
|
||||
name: proxy
|
||||
ports:
|
||||
- containerPort: 9000
|
||||
name: http
|
||||
protocol: TCP
|
||||
- containerPort: 9443
|
||||
name: https
|
||||
protocol: TCP
|
||||
envFrom:
|
||||
- secretRef:
|
||||
name: authentik-outpost-api
|
||||
---
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
annotations:
|
||||
# This example includes annotations for common ingress controllers,
|
||||
# remove annotations not used
|
||||
nginx.ingress.kubernetes.io/affinity: cookie
|
||||
nginx.ingress.kubernetes.io/proxy-buffer-size: 16k
|
||||
nginx.ingress.kubernetes.io/proxy-buffers-number: "4"
|
||||
traefik.ingress.kubernetes.io/affinity: "true"
|
||||
labels:
|
||||
app.kubernetes.io/instance: __OUTPOST_NAME__
|
||||
app.kubernetes.io/name: authentik-outpost
|
||||
name: authentik-outpost
|
||||
spec:
|
||||
ingressClassName: nginx
|
||||
rules:
|
||||
- host: __EXTERNAL_HOSTNAME__
|
||||
http:
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
backend:
|
||||
service:
|
||||
name: authentik-outpost
|
||||
port:
|
||||
name: http
|
||||
```
|
||||
BIN
docs/topics/add-secure-apps/outposts/outpost-create.png
Normal file
BIN
docs/topics/add-secure-apps/outposts/outpost-create.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 131 KiB |
11
docs/topics/add-secure-apps/outposts/upgrading.md
Normal file
11
docs/topics/add-secure-apps/outposts/upgrading.md
Normal file
@ -0,0 +1,11 @@
|
||||
---
|
||||
title: Upgrading an Outpost
|
||||
---
|
||||
|
||||
In the Outpost Overview list, you'll see if any deployed outposts are out of date.
|
||||
|
||||
|
||||
|
||||
To upgrade the Outpost to the latest version, simply adjust the docker tag of the outpost to the new version.
|
||||
|
||||
Since the configuration is managed by authentik, that's all you have to do.
|
||||
BIN
docs/topics/add-secure-apps/outposts/upgrading_outdated.png
Normal file
BIN
docs/topics/add-secure-apps/outposts/upgrading_outdated.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Add an Entra ID provider
|
||||
authentik_enterprise: true
|
||||
---
|
||||
|
||||
For more information about using an Entra ID provider, see the [Overview](./index.md) documentation.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To create an Entra ID provider provider in authentik, you must have already [configured Entra ID](./setup-entra.md) to integrate with authentik. You will need to obtain from Entra three values: the Application (client) ID, the Directory (tenant) ID, and the Client secret. When adding an Entra ID provider in authentik, you must provide these values.
|
||||
|
||||
:::info
|
||||
As detailed in the steps below, when you add an Entra ID provider in authentik you must define the **Backchannel provider** using the name of the Entra ID provider that you created in authentik. If you have also configured Entra ID to log in using authentik, then this configuration can be done on the same app.
|
||||
:::
|
||||
|
||||
### Create the Entra ID provider in authentik
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
2. In the Admin interface, navigate to **Applications -> Providers**.
|
||||
3. Click **Create**, and in the **New provider** box select **Microsoft Entra Provider** as the type and click **Next**.
|
||||
4. Define the following fields:
|
||||
- **Name**: define a descriptive name, such as "Entra provider".
|
||||
|
||||
- **Protocol settings**
|
||||
- **Client ID**: enter the Client ID that you [copied from your Entra app](./setup-entra.md).
|
||||
- **Client Secret**: enter the secret from Entra.
|
||||
- **Tenant ID**: enter the Tenant ID from Entra.
|
||||
- **User deletion action**: determines what authentik will do when a user is deleted from the Entra ID system.
|
||||
- **Group deletion action**: determines what authentik will do when a group is deleted from the Entra ID system.
|
||||
|
||||
**User filtering**
|
||||
|
||||
- **Exclude service accounts**: set whether to include or exclude service accounts.
|
||||
- **Group**: select any specific groups to enforce that filtering (for all actions) is done only for the selected groups.
|
||||
|
||||
**Attribute mapping**
|
||||
|
||||
- **User Property Mappings**: select any applicable mappings, or use the default.
|
||||
- **Group Property Mappings**: select any applicable mappings, or use the default.
|
||||
|
||||
5. Click **Finish**.
|
||||
|
||||
### Create an Entra ID application in authentik
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
2. In the Admin interface, navigate to **Applications -> Applications**.
|
||||
3. Click **Create**, and define the following fields:
|
||||
- **Name**: provide a descriptive name.
|
||||
- **Slug**: enter the name of the app as you want it to appear in the URL.
|
||||
- **Group**: optionally, chose a group; apps in the same group are displayed together on the **My applications** page.
|
||||
- **Provider**: when _not_ used in conjunction with the Entra ID SAML configuration this field should be left empty.
|
||||
- **Backchannel Providers**: this field is required for Entra ID. Select the name of the Entra ID provider that you created in the steps above.
|
||||
- **Policy engine mode**: select **any** or **all** to set your policy mode.
|
||||
- **UI settings**: leave these fields empty for Entra ID.
|
||||
|
||||
4. Click **Create**.
|
||||
43
docs/topics/add-secure-apps/providers/entra/index.md
Normal file
43
docs/topics/add-secure-apps/providers/entra/index.md
Normal file
@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Microsoft Entra ID provider
|
||||
authentik_enterprise: true
|
||||
---
|
||||
|
||||
With the Microsoft Entra ID provider, authentik serves as the single source of truth for all users and groups. Configuring Entra ID as a provider allows for auto-discovery of user and group accounts, on-going synchronization of user data such as email address, name, and status, and integrated data mapping of field names and values.
|
||||
|
||||
- For instructions to configure your Entra ID tenant to integrate with authentik, refer to [Configure Entra ID](./setup-entra.md).
|
||||
- For instructions to add Entra ID as a provider in authentik, refer to [Create a Entra ID provider](./add-entra-provider.md).
|
||||
|
||||
## About using Entra ID with authentik
|
||||
|
||||
The following sections discuss how Entra ID operates with authentik.
|
||||
|
||||
### Discovery
|
||||
|
||||
When first creating and configuring the provider, authentik will run a discovery process and query your Entra ID for all users and groups, and attempt to match them with their respective counterparts in authentik. This discovery takes into consideration any **User filtering** options configured in the provider, such as only linking to authentik users in a specific group or excluding service accounts.
|
||||
|
||||
This discovery happens every time before a full sync is started.
|
||||
|
||||
### Synchronization
|
||||
|
||||
There are two types of synchronization: a direct sync and a full sync.
|
||||
|
||||
A _direct sync_ happens when a user or group is created, updated or deleted in authentik, or when a user is added to or removed from a group. When one of these events happens, the direct sync automatically forwards those changes to Entra ID.
|
||||
|
||||
The _full sync_ happens when the provider is initially created and when it is saved. The full sync goes through all users and groups matching the **User filtering** options set and will create/update them in Entra ID. After the initial sync, authentik will run a full sync every four hours to ensure the consistency of users and groups.
|
||||
|
||||
During either sync, if a user or group was created in authentik and a matching user/group exists in Entra ID, authentik will automatically link them together. Furthermore, users present in authentik but not in Entra ID will be created and and linked.
|
||||
|
||||
When a property mapping has an invalid expression, it will cause the sync to stop to prevent errors from being spammed. To handle any kind of network interruptions, authentik will detect transient request failures and retry any sync tasks.
|
||||
|
||||
### Customization for data mapping
|
||||
|
||||
There are a couple of considerations in regard to how authentik data is mapped to Entra ID user/group data by default.
|
||||
|
||||
- For users, authentik only saves the full display name, not separate first and family names.
|
||||
- By default, authentik synchs a user’s email, a user’s name, and their active status between Entra ID and authentik. For groups, the name is synced.
|
||||
|
||||
Refer to Microsoft documentation for further details.
|
||||
|
||||
- https://learn.microsoft.com/en-us/graph/api/user-post-users?view=graph-rest-1.0&tabs=http#request-body
|
||||
- https://learn.microsoft.com/en-us/graph/api/group-post-groups?view=graph-rest-1.0&tabs=http#request-body
|
||||
28
docs/topics/add-secure-apps/providers/entra/setup-entra.md
Normal file
28
docs/topics/add-secure-apps/providers/entra/setup-entra.md
Normal file
@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Configure Entra ID
|
||||
authentik_enterprise: true
|
||||
---
|
||||
|
||||
The configuration of your Microsoft Entra ID environment must be completed before you [add the new provider](./add-entra-provider.md) in authentik.
|
||||
|
||||
For detailed instructions, refer to Microsoft Entra ID documentation.
|
||||
|
||||
## Configure Entra ID
|
||||
|
||||
1. Log in to the Azure portal and on the Home page, under Azure services, click on or search for **App registrations**.
|
||||
2. On the **App registrations** page, click **New registration**.
|
||||
3. On the **Register an application** page, define the **Name** of the app, and under **Supported account types** select **Accounts in this organizational directory only**. Leave **Redirect URI** empty.
|
||||
4. Click **Register**.
|
||||
The app's detail page displays.
|
||||
5. On the app detail page, copy both the **Application (client) ID** and the **Directory (tenant) ID** values and store in a temporary place. These values will be needed when you [create the Entra ID provider](./add-entra-provider.md) in authentik.
|
||||
6. Next, click on **Certificates and Secrets** in the near-left navigation pane and create a new secret.
|
||||
7. On the **Certificates and Secrets** page, on the **Client secrets** tab, copy the **Value** of the secret and store it in a temporary place. Like with the client ID and the tenant ID, this secret will be needed when you [create the Entra ID provider](./add-entra-provider.md) in authentik.
|
||||
8. Next, click on **API permissions** in the near-left navigation pane.
|
||||
9. Click on **Add a permission** and add the following permissions by selecting **Microsoft Graph** and then **Application Permissions**:
|
||||
- `Group.Create`
|
||||
- `Group.ReadWrite.All`
|
||||
- `GroupMember.ReadWrite.All`
|
||||
- `User.Read`
|
||||
- `User.ReadWrite.All`
|
||||
|
||||
Now you are ready to [add Entra ID as a provider](./add-entra-provider.md) in authentik.
|
||||
@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Create a Google Workspace provider
|
||||
authentik_enterprise: true
|
||||
---
|
||||
|
||||
For more information about using a Google Workspace provider, see the [Overview](./index.md) documentation.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To create a Google Workspace provider in authentik, you must have already [configured Google Workspace](./setup-gws.md) to integrate with authentik.
|
||||
|
||||
:::info
|
||||
When adding the Google Workspace provider in authentik, you must define the **Backchannel provider** using the name of the Google Workspace provider that you created in authentik. If you have also configured Google Workspace to log in using authentik following [these](/integrations/services/google/), then this configuration can be done on the same app.
|
||||
:::
|
||||
|
||||
### Create the Google Workspace provider in authentik
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
|
||||
2. In the Admin interface, navigate to **Applications -> Providers**.
|
||||
|
||||
3. Click **Create**, and select **Google Workspace Provider**, and in the **New provider** box, define the following fields:
|
||||
- **Name**: define a descriptive name, such as "GWS provider".
|
||||
|
||||
- **Protocol settings**
|
||||
- **Credentials**: paste the contents of the JSON file you downloaded earlier.
|
||||
- **Delegated Subject**: enter the email address of the user all of authentik's actions should be delegated to
|
||||
- **Default group email domain**: enter a default domain which will be used to generate the domain for groups synced from authentik.
|
||||
- **User deletion action**: determines what authentik will do when a user is deleted from authentik.
|
||||
- **Group deletion action**: determines what authentik will do when a group is deleted from authentik.
|
||||
|
||||
- **User filtering**
|
||||
- **Exclude service accounts**: set whether to include or exclude service accounts.
|
||||
- **Group**: select any specific groups to enforce that filtering (for all actions) is done only for the selected groups.
|
||||
|
||||
- **Attribute mapping**
|
||||
- **User Property Mappings**: select any applicable mappings, or use the default.
|
||||
- **Group Property Mappings**: select any applicable mappings, or use the default.
|
||||
|
||||
4. Click **Finish**.
|
||||
|
||||
### Create a Google Workspace application in authentik
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
2. In the Admin interface, navigate to **Applications -> Applications**.
|
||||
:::info
|
||||
If you have also configured Google Workspace to log in using authentik following [these](https://docs.goauthentik.io/integrations/services/google/index), then this configuration can be done on the same app by adding this new provider as a backchannel provider on the existing app instead of creating a new app.
|
||||
:::
|
||||
3. Click **Create**, and in the **New provider** box, and define the following fields:
|
||||
- **Slug**: enter the name of the app as you want it to appear in the URL.
|
||||
- **Provider**: when _not_ used in conjunction with the Google SAML configuration should be left empty.
|
||||
- **Backchannel Providers**: this field is required for Google Workspace. Select the name of the Google Workspace provider that you created in the steps above.
|
||||
- **UI settings**: leave these fields empty for Google Workspace.
|
||||
|
||||
4. Click **Finish**.
|
||||
46
docs/topics/add-secure-apps/providers/gws/index.md
Normal file
46
docs/topics/add-secure-apps/providers/gws/index.md
Normal file
@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Google Workspace provider
|
||||
authentik_enterprise: true
|
||||
---
|
||||
|
||||
With the Google Workspace provider, authentik serves as the single source of truth for all users and groups, when using Google products like Gmail.
|
||||
|
||||
- For instructions to configure your Google Workspace to integrate with authentik, refer to [Configure Google Workspace](./setup-gws.md).
|
||||
- For instructions to add Google Workspace as a provider, refer to [Create a Google Workspace provider](./add-gws-provider.md).
|
||||
|
||||
## About using Google Workspace with authentik
|
||||
|
||||
The following sections discuss how Google Workspace operates with authentik.
|
||||
|
||||
### Discovery
|
||||
|
||||
When first creating the provider and setting it up correctly, the provider will run a discovery and query your google workspace for all users and groups, and attempt to match them with their respective counterparts in authentik.
|
||||
|
||||
This matching is done by email address for users as google uses that as their primary identifier, and using group names for groups. This discovery also takes into consideration any **User filtering** options configured in the provider, such as only linking to authentik users in a specific group or excluding service accounts. This discovery happens every time before a full sync is started.
|
||||
|
||||
### Synchronization
|
||||
|
||||
There are two types of synchronization: a direct sync and a full sync.
|
||||
|
||||
A _direct sync_ happens when a user or group is created, updated or deleted in authentik, or when a user is added to or removed from a group. When one of these events happens, the direct sync automatically forwards those changes to Google Workspace.
|
||||
|
||||
The _full sync_ happens when the provider is initially created and when it is saved. The full sync goes through all users and groups matching the **User filtering** options set and will create/update them in Google Workspace. After the initial sync, authentik will run a full sync every four hours to ensure the consistency of users and groups.
|
||||
|
||||
During the full sync, if a user or group was created in authentik and a matching user/group exists in Google Workspace, authentik will automatically link them together. Furthermore, users present in authentik but not in Google Workspace will be created and and linked.
|
||||
|
||||
When a property mapping has an invalid expression, it will cause the sync to stop to prevent errors from being spammed. To handle any kind of network interruptions, authentik will detect transient request failures and retry any sync tasks.
|
||||
|
||||
### Customization for data mapping
|
||||
|
||||
There are a couple of considerations in regard to how authentik data is mapped to google workspace user/group data by default.
|
||||
|
||||
- For users, authentik only saves the full display name, while Google requires given/family name separately, and as such authentik attempts to separate the full name automatically with the default User property mapping.
|
||||
|
||||
- For groups, Google groups require an email address. Thus in authentik the provider configuration has an option **Default group email domain**, which will be used in conjunction with the group’s name to generate an email address. This can be customized with a property mapping.
|
||||
|
||||
- By default, authentik maps a user’s email, a user’s name, and their active status. For groups, the name is synced.
|
||||
|
||||
Refer to Google documentation for further details on which fields data can be mapped to:
|
||||
|
||||
- https://developers.google.com/admin-sdk/directory/reference/rest/v1/users#User
|
||||
- https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups#Group
|
||||
66
docs/topics/add-secure-apps/providers/gws/setup-gws.md
Normal file
66
docs/topics/add-secure-apps/providers/gws/setup-gws.md
Normal file
@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Configure Google Workspace
|
||||
authentik_enterprise: true
|
||||
---
|
||||
|
||||
The configuration and set up of your Google Workspace must be completed before you [add the new provider](./add-gws-provider.md) in authentik.
|
||||
|
||||
## Overview of steps
|
||||
|
||||
The main steps to set up your Google workspace are as follows:
|
||||
|
||||
1. [Create your Google Cloud Project](#create-a-google-cloud-project)
|
||||
2. [Create a service account](#create-a-service-account)
|
||||
3. [Set credentials for the service account](#set-credentials-for-the-service-account)
|
||||
4. [Define access and scope in the Admin Console](#set-credentials-for-the-service-account)
|
||||
5. [Select email address for the Delegated Subject](#select-email-address-for-the-delegated-subject)
|
||||
|
||||
For detailed instructions, refer to Google documentation.
|
||||
|
||||
### Create a Google cloud project
|
||||
|
||||
1. Open the Google Cloud Console (https://cloud.google.com/cloud-console).
|
||||
2. In upper left, click the drop-down box to open the **Select a project** box, and then select **New Project**.
|
||||
3. Create a new project and give it a name like "authentik GWS"
|
||||
4. Use the search bar at the top of your new project page to search for "API Library".
|
||||
5. On the **API Library** page, use the search bar again to find "Admin SDK API".
|
||||
6. On the **Admin SDK API** page, click **Enable**.
|
||||
|
||||
### Create a service account
|
||||
|
||||
1. After the new Admin SDK API is enabled (it might take a few minutes), return to the Google Cloud console home page (click on **Google Cloud** in upper left).
|
||||
2. Use the search bar to find and navigate to the **IAM** page.
|
||||
3. On the **IAM** page, click **Service Accounts** in the left navigation pane.
|
||||
4. At the top of the **Service Accounts** page, click **Create Service Account**.
|
||||
|
||||
- Under **Service account details** page, define the **Name** and **Description** for the new service account, and then click **Create and Continue**.
|
||||
- Under **Grant this service account access to project** you do not need to define a role, so click **Continue**.
|
||||
- Under **Grant users access to project** you do not need to define a role, so click **Done** to complete the creation of the service account.
|
||||
|
||||
### Set credentials for the service account
|
||||
|
||||
1. On the **Service accounts** page, click the account that you just created.
|
||||
2. Click the **Keys** tab at top of the page, the click **Add Key -> Create new key**.
|
||||
3. In the Create box, select JSON as the key type, and then click **Create**.
|
||||
A pop-up displays with the private key, and the key is saved to your computer as a JSON file.
|
||||
Later, when you create your authentik provider for Google Workspace, you will add this key in the **Credentials** field.
|
||||
4. On the service account page, click the **Details** tab, and expand the **Advanced settings** area.
|
||||
5. Copy the **Client ID** (under **Domain-wide delegation**), and then click **View Google Workspace Admin Console**.
|
||||
6. Log in to the Admin Console, and then navigate to **Security -> Access and data control -> API controls**.
|
||||
7. On the **API controls** page, click **Manage Domain Wide Delegation**.
|
||||
8. On the **Domain Wide Delegation** page, click **Add new**.
|
||||
9. In the **Add a new client ID** box, paste in the Client ID that you copied from the Admin console earlier (the value from the downloaded JSON file) and paste in the following scope documents:
|
||||
- `https://www.googleapis.com/auth/admin.directory.user`
|
||||
- `https://www.googleapis.com/auth/admin.directory.group`
|
||||
- `https://www.googleapis.com/auth/admin.directory.group.member`
|
||||
- `https://www.googleapis.com/auth/admin.directory.domain.readonly`
|
||||
|
||||
### Select email address for the Delegated Subject
|
||||
|
||||
The Delegated Subject email address is a required field when creating the provider in authentik.
|
||||
|
||||
1. Open to the main Admin console page, and navigate to **Directory -> Users**.
|
||||
2. You can either select an existing user's email address or **Add new user** and define the user and email address to use as the Delegated Subject.
|
||||
3. Save this email address to enter into authentik when you are creating the Google Workspace provider.
|
||||
|
||||
Now that you have configured your Google Workspace, you are ready to [add it as a provider in authentik](./add-gws-provider.md).
|
||||
22
docs/topics/add-secure-apps/providers/index.mdx
Normal file
22
docs/topics/add-secure-apps/providers/index.mdx
Normal file
@ -0,0 +1,22 @@
|
||||
---
|
||||
title: Providers
|
||||
slug: /providers
|
||||
---
|
||||
|
||||
import DocCardList from "@theme/DocCardList";
|
||||
|
||||
A Provider is an authentication method, a service that is used by authentik to authenticate the user for the associated application. Common Providers are OpenID Connect (OIDC)/OAuth2, LDAP, SAML, and generic proxy provider, and others.
|
||||
|
||||
Providers are the "other half" of [applications](../applications/index.md). They typically exist in a 1-to-1 relationship; each application needs a provider and every provider can be used with one application.
|
||||
|
||||
Applications can use additional providers to augment the functionality of the main provider. For more information, see [Backchannel providers](../applications/manage_apps.mdx#backchannel-providers).
|
||||
|
||||
You can create a new provider in the Admin interface, or you can use the [**Create with provider** option](../applications/manage_apps.mdx#instructions) to create a new application and its provider at the same time.
|
||||
|
||||
When you create certain types of providers, you need to select specific [flows](../flows-stages/flow/index.md) to apply to users who access authentik via the provider. To learn more, refer to our [default flow documentation](../flows-stages/flow/examples/default_flows.md).
|
||||
|
||||
To learn more about each provider type, refer to the documentation for each provider:
|
||||
|
||||
<DocCardList />
|
||||
|
||||
You can also create a SAML provider by uploading an SP metadata XML file that contains the service provider's configuration data. SAML metadata is used to share configuration information between the Identity Provider (IdP) and the Service Provider (SP). An SP metadata XML file typically contains the SP certificate, the entity ID, the Assertion Consumer Service URL (ACS URL), and a log out URL (SingleLogoutService).
|
||||
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup1.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup10.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup10.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup11.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup11.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup12.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup12.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup13.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup13.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup14.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup14.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup15.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup15.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 106 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup16.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup16.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup2.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup3.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup3.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup4.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup4.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup5.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup5.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup6.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup6.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup7.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup7.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup8.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup8.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup9.png
Normal file
BIN
docs/topics/add-secure-apps/providers/ldap/general_setup9.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
95
docs/topics/add-secure-apps/providers/ldap/generic_setup.md
Normal file
95
docs/topics/add-secure-apps/providers/ldap/generic_setup.md
Normal file
@ -0,0 +1,95 @@
|
||||
---
|
||||
title: Create an LDAP provider
|
||||
---
|
||||
|
||||
### Create Service account
|
||||
|
||||
1. Create a new user account to bind with under _Directory_ -> _Users_ -> _Create_, in this example called `ldapservice`.
|
||||
|
||||
Note the DN of this user will be `cn=ldapservice,ou=users,dc=ldap,dc=goauthentik,dc=io`
|
||||
|
||||
:::info
|
||||
Note: The `default-authentication-flow` validates MFA by default, and currently everything but SMS-based devices and WebAuthn (which enables passkey-based authentication) devices are supported by LDAP. If you plan to use only dedicated service accounts to bind to LDAP, or don't use SMS-based authenticators, then you can use the default flow and skip the extra steps below and continue at [Create LDAP Application & Provider](#create-ldap-application--provider)
|
||||
:::
|
||||
|
||||
### LDAP Flow
|
||||
|
||||
#### Create Custom Stages
|
||||
|
||||
1. Create a new identification stage. _Flows & Stage_ -> _Stages_ -> _Create_
|
||||
|
||||
2. Name it `ldap-identification-stage`. Select User fields Username and Email (and UPN if it is relevant to your setup).
|
||||
|
||||
3. Create a new password stage. _Flows & Stage_ -> _Stages_ -> _Create_
|
||||
|
||||
4. Name it `ldap-authentication-password`. Leave the defaults for Backends.
|
||||
|
||||
5. Create a new user login stage. _Flows & Stage_ -> _Stages_ -> _Create_
|
||||
|
||||
6. Name it `ldap-authentication-login`.
|
||||
|
||||
|
||||
#### Create Custom Flow
|
||||
|
||||
1. Create a new authentication flow under _Flows & Stage_ -> _Flows_ -> _Create_, and name it `ldap-authentication-flow`
|
||||
|
||||
2. Click the newly created flow and choose _Stage Bindings_.
|
||||
|
||||
3. Click `Bind Stage` choose `ldap-identification-stage` and set the order to `10`.
|
||||
|
||||
4. Click `Bind Stage` choose `ldap-authentication-login` and set the order to `30`.
|
||||
|
||||
5. Edit the `ldap-identification-stage`.
|
||||
|
||||
6. Change the Password stage to `ldap-authentication-password`.
|
||||
|
||||
|
||||
### Create LDAP Application & Provider
|
||||
|
||||
1. Create the LDAP Application under _Applications_ -> _Applications_ -> _Create With provider_ and name it `LDAP`.
|
||||
|
||||
|
||||
|
||||
### Assign LDAP permissions
|
||||
|
||||
1. Navigate to the LDAP Provider under _Applications_ -> _Providers_ -> `Provider for LDAP`.
|
||||
2. Switch to the _Permissions_ tab.
|
||||
3. Click the _Assign to new user_ button to select a user to assign the full directory search permission to.
|
||||
4. Select the `ldapservice` user typing in its username. Select the _Search full LDAP directory_ permission and click _Assign_
|
||||
|
||||
### Create LDAP Outpost
|
||||
|
||||
1. Create (or update) the LDAP Outpost under _Applications_ -> _Outposts_ -> _Create_. Set the Type to `LDAP` and choose the `LDAP` application created in the previous step.
|
||||
|
||||
|
||||
:::info
|
||||
The LDAP Outpost selects different providers based on their Base DN. Adding multiple providers with the same Base DN will result in inconsistent access
|
||||
:::
|
||||
|
||||
### ldapsearch Test
|
||||
|
||||
Test connectivity by using ldapsearch.
|
||||
|
||||
:::info
|
||||
ldapsearch can be installed on Linux system with these commands
|
||||
|
||||
```shell
|
||||
sudo apt-get install ldap-utils -y # Debian-based systems
|
||||
sudo yum install openldap-clients -y # CentOS-based systems
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
```shell
|
||||
ldapsearch \
|
||||
-x \
|
||||
-H ldap://<LDAP Outpost IP address>:<Port number 389> \ # In production it is recommended to use SSL, which also requires `ldaps://` as the protocol and the SSL port
|
||||
-D 'cn=ldapservice,ou=users,DC=ldap,DC=goauthentik,DC=io' \
|
||||
-w '<ldapuserpassword>' \
|
||||
-b 'DC=ldap,DC=goauthentik,DC=io' \
|
||||
'(objectClass=user)'
|
||||
```
|
||||
|
||||
:::info
|
||||
This query will log the first successful attempt in an event in the _Events_ -> _Logs_ area, further successful logins from the same user are not logged as they are cached in the outpost.
|
||||
:::
|
||||
121
docs/topics/add-secure-apps/providers/ldap/index.md
Normal file
121
docs/topics/add-secure-apps/providers/ldap/index.md
Normal file
@ -0,0 +1,121 @@
|
||||
---
|
||||
title: LDAP Provider
|
||||
---
|
||||
|
||||
You can configure an LDAP Provider for applications that don't support any newer protocols or require LDAP.
|
||||
|
||||
:::info
|
||||
Note: This provider requires the deployment of the [LDAP Outpost](../../outposts/index.mdx)
|
||||
:::
|
||||
|
||||
All users and groups in authentik's database are searchable. Currently, there is limited support for filters (you can only search for objectClass), but this will be expanded in further releases.
|
||||
|
||||
Binding against the LDAP Server uses a flow in the background. This allows you to use the same policies and flows as you do for web-based logins. For more info, see [Bind modes](#binding--bind-modes).
|
||||
|
||||
You can configure under which base DN the information should be available. For this documentation we'll use the default of `DC=ldap,DC=goauthentik,DC=io`.
|
||||
|
||||
Users are available under `ou=users,<base DN>` and groups under `ou=groups,<base DN>`. To aid compatibility, each user belongs to its own "virtual" group, as is standard on most Unix-like systems. This group does not exist in the authentik database, and is generated on the fly. These virtual groups are under the `ou=virtual-groups,<base DN>` DN.
|
||||
|
||||
:::info
|
||||
Note: Every LDAP provider needs to have a unique base DN. You can achieve this by prepending an application-specific OU or DC. e.g. `OU=appname,DC=ldap,DC=goauthentik,DC=io`
|
||||
:::
|
||||
|
||||
The following fields are currently sent for users:
|
||||
|
||||
- `cn`: User's username
|
||||
- `uid`: Unique user identifier
|
||||
- `uidNumber`: A unique numeric identifier for the user
|
||||
- `name`: User's name
|
||||
- `displayName`: User's name
|
||||
- `mail`: User's email address
|
||||
- `objectClass`: A list of these strings:
|
||||
- "user"
|
||||
- "organizationalPerson"
|
||||
- "goauthentik.io/ldap/user"
|
||||
- `memberOf`: A list of all DNs that the user is a member of
|
||||
- `homeDirectory`: A default home directory path for the user, by default `/home/$username`. Can be overwritten by setting `homeDirectory` as an attribute on users or groups.
|
||||
- `ak-active`: "true" if the account is active, otherwise "false"
|
||||
- `ak-superuser`: "true" if the account is part of a group with superuser permissions, otherwise "false"
|
||||
|
||||
The following fields are current set for groups:
|
||||
|
||||
- `cn`: The group's name
|
||||
- `uid`: Unique group identifier
|
||||
- `gidNumber`: A unique numeric identifier for the group
|
||||
- `member`: A list of all DNs of the groups members
|
||||
- `objectClass`: A list of these strings:
|
||||
- "group"
|
||||
- "goauthentik.io/ldap/group"
|
||||
|
||||
A virtual group is also created for each user, they have the same fields as groups but have an additional objectClass: `goauthentik.io/ldap/virtual-group`.
|
||||
The virtual groups gidNumber is equal to the uidNumber of the user.
|
||||
|
||||
**Additionally**, for both users and (non-virtual) groups, any attributes you set are also present as LDAP Attributes.
|
||||
|
||||
:::info
|
||||
Starting with 2021.9.1, custom attributes will override the inbuilt attributes.
|
||||
:::
|
||||
|
||||
:::info
|
||||
Starting with 2023.3, periods and slashes in custom attributes will be sanitized.
|
||||
:::
|
||||
|
||||
## SSL / StartTLS
|
||||
|
||||
You can also configure SSL for your LDAP Providers by selecting a certificate and a server name in the provider settings.
|
||||
|
||||
Starting with authentik 2023.6, StartTLS is supported, and the provider will pick the correct certificate based on the configured _TLS Server name_ field. The certificate is not picked based on the Bind DN, as the StartTLS operation should happen before the bind request to ensure bind credentials are transmitted over TLS.
|
||||
|
||||
This enables you to bind on port 636 using LDAPS.
|
||||
|
||||
## Integrations
|
||||
|
||||
See the integration guide for [sssd](/integrations/services/sssd/) for an example guide.
|
||||
|
||||
## Binding & Bind Modes
|
||||
|
||||
All bind modes rely on flows.
|
||||
|
||||
The following stages are supported:
|
||||
|
||||
- [Identification](../../flows-stages/stages/identification/index.mdx)
|
||||
- [Password](../../flows-stages/stages/password/index.md)
|
||||
- [Authenticator validation](../../flows-stages/stages/authenticator_validate/index.mdx)
|
||||
|
||||
Note: Authenticator validation currently only supports DUO, TOTP and static authenticators.
|
||||
|
||||
Starting with authentik 2023.6, code-based authenticators are only supported when _Code-based MFA Support_ is enabled in the provider. When enabled, all users that will bind to the LDAP provider should have a TOTP device configured, as otherwise a password might be incorrectly rejected when semicolons are used in the password.
|
||||
|
||||
For code-based authenticators, the code must be given as part of the bind password, separated by a semicolon. For example for the password `example-password` and the code `123456`, the input must be `example-password;123456`.
|
||||
|
||||
SMS-based authenticators are not supported as they require a code to be sent from authentik, which is not possible during the bind.
|
||||
|
||||
- [User Logout](../../flows-stages/stages/user_logout.md)
|
||||
- [User Login](../../flows-stages/stages/user_login/index.md)
|
||||
- [Deny](../../flows-stages/stages/deny.md)
|
||||
|
||||
#### Direct bind
|
||||
|
||||
In this mode, the outpost will always execute the configured flow when a new bind request is received.
|
||||
|
||||
#### Cached bind
|
||||
|
||||
This mode uses the same logic as direct bind, however the result is cached for the entered credentials, and saved in memory for the standard session duration. Sessions are saved independently, meaning that revoking sessions does _not_ remove them from the outpost, and neither will changing a users credentials.
|
||||
|
||||
## Searching & Search Modes
|
||||
|
||||
Any user that is authorized to access the LDAP provider's application can execute search the LDAP directory. Without explicit permissions to do broader searches, a user's search request will return information about themselves, including user info, group info, and group membership.
|
||||
|
||||
[Users](../../../users-sources/user/index.mdx) and [roles](../../../users-sources/roles/index.md) can be assigned the permission "Search full LDAP directory" to allow them to search the full LDAP directory and retrieve information about all users in the authentik instance.
|
||||
|
||||
:::info
|
||||
Up to authentik version 2024.8 this was managed using the "Search group" attribute in the LDAP Provider, where users could be added to a group to grant them this permission. With authentik 2024.8 this is automatically migrated to the "Search full LDAP directory" permission, which can be assigned more flexibly.
|
||||
:::
|
||||
|
||||
#### Direct search
|
||||
|
||||
Every LDAP search request will trigger one or more requests to the authentik core API. This will always return the latest data, however also has a performance hit due all the layers the backend requests have to go through, etc.
|
||||
|
||||
#### Cached search
|
||||
|
||||
In this mode, the outpost will periodically fetch all users and groups from the backend, hold them in memory, and respond to search queries directly. This means greatly improved performance but potentially returning old/invalid data.
|
||||
@ -0,0 +1,87 @@
|
||||
## Machine-to-machine authentication
|
||||
|
||||
Client credentials can be used for machine-to-machine communication authentication. Clients can authenticate themselves using service-accounts; standard client_id + client_secret is not sufficient. This behavior is due to providers only being able to have a single secret at any given time.
|
||||
|
||||
Note that authentik does treat a grant type of `password` the same as `client_credentials` to support applications which rely on a password grant.
|
||||
|
||||
### Static authentication
|
||||
|
||||
Hence identification is based on service-accounts, and authentication is based on App-password tokens. These objects can be created in a single step using the _Create Service account_ function.
|
||||
|
||||
An example request can look like this:
|
||||
|
||||
```http
|
||||
POST /application/o/token/ HTTP/1.1
|
||||
Host: authentik.company
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
grant_type=client_credentials&
|
||||
client_id=application_client_id&
|
||||
username=my-service-account&
|
||||
password=my-token&
|
||||
scope=profile
|
||||
```
|
||||
|
||||
This will return a JSON response with an `access_token`, which is a signed JWT token. This token can be sent along requests to other hosts, which can then validate the JWT based on the signing key configured in authentik.
|
||||
|
||||
Starting with authentik 2024.4, it is also possible to encode the username and token of the user to authenticate with, separated with a colon, into a base64 string and pass it as `client_secret` value.
|
||||
|
||||
In addition to that, with authentik 2024.4 it is also possible to pass the configured `client_secret` value, which will automatically generate a service account user for which the JWT token will be issued.
|
||||
|
||||
### JWT-authentication
|
||||
|
||||
#### Externally issued JWTs
|
||||
|
||||
You can authenticate and get a token using an existing JWT. For readability we will refer to the JWT issued by the external issuer/platform as input JWT, and the resulting JWT from authentik as the output JWT.
|
||||
|
||||
To configure this, define a JWKS URL/raw JWKS data in OAuth Sources. If a JWKS URL is specified, authentik will fetch the data and store it in the source, and then select the source in the OAuth2 Provider that will be authenticated against.
|
||||
|
||||
With this configuration, any JWT issued by the configured sources' certificates can be used to authenticate:
|
||||
|
||||
```http
|
||||
POST /application/o/token/ HTTP/1.1
|
||||
Host: authentik.company
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
grant_type=client_credentials&
|
||||
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
|
||||
client_assertion=$inputJWT&
|
||||
client_id=application_client_id
|
||||
```
|
||||
|
||||
Alternatively, you can set the `client_secret` parameter to `$inputJWT`, for applications that can set the password from a file but not other parameters.
|
||||
|
||||
Input JWTs are checked to verify that they are signed by any of the selected _Federated OIDC Sources_, and that their `exp` attribute is not set as now or in the past.
|
||||
|
||||
To dynamically limit access based on the claims of the tokens, you can use _[Expression policies](../../../customize/policies/expression.mdx)_:
|
||||
|
||||
```python
|
||||
return request.context["oauth_jwt"]["iss"] == "https://my.issuer"
|
||||
```
|
||||
|
||||
#### authentik-issued JWTs:ak-version[2024.12]
|
||||
|
||||
To allow federation between providers, modify the provider settings of the application (whose token will be used for authentication) to select the provider of the application to which you want to federate.
|
||||
|
||||
With this configuration, any JWT issued by the configured providers can be used to authenticate:
|
||||
|
||||
```
|
||||
POST /application/o/token/ HTTP/1.1
|
||||
Host: authentik.company
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
grant_type=client_credentials&
|
||||
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
|
||||
client_assertion=$inputJWT&
|
||||
client_id=application_client_id
|
||||
```
|
||||
|
||||
Alternatively, you can set the `client_secret` parameter to the `$inputJWT`, for applications which can set the password from a file but not other parameters.
|
||||
|
||||
Input JWTs must be valid access tokens issued by any of the configured _Federated OIDC Providers_, they must not have been revoked and must not have expired.
|
||||
|
||||
To dynamically limit access based on the claims of the tokens, you can use _[Expression policies](../../../customize/policies/expression.mdx)_:
|
||||
|
||||
```python
|
||||
return request.context["oauth_jwt"]["iss"] == "https://my.issuer"
|
||||
```
|
||||
@ -0,0 +1,19 @@
|
||||
---
|
||||
title: Create an OAuth2 provider
|
||||
---
|
||||
|
||||
To add a provider (and the application that uses the provider for authentication) use the ** Create with provider** option, which creates both the new application and the required provider at the same time. For typical scenarios, authentik recommends that you create both the application and the provider together. (Alternatively, use our legacy process: navigate to **Applications --> Providers**, and then click **Create**.)
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
|
||||
2. Navigate to **Applications -> Applications** and click **Create with provider** to create an application and provider pair. (Alternatively you can create only an application, without a provider, by clicking **Create**.)
|
||||
|
||||
3. In the **New application** box, define the application details, and then click **Next**.
|
||||
|
||||
4. Select the **Provider Type** of **OAuth2/OIDC**, and then click **Next**.
|
||||
|
||||
5. On the **Configure OAuth2/OpenId Provider** page, provide the configuration settings and then click **Submit** to create and save both the application and the provider.
|
||||
|
||||
:::info
|
||||
Optionally, configure the provider to have the `offline_access` scope mapping. Starting with authentik 2024.2, by default applications only receive an access token. To receive a refresh token, both applications and authentik must be configured to request the `offline_access` scope. Do this in the Scope mapping area on the **Configure OAuth2/OpenId Provider** page.
|
||||
:::
|
||||
65
docs/topics/add-secure-apps/providers/oauth2/device_code.md
Normal file
65
docs/topics/add-secure-apps/providers/oauth2/device_code.md
Normal file
@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Device code flow
|
||||
---
|
||||
|
||||
The device code flow is also known as _device flow_ or _device authorization grant flow_. This type of authentication flow is useful for devices with limited input capabilities and/or devices without browsers. The Request for Comments (RFC) 8628) abstract for this flow states:
|
||||
|
||||
> The OAuth 2.0 device authorization grant is designed for Internet-connected devices that either lack a browser to perform a user-agent-based authorization or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorization flow is impractical. It enables OAuth clients on such devices (like smart TVs, media consoles, digital picture frames, and printers) to obtain user authorization to access protected resources by using a user agent on a separate device.
|
||||
|
||||
### Requirements
|
||||
|
||||
This device flow is only possible if the active [brand](../../../sys-mgmt/brands.md) has a device code flow configured. This flow is run _after_ the user logs in, and before the user authenticates.
|
||||
|
||||
authentik does not include a default flow for this use case, so it is necessary to create a new one with a **Designation** of `Stage Configuration`.
|
||||
|
||||
### Device flow initiation
|
||||
|
||||
The flow is initiated by sending a POST request to the device authorization endpoint, `/application/o/device/`, with the following contents:
|
||||
|
||||
```http
|
||||
POST /application/o/device/ HTTP/1.1
|
||||
Host: authentik.company
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
client_id=application_client_id&
|
||||
scope=openid email my-other-scope
|
||||
```
|
||||
|
||||
The response contains the following fields:
|
||||
|
||||
- `device_code`: Device code, which is the code kept on the device
|
||||
- `verification_uri`: The URL to be shown to the enduser to input the code
|
||||
- `verification_uri_complete`: The same URL as above except the code will be prefilled
|
||||
- `user_code`: The raw code for the enduser to input
|
||||
- `expires_in`: The total seconds after which this token will expire
|
||||
- `interval`: The interval in seconds for how often the device should check the token status
|
||||
|
||||
With this response, the device can start checking the status of the token by sending requests to the token endpoint like this:
|
||||
|
||||
```http
|
||||
POST /application/o/token/ HTTP/1.1
|
||||
Host: authentik.company
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
grant_type=urn:ietf:params:oauth:grant-type:device_code&
|
||||
client_id=application_client_id&
|
||||
device_code=device_code_from_above
|
||||
```
|
||||
|
||||
If the user has not opened the link above yet, or has not finished the authentication and authorization yet, the response will contain an `error` element set to `authorization_pending`. The device should re-send the request in the interval set above.
|
||||
|
||||
If the user _has_ finished the authentication and authorization, the response will be similar to any other generic OAuth2 Token request, containing `access_token` and `id_token`.
|
||||
|
||||
### Create and apply a device code flow
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Flows and Stages** > **Flows** and click **Create**.
|
||||
3. Set the following required configurations:
|
||||
- **Name**: provide a name (e.g. `default-device-code-flow`)
|
||||
- **Title**: provide a title (e.g. `Device code flow`)
|
||||
- **Slug**: provide a slug (e.g `default-device-code-flow`)
|
||||
- **Designation**: `Stage Configuration`
|
||||
- **Authentication**: `Require authentication`
|
||||
4. Click **Create**.
|
||||
5. Navigate to **System** > **Brands** and click the **Edit** icon on the default brand.
|
||||
6. Set **Default code flow** to the newly created device code flow and click **Update**.
|
||||
@ -0,0 +1,23 @@
|
||||
---
|
||||
title: GitHub compatibility
|
||||
---
|
||||
|
||||
The OAuth2 provider also exposes a GitHub-compatible endpoint. This endpoint can be used by applications, which support authenticating against GitHub Enterprise, but not generic OpenID Connect.
|
||||
|
||||
To use any of the GitHub Compatibility scopes, you have to use the GitHub Compatibility Endpoints.
|
||||
|
||||
| Endpoint | URL |
|
||||
| --------------- | --------------------------- |
|
||||
| Authorization | `/login/oauth/authorize` |
|
||||
| Token | `/login/oauth/access_token` |
|
||||
| User Info | `/user` |
|
||||
| User Teams Info | `/user/teams` |
|
||||
|
||||
To access the user's email address, a scope of `user:email` is required. To access their groups, `read:org` is required. Because these scopes are handled by a different endpoint, they are not customisable as a Scope Mapping.
|
||||
|
||||
## Special scopes for GitHub compatibility
|
||||
|
||||
- `user`: No-op, is accepted for compatibility but does not give access to any resources
|
||||
- `read:user`: Same as above
|
||||
- `user:email`: Allows read-only access to `/user`, including email address
|
||||
- `read:org`: Allows read-only access to `/user/teams`, listing all the user's groups as teams.
|
||||
182
docs/topics/add-secure-apps/providers/oauth2/index.mdx
Normal file
182
docs/topics/add-secure-apps/providers/oauth2/index.mdx
Normal file
@ -0,0 +1,182 @@
|
||||
---
|
||||
title: OAuth 2.0 provider
|
||||
---
|
||||
|
||||
In authentik, you can [create](./create-oauth2-provider.md) an [OAuth 2.0](https://oauth.net/2/) provider that authentik uses to authenticate the user to the associated application. This provider supports both generic OAuth2 as well as OpenID Connect (OIDC).
|
||||
|
||||
## authentik and OAuth 2.0
|
||||
|
||||
It's important to understand how authentik works with and supports the OAuth 2.0 protocol, so before taking a [closer look at OAuth 2.0 protocol](#about-oauth-20-and-oidc) itself, let's cover a bit about authentik.
|
||||
|
||||
authentik can act either as the OP, (OpenID Provider, with authentik as the IdP), or as the RP (Relying Party, or the application that uses OAuth 2.0 to authenticate). If you want to configure authentik as an OP, then you create a provider, then use the OAuth 2.0 provider. If you want authentik to serve as the RP, then configure a [source](../../../users-sources/sources/index.md). Of course, authentik can serve as both the RP and OP, if you want to use the authentik OAuth provider and also use sources.
|
||||
|
||||
All standard OAuth 2.0 flows (authorization code, client_credentials, implicit, hybrid, device code) and grant types are supported in authentik, and we follow the [OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html). OAuth 2.0 in authentik supports OAuth, PKCE, [Github compatibility](./github-compatibility.md) and the RP receives data from our scope mapping system.
|
||||
|
||||
The authentik OAuth 2.0 provider comes with all the standard functionality and features of OAuth 2.0, including the OAuth 2.0 security principles such as no cleartext storage of credentials, configurable encryption, configurable short expiration times, and the configuration of automatic rotation of refresh tokens. In short, our OAuth 2.0 protocol support provides full coverage.
|
||||
|
||||
## About OAuth 2.0 and OIDC
|
||||
|
||||
OAuth 2.0 is an authorization protocol that allows an application (the RP) to delegate authorization to an OP. OIDC is an authentication protocol built on top of OAuth2, which provides identity credentials and other data on top of OAuth2.
|
||||
|
||||
**OAuth 2.0** typically requires two requests (unlike the previous "three-legged" OAuth 1.0). The two "legs", or requests, for OAuth 2.0 are:
|
||||
|
||||
1. An authorization request is prepared by the RP and contains parameters for its implementation of OAuth and which data it requires, and then the User's browser is redirected to that URL.
|
||||
2. The RP sends a request to authentik in the background to exchange the access code for an access token (and optionally a refresh token).
|
||||
|
||||
In detail, with OAuth2 when a user accesses the application (the RP) via their browser, the RP then prepares a URL with parameters for the OpenID Provider (OP), which the users's browser is redirected to. The OP authenticates the user and generates an authorization code. The OP then redirects the client (the user's browser) back to the RP, along with that authorization code. In the background, the RP then sends that same authorization code in a request authenticated by the `client_id` and `client_secret` to the OP. Finally, the OP responds by sending an Access Token saying this user has been authorised (the RP is recommended to validate this token using cryptography) and optionally a Refresh Token.
|
||||
|
||||
The image below shows a typical authorization code flow.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant user as User
|
||||
participant rp as RP (Relying Party)
|
||||
participant op as OP (OpenID Provider)
|
||||
|
||||
user->>rp: User accesses application
|
||||
rp->>user: RP prepares authorization request & redirects user to OP
|
||||
|
||||
user->>op: User authentication & authorization occurs
|
||||
op->>rp: Redirect back to the RP with an authorization code
|
||||
|
||||
rect
|
||||
|
||||
rp->>op: Exchange authorization code
|
||||
op->>rp: RP receives Access token (optionally Refresh Token)
|
||||
end
|
||||
|
||||
rp->>user: User is logged in
|
||||
```
|
||||
|
||||
| Endpoint | URL |
|
||||
| -------------------- | -------------------------------------------------------------------- |
|
||||
| Authorization | `/application/o/authorize/` |
|
||||
| Token | `/application/o/token/` |
|
||||
| User Info | `/application/o/userinfo/` |
|
||||
| Token Revoke | `/application/o/revoke/` |
|
||||
| End Session | `/application/o/<application slug>/end-session/` |
|
||||
| JWKS | `/application/o/<application slug>/jwks/` |
|
||||
| OpenID Configuration | `/application/o/<application slug>/.well-known/openid-configuration` |
|
||||
|
||||
### Additional configuration options with Redirect URIs
|
||||
|
||||
When using an OAuth 2.0 provider in authentik, the OP must validate the provided redirect URI by the RP. An authentik admin can configure a list in the **Redirect URI** field on the Provider.
|
||||
|
||||
When you create a new OAuth 2.0 provider and app in authentik and you leave the **Redirect URI** field empty, then the first time a user opens that app, authentik uses that URL as the saved redirect URL.
|
||||
|
||||
For advanced use cases, an authentik admin can use regular expressions (regex) instead of a redirect URL. For example, if you want to list ten different applications, instead of listing them all individually, you can create an expression with wildcards. When using regex, be aware that authentik uses a dot as a separator in the URL, but in regex a dot means "one of any character", a wildcard. You should therefore escape the dot with `\.` to prevent its interpretation as a wildcard.
|
||||
|
||||
## OAuth 2.0 flows and grant types
|
||||
|
||||
There are three general flows of OAuth 2.0:
|
||||
|
||||
1. Web-based application authorization (Authorization code, Implicit, Refresh token)
|
||||
2. Client credentials (Machine-to-machine)
|
||||
3. Device code
|
||||
|
||||
Additionally, the [Refresh token](#refresh-token-grant) (grant type) is optionally used with any of the above flows, as well as the client credentials and device code flows.
|
||||
|
||||
### 1: Web-based application authorization
|
||||
|
||||
The flows and grant types used in this case are those used for a typical authorization process, with a user and an application:
|
||||
|
||||
- _Authorization code_ grant type
|
||||
- _Implicit_ grant type (legacy)
|
||||
- _Hybrid_ grant type
|
||||
|
||||
#### Authorization code
|
||||
|
||||
The authorization code is for environments with both a Client and a application server, where the back and forth happens between the client and an app server (the logic lives on app server). The RP needs to authorise itself to the OP. Client ID (public, identifies which app is talking to it) and client secret (the password) that the RP uses to authenticate.
|
||||
|
||||
If you configure authentik to use "Offline access" then during the initial auth the OP sends two tokens, an access token (short-lived, hours, can be customised) and a refresh token (typically longer validity, days or infinite). The RP (the app) saves both tokens. When the access token is about to expire, the RP sends the saved refresh token back to the OP, and requests a new access token. When the refresh token itself is about to expire, the RP can also ask for a new refresh token. This can all happen without user interaction if you configured the offline access.
|
||||
|
||||
:::info
|
||||
Starting with authentik 2024.2, applications only receive an access token. To receive a refresh token, both applications and authentik must be configured to request the `offline_access` scope. In authentik this can be done by selecting the `offline_access` Scope mapping in the provider settings.
|
||||
:::
|
||||
|
||||
The authorization code grant type is used to convert an authorization code to an access token (and optionally a refresh token). The authorization code is retrieved through the authentik [Authorization flow](../../flows-stages/flow/index.md), can only be used once, and expires quickly.
|
||||
|
||||
#### Implicit
|
||||
|
||||
:::info
|
||||
The OAuth 2.0 [Security Best Current Practice document](https://tools.ietf.org/html/draft-ietf-oauth-security-topics) recommends against using the Implicit flow entirely, and OAuth 2.0 for Browser-Based Apps describes the technique of using the authorization code flow with PKCE instead. ([source](https://oauth.net/2/grant-types/implicit/))
|
||||
:::
|
||||
|
||||
This flow is for more modern single page-applications, or ones you download, that are all client-side (all JS, no backend logic, etc) and have no server to make tokens. Because the secret cannot be stored on the client machine, the implicit flow is required in these architectures. With the implicit flow, the flow skips the second part of the two requests seen in the authorization flow; after the initial author request, the implicit flow receives a token, and then with cryptocracy and with PKCE, it can validate that it is the correct client, and that is safe to send a token. The RP (still called that with this implicit flow) can use cryptography to validate the token.
|
||||
|
||||
#### Hybrid
|
||||
|
||||
The Hybrid Flow is an OpenID Connect flow that incorporates traits of both the Implicit flow and the Authorization Code flow. It provides an application instant access to an ID token while ensuring secure and safe retrieval of access tokens and refresh tokens. This can be useful in situations where the application needs to quickly access information about the user, while in the background doing further processing to get additional tokens before gaining access to additional resources.
|
||||
|
||||
### 2. Client credentials
|
||||
|
||||
The client credentials flow and grant types are typically implemented for server-to-server scenarios, when code in a web application invokes a web API.
|
||||
|
||||
For more information, see [Machine-to-machine authentication](./client_credentials.mdx).
|
||||
|
||||
### 3. Device code
|
||||
|
||||
The device code flow is used in situations where there is no browser and limited options for text or data input from a client ("input-constrained devices"). For example, using a subscription TV program on a television, where you use a website on your mobile device to input a code displayed on the TV, authenticate, and then you are logged in to the TV.
|
||||
|
||||
For more information, see [Device code flow](./device_code.md).
|
||||
|
||||
#### Refresh token grant
|
||||
|
||||
Refresh tokens can be used as long-lived tokens to access user data, and further renew the refresh token down the road.
|
||||
|
||||
:::info
|
||||
Starting with authentik 2024.2, the refresh token grant type requires the `offline_access` scope.
|
||||
:::
|
||||
|
||||
## Scope mappings
|
||||
|
||||
Scopes can be configured using scope mappings, a type of [property mapping](../property-mappings/index.md#scope-mappings).
|
||||
|
||||
## Scope authorization
|
||||
|
||||
By default, every user that has access to an application can request any of the configured scopes. Starting with authentik 2022.4, you can do additional checks for the scope in an expression policy (bound to the application):
|
||||
|
||||
```python
|
||||
# There are additional fields set in the context, use `ak_logger.debug(request.context)` to see them.
|
||||
|
||||
if "my-admin-scope" in request.context["oauth_scopes"]:
|
||||
return ak_is_group_member(request.user, name="my-admin-group")
|
||||
return True
|
||||
```
|
||||
|
||||
## Default & special scopes
|
||||
|
||||
When a client does not request any scopes, authentik will treat the request as if all configured scopes were requested. Depending on the configured authorization flow, consent still needs to be given, and all scopes are listed there.
|
||||
|
||||
This does _not_ apply to special scopes, as those are not configurable in the provider.
|
||||
|
||||
### Default
|
||||
|
||||
- `openid`: A scope required by the OpenID Connect spec to specify that an OAuth interaction is OpenID Connect. Does not add any data to the token.
|
||||
- `profile`: Include basic profile information, such as username, name and group membership.
|
||||
- `email`: Include the users' email address.
|
||||
- `entitlements`: Include application entitlement data.
|
||||
- `offline_access`: An OAuth 2.0 scope which indicates that the application is requesting a refresh token.
|
||||
|
||||
### authentik
|
||||
|
||||
- `goauthentik.io/api`: This scope grants the refresh token access to the authentik API on behalf of the user
|
||||
|
||||
### GitHub compatibility
|
||||
|
||||
- `user`: No-op, is accepted for compatibility but does not give access to any resources
|
||||
- `read:user`: Same as above
|
||||
- `user:email`: Allows read-only access to `/user`, including email address
|
||||
- `read:org`: Allows read-only access to `/user/teams`, listing all the user's groups as teams.
|
||||
|
||||
## Signing & Encryption
|
||||
|
||||
[JWTs](https://jwt.io/introduction) created by authentik will always be signed.
|
||||
|
||||
When a _Signing Key_ is selected in the provider, the JWT will be signed asymmetrically with the private key of the selected certificate, and can be verified using the public key of the certificate. The public key data of the signing key can be retrieved via the JWKS endpoint listed on the provider page.
|
||||
|
||||
When no _Signing Key_ is selected, the JWT will be signed symmetrically with the _Client secret_ of the provider, which can be seen in the provider settings.
|
||||
|
||||
### Encryption:ak-version[2024.10]
|
||||
|
||||
authentik can also encrypt JWTs (turning them into JWEs) it issues by selecting an _Encryption Key_ in the provider. When selected, all JWTs will be encrypted symmetrically using the selected certificate. authentik uses the `RSA-OAEP-256` algorithm with the `A256CBC-HS512` encryption method.
|
||||
@ -0,0 +1,13 @@
|
||||
---
|
||||
title: WebFinger support
|
||||
---
|
||||
|
||||
## About WebFinger
|
||||
|
||||
The [WebFinger protocol](https://webfinger.net/) allows for the discovery of information about individuals or entities on the Internet through standard HTTP methods. It enables the retrieval of information associated with a URI that might not be directly usable as a locator, such as those for accounts or email addresses.
|
||||
|
||||
## authentik WebFinger support
|
||||
|
||||
authentik provides a WebFinger endpoint when the **Default application** setting uses an OIDC provider. Instructions on how to set a **Default application** can be found in the [authentik Branding documentation](../../../sys-mgmt/brands.md#external-user-settings).
|
||||
|
||||
The WebFinger endpoint is available at: `https://authentik.company/.well-known/webfinger` (where authentik.company is the FQDN of your authentik instance)
|
||||
@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Expressions
|
||||
---
|
||||
|
||||
The property mapping should return a value that is expected by the provider. Supported types are documented in the individual provider. Returning `None` is always accepted and would simply skip the mapping for which `None` was returned.
|
||||
|
||||
## Available Functions
|
||||
|
||||
import Functions from "../../../expressions/_functions.mdx";
|
||||
|
||||
<Functions />
|
||||
|
||||
## Variables
|
||||
|
||||
import Objects from "../../../expressions/_objects.md";
|
||||
|
||||
<Objects />
|
||||
|
||||
import User from "../../../expressions/_user.md";
|
||||
|
||||
<User />
|
||||
|
||||
- `request`: The current request. This may be `None` if there is no contextual request. See ([Django documentation](https://docs.djangoproject.com/en/3.0/ref/request-response/#httprequest-objects))
|
||||
- Other arbitrary arguments given by the provider, this is documented on the provider.
|
||||
@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Provider property mappings
|
||||
---
|
||||
|
||||
Property mappings allow you to pass information to external applications. For example, pass the current user's groups as a SAML parameter.
|
||||
|
||||
## SAML property mappings
|
||||
|
||||
SAML property mappings allow you embed information into the SAML authentication request. This information can then be used by the application to, for example, assign permissions to the object.
|
||||
|
||||
## Scope mappings
|
||||
|
||||
Scope mappings are used by the OAuth2 provider to map information from authentik to OAuth2/OpenID claims. Values returned by a scope mapping are added as custom claims to access and ID tokens.
|
||||
|
||||
## Skip objects during synchronization
|
||||
|
||||
To skip synchronization for a specific object, you can create a property mapping with an expression that triggers the `SkipObject` exception. This functionality is supported by the following providers: [**Google Workspace**](../gws/), [**Microsoft Entra ID**](../entra/), and [**SCIM**](../scim/).
|
||||
|
||||
**Example:**
|
||||
|
||||
```python
|
||||
if request.user.username == "example_username":
|
||||
raise SkipObject
|
||||
```
|
||||
@ -0,0 +1,6 @@
|
||||
:::info
|
||||
_example-outpost_ is used as a placeholder for the outpost name.
|
||||
_authentik.company_ is used as a placeholder for the authentik install.
|
||||
_app.company_ is used as a placeholder for the external domain for the application.
|
||||
_outpost.company_ is used as a placeholder for the outpost. When using the embedded outpost, this can be the same as _authentik.company_
|
||||
:::
|
||||
@ -0,0 +1,33 @@
|
||||
Use the following configuration:
|
||||
|
||||
```apacheconf
|
||||
app.company {
|
||||
# directive execution order is only as stated if enclosed with route.
|
||||
route {
|
||||
# always forward outpost path to actual outpost
|
||||
reverse_proxy /outpost.goauthentik.io/* http://outpost.company:9000
|
||||
|
||||
# forward authentication to outpost
|
||||
forward_auth http://outpost.company:9000 {
|
||||
uri /outpost.goauthentik.io/auth/caddy
|
||||
|
||||
# capitalization of the headers is important, otherwise they will be empty
|
||||
copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Entitlements X-Authentik-Email X-Authentik-Name X-Authentik-Uid X-Authentik-Jwt X-Authentik-Meta-Jwks X-Authentik-Meta-Outpost X-Authentik-Meta-Provider X-Authentik-Meta-App X-Authentik-Meta-Version
|
||||
|
||||
# optional, in this config trust all private ranges, should probably be set to the outposts IP
|
||||
trusted_proxies private_ranges
|
||||
}
|
||||
|
||||
# actual site configuration below, for example
|
||||
reverse_proxy localhost:1234
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you're trying to proxy to an upstream over HTTPS, you need to set the `Host` header to the value they expect for it to work correctly.
|
||||
|
||||
```conf
|
||||
reverse_proxy /outpost.goauthentik.io/* https://outpost.company {
|
||||
header_up Host {http.reverse_proxy.upstream.host}
|
||||
}
|
||||
```
|
||||
51
docs/topics/add-secure-apps/providers/proxy/_envoy_istio.md
Normal file
51
docs/topics/add-secure-apps/providers/proxy/_envoy_istio.md
Normal file
@ -0,0 +1,51 @@
|
||||
Set the following settings on the _IstioOperator_ resource:
|
||||
|
||||
```yaml
|
||||
apiVersion: install.istio.io/v1alpha1
|
||||
kind: IstioOperator
|
||||
metadata:
|
||||
name: istio
|
||||
namespace: istio-system
|
||||
spec:
|
||||
meshConfig:
|
||||
extensionProviders:
|
||||
- name: "authentik"
|
||||
envoyExtAuthzHttp:
|
||||
# Replace with <service-name>.<namespace>.svc.cluster.local
|
||||
service: "ak-outpost-authentik-embedded-outpost.authentik.svc.cluster.local"
|
||||
port: "9000"
|
||||
pathPrefix: "/outpost.goauthentik.io/auth/envoy"
|
||||
headersToDownstreamOnAllow:
|
||||
- cookie
|
||||
headersToUpstreamOnAllow:
|
||||
- set-cookie
|
||||
- x-authentik-*
|
||||
# Add authorization headers to the allow list if you need proxy providers which
|
||||
# send a custom HTTP-Basic Authentication header based on values from authentik
|
||||
# - authorization
|
||||
includeRequestHeadersInCheck:
|
||||
- cookie
|
||||
```
|
||||
|
||||
Afterwards, you can create _AuthorizationPolicy_ resources to protect your applications like this:
|
||||
|
||||
```yaml
|
||||
apiVersion: security.istio.io/v1beta1
|
||||
kind: AuthorizationPolicy
|
||||
metadata:
|
||||
name: authentik-policy
|
||||
namespace: istio-system
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
istio: ingressgateway
|
||||
action: CUSTOM
|
||||
provider:
|
||||
name: "authentik"
|
||||
rules:
|
||||
- to:
|
||||
- operation:
|
||||
hosts:
|
||||
# You can create a single resource and list all Domain names here, or create multiple resources
|
||||
- "app.company"
|
||||
```
|
||||
@ -0,0 +1,46 @@
|
||||
Create a new ingress for the outpost
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: authentik-outpost
|
||||
spec:
|
||||
rules:
|
||||
- host: app.company
|
||||
http:
|
||||
paths:
|
||||
- path: /outpost.goauthentik.io
|
||||
pathType: Prefix
|
||||
backend:
|
||||
# Or, to use an external Outpost, create an ExternalName service and reference that here.
|
||||
# See https://kubernetes.io/docs/concepts/services-networking/service/#externalname
|
||||
service:
|
||||
name: ak-outpost-example-outpost
|
||||
port:
|
||||
number: 9000
|
||||
```
|
||||
|
||||
This ingress handles authentication requests, and the sign-in flow.
|
||||
|
||||
Add these annotations to the ingress you want to protect
|
||||
|
||||
:::warning
|
||||
This configuration requires that you enable [`allow-snippet-annotations`](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#allow-snippet-annotations), for example by setting `controller.allowSnippetAnnotations` to `true` in your helm values for the ingress-nginx installation.
|
||||
:::
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
annotations:
|
||||
# This should be the in-cluster DNS name for the authentik outpost service
|
||||
# as when the external URL is specified here, nginx will overwrite some crucial headers
|
||||
nginx.ingress.kubernetes.io/auth-url: |-
|
||||
http://ak-outpost-example.authentik.svc.cluster.local:9000/outpost.goauthentik.io/auth/nginx
|
||||
# If you're using domain-level auth, use the authentication URL instead of the application URL
|
||||
nginx.ingress.kubernetes.io/auth-signin: |-
|
||||
https://app.company/outpost.goauthentik.io/start?rd=$scheme://$http_host$escaped_request_uri
|
||||
nginx.ingress.kubernetes.io/auth-response-headers: |-
|
||||
Set-Cookie,X-authentik-username,X-authentik-groups,X-authentik-entitlements,X-authentik-email,X-authentik-name,X-authentik-uid
|
||||
nginx.ingress.kubernetes.io/auth-snippet: |
|
||||
proxy_set_header X-Forwarded-Host $http_host;
|
||||
```
|
||||
@ -0,0 +1,73 @@
|
||||
```nginx
|
||||
# Increase buffer size for large headers
|
||||
# This is needed only if you get 'upstream sent too big header while reading response
|
||||
# header from upstream' error when trying to access an application protected by goauthentik
|
||||
proxy_buffers 8 16k;
|
||||
proxy_buffer_size 32k;
|
||||
|
||||
# Make sure not to redirect traffic to a port 4443
|
||||
port_in_redirect off;
|
||||
|
||||
location / {
|
||||
# Put your proxy_pass to your application here
|
||||
proxy_pass $forward_scheme://$server:$port;
|
||||
# Set any other headers your application might need
|
||||
# proxy_set_header Host $host;
|
||||
# proxy_set_header ...
|
||||
|
||||
##############################
|
||||
# authentik-specific config
|
||||
##############################
|
||||
auth_request /outpost.goauthentik.io/auth/nginx;
|
||||
error_page 401 = @goauthentik_proxy_signin;
|
||||
auth_request_set $auth_cookie $upstream_http_set_cookie;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
|
||||
# translate headers from the outposts back to the actual upstream
|
||||
auth_request_set $authentik_username $upstream_http_x_authentik_username;
|
||||
auth_request_set $authentik_groups $upstream_http_x_authentik_groups;
|
||||
auth_request_set $authentik_entitlements $upstream_http_x_authentik_entitlements;
|
||||
auth_request_set $authentik_email $upstream_http_x_authentik_email;
|
||||
auth_request_set $authentik_name $upstream_http_x_authentik_name;
|
||||
auth_request_set $authentik_uid $upstream_http_x_authentik_uid;
|
||||
|
||||
proxy_set_header X-authentik-username $authentik_username;
|
||||
proxy_set_header X-authentik-groups $authentik_groups;
|
||||
proxy_set_header X-authentik-entitlements $authentik_entitlements;
|
||||
proxy_set_header X-authentik-email $authentik_email;
|
||||
proxy_set_header X-authentik-name $authentik_name;
|
||||
proxy_set_header X-authentik-uid $authentik_uid;
|
||||
|
||||
# This section should be uncommented when the "Send HTTP Basic authentication" option
|
||||
# is enabled in the proxy provider
|
||||
# auth_request_set $authentik_auth $upstream_http_authorization;
|
||||
# proxy_set_header Authorization $authentik_auth;
|
||||
}
|
||||
|
||||
# all requests to /outpost.goauthentik.io must be accessible without authentication
|
||||
location /outpost.goauthentik.io {
|
||||
# When using the embedded outpost, use:
|
||||
proxy_pass http://authentik.company:9000/outpost.goauthentik.io;
|
||||
# For manual outpost deployments:
|
||||
# proxy_pass http://outpost.company:9000;
|
||||
|
||||
# Note: ensure the Host header matches your external authentik URL:
|
||||
proxy_set_header Host $host;
|
||||
|
||||
proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
auth_request_set $auth_cookie $upstream_http_set_cookie;
|
||||
proxy_pass_request_body off;
|
||||
proxy_set_header Content-Length "";
|
||||
}
|
||||
|
||||
# Special location for when the /auth endpoint returns a 401,
|
||||
# redirect to the /start URL which initiates SSO
|
||||
location @goauthentik_proxy_signin {
|
||||
internal;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
return 302 /outpost.goauthentik.io/start?rd=$scheme://$http_host$request_uri;
|
||||
# For domain level, use the below error_page to redirect to your authentik server with the full redirect path
|
||||
# return 302 https://authentik.company/outpost.goauthentik.io/start?rd=$scheme://$http_host$request_uri;
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,87 @@
|
||||
```nginx
|
||||
# Upgrade WebSocket if requested, otherwise use keepalive
|
||||
map $http_upgrade $connection_upgrade_keepalive {
|
||||
default upgrade;
|
||||
'' '';
|
||||
}
|
||||
|
||||
server {
|
||||
# SSL and VHost configuration
|
||||
listen 443 ssl http2;
|
||||
server_name _;
|
||||
|
||||
ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
|
||||
ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
|
||||
|
||||
# Increase buffer size for large headers
|
||||
# This is needed only if you get 'upstream sent too big header while reading response
|
||||
# header from upstream' error when trying to access an application protected by goauthentik
|
||||
proxy_buffers 8 16k;
|
||||
proxy_buffer_size 32k;
|
||||
|
||||
location / {
|
||||
# Put your proxy_pass to your application here, and all the other statements you'll need
|
||||
# proxy_pass http://localhost:5000;
|
||||
# proxy_set_header Host $host;
|
||||
# proxy_set_header ...
|
||||
# Support for websocket
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection $connection_upgrade_keepalive;
|
||||
|
||||
##############################
|
||||
# authentik-specific config
|
||||
##############################
|
||||
auth_request /outpost.goauthentik.io/auth/nginx;
|
||||
error_page 401 = @goauthentik_proxy_signin;
|
||||
auth_request_set $auth_cookie $upstream_http_set_cookie;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
|
||||
# translate headers from the outposts back to the actual upstream
|
||||
auth_request_set $authentik_username $upstream_http_x_authentik_username;
|
||||
auth_request_set $authentik_groups $upstream_http_x_authentik_groups;
|
||||
auth_request_set $authentik_entitlements $upstream_http_x_authentik_entitlements;
|
||||
auth_request_set $authentik_email $upstream_http_x_authentik_email;
|
||||
auth_request_set $authentik_name $upstream_http_x_authentik_name;
|
||||
auth_request_set $authentik_uid $upstream_http_x_authentik_uid;
|
||||
|
||||
proxy_set_header X-authentik-username $authentik_username;
|
||||
proxy_set_header X-authentik-groups $authentik_groups;
|
||||
proxy_set_header X-authentik-entitlements $authentik_entitlements;
|
||||
proxy_set_header X-authentik-email $authentik_email;
|
||||
proxy_set_header X-authentik-name $authentik_name;
|
||||
proxy_set_header X-authentik-uid $authentik_uid;
|
||||
|
||||
# This section should be uncommented when the "Send HTTP Basic authentication" option
|
||||
# is enabled in the proxy provider
|
||||
# auth_request_set $authentik_auth $upstream_http_authorization;
|
||||
# proxy_set_header Authorization $authentik_auth;
|
||||
}
|
||||
|
||||
# all requests to /outpost.goauthentik.io must be accessible without authentication
|
||||
location /outpost.goauthentik.io {
|
||||
# When using the embedded outpost, use:
|
||||
proxy_pass http://authentik.company:9000/outpost.goauthentik.io;
|
||||
# For manual outpost deployments:
|
||||
# proxy_pass http://outpost.company:9000;
|
||||
|
||||
# Note: ensure the Host header matches your external authentik URL:
|
||||
proxy_set_header Host $host;
|
||||
|
||||
proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
auth_request_set $auth_cookie $upstream_http_set_cookie;
|
||||
proxy_pass_request_body off;
|
||||
proxy_set_header Content-Length "";
|
||||
}
|
||||
|
||||
# Special location for when the /auth endpoint returns a 401,
|
||||
# redirect to the /start URL which initiates SSO
|
||||
location @goauthentik_proxy_signin {
|
||||
internal;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
return 302 /outpost.goauthentik.io/start?rd=$scheme://$http_host$request_uri;
|
||||
# For domain level, use the below error_page to redirect to your authentik server with the full redirect path
|
||||
# return 302 https://authentik.company/outpost.goauthentik.io/start?rd=$scheme://$http_host$request_uri;
|
||||
}
|
||||
}
|
||||
```
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user