habsi/authentik
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

website: latest migration to new structure (#11522)

Browse Source 
* 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

---------

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
2024-10-08 14:07:19 -05:00
committed by GitHub
parent 9200a598ec
commit 9a89a5f94b
336 changed files with 2624 additions and 871 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
website/docs/users-sources/sources/protocols/ldap/index.md Normal file
View 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
View 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
View 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
View 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 `_`.
:::