docs: complete restructure of Flagsmith documentation (#6210)

Co-authored-by: Guilherme <guilherme@writechoice.io>
Co-authored-by: Robert Norrie <robertnorrie@me.com>
Co-authored-by: htessaro <heitor@writechoice.io>
Co-authored-by: lucaspr2 <lucasp@writechoice.io>
Co-authored-by: wadii <wadii.zaim@flagsmith.com>

Author: 6 people

README.md

@@ -19,7 +19,7 @@
 
 # [Flagsmith](https://flagsmith.com/) is an Open-Source Feature Flagging Tool to Ship Faster & Control Releases 
 
-Change the way your team releases software. Roll out, segment, and optimise—with granular control. Stay secure with on-premise and private cloud hosting.
+Change the way your team releases software. Roll out, segment, and optimise—with granular control. Stay secure with on-premise and private cloud hosting. 
 
 * Feature flags: Release features behind the safety of a feature flag
 * Make changes remotely: Easily toggle individual features on and off, and make changes without deploying new code

api/Makefile

@@ -151,7 +151,7 @@ integrate-private-tests:
 
 .PHONY: generate-docs
 generate-docs:
-	poetry run flagsmith docgen metrics > ../docs/docs/system-administration/metrics.md
+	poetry run flagsmith docgen metrics > ../docs/docs/administration-and-security/platform-configuration/metrics.md
 
 .PHONY: add-known-sdk-version
 add-known-sdk-version:

docs/docs/administration-and-security/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Administration and Security",
+    "position": 4,
+    "collapsed": true
+}

docs/docs/administration-and-security/access-control/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Access Control",
+    "position": 2,
+    "collapsed": true
+}

…administration/authentication/05-ADFS.md …tion-and-security/access-control/adfs.mddocs/docs/system-administration/authentication/05-ADFS.md renamed to docs/docs/administration-and-security/access-control/adfs.md docs/docs/system-administration/authentication/05-ADFS.md renamed to docs/docs/administration-and-security/access-control/adfs.md

@@ -1,5 +1,7 @@
 ---
 title: ADFS
+sidebar_label: ADFS
+sidebar_position: 20
 ---
 
 :::tip

…m-administration/authentication/index.md …ion-and-security/access-control/index.mddocs/docs/system-administration/authentication/index.md renamed to docs/docs/administration-and-security/access-control/index.md docs/docs/system-administration/authentication/index.md renamed to docs/docs/administration-and-security/access-control/index.md

@@ -2,7 +2,7 @@
 title: Authentication
 description: Customise how your users log in to the Flagsmith dashboard
 sidebar_label: Overview
-sidebar_position: 1
+sidebar_position: 10
 ---
 
 Flagsmith supports a variety of authentication methods for logging into the dashboard:
@@ -21,9 +21,9 @@ Two-factor authentication requires a [Start-Up or Enterprise subscription](https
 
 Using the following authentication methods requires an [Enterprise subscription](https://flagsmith.com/pricing):
 
-- [SAML](/system-administration/authentication/SAML)
-- Active Directory (LDAP)
-- Microsoft ADFS
+- [SAML](/administration-and-security/access-control/saml)
+- [Active Directory (LDAP)](/administration-and-security/access-control/ldap)
+- [Microsoft ADFS](/administration-and-security/access-control/adfs)
 
 Please get in touch in order to integrate with LDAP or ADFS.
 
@@ -37,7 +37,7 @@ and authentication methods you want to allow for your users, and when would be a
 restrictions.
 
 If you are self-hosting Flagsmith, you can restrict authentication methods per email domain from
-[Django Admin](/deployment/configuration/django-admin):
+[Django Admin](/deployment-self-hosting/administration-and-maintenance/using-the-django-admin):
 
 1. On the Django Admin sidebar, click on "Domain auth methods".
 2. Click "Add domain auth methods".
@@ -50,7 +50,7 @@ If you are self-hosting Flagsmith, you can restrict authentication methods per e
 If you are self-hosting Flagsmith, you can disable password authentication by setting the `PREVENT_EMAIL_PASSWORD` 
 environment variable on the Flagsmith API. This will also hide the username and password fields from the login screen.
 Note that this does not disable password authentication for
-[Django Admin](/deployment/configuration/django-admin#email-and-password).
+[Django Admin](/deployment-self-hosting/administration-and-maintenance/using-the-django-admin#email-and-password).
 
 If you have a private cloud Flagsmith instance, contact Flagsmith support to disable password authentication once 
 you have successfully set up an alternative authentication method.

…administration/authentication/04-LDAP.md …tion-and-security/access-control/ldap.mddocs/docs/system-administration/authentication/04-LDAP.md renamed to docs/docs/administration-and-security/access-control/ldap.md docs/docs/system-administration/authentication/04-LDAP.md renamed to docs/docs/administration-and-security/access-control/ldap.md

@@ -1,5 +1,7 @@
 ---
 title: LDAP
+sidebar_label: LDAP
+sidebar_position: 50
 ---
 
 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
@@ -10,37 +12,37 @@ LDAP authentication requires a self-hosted [Enterprise subscription](https://fla
 
 :::
 
-Flagsmith can be configured to use LDAP for authentication with [environment variables](#backend-environment-variables).
-When enabled, it works by authenticating the user with username and password using the ldap server, fetching the user
-details from the LDAP server (if the authentication was successful) and creating the user in the Django database.
+Flagsmith can be configured to use LDAP for authentication with [environment variables](#backend-environment-variables). 
+
+When LDAP is enabled, it works by authenticating the user with username and password using the ldap server, fetching the user details from the LDAP server (if the authentication was successful) and creating the user in the Django database.
 
 ## Using Microsoft Active Directory
 
-By default, Flagsmith supports logging in via OpenLDAP. To connect to a Microsoft Active Directory, you need to modify
-the following environment variables.
+By default, Flagsmith supports logging in via OpenLDAP. To connect to a Microsoft Active Directory, you need to modify the following environment variables.
+
+Flagsmith provides different `LDAP_AUTH_FORMAT_USERNAME` settings to accommodate various Active Directory username formats:
 
-For simple usernames (e.g. "username"):
+- **Simple usernames** (e.g. "username"):
 
 ```txt
 LDAP_AUTH_FORMAT_USERNAME="django_python3_ldap.utils.format_username_active_directory"
 ```
 
-For down-level login name formats (e.g. "DOMAIN\username"):
+- **Down-level login name formats** (e.g. "DOMAIN\username"):
 
 ```txt
 LDAP_AUTH_FORMAT_USERNAME="django_python3_ldap.utils.format_username_active_directory"
 LDAP_AUTH_ACTIVE_DIRECTORY_DOMAIN="DOMAIN"
 ```
 
-For user-principal-name formats (e.g. "user@domain.com"):
+- **User-principal-name formats** (e.g. "user@domain.com"):
 
 ```txt
 LDAP_AUTH_FORMAT_USERNAME="django_python3_ldap.utils.format_username_active_directory_principal"
 LDAP_AUTH_ACTIVE_DIRECTORY_DOMAIN="domain.com"
 ```
 
-Depending on how your Active Directory server is configured, the following additional settings may match your server
-better than the defaults used by django-python3-ldap:
+Depending on how your Active Directory server is configured, the following additional settings may match your server better than the defaults used by django-python3-ldap:
 
 ```txt
 LDAP_AUTH_USER_FIELDS=username=sAMAccountName,email=mail,first_name=givenName,last_name=sn
@@ -49,8 +51,7 @@ LDAP_AUTH_OBJECT_CLASS="user"
 
 ## Sync LDAP groups
 
-You can synchronise Flagsmith users and groups with your LDAP (Directory) users and groups by running the following
-command:
+You can synchronise Flagsmith users and groups with your LDAP (Directory) users and groups by running the following command:
 
 ```bash
 python manage.py sync_ldap_users_and_groups
@@ -63,7 +64,7 @@ Running this command will:
 - Remove users from group if they no longer belong to that group in Directory
 - Add users to group if they belong to a new group in Directory
 
-:::note Before running this command, please make sure to set the following environment variables:
+:::note Before running the synchronisation command, please make sure to set the following environment variables:
 
 - LDAP_SYNC_USER_USERNAME
 - LDAP_SYNC_USER_PASSWORD
@@ -75,9 +76,7 @@ Running this command will:
 
 ## Backend environment variables
 
-Note that some environment variables may be different depending on the image that you are using
-(`flagsmith/flagsmith-api-ee` or `flagsmith/flagsmith-private-cloud`). Please select the correct tab below to ensure you
-are using the correct environment variables.
+Note that some environment variables may be different depending on the image that you are using (`flagsmith/flagsmith-api-ee` or `flagsmith/flagsmith-private-cloud`). Please select the correct tab below to ensure you are using the correct environment variables.
 
 <Tabs groupId="ImageType">
 <TabItem value="ee" label="flagsmith-api-ee">

docs/docs/administration-and-security/access-control/oauth.md

@@ -0,0 +1,41 @@
+---
+title: OAuth
+sidebar_label: OAuth
+sidebar_position: 40
+---
+
+This guide explains how to set up OAuth authentication for Flagsmith using Google and GitHub as identity providers. OAuth allows your users to log in to Flagsmith using their existing credentials from these services.
+
+## Prerequisites
+
+- Administrative access to your Flagsmith instance to configure environment variables and Flagsmith on Flagsmith flags.
+- An account with Google Cloud Console and/or GitHub with permissions to create OAuth applications.
+ 
+## Configure OAuth for Google
+
+Follow these steps to set up OAuth with Google:
+
+1. Follow Google's official guide on [Setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849?hl=en) to create your OAuth 2.0 client ID and client secret.
+- Create the Flagsmith on Flagsmith flag as detailed in the [deployment documentation](/deployment-self-hosting/core-configuration/environment-variables#oauth-google).
+
+## Configure OAuth for GitHub
+
+As a pre-requisite for this configuration make sure to have [Flagsmith on Flagsmith](/deployment-self-hosting/core-configuration/running-flagsmith-on-flagsmith) set up. Follow these steps to set up OAuth with GitHub:
+
+1. Configure the following environment variables:
+    - `GITHUB_CLIENT_ID`
+    - `GITHUB_CLIENT_SECRET`
+
+2. Configure OAuth for GitHub:
+    - [Create an OAuth GitHub application](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app)
+    - For the Authorization callback URL use: `https://<your flagsmith domain name>/oauth/github`
+3. Create the Flagsmith on Flagsmith flag as it shows [here](/deployment-self-hosting/core-configuration/environment-variables#oauth-github).
+
+Now you would be able to see the GitHub SSO option.
+
+<div style={{textAlign: 'center'}}><img width="75%" src="/img/Flagsmith_GitHub_SignUp.png"/></div>
+
+## See Also
+
+- [Flagsmith Deployment Documentation](/deployment-self-hosting/core-configuration/running-flagsmith-on-flagsmith): For detailed information on setting up "Flagsmith on Flagsmith" and related configurations.
+- [SAML SSO](/administration-and-security/access-control/saml): For information on configuring SAML-based SSO.

docs/docs/administration-and-security/access-control/okta.md

@@ -0,0 +1,33 @@
+---
+title: Okta
+sidebar_label: Okta
+sidebar_position: 30
+---
+
+Flagsmith can integrate with Okta single sign-on (SSO) by using SAML. We provide a first-party Okta integration to simplify the setup. This guide explains how to integrate Flagsmith with Okta SSO.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- Access to your Flagsmith organisation with permissions to create and manage SAML configurations.
+- An Okta account with administrative access to add and configure applications.
+
+
+## Configure Okta SSO
+
+Follow these steps to set up the Flagsmith Okta integration:
+
+1. Create a [Flagsmith SAML configuration](/administration-and-security/access-control/saml#setup). You can leave the identity provider metadata blank for now.
+2. Add the [Flagsmith Okta integration](https://www.okta.com/integrations/flagsmith/) to your Okta account, and open  it in the Okta dashboard.
+3. Select the "Sign On" tab, and click "Edit".
+4. Under "Advanced Sign-on Settings", fill out these fields and then click Save:
+   - **API Base URL** should be `https://api.flagsmith.com` on SaaS, or your API root URL otherwise.
+   - **SAML Organisation** should be the name of the SAML configuration you previously created.
+5. Staying on the "Sign On" tab, find the "Metadata URL" in the "Sign on methods" section. Save this metadata to a file and upload it to the "IdP Metadata XML" of your Flagsmith SAML configuration.
+
+Once your Flagsmith SAML configuration has your Okta IdP metadata set, your users can log in to Flagsmith with Okta by clicking "Single Sign-On" at the login page, and typing the name of the SAML configuration you created.
+
+## User attributes
+
+By default, the Flagsmith Okta integration will map your users' Okta email address, given name and surname so that they are visible within Flagsmith. If you need to map different attributes, you can [customise the attribute mappings](/administration-and-security/access-control/saml#attribute-mapping) on your SAML configuration.