Break down Sources into individual sections in Docs (#1052)

* Create index.mdx

Add Wekan example

* updated to include wekan entry

* Update and rename website/docs/sources.md to website/docs/sources/index.md

Break Sources into individual pages.

* Update and rename website/docs/sources/index.md to website/docs/sources/ldap/index.md

* Create index.md

* Update index.md

* Update index.md

* Create index.md

* Create index.md

* Create index.md

* Update index.md

* Update index.md

* Update index.md

* Create index.md

* discord images

* spacing

* Added discord

* discord changes

* Added sources breakdown to the sidebar

* Fixed the saml title

* Added github examples

* fixed formatting

* Changed file path, updated sidebar, added google.

* fixed a spelling mistake

* Cleaned up formatting

* Fixed Notes
This commit is contained in:
Ernie 2021-06-22 15:46:44 -04:00 committed by GitHub
parent b69248dd55
commit 2a670afd02
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
24 changed files with 269 additions and 23 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 115 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 103 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

View File

@ -0,0 +1,54 @@
---
title: Discord
---
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
![New Application Button](discord1.png)
2. Name the Application
![Name App](discord2.png)
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.
![Example Screen](discord4.png)
## Authentik
8. Under _Resources -> Sources_ 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
13. **Provider type:** Discord
Here is an exmple of a complete Authentik Discord OAuth Source
![Example Screen](discord5.png)
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 the Sources page
:::

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 52 KiB

View File

@ -0,0 +1,60 @@
---
title: Github
---
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 neww application**
![Register OAuth App](githubdeveloper1.png)
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
![Example Screen](githubdeveloperexample.png)
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 _Resources -> Sources_ 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
13. **Provider Type:** Github
Expand URL settings:
:::note
As of June 20 2021 these URLS are correct. Here is the Github reference URL https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps
:::
14. **Authorization URL:** `https://github.com/login/oauth/authorize`
15. **Access token URL:** `https://github.com/login/oauth/access_token`
16. **Profile URL:** `https://api.github.com/user`
Here is an exmple of a complete Authentik Github OAuth Source
![Example Screen](githubexample2.png)
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 the Sources page
:::

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 103 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 51 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 56 KiB

View File

@ -0,0 +1,83 @@
---
title: Google
---
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.
![Example Screen](googledeveloper1.png)
3. **Project Name**: Choose a name
4. **Organization**: Leave as defaut if unsure
5. **Location**: Leave as default if unsure
![Example Screen](googledeveloper2.png)
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.
![Example Screen](googledeveloper3.png)
9. Click on **Configure Consent Screen**
![Example Screen](googledeveloper4.png)
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 acces 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**
![Example Screen](googledeveloper5.png)
21. **Application Type:** Web Application
22. **Name:** Choose a name
23. **Authorized redirect URIs:** `https://authenik.company/source/oauth/callback/google/`
![Example Screen](googledeveloper6.png)
24. Click **Create**
25. Copy and store _Your Client ID_ and _Your Client Secret_ for later
## Authentik
26. Under _Resources -> Sources_ 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
31. **Provider Type:** Google
Here is an exmple of a complete Authentik Google OAuth Source
![Example Screen](authentiksource.png)
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 the Sources page
:::

View File

@ -0,0 +1,14 @@
---
title: Sources
---
Sources allow you to connect authentik to an existing user directory. They can also be used for social logins, using external providers such as Facebook, Twitter, etc.
### Add Sources to Default Login Page
To have sources show on the default login screen you will need to add them. This is assuming you have not created or renamed the default stages and flows.
1. Access 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 addtional sources you have configured. Click all applicable sources to have them displayed on the Login Page

View File

@ -1,26 +1,9 @@
--- ---
title: Sources title: LDAP
--- ---
Sources allow you to connect authentik to an existing user directory. They can also be used for social logins, using external providers such as Facebook, Twitter, etc. Sources allow you to connect authentik to an existing user directory. They can also be used for social logins, using external providers such as Facebook, Twitter, etc.
## Generic OAuth Source
**All Integration-specific Sources are documented in the Integrations Section**
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.
## 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.
## LDAP Source ## LDAP Source
This source allows you to import users and groups from an LDAP Server. This source allows you to import users and groups from an LDAP Server.

View File

@ -0,0 +1,18 @@
---
title: Generic OAuth Source
---
## Generic OAuth Source
:::note
All Integration-specific Sources are documented in the Integrations Section
:::
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.

View File

@ -0,0 +1,21 @@
---
title: Plex
---
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.

View File

@ -0,0 +1,7 @@
---
title: SAML
---
## 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.

View File

@ -20,10 +20,6 @@ module.exports = {
"installation/reverse-proxy", "installation/reverse-proxy",
], ],
}, },
{
type: "doc",
id: "sources",
},
{ {
type: "category", type: "category",
label: "Providers", label: "Providers",
@ -67,7 +63,17 @@ module.exports = {
{ {
type: "category", type: "category",
label: "as Source", label: "as Source",
items: ["integrations/sources/active-directory/index"], items: [
"integrations/sources/index",
"integrations/sources/active-directory/index",
"integrations/sources/discord/index",
"integrations/sources/github/index",
"integrations/sources/google/index",
"integrations/sources/ldap/index",
"integrations/sources/oauth/index",
"integrations/sources/plex/index",
"integrations/sources/saml/index",
],
}, },
{ {
type: "category", type: "category",