website: latest PR for new Docs structure (#11639)
* first pass
* dependency shenanigans
* move blueprints
* few broken links
* change config the throw errors
* internal file edits
* fighting links
* remove sidebarDev
* fix subdomain
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
* fix relative URL
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
* fix mismatched package versions
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
* fix api reference build
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
* test tweak
* links hell
* more links hell
* links hell2
* yep last of the links
* last broken link fixed
* re-add cves
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
* add devdocs redirects
* add dir
* tweak netlify.toml
* move latest 2 CVES into dir
* fix links to moved cves
* typoed title fix
* fix link
* remove banner
* remove committed api docs
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
* integrations: remove version dropdown
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
* Update Makefile
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
* change doc links in web as well
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
* fix some more docs paths
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
* fix more docs paths
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
* ci: require ci-web.build for merging
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
* Revert "ci: require ci-web.build for merging"
This reverts commit b99a4842a9.
* remove sluf for Application
* put slug back in
* minor fix to trigger deploy
* Spelled out Documentation in menu bar
* remove image redirects...
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
* remove explicit index.md
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
* remove mdx first
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
* then remove .md
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
* add missing prefix
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
---------
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
Co-authored-by: Tana M Berry <tana@goauthentik.com>
Co-authored-by: Jens Langhammer <jens@goauthentik.io>
Co-authored-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
This commit is contained in:
Tana M Berry
BIN
website/docs/users-sources/access-control/flow-page.png
Normal file
BIN
website/docs/users-sources/access-control/flow-page.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
15
website/docs/users-sources/access-control/index.mdx
Normal file
15
website/docs/users-sources/access-control/index.mdx
Normal file
@ -0,0 +1,15 @@
|
||||
---
|
||||
title: About access control
|
||||
---
|
||||
|
||||
import DocCardList from "@theme/DocCardList";
|
||||
|
||||
To comply with important regulations such as PCI-DSS, HIPAA, SOC 2, and GDPR, it's necessary to have the ability to control which users have access to specific areas of the system, what [permissions](./permissions.md) they have globally and on certain objects, and a way to monitor [events](../../sys-mgmt/events/index.md) related to user activity.
|
||||
|
||||
In authentik, we provide role-based access control (RBAC), an industry standard for managing access control. By carefully designing roles with appropriate permissions, and then assigning those roles to groups, RBAC provides a fine-tuned approach to controlling user access.
|
||||
|
||||
RBAC is a way of ensuring the well-known [principal of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) whereby "every module (such as a process, a user, or a program, depending on the subject) must be able to access only the information and resources that are necessary for its legitimate purpose."
|
||||
|
||||
To learn more about access control with authentik, refer to these topics:
|
||||
|
||||
<DocCardList />
|
||||
132
website/docs/users-sources/access-control/manage_permissions.md
Normal file
132
website/docs/users-sources/access-control/manage_permissions.md
Normal file
@ -0,0 +1,132 @@
|
||||
---
|
||||
title: "Manage permissions"
|
||||
description: "Learn how to use global and object permissions in authentik."
|
||||
---
|
||||
|
||||
Refer to the following topics for instructions to view and manage permissions. To learn more about the concepts and fundamanetals of authentik permissions, refer to [About Permissions](./permissions.md).
|
||||
|
||||
## View permissions
|
||||
|
||||
You can view all permissions that are assigned to a user, group, role, flow, or stage.
|
||||
|
||||
### View user and role permissions
|
||||
|
||||
To view _object_ permissions for a specific user or role:
|
||||
|
||||
1. Go to the Admin interface and navigate to **Directory**.
|
||||
2. Select either **Users** or **Roles**
|
||||
3. Select a specific user/role by clicking on the name (this opens the details page).
|
||||
4. Click the **Permissions** tab at the top of the page
|
||||
5. Select the **Assigned global permissions** sub-tab to see global permissions and the **Assigned object permissions** sub-tab to see the object-level permissions.
|
||||
|
||||
### View flow permissions
|
||||
|
||||
\_These instructions apply to all objects that have a detail page, which can be accessed by clicking on the name in the list page.\_\_
|
||||
|
||||
1. Go to the Admin interface and navigate to **Flows and Stages -> Flows**.
|
||||
2. Click the name of the flow (this opens the details page).
|
||||
3. Click the **Permissions** tab at the top of the page.
|
||||
4. View the assigned permissions using the **User Object Permissions** and the **Role Object Permissions** tabs.
|
||||
|
||||
### View stage permissions
|
||||
|
||||
\_These instructions apply to all objects that **do not** have a detail page.\_\_
|
||||
|
||||
1. Go to the Admin interface and navigate to **Flows and Stages -> Stages**.
|
||||
2. On the row for the specific stage whose permissions you want to view, click the **lock icon**.
|
||||
3. On the **Update Permissions** window, you can view the assigned permissions using the **User Object Permissions** and the **Role Object Permissions** tabs.
|
||||
|
||||
## Manage permissions
|
||||
|
||||
You can assign or remove permissions to a user, role, group, flow, or stage.
|
||||
|
||||
### Assign, modify, or remove permissions for a user
|
||||
|
||||
To assign or remove _object_ permissions for a specific user:
|
||||
|
||||
1. Go to the Admin interface and navigate to **Directory -> Users**.
|
||||
2. Select a specific user by clicking on the user's name.
|
||||
3. Click the **Permissions** tab at the top of the page.
|
||||
4. To assign or remove permissions that another _user_ has on this specific user:
|
||||
1. Click the **User Object Permissions** tab, and then click **Assign to new user**.
|
||||
2. In the **User** drop-down, select the user object.
|
||||
3. Use the toggles to set which permissions on that selected user object you want to grant to (or remove from) the specific user.
|
||||
4. Click **Assign** to save your settings and close the modal.
|
||||
5. To assign or remove permissions that another _role_ has on this specific user:
|
||||
1. Click the **Role Object Permissions** tab, and then click **Assign to new role**.
|
||||
2. In the **User** drop-down, select the user object.
|
||||
3. Use the toggles to set which permissions you want to grant to (or remove from) the selected role.
|
||||
4. Click **Assign** to save your settings and close the modal.
|
||||
|
||||
To assign or remove _global_ permissions for a user:
|
||||
|
||||
1. Go to the Admin interface and navigate to **Directory -> Users**.
|
||||
2. Select a specific user the clicking on the user's name.
|
||||
3. Click the **Permissions** tab at the top of the page.
|
||||
4. Click **Assigned Global Permissions** to the left.
|
||||
5. In the **Assign permissions** area, click **Assign Permission**.
|
||||
6. In the **Assign permission to user** modal box, click the plus sign (**+**) and then click the checkbox beside each permission that you want to assign to the user. To remove permissions, deselect the checkbox.
|
||||
7. Click **Add**, and then click **Assign** to save your changes and close the modal.
|
||||
|
||||
### Assign or remove permissions on a specific group
|
||||
|
||||
:::info
|
||||
Note that groups themselves do not have permissions. Rather, users and roles have permissions assigned that allow them to create, modify, delete, etc., a group.
|
||||
Also there are no global permissions for groups.
|
||||
:::
|
||||
|
||||
To assign or remove _object_ permissions on a specific group by users and roles:
|
||||
|
||||
1. Go to the Admin interface and navigate to **Directory -> Groups**.
|
||||
2. Select a specific group by clicking the group's name.
|
||||
3. Click the **Permissions** tab at the top of the page.
|
||||
To assign or remove permissions that another _user_ has on this specific group:
|
||||
1. Click **User Object Permissions** to the left, and then click **Assign to new user**.
|
||||
2. In the **User** drop-down, select the user object.
|
||||
3. Use the toggles to set which permissions on that selected group you want to grant to (or remove from) the specific user.
|
||||
4. Click **Assign** to save your settings and close the modal.
|
||||
4. To assign or remove permissions that another _role_ has on this specific group:
|
||||
1. Click **Role Object Permissions** to the left, and then click **Assign to new role**.
|
||||
2. In the **Role** drop-down, select the role.
|
||||
3. Use the toggles to set which permissions you want to grant to (or remove from ) the selected role.
|
||||
4. Click **Assign** to save your settings and close the modal.
|
||||
|
||||
### Assign or remove permissions for a specific role
|
||||
|
||||
To assign or remove _object_ permissions for a specific role:
|
||||
|
||||
1. Go to the Admin interface and navigate to **Directory -> Roles**.
|
||||
2. Select a specific role the clicking on the role's name.
|
||||
3. Click the **Permissions** tab at the top of the page.
|
||||
To assign or remove permissions that another _user_ has on this specific role:
|
||||
1. Click **User Object Permissions** to the left, and then click **Assign to new user**.
|
||||
2. In the **User** drop-down, select the user object.
|
||||
3. Use the toggles to set which permissions on that role you want to grant to (or remove from) the selected user.
|
||||
4. Click **Assign** to save your settings and close the modal.
|
||||
4. To assign or remove permissions that another _role_ has on this specific group:
|
||||
1. Click **Role Object Permissions** to the left, and then click **Assign to new role**.
|
||||
2. In the **Role** drop-down, select the role.
|
||||
3. Use the toggles to set which permissions you want to grant to (or remove from) the selected role.
|
||||
4. Click **Assign** to save your settings and close the modal.
|
||||
|
||||
To assign or remove _global_ permissions for a role:
|
||||
|
||||
1. Go to the Admin interface and navigate to **Directory -> Roles**.
|
||||
2. Select a specific role by clicking on the role's name.
|
||||
3. Click the **Permissions** tab at the top of the page.
|
||||
4. Click **Assigned Global Permissions** to the left, and then click **Assign Permission**.
|
||||
5. In the **Assign permissions to role** modal, click the plus sign (**+**) and then click the checkbox beside each permission that you want to assign to the role. To remove permissions, deselect the checkbox.
|
||||
6. Click **Assign** to save your changes and close the modal.
|
||||
|
||||
### Assign or remove flow permissions
|
||||
|
||||
1. Go to the Admin interface and navigate to **Flows and Stages -> Flows**.
|
||||
2. Click the name of the flow (this opens the details page).
|
||||
3. Click the **Permissions** tab at the top of the page.
|
||||
4. Add or remove permissions using the **User Object Permissions** and the **Role Object Permissions** tabs.
|
||||
|
||||
### Assign or remove stage permissions
|
||||
|
||||
1. Go to the Admin interface and navigate to **Flows and Stages -> Stagess**.
|
||||
2. On the row for the specific stage that you want to manage permissions, click the **lock icon**.
|
||||
3. On the **Update Permissions** modal window, you can add or remove the assigned permissions using the **User Object Permissions** and the **Role Object Permissions** tabs.
|
||||
46
website/docs/users-sources/access-control/permissions.md
Normal file
46
website/docs/users-sources/access-control/permissions.md
Normal file
@ -0,0 +1,46 @@
|
||||
---
|
||||
title: "About permissions"
|
||||
description: "Learn about global and object permissions in authentik."
|
||||
---
|
||||
|
||||
Permissions are the central components in all access control systems, the lowest-level components, the controlling pieces of access data. Permissions are assigned to (or removed from!) to define exactly WHO can do WHAT to WHICH part of the overall software system.
|
||||
|
||||
:::info
|
||||
Note that global and object permissions only apply to objects within authentik, and not to who can access certain applications (which are access-controlled using [policies](../../customize/policies/index.md)).
|
||||
:::
|
||||
|
||||
For instructions to add, remove, and manage permissions, refer to [Manage Permissions](./manage_permissions.md).
|
||||
|
||||
## Fundamentals of authentik permissions
|
||||
|
||||
There are two main types of permissions in authentik:
|
||||
|
||||
- [**Global permissions**](#global-permissions)
|
||||
- [**Object permissions**](#object-permissions)
|
||||
|
||||
### Global permissions
|
||||
|
||||
Global permissions define who can do what on a global level across the entire system. Some examples in authentik are the ability to add new [flows](../../add-secure-apps/flows-stages/flow/index.md) or to create a URL for users to recover their login credentials.
|
||||
|
||||
You can assign _global permissions_ to individual [users](../user/index.mdx) or to [roles](../roles/index.md). The most common and best practice is to assign permissions to roles.
|
||||
|
||||
### Object permissions
|
||||
|
||||
Object permissions have two categories:
|
||||
|
||||
- **_User_ object permissions**: defines WHO (which user) can change the **_object_**
|
||||
- **_Role_ object permissions**: defines which ROLE can change the **_object_**
|
||||
|
||||
Object permissions are assigned, as the name indicates, to an object ([users](../user/index.mdx), [groups](../groups/index.mdx), [roles](../roles/index.md), [flows](../../add-secure-apps/flows-stages/flow/index.md), and stages), and the assigned permissions state exactly what a user or role can do TO the object (i.e. what permissions does the user or role have on that object).
|
||||
|
||||
When working with object permissions it is important to understand that when you are viewing the page for an object, the permissions table shows which users or roles have permissions ON that specific object. Those permissions describe what those users or roles can do TO the object detailed on the page.
|
||||
|
||||
For example, the Admin interface UI shown below shows a user page for the user named Peter.
|
||||
|
||||
|
||||
|
||||
You can see in the **User Object Permissions** table that the Admin user (`akadmin`) and one other user (roberto) has permissions on Peter (that is, on the user object named Peter).
|
||||
|
||||
Looking at another example, with a flow object called `default-recovery-flow`, you can see that the Admin user (akadmin) has all object permissions on the flow, but roberto only has a few permissions on that flow.
|
||||
|
||||
|
||||
BIN
website/docs/users-sources/access-control/user-page.png
Normal file
BIN
website/docs/users-sources/access-control/user-page.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 71 KiB |
16
website/docs/users-sources/groups/group_ref.md
Normal file
16
website/docs/users-sources/groups/group_ref.md
Normal file
@ -0,0 +1,16 @@
|
||||
---
|
||||
title: Group properties and attributes
|
||||
---
|
||||
|
||||
## Object properties
|
||||
|
||||
The Group object has the following properties:
|
||||
|
||||
- `name` Group's display name.
|
||||
- `is_superuser` Boolean field if the group's users are superusers.
|
||||
- `parent` The parent Group of this Group.
|
||||
- `attributes` Dynamic attributes, see [Attributes](#attributes)
|
||||
|
||||
## Attributes
|
||||
|
||||
See [the user reference](../user/user_ref.md#attributes) for well-known attributes.
|
||||
16
website/docs/users-sources/groups/index.mdx
Normal file
16
website/docs/users-sources/groups/index.mdx
Normal file
@ -0,0 +1,16 @@
|
||||
---
|
||||
title: About groups
|
||||
description: Learn about groups in authentik
|
||||
---
|
||||
|
||||
## Hierarchy
|
||||
|
||||
Groups can be children of another group. Members of children groups are effective members of the parent group.
|
||||
|
||||
When you bind a group to an application or flow, any members of any child group of the selected group will have access.
|
||||
|
||||
Recursion is limited to 20 levels to prevent deadlocks.
|
||||
|
||||
## Attributes
|
||||
|
||||
Attributes of groups are recursively merged, for all groups the user is a _direct_ member of.
|
||||
57
website/docs/users-sources/groups/manage_groups.md
Normal file
57
website/docs/users-sources/groups/manage_groups.md
Normal file
@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Manage groups
|
||||
description: "Learn how to work with groups in authentik."
|
||||
---
|
||||
|
||||
A group is a collection of users. Refer to the following sections to learn how to create and manage groups, assign users and roles to groups, and how [permissions](../access-control/manage_permissions.md) work on a group level.
|
||||
|
||||
## Create a group
|
||||
|
||||
To create a new group, follow these steps:
|
||||
|
||||
1. In the Admin interface, navigate to **Directory > Groups**.
|
||||
2. Click **Create** at the top of the Groups page.
|
||||
3. In the Create modal, define the following:
|
||||
- **Name** of the group
|
||||
- Whether or not users in that group will all be **super-users** (means anyone in that group has all permissions on everything)
|
||||
- The **Parent** group
|
||||
- Select **Roles** to apply to this group
|
||||
- Any custom attributes
|
||||
4. Click **Create**.
|
||||
|
||||
:::info
|
||||
To create a super-user, you need to add the user to a group that has super-user permissions. All members of that group are super-users.
|
||||
:::
|
||||
|
||||
## Modify a group
|
||||
|
||||
To edit the group's name, parent group, whether or not the group is for superusers, associated roles, and any custom attributes, click the Edit icon beside the role's name. Make the changes, and then click **Update**.
|
||||
|
||||
To [add or remove users](../user/user_basic_operations.md#add-a-user-to-a-group) from the group, or to manage permissions assigned to the group, click on the name of the group to go to the group's detail page.
|
||||
|
||||
For more information about permissions, refer to ["Assign or remove permissions for a specific group"](../access-control/manage_permissions.md#assign-or-remove-permissions-on-a-specific-group).
|
||||
|
||||
## Delete a group
|
||||
|
||||
To delete a group, follow these steps:
|
||||
|
||||
1. In the Admin interface, navigate to **Directory > Groups**.
|
||||
2. Select the checkbox beside the name of the group that you want to delete.
|
||||
3. Click **Delete**.
|
||||
|
||||
## Assign a role to a group
|
||||
|
||||
You can assign a role to a group, and then all users in the group inherit the permissions assigned to that role. For instructions and more information, see ["Assign a role to a group"](../roles/manage_roles.md#assign-a-role-to-a-group).
|
||||
|
||||
## Delegating group member management <span class="badge badge--version">authentik 2024.4+</span>
|
||||
|
||||
To give a specific Role or User the ability to manage group members, the following permissions need to be granted on the matching Group object:
|
||||
|
||||
- Can view group
|
||||
- Can add user to group
|
||||
- Can remove user from group
|
||||
- Can access admin interface (for managing a group's user within the authentik Admin interface)
|
||||
|
||||
In addition, the permission "Can view User" needs to be assigned, either globally or on specific users that should be manageable.
|
||||
|
||||
These permissions can be assigned to a [Role](../roles/index.md) or directly to a [User](../user/index.mdx).
|
||||
19
website/docs/users-sources/roles/index.md
Normal file
19
website/docs/users-sources/roles/index.md
Normal file
@ -0,0 +1,19 @@
|
||||
---
|
||||
title: About roles
|
||||
---
|
||||
|
||||
import DocCardList from "@theme/DocCardList";
|
||||
|
||||
Roles are a way to simplify the assignment of permissions. Roles are also the backbone of role-based access control (RBAC), an industry standard for managing [access control](../access-control/index.mdx). In authentik, RBAC is how you manage access to system components and specific objects such as flows, stages, users, etc.
|
||||
|
||||
Think of roles as a collection of permissions. A role, along with its "bucket" of assigned permissions, can then be assigned to a group, which means that every user who is a part of that group will inherit all of the permissions in that role's "bucket".
|
||||
|
||||
For example, let's take a look at the following scenario:
|
||||
|
||||
> You need to add 5 new users, all new hires, to authentik, your identity management system. These users will be the first team members on the brand new Security team, so they will need some high-level permissions, with object permissions to create and remove other users, revoke permissions, and send recovery emails. They will also need [global permissions](../access-control/permissions.md#fundamentals-of-authentik-permissions) to control access to flows and stages.
|
||||
|
||||
The easiest workflow for setting up these new users involves [creating a role](./manage_roles.md#create-a-role) specifically for their type of work, and then [assigning that role to a group](./manage_roles.md#assign-a-role-to-a-group) to which all of the users belong.
|
||||
|
||||
To learn more about working with roles in authentik, refer to the following topics:
|
||||
|
||||
<DocCardList />
|
||||
48
website/docs/users-sources/roles/manage_roles.md
Normal file
48
website/docs/users-sources/roles/manage_roles.md
Normal file
@ -0,0 +1,48 @@
|
||||
---
|
||||
title: "Manage roles"
|
||||
description: "Learn how to work with roles and permissions in authentik."
|
||||
---
|
||||
|
||||
Roles are a collection of permissions, which can then be assigned, en masse, to a group. Using roles is a way to quickly grant permissions; by adding a user to the group with the appropriate assigned roles, any user in that group then inherits all of those permissions that are assigned to the role.
|
||||
|
||||
:::info
|
||||
In authentik, we assign roles to groups, not to individual users.
|
||||
:::
|
||||
|
||||
## Create a role
|
||||
|
||||
To create a new role, follow these steps:
|
||||
|
||||
1. In the Admin interface, navigate to **Directory > Roles**.
|
||||
2. Click **Create**, enter the name of the role, and then click **Create** in the modal.
|
||||
3. Next, [assign permissions to the role](../access-control/manage_permissions.md#assign-or-remove-permissions-for-a-specific-role).
|
||||
|
||||
## Modify a role
|
||||
|
||||
To modify a role, follow these steps:
|
||||
|
||||
- To edit the name of the role, click the Edit icon beside the role's name.
|
||||
|
||||
- To modify the permissions that are assigned to the role click on the role's name to go to the role's detail page. There you can add, modify, or remove permissions. For more information, refer to ["Assign or remove permissions for a specific role"](../access-control/manage_permissions.md#assign-or-remove-permissions-for-a-specific-role).
|
||||
|
||||
## Delete a role
|
||||
|
||||
To delete a role, follow these steps:
|
||||
|
||||
1. In the Admin interface, navigate to **Directory > Roles**.
|
||||
2. Select the checkbox beside the name of the role that you want to delete.
|
||||
3. Click **Delete**.
|
||||
|
||||
## Assign a role to a group
|
||||
|
||||
In authentik, roles are assigned to [groups](../groups/index.mdx), not to individual users.
|
||||
|
||||
1. To assign the role to a group, navigate to **Directory -> Groups**.
|
||||
2. Click the name of the group to which you want to add a role.
|
||||
3. On the group's detail page, on the Overview tab, click **Edit** in the **Group Info** area.
|
||||
4. On the **Update Group** modal, in the **Roles** field, scroll through the list of existent roles, and click to select the one you want to add to the group. (You can select multiple roles at once by holding the Control and Command keys while selecting the roles.)
|
||||
5. Click **Update** to add the role(s) and close the modal.
|
||||
|
||||
:::info
|
||||
To remove a role from a group, hold the Command key and click the name of the role that you want to remove from the group. This desepcts the role. Then click **Update**.
|
||||
:::
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Active Directory
|
||||
---
|
||||
|
||||
<span class="badge badge--secondary">Support level: Community</span>
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `ad.company` is the Name of the Active Directory domain.
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
|
||||
## Active Directory setup
|
||||
|
||||
1. Open Active Directory Users and Computers
|
||||
|
||||
2. Create a user in Active Directory, matching your naming scheme
|
||||
|
||||
|
||||
|
||||
3. Give the User a password, generated using for example `pwgen 64 1` or `openssl rand 36 | base64 -w 0`.
|
||||
|
||||
4. Open the Delegation of Control Wizard by right-clicking the domain and selecting "All Tasks".
|
||||
|
||||
5. Select the authentik service user you've just created.
|
||||
|
||||
6. Ensure the "Reset user password and force password change at next logon" Option is checked.
|
||||
|
||||
|
||||
|
||||
7. Grant these additional permissions (only required when _Sync users' password_ is enabled, and dependent on your AD Domain)
|
||||
|
||||
|
||||
|
||||
Additional info: https://support.microfocus.com/kb/doc.php?id=7023371
|
||||
|
||||
## authentik Setup
|
||||
|
||||
In authentik, create a new LDAP Source in Directory -> Federation & Social login.
|
||||
|
||||
Use these settings:
|
||||
|
||||
- Server URI: `ldap://ad.company`
|
||||
|
||||
For authentik to be able to write passwords back to Active Directory, make sure to use `ldaps://`. You can test to verify LDAPS is working using `ldp.exe`.
|
||||
|
||||
You can specify multiple servers by separating URIs with a comma, like `ldap://dc1.ad.company,ldap://dc2.ad.company`.
|
||||
|
||||
When using a DNS entry with multiple Records, authentik will select a random entry when first connecting.
|
||||
|
||||
- Bind CN: `<name of your service user>@ad.company`
|
||||
- Bind Password: The password you've given the user above
|
||||
- Base DN: The base DN which you want authentik to sync
|
||||
- Property mappings: Control/Command-select all Mappings which start with "authentik default LDAP" and "authentik default Active Directory"
|
||||
- Group property mappings: Select "authentik default LDAP Mapping: Name"
|
||||
|
||||
Additional settings that might need to be adjusted based on the setup of your domain:
|
||||
|
||||
- Group: If enabled, all synchronized groups will be given this group as a parent.
|
||||
- Addition User/Group DN: Additional DN which is _prepended_ to your Base DN configured above to limit the scope of synchronization for Users and Groups
|
||||
- User object filter: Which objects should be considered users. For Active Directory set it to `(&(objectClass=user)(!(objectClass=computer)))` to exclude Computer accounts.
|
||||
- Group object filter: Which objects should be considered groups.
|
||||
- Group membership field: Which user field saves the group membership
|
||||
- Object uniqueness field: A user field which contains a unique Identifier
|
||||
|
||||
After you save the source, a synchronization will start in the background. When its done, you can see the summary under Dashboards -> System Tasks.
|
||||
|
||||
|
||||
|
||||
To finalise the Active Directory setup, you need to enable the backend "authentik LDAP" in the Password Stage.
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 143 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 181 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 98 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 100 KiB |
@ -0,0 +1,81 @@
|
||||
---
|
||||
title: FreeIPA
|
||||
---
|
||||
|
||||
<span class="badge badge--secondary">Support level: Community</span>
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `svc_authentik` is the name of the bind account.
|
||||
- `freeipa.company` is the Name of the domain.
|
||||
- `ipa1.freeipa.company` is the Name of the FreeIPA server.
|
||||
|
||||
## FreeIPA Setup
|
||||
|
||||
1. Log into FreeIPA.
|
||||
|
||||
2. Create a user in FreeIPA, matching your naming scheme. Provide a strong password, example generation methods: `pwgen 64 1` or `openssl rand 36 | base64 -w 0`. After you are done click **Add and Edit**.
|
||||
|
||||
|
||||
|
||||
3. In the user management screen, select the Roles tab.
|
||||
|
||||
|
||||
|
||||
4. Add a role that has privileges to change user passwords, the default `User Administrators` role is sufficient. This is needed to support password resets from within authentik.
|
||||
|
||||
|
||||
|
||||
5. By default, if an administrator account resets a user's password in FreeIPA the user's password expires after the first use and must be reset again. This is a security feature to ensure password complexity and history policies are enforced. To bypass this feature for a more seamless experience, you can make the following modification on each of your FreeIPA servers:
|
||||
|
||||
```
|
||||
$ ldapmodify -x -D "cn=Directory Manager" -W -h ipa1.freeipa.company -p 389
|
||||
|
||||
dn: cn=ipa_pwd_extop,cn=plugins,cn=config
|
||||
changetype: modify
|
||||
add: passSyncManagersDNs
|
||||
passSyncManagersDNs: uid=svc_authentik,cn=users,cn=accounts,dc=freeipa,dc=company
|
||||
```
|
||||
|
||||
Additional info: [22.1.2. Enabling Password Reset Without Prompting for a Password Change at the Next Login](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/linux_domain_identity_authentication_and_policy_guide/user-authentication#user-passwords-no-expiry)
|
||||
|
||||
## authentik Setup
|
||||
|
||||
In authentik, create a new LDAP Source in Resources -> Sources.
|
||||
|
||||
Use these settings:
|
||||
|
||||
- Server URI: `ldaps://ipa1.freeipa.company`
|
||||
|
||||
You can specify multiple servers by separating URIs with a comma, like `ldap://ipa1.freeipa.company,ldap://ipa2.freeipa.company`.
|
||||
|
||||
When using a DNS entry with multiple Records, authentik will select a random entry when first connecting.
|
||||
|
||||
- Bind CN: `uid=svc_authentik,cn=users,cn=accounts,dc=freeipa,dc=company`
|
||||
- Bind Password: The password you've given the user above
|
||||
- Base DN: `dc=freeipa,dc=company`
|
||||
- Property mappings: Control/Command-select all Mappings which start with "authentik default LDAP" and "authentik default OpenLDAP"
|
||||
- Group property mappings: Select "authentik default OpenLDAP Mapping: cn"
|
||||
|
||||
Additional settings:
|
||||
|
||||
- Group: If selected, all synchronized groups will be given this group as a parent.
|
||||
- Addition User/Group DN: `cn=users,cn=accounts`
|
||||
- Addition Group DN: `cn=groups,cn=accounts`
|
||||
- User object filter: `(objectClass=person)`
|
||||
- Group object filter: `(objectClass=groupofnames)`
|
||||
- Group membership field: `member`
|
||||
- Object uniqueness field: `ipaUniqueID`
|
||||
|
||||
|
||||
|
||||
|
||||
After you save the source, you can kick off a synchronization by navigating to the source, clicking on the "Sync" tab, and clicking the "Run sync again" button.
|
||||
|
||||
|
||||
|
||||
Lastly, verify that the "User database + LDAP password" backend is selected in the "Password Stage" under Flows -> Stages.
|
||||
|
||||
|
||||
26
website/docs/users-sources/sources/index.md
Normal file
26
website/docs/users-sources/sources/index.md
Normal file
@ -0,0 +1,26 @@
|
||||
---
|
||||
title: Sources
|
||||
---
|
||||
|
||||
Sources allow you to connect authentik to an external user directory. Sources can also be used with social login providers such as Facebook, Twitter, or GitHub.
|
||||
|
||||
### Find your source
|
||||
|
||||
Sources are in the following general categories:
|
||||
|
||||
- **Protocols** ([LDAP](./protocols/ldap/index.md), [OAuth](./protocols/oauth/index.md), [SAML](./protocols/saml/index.md), and [SCIM](./protocols/scim/index.md))
|
||||
- [**Property mappings**](./property-mappings/index.md) or how to import data from a source
|
||||
- **Directory synchronization** (Active Directory, FreeIPA)
|
||||
- **Social logins** (Apple, Discord, Twitch, Twitter, and many others)
|
||||
|
||||
For instructions to add a specific source, refer to the documentation links in the left navigation pane.
|
||||
|
||||
### Add Sources to Default Login Page
|
||||
|
||||
To have sources show on the default login screen you will need to add them to the flow. The process below assumes that you have not created or renamed the default stages and flows.
|
||||
|
||||
1. In the Admin interface, navigate to the **Flows** section.
|
||||
2. Click on **default-authentication-flow**.
|
||||
3. Click the **Stage Bindings** tab.
|
||||
4. Chose **Edit Stage** for the _default-authentication-identification_ stage.
|
||||
5. Under **Sources** you should see the additional sources that you have configured. Click all applicable sources to have them displayed on the Login page.
|
||||
@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Sources expression property mappings
|
||||
---
|
||||
|
||||
The property mapping should return a value that is expected by the source. Returning `None` is always accepted and would simply skip the mapping for which `None` was returned.
|
||||
|
||||
## Variables
|
||||
|
||||
- Arbitrary arguments given by the source (this is documented by the source).
|
||||
- `properties`: A Python dictionary containing the result of the previously run property mappings, plus the initial data computed by the source.
|
||||
- `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))
|
||||
|
||||
import Objects from "../../../expressions/\_objects.md";
|
||||
|
||||
<Objects />
|
||||
|
||||
## Available Functions
|
||||
|
||||
import Functions from "../../../expressions/\_functions.md";
|
||||
|
||||
<Functions />
|
||||
@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Source property mappings
|
||||
---
|
||||
|
||||
Source property mappings allow you to modify or gather extra information from sources.
|
||||
|
||||
This page is an overview of how property mappings work. For information about specific protocol, please refer to each protocol page:
|
||||
|
||||
- [LDAP](../protocols/ldap/index.md#ldap-source-property-mappings)
|
||||
- [OAuth](../protocols/oauth/index.md#oauth-source-property-mappings)
|
||||
- [SAML](../protocols/saml/index.md#saml-source-property-mappings)
|
||||
- [SCIM](../protocols/scim/index.md#scim-source-property-mappings)
|
||||
|
||||
## Create a custom source property mapping
|
||||
|
||||
If the default source mappings are not enough, or if you need to get additional data from the source, you can create your own custom source property mappings.
|
||||
|
||||
Here are the steps:
|
||||
|
||||
1. In authentik, open the Admin interface, and then navigate to **Customization -> Property Mappings**.
|
||||
2. Click **Create**, select the property mapping type for your source, and then click **Next**.
|
||||
3. Type a unique and meaningful **Name**, such as `ldap-displayName-mapping:name`.
|
||||
4. In the **Expression** field enter Python expressions to retrieve the value from the source. See [Expression Semantics](#expression-semantics) below for details.
|
||||
5. In the source configuration, select the newly created property mapping as a **User property mapping** if it applies to users, or **Group property mapping** if it applies to groups.
|
||||
|
||||
## How it works
|
||||
|
||||
### Expression semantics
|
||||
|
||||
Each source provides the Python expression with additional data. You can import parts of that data into authentik users and groups. Assuming the source provides us with a `data` Python dictionary, you can write the following:
|
||||
|
||||
```python
|
||||
return {
|
||||
"name": data.get("displayName"),
|
||||
}
|
||||
```
|
||||
|
||||
You can see that the expression returns a Python dictionary. The dictionary keys must match [User properties](../../user/user_ref.md#object-properties) or [Group properties](../../groups/group_ref.md#object-properties). Note that for users, `ak_groups` and `group_attributes` cannot be set.
|
||||
|
||||
See each source documentation for a reference of the available data. See the authentik [expressions documentation](./expressions.md) for available data and functions.
|
||||
|
||||
Note that the [`list_flatten`](./expressions.md#list_flattenvalue-listany--any---optionalany) method is applied for all top-level properties, but not for attributes:
|
||||
|
||||
```python
|
||||
return {
|
||||
"username": data.get("username"), # list_flatten is automatically applied to top-level attributes
|
||||
"attributes": {
|
||||
"phone": list_flatten(data.get("phoneNumber")), # but not for attributes!
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Object construction process
|
||||
|
||||
A user or group object is constructed as follows:
|
||||
|
||||
1. The source provides initial properties based on commonly used data.
|
||||
2. Each property mapping associated with the source is run and results are merged into the previous properties.
|
||||
- If a property mapping throws an error, the process is aborted. If that happens inside a synchronization process, the object is skipped. If it happens during an enrollment or authentication flow, the flow is cancelled.
|
||||
- If a property mapping sets one attribute to `None`, that attribute is then discarded.
|
||||
3. If the `username` field is not set for user objects, or the `name` field is not set for group objects, the process is aborted.
|
||||
4. The object is created or updated. The `attributes` property is merged with existing data if the object already exists.
|
||||
|
||||
### Group synchronization
|
||||
|
||||
LDAP and SCIM sources have built-in mechanisms to get groups. This section does not apply to them.
|
||||
|
||||
You can write a custom property mapping to set the user's groups:
|
||||
|
||||
```python
|
||||
return {
|
||||
"groups": data.get("groups", []),
|
||||
}
|
||||
```
|
||||
|
||||
The `groups` attribute is a special attribute that must contain group identifiers. By default, those identifiers are also used as the group name by default, those identifiers are also used as the group name. Each of those identifiers is then given to group property mappings as the `group_id` variable, if extra processing needs to happen.
|
||||
136
website/docs/users-sources/sources/protocols/ldap/index.md
Normal file
136
website/docs/users-sources/sources/protocols/ldap/index.md
Normal file
@ -0,0 +1,136 @@
|
||||
---
|
||||
title: LDAP Source
|
||||
---
|
||||
|
||||
Sources allow you to connect authentik to an existing user directory. This source allows you to import users and groups from an LDAP Server.
|
||||
|
||||
:::info
|
||||
For Active Directory, follow the [Active Directory Integration](../../directory-sync/active-directory/index.md)
|
||||
|
||||
For FreeIPA, follow the [FreeIPA Integration](../../directory-sync/freeipa/index.md)
|
||||
:::
|
||||
|
||||
## Configuration options for LDAP sources
|
||||
|
||||
To create or edit a source in authentik, open the Admin interface and navigate to **Directory -> Ferderation and Social login**. There you can create a new LDAP source, or edit an existing one, using the following settings.
|
||||
|
||||
- **Enabled**: Toggle this option on to allow authentik to use the defined LDAP source.
|
||||
|
||||
- **Update internal password on login**: When the user logs in to authentik using the LDAP password backend, the password is stored as a hashed value in authentik. Toggle off (default setting) if you do not want to store the hashed passwords in authentik.
|
||||
|
||||
- **Sync users**: Enable or disable user synchronization between authentik and the LDAP source.
|
||||
|
||||
- **User password writeback**: Enable this option if you want to write password changes that are made in authentik back to LDAP.
|
||||
|
||||
- **Sync groups**: Enable/disable group synchronization. Groups are synced in the background every 5 minutes.
|
||||
|
||||
- **Parent group**: Optionally set this group as the parent group for all synced groups. An example use case of this would be to import Active Directory groups under a root `imported-from-ad` group.
|
||||
|
||||
#### Connection settings
|
||||
|
||||
- **Server URI**: URI to your LDAP server/Domain Controller. You can specify multiple servers by separating URIs with a comma, like `ldap://ldap1.company,ldap://ldap2.company`. When using a DNS entry with multiple Records, authentik will select a random entry when first connecting.
|
||||
|
||||
- **Enable StartTLS**: Enables StartTLS functionality. To use LDAPS instead, use port `636`.
|
||||
- **Use Server URI for SNI verification**: this setting is required for servers using TLS 1.3+
|
||||
|
||||
- **TLS Verification Certificate**: Specify a keypair to validate the remote certificate.
|
||||
|
||||
- **TLS Client authentication**: Client certificate keypair to authenticate against the LDAP Server's Certificate.
|
||||
|
||||
- **Bind CN**: CN of the bind user. This can also be a UPN in the format of `user@domain.tld`.
|
||||
|
||||
- **Bind password**: Password used during the bind process.
|
||||
|
||||
- **Base DN**: Base DN (distinguished name) used for all LDAP queries.
|
||||
|
||||
#### LDAP Attribute mapping
|
||||
|
||||
- **User Property Mappings** and **Group Property Mappings**: Define which LDAP properties map to which authentik properties. The default set of property mappings is generated for Active Directory. See also our documentation on [property mappings](#ldap-source-property-mappings).
|
||||
|
||||
:::warning
|
||||
When the **Sync users** and or the **Sync groups** options are enabled, their respective property mapping options must have at least one mapping selected, otherwise the sync will not start.
|
||||
:::
|
||||
|
||||
#### Additional Settings
|
||||
|
||||
- **Group**: Parent group for all the groups imported from LDAP.
|
||||
|
||||
- **User path**: Path template for all new users created.
|
||||
|
||||
- **Addition User DN**: Prepended to the base DN for user queries.
|
||||
|
||||
- **Addition Group DN**: Prepended to the base DN for group queries.
|
||||
|
||||
- **User object filter**: Consider objects matching this filter to be users.
|
||||
|
||||
- **Group object filter**: Consider objects matching this filter to be groups.
|
||||
|
||||
- **Group membership field**: This field contains the user's group memberships.
|
||||
|
||||
- **Object uniqueness field**: This field contains a unique identifier.
|
||||
|
||||
## LDAP source property mappings
|
||||
|
||||
See the [overview](../../property-mappings/index.md) for information on how property mappings work.
|
||||
|
||||
By default, authentik ships with [pre-configured mappings](#built-in-property-mappings) for the most common LDAP setups. These mappings can be found on the LDAP Source Configuration page in the Admin interface.
|
||||
|
||||
You can assign the value of a mapping to any user attribute. Keep in mind though, data types from the LDAP server will be carried over. This means that with some implementations, where fields are stored as array in LDAP, they will be saved as array in authentik. To prevent this, use the built-in `list_flatten` function. Here is an example mapping for the user's username and a custom attribute for a phone number:
|
||||
|
||||
```python
|
||||
return {
|
||||
"username": ldap.get("uid"), # list_flatten is automatically applied to top-level attributes
|
||||
"attributes": {
|
||||
"phone": list_flatten(ldap.get("phoneNumber")), # but not for attributes!
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Built-in property mappings
|
||||
|
||||
LDAP property mappings are used when you define a LDAP source. These mappings define which LDAP property maps to which authentik property. By default, the following mappings are created:
|
||||
|
||||
- authentik default Active Directory Mapping: givenName
|
||||
- authentik default Active Directory Mapping: sAMAccountName
|
||||
- authentik default Active Directory Mapping: sn
|
||||
- authentik default Active Directory Mapping: userPrincipalName
|
||||
- authentik default LDAP Mapping: mail
|
||||
- authentik default LDAP Mapping: Name
|
||||
- authentik default OpenLDAP Mapping: cn
|
||||
- authentik default OpenLDAP Mapping: uid
|
||||
|
||||
These are configured with most common LDAP setups.
|
||||
|
||||
### Expression data
|
||||
|
||||
The following variables are available to LDAP source property mappings:
|
||||
|
||||
- `ldap`: A Python dictionary containing data from LDAP.
|
||||
- `dn`: The object DN.
|
||||
|
||||
### Additional expression semantics
|
||||
|
||||
If you need to skip synchronization for a specific object, you can raise the `StopSync` exception:
|
||||
|
||||
```python
|
||||
if ldap.get("cn") == "doNotSync":
|
||||
raise StopSync
|
||||
```
|
||||
|
||||
## Password login
|
||||
|
||||
By default, authentik doesn't update the password it stores for a user when they log in using their LDAP credentials. That means that if the LDAP server is not reachable by authentik, users will not be able to log in. This behavior can be turned on with the **Update internal password on login** setting on the LDAP source.
|
||||
|
||||
:::note
|
||||
Sources created prior to the 2024.2 release have this setting turned on by default.
|
||||
:::
|
||||
|
||||
Be aware of the following security considerations when turning on this functionality:
|
||||
|
||||
- Updating the LDAP password does not invalidate the password stored in authentik; however for LDAP Servers like FreeIPA and Active Directory, authentik will lock its internal password during the next LDAP sync. For other LDAP servers, the old passwords will still be valid indefinitely.
|
||||
- Logging in via LDAP credentials overwrites the password stored in authentik if users have different passwords in LDAP and authentik.
|
||||
- Custom security measures that are used to secure the password in LDAP may differ from the ones used in authentik. Depending on threat model and security requirements this could lead to unknowingly being non-compliant.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
To troubleshoot LDAP sources and their synchronization, see [LDAP Troubleshooting](../../../../troubleshooting/ldap_source.md).
|
||||
55
website/docs/users-sources/sources/protocols/oauth/index.md
Normal file
55
website/docs/users-sources/sources/protocols/oauth/index.md
Normal file
@ -0,0 +1,55 @@
|
||||
---
|
||||
title: OAuth Source
|
||||
---
|
||||
|
||||
This source allows users to enroll themselves with an external OAuth-based Identity Provider. The generic provider expects the endpoint to return OpenID-Connect compatible information. Vendor-specific implementations have their own OAuth Source.
|
||||
|
||||
- Policies: Allow/Forbid users from linking their accounts with this provider.
|
||||
- Request Token URL: This field is used for OAuth v1 implementations and will be provided by the provider.
|
||||
- Authorization URL: This value will be provided by the provider.
|
||||
- Access Token URL: This value will be provided by the provider.
|
||||
- Profile URL: This URL is called by authentik to retrieve user information upon successful authentication.
|
||||
- Consumer key/Consumer secret: These values will be provided by the provider.
|
||||
- Scopes: Configure additional scopes to send to the provider.
|
||||
|
||||
Starting with authentik 2022.10, the default scopes can be replaced by prefix the value for scopes with `*`.
|
||||
|
||||
### OpenID Connect <span class="badge badge--version">authentik 2022.6+</span>
|
||||
|
||||
#### Well-known
|
||||
|
||||
Instead of configuring the URLs for a source manually, and the application you're configuring implements the [OpenID Connect Discovery Spec](https://openid.net/specs/openid-connect-discovery-1_0.html), you can configure the source with a single URL. The URL should always end with `.well-known/openid-configuration`. Many applications don't explicitly mention this URL, but for most of them it will be `https://application.company/.well-known/openid-configuration`.
|
||||
|
||||
This URL is fetched upon saving the source, and all the URLs will be replaced by the ones from the Discovery document. No automatic re-fetching is done.
|
||||
|
||||
#### JWKS
|
||||
|
||||
To simplify Machine-to-machine authentication, you can create an OAuth Source as "trusted" source of JWTs. Create a source and configure either the Well-known URL or the OIDC JWKS URL, or you can manually enter the JWKS data if you so desire.
|
||||
|
||||
Afterwards, this source can be selected in one or multiple OAuth2 providers, and any JWT issued by any of the configured sources' JWKS will be able to authenticate. To learn more about this, see [JWT-authentication](../../../../add-secure-apps/providers/oauth2/client_credentials#jwt-authentication).
|
||||
|
||||
## OAuth source property mappings
|
||||
|
||||
See the [overview](../../property-mappings/index.md) for information on how property mappings work.
|
||||
|
||||
### Expression data
|
||||
|
||||
The following variables are available to OAuth source property mappings:
|
||||
|
||||
- `info`: A Python dictionary containing OAuth claims. For example (values might differ depending on the source):
|
||||
```python
|
||||
{
|
||||
"iss": "https://source.company",
|
||||
"sub": "f153e7da687eec8c8789c72b6cc6bb5197df7b48b263b3151f36908e1bc10691",
|
||||
"aud": "01e4DmQiG1d3kaewD3Mkz7E7kXknk9j43eZMkNaE",
|
||||
"aud": "a7809c1b1c4aaa50adfb68660a6273dd9c8d15e4",
|
||||
"email": "user@authentik.company",
|
||||
"email_verified": True,
|
||||
"name": "User",
|
||||
"given_name": "User",
|
||||
"preferred_username": "user",
|
||||
"nickname": "user",
|
||||
}
|
||||
```
|
||||
- `client`: An OAuth client object to make requests to the Source with authentication built-in.
|
||||
- `token`: A Python dictionary containing OAuth tokens.
|
||||
93
website/docs/users-sources/sources/protocols/saml/index.md
Normal file
93
website/docs/users-sources/sources/protocols/saml/index.md
Normal file
@ -0,0 +1,93 @@
|
||||
---
|
||||
title: SAML Source
|
||||
---
|
||||
|
||||
This source allows authentik to act as a SAML Service Provider. Just like the SAML Provider, it supports signed requests. Vendor-specific documentation can be found in the Integrations Section.
|
||||
|
||||
## Terminology
|
||||
|
||||
| Abbreviation | Name | Description |
|
||||
| ------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| IDP | Identity Provider | The authoritative SAML authentication source that holds the user database |
|
||||
| SP | Service Provider | The client which is connected to an IDP, usually providing a service (e.g. a web application). In the current context, authentik is the SP. |
|
||||
| - | Assertion | A message sent by the IDP asserting that the user has been identified |
|
||||
| ACS | Assertion Consumer Service | The service on the SP side that consumes the assertion sent from the IDP |
|
||||
| SSO URL | Single Sign-On URL | The URL on the IDP side which the SP calls to initiate an authentication process |
|
||||
| SLO URL | Single Log-Out URL | The URL on the IDP side which the SP calls to invalidate a session and logout the user from the IDP as well as the SP |
|
||||
|
||||
## Example configuration
|
||||
|
||||
If you have the provider metadata, you should be able to extract all values you need from this. There is an example provided for a basic IDP metadata file below.
|
||||
|
||||
| Name | Example | Description |
|
||||
| -------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Name | Company SAML | The name of the authentication source |
|
||||
| Slug | company-saml | The slug used in URLs for the source |
|
||||
| SSO URL | https://saml.company/login/saml | The SingleSignOnService URL for the IDP, this can be found in the metadata or IDP documentation. There can be different URLs for different Binding Types (e.g. HTTP-Redirect and HTTP-POST), use the URL corresponding to the binding type you choose below |
|
||||
| SLO URL | https://saml.company/logout/saml | The URL that is called when a user logs out of authentik, can be used to automatically log the user out of the SAML IDP after logging out of Authentik. Not supported by all IDPs, and not always wanted behaviour. |
|
||||
| Issuer/Entity ID | https://authentik.company | The identifier for the authentik instance in the SAML federation, can be chosen freely. This is used to identify the SP on the IDP side, it usually makes sense to configure this to the URL of the SP or the path corresponding to the SP (e.g. `/source/saml/<source-slug>/` |
|
||||
| Binding Type | HTTP-POST | How authentik communicates with the SSO URL (302 redirect or POST request). This will depend on what the provider supports. |
|
||||
| Allow IDP-Initiated Logins | False | Whether to allow the IDP to log users into authentik without any interaction. Activating this may constitute a security risk since this request is not verified, and could be utilised by an attacker to authenticate a user without interaction on their side. |
|
||||
| NameID Policy | Persistent | Depending on what the IDP sends as persistent ID, some IDPs use the username or email address while others will use a random string/hashed value. If the user in authentik receives a random string as a username, try using Email address or Windows |
|
||||
| Flow settings | Default | If there are custom flows in your instance for external authentication, change to use them here |
|
||||
|
||||
## Adding authentik as a server provider with your IDP
|
||||
|
||||
This will depend heavily on what software you are using for your IDP. On the Metadata tab in the SAML Federation Source you can download the metadata for the service provider, this should enable you to import this into most IDPs. If this does not work, the important parts are:
|
||||
|
||||
- Entity ID: Taken from the Issuer/Entity ID field above
|
||||
- Return URL/ACS URL: `https://authentik.company/source/saml/<source-slug>/acs/`
|
||||
- Certificate: If you have chosen to sign your outgoing requests, use the public side of the certificate that you specified in the settings
|
||||
|
||||
## Example IDP metadata
|
||||
|
||||
```xml
|
||||
<md:EntityDescriptor entityID="https://saml.company/idp">
|
||||
<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" WantAuthnRequestsSigned="false">
|
||||
<md:NameIDFormat>
|
||||
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
|
||||
</md:NameIDFormat>
|
||||
<md:NameIDFormat>
|
||||
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
|
||||
</md:NameIDFormat>
|
||||
<md:NameIDFormat>
|
||||
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
|
||||
</md:NameIDFormat>
|
||||
<md:NameIDFormat>
|
||||
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
|
||||
</md:NameIDFormat>
|
||||
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://saml.company/login/saml/"/>
|
||||
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://saml.company/login/saml/"/>
|
||||
</md:IDPSSODescriptor>
|
||||
<md:Organization>
|
||||
<md:OrganizationName xml:lang="en">Example Organization</md:OrganizationName>
|
||||
<md:OrganizationDisplayName xml:lang="en">Example Organization</md:OrganizationDisplayName>
|
||||
<md:OrganizationURL xml:lang="en">http://www.company</md:OrganizationURL>
|
||||
</md:Organization>
|
||||
<md:ContactPerson contactType="technical">
|
||||
<md:Company>Example Organization</md:Company>
|
||||
<md:GivenName>John</md:GivenName>
|
||||
<md:SurName>Doe</md:SurName>
|
||||
<md:EmailAddress>john.doe@company</md:EmailAddress>
|
||||
<md:TelephoneNumber>012 345 67890</md:TelephoneNumber>
|
||||
</md:ContactPerson>
|
||||
<md:ContactPerson contactType="support">
|
||||
<md:Company>Example Organization</md:Company>
|
||||
<md:GivenName>Helpdesk</md:GivenName>
|
||||
<md:SurName>Support</md:SurName>
|
||||
<md:EmailAddress>helpdesk@company</md:EmailAddress>
|
||||
<md:TelephoneNumber>012 345 67890</md:TelephoneNumber>
|
||||
</md:ContactPerson>
|
||||
</md:EntityDescriptor>
|
||||
```
|
||||
|
||||
## SAML source property mappings
|
||||
|
||||
See the [overview](../../property-mappings/index.md) for information on how property mappings work.
|
||||
|
||||
### Expression data
|
||||
|
||||
The following variables are available to SAML source property mappings:
|
||||
|
||||
- `root`: An XML `ETree` object containing data from the source.
|
||||
- `name_id`: An XML `Element` object identifying the user.
|
||||
76
website/docs/users-sources/sources/protocols/scim/index.md
Normal file
76
website/docs/users-sources/sources/protocols/scim/index.md
Normal file
@ -0,0 +1,76 @@
|
||||
---
|
||||
title: SCIM Source
|
||||
---
|
||||
|
||||
:::info
|
||||
This feature is in technical preview, so please report any bugs on [GitHub](https://github.com/goauthentik/authentik/issues).
|
||||
:::
|
||||
|
||||
The SCIM source allows other applications to directly create users and groups within authentik. SCIM provides predefined schema for users and groups, with a RESTful API, to enable automatic user provisioning and deprovisioning, SCIM is supported by applications such as Microsoft Entra ID, Google Workspace, and Okta.
|
||||
|
||||
The base SCIM URL is in the format of `https://authentik.company/source/scim/<source-slug>/v2`. Authentication is done via Bearer tokens that are generated by authentik. When an SCIM source is created, a service account is created and a matching token is provided.
|
||||
|
||||
## First steps
|
||||
|
||||
To set up an SCIM source, log in as an administrator into authentik. Navigate to **Directory->Federation & Social login**, and click on **Create**. Select the **SCIM Source** type in the wizard, and give the source a name.
|
||||
|
||||
After the source is created, click on the name of the source in the list, and you will see the **SCIM Base URL** which is used by the SCIM client. Use the **Click to copy token** button to copy the token which is used by the client to authenticate SCIM requests.
|
||||
|
||||
## Supported Options & Resource types
|
||||
|
||||
### `/v2/Users`
|
||||
|
||||
Endpoint to list, create, update and delete users.
|
||||
|
||||
### `/v2/Groups`
|
||||
|
||||
Endpoint to list, create, update and delete groups.
|
||||
|
||||
There is also the `/v2/ServiceProviderConfig` and `/v2/ResourceTypes`, which is used by SCIM-enabled applications to find out which features authentik supports.
|
||||
|
||||
## SCIM source property mappings
|
||||
|
||||
See the [overview](../../property-mappings/index.md) for information on how property mappings work.
|
||||
|
||||
### Expression data
|
||||
|
||||
Each top level SCIM attribute is available as a variable in the expression. For example given an SCIM request with the payload of
|
||||
|
||||
```json
|
||||
{
|
||||
"schemas": [
|
||||
"urn:scim:schemas:core:2.0",
|
||||
"urn:scim:schemas:extension:enterprise:2.0"
|
||||
],
|
||||
"userName": "foo.bar",
|
||||
"name": {
|
||||
"familyName": "bar",
|
||||
"givenName": "foo",
|
||||
"formatted": "foo.bar"
|
||||
},
|
||||
"emails": [
|
||||
{
|
||||
"value": "foo.bar@authentik.company",
|
||||
"type": "work",
|
||||
"primary": true
|
||||
}
|
||||
],
|
||||
"title": "",
|
||||
"urn:scim:schemas:extension:enterprise:2.0": {
|
||||
"department": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The following variables are available in the expression:
|
||||
|
||||
- `schemas` as a list of strings
|
||||
- `userName` as a string
|
||||
- `name` as a dictionary
|
||||
- `emails` as a dictionary
|
||||
- `title` as a string
|
||||
- `urn_scim_schemas_extension_enterprise_2_0` as a dictionary
|
||||
|
||||
:::info
|
||||
Top-level keys which include symbols not allowed in python syntax are converted to `_`.
|
||||
:::
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 86 KiB |
@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Apple
|
||||
---
|
||||
|
||||
<span class="badge badge--primary">Support level: authentik</span>
|
||||
|
||||
Allows users to authenticate using their Apple ID.
|
||||
|
||||
## Preparation
|
||||
|
||||
:::caution
|
||||
An Apple developer account is required.
|
||||
:::
|
||||
|
||||
:::caution
|
||||
Apple mandates the use of a [registered TLD](https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains), as such this source will not work with .local and other non-public TLDs.
|
||||
:::
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
|
||||
## Apple
|
||||
|
||||
1. Log into your Apple developer account, and navigate to **Certificates, IDs & Profiles**, then click **Identifiers** in the sidebar.
|
||||
2. Register a new Identifier with the type of **App IDs**, and the subtype **App**.
|
||||
3. Choose a name that users will recognise for the **Description** field.
|
||||
4. For your bundle ID, use the reverse domain of authentik, in this case `company.authentik`.
|
||||
5. Scroll down the list of capabilities, and check the box next to **Sign In with Apple**.
|
||||
6. At the top, click **Continue** and **Register**.
|
||||
|
||||
|
||||
|
||||
7. Register another new Identifier with the type of **Services IDs**.
|
||||
8. Again, choose the same name as above for your **Description** field.
|
||||
9. Use the same identifier as above, but add a suffix like `signin` or `oauth`, as identifiers are unique.
|
||||
10. At the top, click **Continue** and **Register**.
|
||||
|
||||
|
||||
|
||||
11. Once back at the overview list, click on the just-created Identifier.
|
||||
12. Enable the checkbox next to **Sign In with Apple**, and click **Configure**
|
||||
13. Under domains, enter `authentik.company`.
|
||||
14. Under **Return URLs**, enter `https://authentik.company/source/oauth/callback/apple/`.
|
||||
|
||||
|
||||
|
||||
15. Click on **Keys** in the sidebar. Register a new Key with any name, and select **Sign in with Apple**.
|
||||
16. Click on **Configure**, and select the App ID you've created above.
|
||||
17. At the top, click **Save**, **Continue** and **Register**.
|
||||
18. Download the Key file and note the **Key ID**.
|
||||
|
||||
|
||||
|
||||
19. Note the Team ID, visible at the top of the page.
|
||||
|
||||
## authentik
|
||||
|
||||
20. Under _Directory -> Federation & Social login_ Click **Create Apple OAuth Source**
|
||||
|
||||
21. **Name**: `Apple`
|
||||
22. **Slug**: `apple`
|
||||
23. **Consumer Key:** The identifier from step 9, then `;`, then your Team ID from step 19, then `;`, then the Key ID from step 18.
|
||||
|
||||
Example: `io.goauthentik.dev-local;JQNH45HN7V;XFBNJ82BV6`
|
||||
|
||||
24. **Consumer Secret:** Paste the contents of the keyfile you've downloaded
|
||||
|
||||
Save, and you now have Apple as a source.
|
||||
|
||||
:::note
|
||||
For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page).
|
||||
:::
|
||||
BIN
website/docs/users-sources/sources/social-logins/apple/key.png
Normal file
BIN
website/docs/users-sources/sources/social-logins/apple/key.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 46 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 88 KiB |
@ -0,0 +1,113 @@
|
||||
---
|
||||
title: Azure AD
|
||||
---
|
||||
|
||||
<span class="badge badge--secondary">Support level: Community</span>
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
|
||||
## Azure setup
|
||||
|
||||
1. Navigate to [portal.azure.com](https://portal.azure.com), and open the _App registration_ service
|
||||
2. Register a new application
|
||||
|
||||
Under _Supported account types_, select whichever account type applies to your use-case.
|
||||
|
||||
|
||||
|
||||
3. Take note of the _Application (client) ID_ value.
|
||||
|
||||
If you selected _Single tenant_ in the _Supported account types_ prompt, also note the _Directory (tenant) ID_ value.
|
||||
|
||||
4. Navigate to _Certificates & secrets_ in the sidebar, and to the _Client secrets_ tab.
|
||||
5. Add a new secret, with an identifier of your choice, and select any expiration. Currently the secret in authentik has to be rotated manually or via API, so it is recommended to choose at least 12 months.
|
||||
6. Note the secret's value in the _Value_ column.
|
||||
|
||||
## authentik Setup
|
||||
|
||||
In authentik, create a new _Azure AD OAuth Source_ in Resources -> Sources.
|
||||
|
||||
Use the following settings:
|
||||
|
||||
- Name: `Azure AD`
|
||||
- Slug: `azure-ad` (this must match the URL being used above)
|
||||
- Consumer key: `*Application (client) ID* value from above`
|
||||
- Consumer secret: `*Value* of the secret from above`
|
||||
|
||||
If you kept the default _Supported account types_ selection of _Single tenant_, then you must change the URL below as well:
|
||||
|
||||
- OIDC Well-known URL: `https://login.microsoftonline.com/*Directory (tenant) ID* from above/v2.0/.well-known/openid-configuration`
|
||||
|
||||
|
||||
|
||||
Save, and you now have Azure AD as a source.
|
||||
|
||||
:::note
|
||||
For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page).
|
||||
:::
|
||||
|
||||
### Automatic user enrollment and attribute mapping
|
||||
|
||||
Using the following process you can auto-enroll your users without interaction, and directly control the mapping Azure attribute to authentik.
|
||||
attribute.
|
||||
|
||||
1. Create a new _Expression Policy_ (see [here](../../../../customize/policies/index.md) for details).
|
||||
2. Use _azure-ad-mapping_ as the name.
|
||||
3. Add the following code and adjust to your needs.
|
||||
|
||||
```python
|
||||
# save existing prompt data
|
||||
current_prompt_data = context.get('prompt_data', {})
|
||||
# make sure we are used in an oauth flow
|
||||
if 'oauth_userinfo' not in context:
|
||||
ak_logger.warning(f"Missing expected oauth_userinfo in context. Context{context}")
|
||||
return False
|
||||
oauth_data = context['oauth_userinfo']
|
||||
# map fields directly to user left hand are the field names provided by
|
||||
# the microsoft graph api on the right the user field names as used by authentik
|
||||
required_fields_map = {
|
||||
'name': 'username',
|
||||
'upn': 'email',
|
||||
'given_name': 'name'
|
||||
}
|
||||
missing_fields = set(required_fields_map.keys()) - set(oauth_data.keys())
|
||||
if missing_fields:
|
||||
ak_logger.warning(f"Missing expected fields. Missing fields {missing_fields}.")
|
||||
return False
|
||||
for oauth_field, user_field in required_fields_map.items():
|
||||
current_prompt_data[user_field] = oauth_data[oauth_field]
|
||||
# Define fields that should be mapped as extra user attributes
|
||||
attributes_map = {
|
||||
'upn': 'upn',
|
||||
'family_name': 'sn',
|
||||
'name': 'name'
|
||||
}
|
||||
missing_attributes = set(attributes_map.keys()) - set(oauth_data.keys())
|
||||
if missing_attributes:
|
||||
ak_logger.warning(f"Missing attributes: {missing_attributes}.")
|
||||
return False
|
||||
# again make sure not to overwrite existing data
|
||||
current_attributes = current_prompt_data.get('attributes', {})
|
||||
for oauth_field, user_field in attributes_map.items():
|
||||
current_attributes[user_field] = oauth_data[oauth_field]
|
||||
current_prompt_data['attributes'] = current_attributes
|
||||
context['prompt_data'] = current_prompt_data
|
||||
return True
|
||||
```
|
||||
|
||||
4. Create a new enrollment flow _azure-ad-enrollment_ (see [here](../../../../add-secure-apps/flows-stages/flow/index.md) for details).
|
||||
5. Add the policy _default-source-enrollment-if-sso_ to the flow. To do so open the newly created flow.
|
||||
Click on the tab **Policy/Group/User Bindings**. Click on **Bind existing policy** and choose _default-source-enrollment-if-sso_
|
||||
from the list.
|
||||
6. Bind the stages _default-source-enrollment-write_ (order 0) and _default-source-enrollment-login_ (order 10) to the flow.
|
||||
7. Bind the policy _azure-ad-mapping_ to the stage _default-source-enrollment-write_. To do so open the flow _azure-ad-enrollment_
|
||||
open the tab **Stage Bindings**, open the dropdown menu for the stage _default-source-enrollment-write_ and click on **Bind existing policy**
|
||||
Select _azure-ad-mapping_.
|
||||
8. Open the source _azure-ad_. Click on edit.
|
||||
9. Open **Flow settings** and choose _azure-ad-enrollment_ as enrollment flow.
|
||||
|
||||
Try to login with a **_new_** user. You should see no prompts and the user should have the correct information.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
@ -0,0 +1,383 @@
|
||||
---
|
||||
title: Discord
|
||||
---
|
||||
|
||||
<span class="badge badge--primary">Support level: authentik</span>
|
||||
|
||||
Allows users to authenticate using their Discord credentials
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
|
||||
## Discord
|
||||
|
||||
1. Create an application in the Discord Developer Portal (This is Free) https://discord.com/developers/applications
|
||||
|
||||
|
||||
|
||||
2. Name the Application
|
||||
|
||||
|
||||
|
||||
3. Select **OAuth2** from the left Menu
|
||||
|
||||
4. Copy the **Client ID** and _save it for later_
|
||||
|
||||
5. **Click to Reveal** the Client Secret and _save it for later_
|
||||
|
||||
6. Click **Add Redirect** and add https://authentik.company/source/oauth/callback/discord/
|
||||
|
||||
Here is an example of a completed OAuth2 screen for Discord.
|
||||
|
||||
|
||||
|
||||
## authentik
|
||||
|
||||
8. Under _Directory -> Federation & Social login_ Click **Create Discord OAuth Source**
|
||||
|
||||
9. **Name:** Choose a name (For the example I used Discord)
|
||||
10. **Slug:** discord (You can choose a different slug, if you do you will need to update the Discord redirect URLand point it to the correct slug.)
|
||||
11. **Consumer Key:** Client ID from step 4
|
||||
12. **Consumer Secret:** Client Secret from step 5
|
||||
|
||||
Here is an example of a complete authentik Discord OAuth Source
|
||||
|
||||
|
||||
|
||||
Save, and you now have Discord as a source.
|
||||
|
||||
:::note
|
||||
For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page).
|
||||
:::
|
||||
|
||||
### Checking for membership of a Discord Guild
|
||||
|
||||
:::info
|
||||
Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds guilds.members.read` scopes added under **Protocol settings**.
|
||||
:::
|
||||
|
||||
Create a new **Expression Policy** with the content below, adjusting the variables where required:
|
||||
|
||||
```python
|
||||
# To get the guild ID number for the parameters, open Discord, go to Settings > Advanced and enable developer mode.
|
||||
# Right-click on the server/guild title and select "Copy ID" to get the guild ID.
|
||||
|
||||
ACCEPTED_GUILD_ID = "123456789123456789"
|
||||
GUILD_NAME_STRING = "The desired server/guild name in the error message."
|
||||
|
||||
# Only change below here if you know what you are doing.
|
||||
|
||||
# Ensure flow is only run during OAuth logins via Discord
|
||||
if context['source'].provider_type != "discord":
|
||||
return True
|
||||
|
||||
# Get the user-source connection object from the context, and get the access token
|
||||
connection = context.get("goauthentik.io/sources/connection")
|
||||
if not connection:
|
||||
return False
|
||||
access_token = connection.access_token
|
||||
|
||||
guilds = requests.get(
|
||||
"https://discord.com/api/users/@me/guilds",
|
||||
headers= {
|
||||
"Authorization": f"Bearer {access_token}",
|
||||
}
|
||||
).json()
|
||||
|
||||
user_matched = any(ACCEPTED_GUILD_ID == g["id"] for g in guilds)
|
||||
if not user_matched:
|
||||
ak_message(f"User is not a member of {GUILD_NAME_STRING}.")
|
||||
return user_matched
|
||||
```
|
||||
|
||||
Now bind this policy to the chosen enrollment and authentication flows for the Discord OAuth source.
|
||||
|
||||
### Checking for membership of a Discord Guild role
|
||||
|
||||
:::info
|
||||
Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds guilds.members.read` scopes added under **Protocol settings**.
|
||||
:::
|
||||
|
||||
Create a new **Expression Policy** with the content below, adjusting the variables where required:
|
||||
|
||||
```python
|
||||
# To get the role and guild ID numbers for the parameters, open Discord, go to Settings > Advanced and
|
||||
# enable developer mode.
|
||||
# Right-click on the server/guild title and select "Copy ID" to get the guild ID.
|
||||
# Right-click on the server/guild title and select server settings > roles, right click on the role and click
|
||||
# "Copy ID" to get the role ID.
|
||||
|
||||
ACCEPTED_ROLE_ID = "123456789123456789"
|
||||
ACCEPTED_GUILD_ID = "123456789123456789"
|
||||
GUILD_NAME_STRING = "The desired server/guild name in the error message."
|
||||
ROLE_NAME_STRING = "The desired role name in the error message."
|
||||
|
||||
# Only change below here if you know what you are doing.
|
||||
GUILD_API_URL = f"https://discord.com/api/users/@me/guilds/{ACCEPTED_GUILD_ID}/member"
|
||||
|
||||
# Ensure flow is only run during OAuth logins via Discord
|
||||
if context['source'].provider_type != "discord":
|
||||
return True
|
||||
|
||||
# Get the user-source connection object from the context, and get the access token
|
||||
connection = context.get("goauthentik.io/sources/connection")
|
||||
if not connection:
|
||||
return False
|
||||
access_token = connection.access_token
|
||||
|
||||
guild_member_object = requests.get(
|
||||
GUILD_API_URL,
|
||||
headers= {
|
||||
"Authorization": f"Bearer {access_token}",
|
||||
}
|
||||
).json()
|
||||
|
||||
# The response for JSON errors is held within guild_member_object['code']
|
||||
# See: https://discord.com/developers/docs/topics/opcodes-and-status-codes#json
|
||||
# If the user isn't in the queried guild, it gives the somewhat misleading code = 10004.
|
||||
if "code" in guild_member_object:
|
||||
if guild_member_object['code'] == 10004:
|
||||
ak_message(f"User is not a member of {GUILD_NAME_STRING}.")
|
||||
else:
|
||||
ak_create_event("discord_error", source=context['source'], code=guild_member_object['code'])
|
||||
ak_message("Discord API error, try again later.")
|
||||
# Policy does not match if there is any error.
|
||||
return False
|
||||
|
||||
user_matched = any(ACCEPTED_ROLE_ID == g for g in guild_member_object["roles"])
|
||||
if not user_matched:
|
||||
ak_message(f"User is not a member of the {ROLE_NAME_STRING} role in {GUILD_NAME_STRING}.")
|
||||
return user_matched
|
||||
```
|
||||
|
||||
Now bind this policy to the chosen enrollment and authentication flows for the Discord OAuth source.
|
||||
|
||||
### Syncing Discord roles to authentik groups
|
||||
|
||||
:::info
|
||||
Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds.members.read` scopes added under **Protocol settings**.
|
||||
:::
|
||||
|
||||
:::info
|
||||
Any authentik role that you want to sync with a Discord role needs to have the **attribute** `discord_role_id` with a value of the Discord role's ID set.
|
||||
This setting can be found under `Authentik > Admin Interface > Directory > Groups > YOUR_GROUP > Attributes`
|
||||
Example: `discord_role_id: "<ROLE ID>"`
|
||||
:::
|
||||
|
||||
The following two policies allow you to synchronize roles in a Discord guild with roles in authentik.
|
||||
Whenever a user enrolls or signs in to authentik via a Discord source, these policies will check the user's Discord roles and apply the user's authentik roles accordingly.
|
||||
All roles with the attribute `discord_role_id` defined will be added or removed depending on whether the user is a member of the defined Discord role.
|
||||
|
||||
Create a new **Expression Policy** with the content below, adjusting the variables where required.
|
||||
|
||||
#### Sync on enrollment
|
||||
|
||||
The following policy will apply the above behaviour when a user enrolls.
|
||||
|
||||
```python
|
||||
from authentik.core.models import Group
|
||||
GUILD_API_URL = "https://discord.com/api/users/@me/guilds/{guild_id}/member"
|
||||
|
||||
### CONFIG ###
|
||||
guild_id = "<YOUR GUILD ID>"
|
||||
##############
|
||||
|
||||
# Ensure flow is only run during OAuth logins via Discord
|
||||
if context["source"].provider_type != "discord":
|
||||
return True
|
||||
|
||||
# Get the user-source connection object from the context, and get the access token
|
||||
connection = context.get("goauthentik.io/sources/connection")
|
||||
if not connection:
|
||||
return False
|
||||
access_token = connection.access_token
|
||||
|
||||
guild_member_request = requests.get(
|
||||
GUILD_API_URL.format(guild_id=guild_id),
|
||||
headers={
|
||||
"Authorization": f"Bearer {access_token}",
|
||||
},
|
||||
)
|
||||
guild_member_info = guild_member_request.json()
|
||||
|
||||
# Ensure we are not being ratelimited
|
||||
if guild_member_request.status_code == 429:
|
||||
ak_message(f"Discord is throttling this connection. Retry in {int(guild_member_info['retry_after'])}s")
|
||||
return False
|
||||
|
||||
# Ensure user is a member of the guild
|
||||
if "code" in guild_member_info:
|
||||
if guild_member_info["code"] == 10004:
|
||||
ak_message("User is not a member of the guild")
|
||||
else:
|
||||
ak_create_event("discord_error", source=context["source"], code=guild_member_info["code"])
|
||||
ak_message("Discord API error, try again later.")
|
||||
return False
|
||||
|
||||
# Get all discord_groups
|
||||
discord_groups = Group.objects.filter(attributes__discord_role_id__isnull=False)
|
||||
|
||||
# Filter matching roles based on guild_member_info['roles']
|
||||
user_groups_discord_updated = discord_groups.filter(attributes__discord_role_id__in=guild_member_info["roles"])
|
||||
|
||||
# Set matchin_roles in flow context
|
||||
request.context["flow_plan"].context["groups"] = user_groups_discord_updated
|
||||
|
||||
# Create event with roles added
|
||||
ak_create_event(
|
||||
"discord_role_sync",
|
||||
user_discord_roles_added=", ".join(str(group) for group in user_groups_discord_updated),
|
||||
)
|
||||
|
||||
return True
|
||||
|
||||
```
|
||||
|
||||
Now bind this policy to the chosen enrollment flows for the Discord OAuth source.
|
||||
|
||||
#### Sync on authentication
|
||||
|
||||
The following policy will apply the above behaviour when a user logs in.
|
||||
|
||||
```python
|
||||
from authentik.core.models import Group
|
||||
GUILD_API_URL = "https://discord.com/api/users/@me/guilds/{guild_id}/member"
|
||||
|
||||
### CONFIG ###
|
||||
guild_id = "<YOUR GUILD ID>"
|
||||
##############
|
||||
|
||||
# Ensure flow is only run during OAuth logins via Discord
|
||||
if context["source"].provider_type != "discord":
|
||||
return True
|
||||
|
||||
# Get the user-source connection object from the context, and get the access token
|
||||
connection = context.get("goauthentik.io/sources/connection")
|
||||
if not connection:
|
||||
return False
|
||||
access_token = connection.access_token
|
||||
|
||||
guild_member_request = requests.get(
|
||||
GUILD_API_URL.format(guild_id=guild_id),
|
||||
headers={
|
||||
"Authorization": f"Bearer {access_token}"
|
||||
},
|
||||
)
|
||||
guild_member_info = guild_member_request.json()
|
||||
|
||||
# Ensure we are not being ratelimited
|
||||
if guild_member_request.status_code == 429:
|
||||
ak_message(f"Discord is throttling this connection. Retry in {int(guild_member_info['retry_after'])}s")
|
||||
return False
|
||||
|
||||
# Ensure user is a member of the guild
|
||||
if "code" in guild_member_info:
|
||||
if guild_member_info["code"] == 10004:
|
||||
ak_message("User is not a member of the guild")
|
||||
else:
|
||||
ak_create_event("discord_error", source=context["source"], code=guild_member_info["code"])
|
||||
ak_message("Discord API error, try again later.")
|
||||
return False
|
||||
|
||||
# Get all discord_groups
|
||||
discord_groups = Group.objects.filter(attributes__discord_role_id__isnull=False)
|
||||
|
||||
# Split user groups into discord groups and non discord groups
|
||||
user_groups_non_discord = request.user.ak_groups.exclude(pk__in=discord_groups.values_list("pk", flat=True))
|
||||
user_groups_discord = list(request.user.ak_groups.filter(pk__in=discord_groups.values_list("pk", flat=True)))
|
||||
|
||||
# Filter matching roles based on guild_member_info['roles']
|
||||
user_groups_discord_updated = discord_groups.filter(attributes__discord_role_id__in=guild_member_info["roles"])
|
||||
|
||||
# Combine user_groups_non_discord and matching_roles
|
||||
user_groups_updated = user_groups_non_discord.union(user_groups_discord_updated)
|
||||
|
||||
# Update user's groups
|
||||
request.user.ak_groups.set(user_groups_updated)
|
||||
|
||||
# Create event with roles changed
|
||||
ak_create_event(
|
||||
"discord_role_sync",
|
||||
user_discord_roles_before=", ".join(str(group) for group in user_groups_discord),
|
||||
user_discord_roles_after=", ".join(str(group) for group in user_groups_discord_updated),
|
||||
)
|
||||
|
||||
return True
|
||||
|
||||
```
|
||||
|
||||
Now bind this policy to the chosen authentication flows for the Discord OAuth source.
|
||||
|
||||
### Store OAuth info in attribute and create avatar attribute from Discord avatar
|
||||
|
||||
:::info
|
||||
Ensure that the Discord OAuth source in **Federation & Social login** has the additional `guilds.members.read` scopes added under **Protocol settings**.
|
||||
:::
|
||||
|
||||
:::info
|
||||
In order to use the created attribute in authentik you will have to set authentik configuration arguments found at: https://docs.goauthentik.io/docs/core/settings#avatars
|
||||
:::
|
||||
|
||||
Create a new **Expression Policy** with the content below, adjusting the variables where required:
|
||||
|
||||
```python
|
||||
import base64
|
||||
import requests
|
||||
|
||||
AVATAR_SIZE = "64" # Valid values: 16,32,64,128,256,512,1024. Larger values may cause HTTP error 431 on applications/providers due to headers being too large.
|
||||
|
||||
# Only change below here if you know what you are doing.
|
||||
AVATAR_URL = "https://cdn.discordapp.com/avatars/{id}/{avatar}.png?size={avatar_size}"
|
||||
AVATAR_STREAM_CONTENT = "data:image/png;base64,{base64_string}" # Converts base64 image into html syntax usable with authentik's avatar attributes feature
|
||||
|
||||
|
||||
def get_as_base64(url):
|
||||
"""Returns the base64 content of the url"""
|
||||
return base64.b64encode(requests.get(url).content)
|
||||
|
||||
|
||||
def get_avatar_from_avatar_url(url):
|
||||
"""Returns an authentik-avatar-attributes-compatible string from an image url"""
|
||||
cut_url = f"{url}"
|
||||
return AVATAR_STREAM_CONTENT.format(
|
||||
base64_string=(get_as_base64(cut_url).decode("utf-8"))
|
||||
)
|
||||
|
||||
|
||||
# Ensure flow is only run during OAuth logins via Discord
|
||||
if context["source"].provider_type != "discord":
|
||||
return True
|
||||
|
||||
user = request.user
|
||||
userinfo = request.context["oauth_userinfo"]
|
||||
|
||||
# Assigns the discord attributes to the user
|
||||
user.attributes["discord"] = {
|
||||
"id": userinfo["id"],
|
||||
"username": userinfo["username"],
|
||||
"discriminator": userinfo["discriminator"],
|
||||
"email": userinfo["email"],
|
||||
"avatar": userinfo["avatar"],
|
||||
"avatar_url": (
|
||||
AVATAR_URL.format(
|
||||
id=userinfo["id"], avatar=userinfo["avatar"], avatar_size=AVATAR_SIZE
|
||||
)
|
||||
if userinfo["avatar"]
|
||||
else None
|
||||
),
|
||||
}
|
||||
|
||||
# If the user has an avatar, assign it to the user
|
||||
avatar_url = user.attributes["discord"].get("avatar_url", None)
|
||||
if avatar_url is not None:
|
||||
user.attributes["avatar"] = get_avatar_from_avatar_url(avatar_url)
|
||||
|
||||
user.save()
|
||||
return True
|
||||
|
||||
```
|
||||
|
||||
Now bind this policy to the chosen enrollment and authentication flows for the Discord OAuth source.
|
||||
@ -0,0 +1,74 @@
|
||||
---
|
||||
title: Facebook
|
||||
---
|
||||
|
||||
<span class="badge badge--secondary">Support level: Community</span>
|
||||
|
||||
Adding Facebook as a source allows users to authenticate through authentik using their Facebook credentials.
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
|
||||
## Facebook configuration
|
||||
|
||||
To integrate authentik with Facebook and access the user credentials from Facebook, you first need to register with Meta for Developers and create a developers account. Refer to the [Facebook documentation](https://developers.facebook.com/docs/development) for exact steps.
|
||||
|
||||
1. Visit https://developers.facebook.com/ and log in to your Facebook account.
|
||||
2. After you log in, go to https://developers.facebook.com/async/registration and follow the steps to register as a developer.
|
||||
|
||||
Next, create an app so that Facebook generates a unique ID for your authentik app.
|
||||
|
||||
:::info
|
||||
You will need the Facebook **App ID** and **App Secret** values from the Facebook app in order to configure the authentik integration. See Step 11. below for instructions.
|
||||
:::
|
||||
|
||||
3. On the Meta for Developers Dashboard click **Create**.
|
||||
4. Follow the prompts to create the app.
|
||||
|
||||
After you create the app you need to customize the login settings.
|
||||
|
||||
5. Go back to the Dashboard and in the left navigation pane click **Use Cases**.
|
||||
6. On the **Use cases** page, click **Customize** under **Authentication and account creation**.
|
||||
7. On the **Customize** page, click **Go to settings**.
|
||||
8. On the **Facebook Login settings** page set the **Valid OAuth redirect URIs** field to `https://authentik.company/source/oauth/callback/facebook/` and then click **Save**.
|
||||
|
||||
9. Navigate to the **Use cases -> Customize** page.
|
||||
10. Under **Permissions** click **Add** for the **email** permission.
|
||||
|
||||
Next, you need to obtain the App ID and the App Secret for the Facebook app, and enter those into your authentik source configuration.
|
||||
|
||||
11. Go back to the Dashboard, and in the bottom left in the navigation pane, click on **App settings -> Basic**.
|
||||
12. Copy the **App ID** and the **App secret** values and temporarily store them in a safe place until you enter them into authentik.
|
||||
|
||||
Finally, you need to publish the Facebook app.
|
||||
|
||||
12. Go back to the Dashboard, and on the **Create and publish this app** page, follow the prompts.
|
||||
|
||||
## authentik configuration
|
||||
|
||||
1. Log into authentik as admin, and then navigate to **Directory -> Federation & Social login**
|
||||
2. Click **Create**.
|
||||
3. In the **New Source** modal box, for **Select type** select **Facebook OAuth Source** and then click **Next**.
|
||||
4. Define the following fields:
|
||||
- **Name**: provide a descriptive name
|
||||
- **Slug**: leave default value (If you choose a different slug then the default, the URL will need to be updated to reflect the change)
|
||||
- **User matching mode**: leave default option unless other configuration is needed
|
||||
- **User path**: leave default option unless other configuration is needed
|
||||
- **Icon**: optionally you can select a specific icon of logo to display on the login form.
|
||||
- **Protocol settings**
|
||||
- **Consumer Key**: enter the **App ID** from Facebook
|
||||
- **Consumer Secret**: enter the **App Secret** from Facebook
|
||||
- **Scopes**: define any further access scopes
|
||||
- **Flow settings**
|
||||
- **Authentication flow**: leave the default `default-source-authentication` option.
|
||||
- **Enrollment flow**: leave the default `default-source-enrollment` option.
|
||||
5. Click **Finish** to save your settings and close the modal box.
|
||||
|
||||
You now have Facebook as a source. Verify by checking that appears on the **Directory -> Federation & Social login** page in authentik.
|
||||
|
||||
:::note
|
||||
For more details on how to display the new source on the authentik Login page refer to [Add Sources to default Login form](../../index.md#add-sources-to-default-login-page).
|
||||
:::
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 124 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
102
website/docs/users-sources/sources/social-logins/github/index.md
Normal file
102
website/docs/users-sources/sources/social-logins/github/index.md
Normal file
@ -0,0 +1,102 @@
|
||||
---
|
||||
title: Github
|
||||
---
|
||||
|
||||
<span class="badge badge--primary">Support level: authentik</span>
|
||||
|
||||
Allows users to authenticate using their Github credentials
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
- `www.my.company` Homepage URL for your site
|
||||
|
||||
## Github
|
||||
|
||||
1. Create an OAuth app under Developer Settings https://github.com/settings/developers by clicking on the **Register a new application**
|
||||
|
||||
|
||||
|
||||
2. **Application Name:** Choose a name users will recognize ie: authentik
|
||||
3. **Homepage URL**:: www.my.company
|
||||
4. **Authorization callback URL**: https://authentik.company/source/oauth/callback/github
|
||||
5. Click **Register Application**
|
||||
|
||||
Example screenshot
|
||||
|
||||
|
||||
|
||||
6. Copy the **Client ID** and _save it for later_
|
||||
7. Click **Generate a new client secret** and _save it for later_ You will not be able to see the secret again, so be sure to copy it now.
|
||||
|
||||
## authentik
|
||||
|
||||
8. Under _Directory -> Federation & Social login_ Click **Create Github OAuth Source**
|
||||
|
||||
9. **Name**: Choose a name (For the example I use Github)
|
||||
10. **Slug**: github (If you choose a different slug the URLs will need to be updated to reflect the change)
|
||||
11. **Consumer Key:** Client ID from step 6
|
||||
12. **Consumer Secret:** Client Secret from step 7
|
||||
|
||||
Here is an example of a complete authentik Github OAuth Source
|
||||
|
||||
|
||||
|
||||
Save, and you now have Github as a source.
|
||||
|
||||
:::note
|
||||
For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page).
|
||||
:::
|
||||
|
||||
### Checking for membership of a GitHub Organisation <span class="badge badge--version">authentik 2021.12.5.+</span>
|
||||
|
||||
To check if the user is member of an organisation, you can use the following policy on your flows:
|
||||
|
||||
:::info
|
||||
Make sure to include `read:org` in the sources' _Scopes_ setting.
|
||||
:::
|
||||
|
||||
```python
|
||||
# Ensure flow is only run during oauth logins via Github
|
||||
if context["source"].provider_type != "github":
|
||||
return True
|
||||
|
||||
accepted_org = "foo"
|
||||
|
||||
# Get the user-source connection object from the context, and get the access token
|
||||
connection = context["goauthentik.io/sources/connection"]
|
||||
access_token = connection.access_token
|
||||
|
||||
# We also access the user info authentik already retrieved, to get the correct username
|
||||
github_username = context["oauth_userinfo"]
|
||||
|
||||
# Github does not include Organisations in the userinfo endpoint, so we have to call another URL
|
||||
|
||||
orgs_response = requests.get(
|
||||
"https://api.github.com/user/orgs",
|
||||
auth=(github_username["login"], access_token),
|
||||
headers={
|
||||
"accept": "application/vnd.github.v3+json"
|
||||
}
|
||||
)
|
||||
orgs_response.raise_for_status()
|
||||
orgs = orgs_response.json()
|
||||
|
||||
# `orgs` will be formatted like this
|
||||
# [
|
||||
# {
|
||||
# "login": "goauthentik",
|
||||
# [...]
|
||||
# }
|
||||
# ]
|
||||
user_matched = any(org['login'] == accepted_org for org in orgs)
|
||||
if not user_matched:
|
||||
ak_message(f"User is not member of {accepted_org}.")
|
||||
return user_matched
|
||||
```
|
||||
|
||||
If a user is not member of the chosen organisation, they will see this message
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 86 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
102
website/docs/users-sources/sources/social-logins/google/index.md
Normal file
102
website/docs/users-sources/sources/social-logins/google/index.md
Normal file
@ -0,0 +1,102 @@
|
||||
---
|
||||
title: Google
|
||||
---
|
||||
|
||||
<span class="badge badge--secondary">Support level: Community</span>
|
||||
|
||||
Allows users to authenticate using their Google credentials
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
|
||||
## Google
|
||||
|
||||
You will need to create a new project, and OAuth credentials in the Google Developer console. The developer console can be overwhelming at first.
|
||||
|
||||
1. Visit https://console.developers.google.com/ to create a new project
|
||||
2. Create a New project.
|
||||
|
||||
|
||||
|
||||
3. **Project Name**: Choose a name
|
||||
4. **Organization**: Leave as default if unsure
|
||||
5. **Location**: Leave as default if unsure
|
||||
|
||||
|
||||
|
||||
6. Click **Create**
|
||||
7. Choose your project from the drop down at the top
|
||||
8. Click the **Credentials** menu item on the left. It looks like a key.
|
||||
|
||||
|
||||
|
||||
9. Click on **Configure Consent Screen**
|
||||
|
||||
|
||||
|
||||
10. **User Type:** If you do not have a Google Workspace (GSuite) account choose _External_. If you do have a Google Workspace (Gsuite) account and want to limit access to only users inside of your organization choose _Internal_
|
||||
|
||||
_I'm only going to list the mandatory/important fields to complete._
|
||||
|
||||
11. **App Name:** Choose an Application
|
||||
12. **User Support Email:** Must have a value
|
||||
13. **Authorized Domains:** authentik.company
|
||||
14. **Developer Contact Info:** Must have a value
|
||||
15. Click **Save and Continue**
|
||||
16. If you have special scopes configured for google, enter them on this screen. If not click **Save and Continue**
|
||||
17. If you want to create Test Users enter them here, if not click **Save and Continue**
|
||||
18. From the _Summary Page_ click on the \*_Credentials_ link on the left. Same link as step 8
|
||||
19. Click **Create Credentials** on the top of the screen
|
||||
20. Choose **OAuth Client ID**
|
||||
|
||||
|
||||
|
||||
21. **Application Type:** Web Application
|
||||
22. **Name:** Choose a name
|
||||
23. **Authorized redirect URIs:** `https://authentik.company/source/oauth/callback/google/`
|
||||
|
||||
|
||||
|
||||
24. Click **Create**
|
||||
25. Copy and store _Your Client ID_ and _Your Client Secret_ for later
|
||||
|
||||
## authentik
|
||||
|
||||
26. Under _Directory -> Federation & Social login_ Click **Create Google OAuth Source**
|
||||
|
||||
27. **Name**: Choose a name (For the example I use Google)
|
||||
28. **Slug**: google (If you choose a different slug the URLs will need to be updated to reflect the change)
|
||||
29. **Consumer Key:** Your Client ID from step 25
|
||||
30. **Consumer Secret:** Your Client Secret from step 25
|
||||
|
||||
Here is an example of a complete authentik Google OAuth Source
|
||||
|
||||
|
||||
|
||||
Save, and you now have Google as a source.
|
||||
|
||||
:::note
|
||||
For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page).
|
||||
:::
|
||||
|
||||
## Username mapping
|
||||
|
||||
Since google does not have the concept of a username, authentik will by default prompt the user for a username when they first enroll through a google source. To change this behaviour and automatically use the email address as username, create an expression policy to set the username to the email, and bind it to the enrollment flow.
|
||||
|
||||
Create an expression policy with this expression:
|
||||
|
||||
```python
|
||||
email = request.context["prompt_data"]["email"]
|
||||
# Direct set username to email
|
||||
request.context["prompt_data"]["username"] = email
|
||||
# Set username to email without domain
|
||||
# request.context["prompt_data"]["username"] = email.split("@")[0]
|
||||
return False
|
||||
```
|
||||
|
||||
Afterwards, edit the source's enrollment flow (by default _default-source-enrollment_), expand the policies bound to the first stage (_default-source-enrollment-prompt_), and bind the policy created above. Make sure the newly created policy comes before _default-source-enrollment-if-username_. Afterwards, any new logins will automatically have their google email address used as their username.
|
||||
|
||||
This can be combined with disallowing users from changing their usernames, see [Configuration](../../../../sys-mgmt/settings.md#allow-users-to-change-username).
|
||||
@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Mailcow
|
||||
---
|
||||
|
||||
<span class="badge badge--secondary">Support level: Community</span>
|
||||
|
||||
Allows users to authenticate using their Mailcow credentials
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
- `mailcow.company` is the FQDN of the mailcow install.
|
||||
|
||||
## Mailcow
|
||||
|
||||
1. Log into mailcow as an admin and navigate to the OAuth2 Apps settings
|
||||
|
||||
|
||||
|
||||
2. Click "Add OAuth2 Client"
|
||||
|
||||
3. Insert the redirect URL: `https://authentik.company/source/oauth/callback/mailcow/`
|
||||
|
||||
|
||||
|
||||
4. Copy the **Client ID** and **Client secret** and _save it for later_
|
||||
|
||||
|
||||
|
||||
## authentik
|
||||
|
||||
5. Under _Directory -> Federation & Social login_ Click **Create > Mailcow OAuth Source**
|
||||
|
||||
|
||||
|
||||
6. **Name:** Choose a name (For the example I used Mailcow)
|
||||
7. **Slug:** mailcow (You can choose a different slug, if you do you will need to update the Mailcow redirect URL and point it to the correct slug.)
|
||||
8. **Consumer Key:** Client ID from step 4
|
||||
9. **Consumer Secret:** Client Secret from step 4
|
||||
10. **Authorization URL:** https://mailcow.company/oauth/authorize
|
||||
11. **Access token URL:** https://mailcow.company/oauth/token
|
||||
12. **Profile URL:** https://mailcow.company/oauth/profile
|
||||
|
||||
Here is an example of a complete authentik Mailcow OAuth Source
|
||||
|
||||
|
||||
|
||||
Save, and you now have Mailcow as a source.
|
||||
|
||||
:::note
|
||||
For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page).
|
||||
:::
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 5.2 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Plex
|
||||
---
|
||||
|
||||
<span class="badge badge--secondary">Support level: Community</span>
|
||||
|
||||
Allows users to authenticate using their Plex credentials
|
||||
|
||||
## Preparation
|
||||
|
||||
None
|
||||
|
||||
## authentik -> Sources
|
||||
|
||||
Add _Plex_ as a _source_
|
||||
|
||||
- Name: Choose a name
|
||||
- Slug: Set a slug
|
||||
- Client ID: Set a unique Client Id or leave the generated ID
|
||||
- Press _Load Servers_ to login to plex and pick the authorized Plex Servers for "allowed users"
|
||||
- Decide if _anyone_ with a plex account can authenticate or only friends you share with
|
||||
|
||||
Save, and you now have Plex as a source.
|
||||
|
||||
:::note
|
||||
For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page).
|
||||
:::
|
||||
|
||||
## Plex source property mappings
|
||||
|
||||
See the [overview](../../property-mappings/index.md) for information on how property mappings work.
|
||||
|
||||
### Expression data
|
||||
|
||||
The following variables are available to OAuth source property mappings:
|
||||
|
||||
- `info`: A Python dictionary containing Plex user data.
|
||||
- `auth_api`: A Plex client object to make requests to the Source with authentication built-in.
|
||||
@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Twitch
|
||||
---
|
||||
|
||||
<span class="badge badge--secondary">Support level: Community</span>
|
||||
|
||||
Allows users to authenticate using their Twitch credentials
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
|
||||
## Twitch
|
||||
|
||||
1. Click **Register Your Application** in the Twitch Developers Console https://dev.twitch.tv/console
|
||||
|
||||
|
||||
|
||||
2. Name your Application
|
||||
|
||||
3. Add https://authentik.company/source/oauth/callback/twitch in the **OAuth Redirect URLs** field
|
||||
|
||||
4. Select a Category for your Application
|
||||
|
||||
5. Click **Create** to finish the registration of your Application
|
||||
|
||||
|
||||
|
||||
6. Click **Manage** on your newly created Application
|
||||
|
||||
|
||||
|
||||
7. Copy your Client ID and save it for later
|
||||
|
||||
8. Click **New Secret** to create a new Secret
|
||||
|
||||
9. Copy the above Secret and also save it for later
|
||||
|
||||
|
||||
|
||||
## authentik
|
||||
|
||||
10. Under _Directory -> Federation & Social login_ Click **Create Twitch OAuth Source**
|
||||
|
||||
11. **Name:** Choose a name (For the example I used Twitch)
|
||||
12. **Slug:** twitch (You can choose a different slug, if you do you will need to update the Twitch redirect URL and point it to the correct slug.)
|
||||
13. **Consumer Key:** Client ID from step 7
|
||||
14. **Consumer Secret:** Secret from step 9
|
||||
|
||||
Here is an example of a complete authentik Twitch OAuth Source
|
||||
|
||||
|
||||
|
||||
Save, and you now have Twitch as a source.
|
||||
|
||||
:::note
|
||||
For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page).
|
||||
:::
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 74 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 73 KiB |
@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Twitter
|
||||
---
|
||||
|
||||
<span class="badge badge--primary">Support level: authentik</span>
|
||||
|
||||
Allows users to authenticate using their twitter credentials
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
|
||||
## Twitter
|
||||
|
||||
You will need to create a new project, and OAuth credentials in the Twitter Developer console.
|
||||
|
||||
1. Visit https://developer.twitter.com/ to create a new App
|
||||
2. Select an environment fitting to your use-case
|
||||
3. Give the app a name, for example _authentik_
|
||||
4. Finish setting up the app by clicking **App settings**. Any of the API keys on this screen are not used by authentik.
|
||||
5. Click the **Set up** button
|
||||
|
||||
|
||||
|
||||
6. Enable **OAuth 2.0**
|
||||
7. Set **Type of App** to _Web_
|
||||
8. Set **Callback URI / Redirect URL** to `https://authentik.company/source/oauth/callback/twitter/`
|
||||
9. Set **Website URL** to `https://authentik.company`
|
||||
|
||||
|
||||
|
||||
10. Confirm with **Save**
|
||||
11. Copy and store **Client ID** and **Client Secret** for later
|
||||
|
||||
## authentik
|
||||
|
||||
1. Under _Directory -> Federation & Social login_ Click **Create Twitter OAuth Source**
|
||||
|
||||
2. **Name**: Choose a name (For the example I use Google)
|
||||
3. **Slug**: twitter (If you choose a different slug the URLs will need to be updated to reflect the change)
|
||||
4. **Consumer Key:** Your Client ID from step 25
|
||||
5. **Consumer Secret:** Your Client Secret from step 25
|
||||
|
||||
:::note
|
||||
For more details on how-to have the new source display on the Login Page see [here](../../index.md#add-sources-to-default-login-page).
|
||||
:::
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
BIN
website/docs/users-sources/user/create_invite.png
Normal file
BIN
website/docs/users-sources/user/create_invite.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 171 KiB |
13
website/docs/users-sources/user/index.mdx
Normal file
13
website/docs/users-sources/user/index.mdx
Normal file
@ -0,0 +1,13 @@
|
||||
---
|
||||
title: About users
|
||||
---
|
||||
|
||||
import DocCardList from "@theme/DocCardList";
|
||||
|
||||
In authentik you can create and manage users with fine-tuned access control, session and event details, group membership, super-user rights, impersonation, and password management and recovery.
|
||||
|
||||
To learn more about Enterprise licenses with internal and external users, refer to our [Enterprise documentation](../../enterprise/manage-enterprise.md#about-users-and-licenses).
|
||||
|
||||
To learn more about working with users in authentik, refer to the following topics:
|
||||
|
||||
<DocCardList />
|
||||
49
website/docs/users-sources/user/invitations.md
Normal file
49
website/docs/users-sources/user/invitations.md
Normal file
@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Invitations
|
||||
description: "Learn how to create an invitation URL for new users to enroll."
|
||||
---
|
||||
|
||||
Invitations are another way to create a user, by inviting someone to join your authentik instance, as a new user. With invitations, you can either email an enrollment invitation URL to one or more specific recipients with pre-defined credentials, or you can email a URL to users, who can then log in and define their own credentials.
|
||||
|
||||
:::info
|
||||
You can also create a policy to see if the invitation was ever used.
|
||||
:::
|
||||
|
||||
## Create an invitation
|
||||
|
||||
The fastest way to create an invitation is to use our pre-defined `default-enrollment-flow` that has the necessary stages and prompts already included.
|
||||
|
||||
**Step 1. Download the `default-enrollment-flow` file**
|
||||
|
||||
To download the `default-enrollment-flow` file, run this command:
|
||||
|
||||
```shell
|
||||
wget https://goauthentik.io/blueprints/example/flows-enrollment-2-stage.yaml
|
||||
```
|
||||
|
||||
Alternatively, use this [link](/blueprints/example/flows-enrollment-2-stage.yaml) to view and save the file. For more details, refer to the [documentation](https://goauthentik.io/docs/flow/examples/flows#enrollment-2-stage).
|
||||
|
||||
**Step 2. Import the `default-enrollment-flow` file**
|
||||
|
||||
In authentik, navigate to the Admin UI, and then click **Flows** in the left navigation pane.
|
||||
|
||||
At the top of the Flows page, click **Import**, and then select the `flows-enrollment-2-stage.yaml` file that you just downloaded.
|
||||
|
||||
**Step 3. Create the invitation object**
|
||||
|
||||
In the Admin UI, navigate to **Directory --> Invitations**, and then click **Create** to open the **Create Invitation** modal. Define the following fields:
|
||||
|
||||
- **Name**: provide a name for your invitation object.
|
||||
- **Expires**: select a date for when you want the invitation to expire.
|
||||
- **Flow**: in the drop-down menu, select the **default-enrollment-flow** Flow.
|
||||
- **Custom attributes**: (_optional_) enter optional key/value pairs here, to pre-define any information about the user that you will invite to enroll. The data entered here is considered as a variable, specifically the `context['prompt_data']` variable. This data is read by the context flow's [prompt stage](../../add-secure-apps/flows-stages/stages/prompt/index.md) in an expression policy.
|
||||
|
||||
|
||||
|
||||
- **Single use**: specify whether or not you want the invitation to expire after a single use.
|
||||
|
||||
Click **Save** to save the new invitation and close the modal and return to the **Invitations** page.
|
||||
|
||||
**Step 3. Email the invitation**
|
||||
|
||||
On the **Invitations** page, click the chevron beside your new invitation, to expand the details. The **Link to use the invitation** displays with the URL. Copy the URL and send it in an email to the people you want to invite to enroll.
|
||||
122
website/docs/users-sources/user/user_basic_operations.md
Normal file
122
website/docs/users-sources/user/user_basic_operations.md
Normal file
@ -0,0 +1,122 @@
|
||||
---
|
||||
title: Manage users
|
||||
---
|
||||
|
||||
The following topics are for the basic management of users: how to create, modify, delete or deactivate users, and using a recovery email.
|
||||
|
||||
[Policies](../../customize/policies/index.md) can be used to further manage how users are authenticated. For example, by default authentik does not require email addresses be unique, but you can use a policy to [enforce unique email addresses](../../customize/policies/working_with_policies/unique_email.md).
|
||||
|
||||
### Create a user
|
||||
|
||||
> If you want to automate user creation, you can do that either by [invitations](./invitations.md), [`user_write` stage](../../add-secure-apps/flows-stages/stages/user_write.md), or [using the API](/docs/developer-docs/api/reference/core-users-create).
|
||||
|
||||
1. In the Admin interface of your authentik instance, select **Directory > Users** in the left side menu.
|
||||
2. Select the folder where you want to create a user.
|
||||
3. Click **Create** (for a default user).
|
||||
4. Fill in the required fields:
|
||||
|
||||
- **Username**: This value must be unique across your user folders.
|
||||
- **Path**: The path where the user will be created. It will be automatically populated with the folder you selected in the previous step.
|
||||
|
||||
5. Fill the **_optional_** fields if needed:
|
||||
|
||||
- **Name**: The display name of the user.
|
||||
- **Email**: The email address of the user. Email addresses are used in [email stages](../../add-secure-apps/flows-stages/stages/email/index.mdx) and to receive [notifications](../../sys-mgmt/events/notifications.md), if configured.
|
||||
- **Is active**: Define if the newly created user account is active. Selected by default.
|
||||
- **Attributes**: Custom attributes definition for the user, in YAML or JSON format. These attributes can be used to enforce additional prompts on authentication stages or define conditions to enforce specific policies if the current implementation does not fit your use case. The value is an empty dictionary by default.
|
||||
|
||||
6. Click **Create**
|
||||
|
||||
You should see a confirmation pop-up on the top-right of the screen that the user has been created, and see the new user in the user list. You can directly click the username if you want to [modify your user](./user_basic_operations#modify-a-user).
|
||||
|
||||
:::info
|
||||
To create a super-user, you need to add the user to a group that has super-user permissions. For more information, refer to [Create a Group](../groups/manage_groups.md#create-a-group).
|
||||
:::
|
||||
|
||||
### View user details
|
||||
|
||||
In the **Directory > Users** menu of the Admin interface, you can browse all the users in your authentik instance.
|
||||
|
||||
To view details about a specific user:
|
||||
|
||||
1. In the list of all users, click on the name of the user you want to check.
|
||||
|
||||
This takes you to the **Overview** tab, with basic information about the user, and also quick access to perform basic actions to the user.
|
||||
|
||||
2. To see further details, click any of the other tabs:
|
||||
|
||||
- **Session** shows the active sessions established by the user. If there is any need, you can clean up the connected devices for a user by selecting the device(s) and then clicking **Delete**. This forces the user to authenticate again on the deleted devices.
|
||||
- **Groups** allows you to manage the group membership of the user. You can find more details on [groups](../groups/index.mdx).
|
||||
- **User events** displays all the events generated by the user during a session, such as login, logout, application authorisation, password reset, user info update, etc.
|
||||
- **Explicit consent** lists all the permissions the user has given explicitly to an application. Entries will only appear if the user is validating an [explicit consent flow in an OAuth2 provider](../../add-secure-apps/providers/oauth2/index.md). If you want to delete the explicit consent (because the application is requiring new permissions, or the user has explicitly asked to reset his consent on third-party apps), select the applications and click **Delete**. The user will be asked to again give explicit consent to share information with the application.
|
||||
- **OAuth Refresh Tokens** lists all the OAuth tokens currently distributed. You can remove the tokens by selecting the applications and then clicking **Delete**.
|
||||
- **MFA Authenticators** shows all the authentications that the user has registered to their user profile. You can remove the tokens if the user has lost their authenticator and want to enroll a new one.
|
||||
|
||||
## Modify a user
|
||||
|
||||
After the creation of the user, you can edit any parameter defined during the creation.
|
||||
|
||||
To modify a user object, go to **Directory > Users**, and click the edit icon beside the name. You can also go into [user details](#view-user-details), and click **Edit**.
|
||||
|
||||
### Assign, modify, or remove permissions for a user
|
||||
|
||||
You can grant a user specific global or object-level permissions. Alternatively, you can add a user to a group that has the appropriate permissions, and the user inherits all of the group's permissions.
|
||||
|
||||
For more information, review ["Permissions"](../access-control/permissions.md).
|
||||
|
||||
## Add a user to a group
|
||||
|
||||
1. To add a user to a group, navigate to **Directory > Users** to display all users.
|
||||
2. Click the name of the user to display the full user details page.
|
||||
3. Click the **Groups** tab, and then click either **Add to existing group** or **Add to new group**.
|
||||
|
||||
## User credentials recovery
|
||||
|
||||
If a user has lost their credentials, there are several options.
|
||||
|
||||
### Email them a recovery link
|
||||
|
||||
1. In the Admin interface, navigate to **Directory > Users** to display all users.
|
||||
2. Either click the name of the user to display the full User details page, or click the chevron (the › symbol) beside their name to expand the options.
|
||||
3. To generate a recovery link, which you can then copy and paste into an email, click **View recovery link**.
|
||||
|
||||
A pop-up will appear on your browser with the link for you to copy and to send to the user.
|
||||
|
||||
### Automate email to a user
|
||||
|
||||
You can use our automated email to send a link with the URL for the user to reset their password. This option will only work if you have properly [configured a SMTP server during the installation](../../install-config/install/docker-compose.mdx#email-configuration-optional-but-recommended) and set an email address for the user.
|
||||
|
||||
1. In the Admin interface, navigate to **Directory > Users** to display all users.
|
||||
2. Either click the name of the user to display the full User details page, or click the chevron beside their name to expand the toptions.
|
||||
3. To send the automated email to the user, click **Email recovery link**.
|
||||
|
||||
If the user does not receive the email, check if the mail server parameters [are properly configured](../../troubleshooting/emails.md).
|
||||
|
||||
### Reset the password for the user
|
||||
|
||||
As an Admin, you can simply reset the password for the user.
|
||||
|
||||
1. In the Admin interface, navigate to **Directory > Users** to display all users.
|
||||
2. Either click the name of the user to display the full User details page, or click the chevron beside their name to expand the toptions.
|
||||
3. To reset the user's password, click **Reset password**, and then define the new value.
|
||||
|
||||
## Deactivate or Delete user
|
||||
|
||||
#### To deactivate a user:
|
||||
|
||||
1. Go into the user list or detail, and click **Deactivate**.
|
||||
2. Review the changes and click **Update**.
|
||||
|
||||
The active sessions are revoked and the authentication of the user blocked. You can reactivate the account by following the same procedure.
|
||||
|
||||
#### To delete a user:
|
||||
|
||||
:::caution
|
||||
This deletion is not reversible, so be sure you do not need to recover any identity data of the user.
|
||||
You may instead deactivate the account to preserve identity data.
|
||||
:::
|
||||
|
||||
1. Go into the user list and select one (or multiple users) to delete and click **Delete** on the top-right of the page.
|
||||
2. Review the changes and click **Delete**.
|
||||
|
||||
The user list refreshes and no longer displays the removed users.
|
||||
99
website/docs/users-sources/user/user_ref.md
Normal file
99
website/docs/users-sources/user/user_ref.md
Normal file
@ -0,0 +1,99 @@
|
||||
---
|
||||
title: User properties and attributes
|
||||
---
|
||||
|
||||
## Object properties
|
||||
|
||||
The User object has the following properties:
|
||||
|
||||
- `username`: User's username.
|
||||
- `email` User's email.
|
||||
- `uid` User's unique ID
|
||||
- `name` User's display name.
|
||||
- `is_staff` Boolean field if user is staff.
|
||||
- `is_active` Boolean field if user is active.
|
||||
- `date_joined` Date user joined/was created.
|
||||
- `password_change_date` Date password was last changed.
|
||||
- `path` User's path, see [Path](#path-authentik-20227)
|
||||
- `attributes` Dynamic attributes, see [Attributes](#attributes)
|
||||
- `group_attributes()` Merged attributes of all groups the user is member of and the user's own attributes.
|
||||
- `ak_groups` This is a queryset of all the user's groups.
|
||||
|
||||
You can do additional filtering like:
|
||||
|
||||
```python
|
||||
user.ak_groups.filter(name__startswith='test')
|
||||
```
|
||||
|
||||
For Django field lookups, see [here](https://docs.djangoproject.com/en/4.2/ref/models/querysets/#id4).
|
||||
|
||||
To get the name of all groups, you can use this command:
|
||||
|
||||
```python
|
||||
[group.name for group in user.ak_groups.all()]
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
List all the User's group names:
|
||||
|
||||
```python
|
||||
for group in user.ak_groups.all():
|
||||
yield group.name
|
||||
```
|
||||
|
||||
## Path <span class="badge badge--version">authentik 2022.7+</span>
|
||||
|
||||
Paths can be used to organize users into folders depending on which source created them or organizational structure. Paths may not start or end with a slash, but they can contain any other character as path segments. The paths are currently purely used for organization, it does not affect their permissions, group memberships, or anything else.
|
||||
|
||||
## Attributes
|
||||
|
||||
### `goauthentik.io/user/can-change-username`
|
||||
|
||||
Optional flag, when set to false prevents the user from changing their own username.
|
||||
|
||||
### `goauthentik.io/user/can-change-name`
|
||||
|
||||
Optional flag, when set to false prevents the user from changing their own name.
|
||||
|
||||
### `goauthentik.io/user/can-change-email`
|
||||
|
||||
Optional flag, when set to false prevents the user from changing their own email address.
|
||||
|
||||
### `goauthentik.io/user/token-expires`:
|
||||
|
||||
Optional flag, when set to false, Tokens created by the user will not expire.
|
||||
|
||||
Only applies when the token creation is triggered by the user with this attribute set. Additionally, the flag does not apply to superusers.
|
||||
|
||||
### `goauthentik.io/user/token-maximum-lifetime`:
|
||||
|
||||
Optional flag, when set, defines the maximum lifetime of user-created tokens. Defaults to the system setting if not set.
|
||||
|
||||
Only applies when `goauthentik.io/user/token-expires` set to true.
|
||||
|
||||
Format is string of format `days=10;hours=1;minute=3;seconds=5`.
|
||||
|
||||
### `goauthentik.io/user/debug`:
|
||||
|
||||
See [Troubleshooting access problems](../../troubleshooting/access.md), when set, the user gets a more detailed explanation of access decisions.
|
||||
|
||||
### `additionalHeaders`:
|
||||
|
||||
:::info
|
||||
This field is only used by the Proxy Provider.
|
||||
:::
|
||||
|
||||
Some applications can be configured to create new users using header information forwarded from authentik. You can forward additional header information by adding each header
|
||||
underneath `additionalHeaders`:
|
||||
|
||||
#### Example:
|
||||
|
||||
```yaml
|
||||
additionalHeaders:
|
||||
REMOTE-USER: joe.smith
|
||||
REMOTE-EMAIL: joe@jsmith.com
|
||||
REMOTE-NAME: Joseph
|
||||
```
|
||||
|
||||
These headers will now be passed to the application when the user logs in. Most applications will need to be configured to accept these headers. Some examples of applications that can accept additional headers from an authentik Proxy Provider are [Grafana](https://grafana.com/docs/grafana/latest/auth/auth-proxy/) and [Tandoor Recipes](https://docs.tandoor.dev/features/authentication/).
|
||||
Reference in New Issue
Block a user