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
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 |
Reference in New Issue
Block a user