diff --git a/.github/vale/dicts/aiven.dic b/.github/vale/dicts/aiven.dic index a3b44e17d4..bf5df58e5d 100644 --- a/.github/vale/dicts/aiven.dic +++ b/.github/vale/dicts/aiven.dic @@ -12,6 +12,7 @@ APIs ARN Astacus Auth0 +autojoin autovacuum Avro AZ @@ -73,6 +74,7 @@ failover fileset filesets Flink +FusionAuth Gantt geocoder geocoding diff --git a/.github/vale/styles/Aiven/capitalization_headings.yml b/.github/vale/styles/Aiven/capitalization_headings.yml index 2660de9b45..0e2c76fd60 100644 --- a/.github/vale/styles/Aiven/capitalization_headings.yml +++ b/.github/vale/styles/Aiven/capitalization_headings.yml @@ -41,6 +41,7 @@ exceptions: - Elasticsearch - European Union - Flink + - FusionAuth - GiB - GitHub - Go diff --git a/_toc.yml b/_toc.yml index 7a9135def9..1e548ef26a 100644 --- a/_toc.yml +++ b/_toc.yml @@ -134,16 +134,18 @@ entries: title: SAML Authentication entries: - file: docs/platform/howto/saml/saml-authentication - - file: docs/platform/howto/saml/setup-saml-onelogin - title: Setting up SAML with OneLogin - - file: docs/platform/howto/saml/setup-saml-azure - title: Setting up SAML with Azure - - file: docs/platform/howto/saml/setup-saml-okta - title: Setting up SAML with Okta - file: docs/platform/howto/saml/setup-saml-auth0 title: Setting up SAML with Auth0 + - file: docs/platform/howto/saml/setup-saml-azure + title: Setting up SAML with Azure + - file: docs/platform/howto/saml/setup-saml-fusionauth + title: Setting up SAML with FusionAuth - file: docs/platform/howto/saml/setup-saml-jumpcloud title: Setting up SAML with JumpCloud + - file: docs/platform/howto/saml/setup-saml-okta + title: Setting up SAML with Okta + - file: docs/platform/howto/saml/setup-saml-onelogin + title: Setting up SAML with OneLogin - file: docs/platform/howto/list-support title: Support entries: diff --git a/docs/platform/howto/saml/saml-authentication.rst b/docs/platform/howto/saml/saml-authentication.rst index 6463e6e839..0a5e32d265 100644 --- a/docs/platform/howto/saml/saml-authentication.rst +++ b/docs/platform/howto/saml/saml-authentication.rst @@ -15,10 +15,11 @@ To set up a SAML authentication method for your organization in Aiven, there are Setup instructions for specific providers are available on the following pages: -* :doc:`Set up SAML with OneLogin ` +* :doc:`Set up SAML with Auth0 ` +* :doc:`Set up SAML with FusionAuth ` * :doc:`Set up SAML with Microsoft Azure Active Directory ` * :doc:`Set up SAML with Okta ` -* :doc:`Set up SAML with Auth0 ` +* :doc:`Set up SAML with OneLogin ` If your provider isn't listed, contact us at support@Aiven.io so we can assist you with the configuration. diff --git a/docs/platform/howto/saml/setup-saml-fusionauth.rst b/docs/platform/howto/saml/setup-saml-fusionauth.rst new file mode 100644 index 0000000000..0df5730b00 --- /dev/null +++ b/docs/platform/howto/saml/setup-saml-fusionauth.rst @@ -0,0 +1,135 @@ +Set up SAML authentication with FusionAuth +========================================== + +This article explains how to set up SAML with `FusionAuth `_ for an organization in Aiven. For more information on SAML and instructions for other identity providers, see the :doc:`Set up SAML authentication ` article. + +Prerequisite steps in Aiven Console +------------------------------------ + +#. In the organization, click **Admin**. + +#. Select **Authentication**. + +#. Click **Add authentication method**. + +#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method. + +#. Click **Add method**. + +You are shown two parameters needed to set up the SAML authentication in FusionAuth: + +* Metadata URL +* ACS URL + +Configure SAML on FusionAuth +---------------------------- + +The setup on FusionAuth has three parts: + +* create an API key +* generate a custom RSA certificate +* create an application + +First you need to create an API Key in your FusionAuth instance: + +#. In FusionAuth, go to **Settings** > **API Keys**. + +#. Click the **Add** icon. + +#. Enter a description for the key (for example, "Certificate generator"). + +#. In the **Endpoints** list, find ``/api/key/import``. + +#. Toggle on **POST**. + +#. Click the **Save** icon. + + .. image:: /images/platform/howto/saml/fusionauth/create-api-key.png + :alt: Creating API Key. + +#. On the **API Keys** page, find your new key and click on the value in the **Key** column. + +#. Copy the whole key. You’ll use this for the script. + + .. image:: /images/platform/howto/saml/fusionauth/grab-api-key.png + :alt: Grabbing API Key. + +#. Clone `the FusionAuth example scripts GitHub repository `__. + + .. code:: shell + + git clone git@github.com:FusionAuth/fusionauth-example-scripts.git + cd fusionauth-example-scripts/v3-certificate + +#. Run the ``generate-certificate`` script. + + .. code:: shell + + ./generate-certificate + +#. Give the key a meaningful name (for example, "Aiven key"). + +#. Copy the generated certificate that the script creates. You now have a certificate in the **Key Master** in your FusionAuth instance. + +Next, create an application in your FusionAuth instance: + +#. In **Applications**, click the **Add** icon. + +#. Enter a name for the application (for example, "Aiven"). + +#. On the **SAML** tab, and toggle on the **Enabled** switch. + +#. Paste the **Metadata URL** and **ACS URL** you copied from the Aiven Console to the **Issuer** and +**Authorized redirect URLs** fields in your FusionAuth application, respectively. + +.. list-table:: + :header-rows: 1 + :align: left + + * - Aiven + - FusionAuth + * - Metadata URL + - Issuer + * - ACS URL + - Authorized redirect URLs + +#. In the **Authentication response** section, change the **Signing key** to the API key you created. + +#. Click the **Save** icon to save your application. + +#. On the **Applications** page, click the magnifying glass. + +#. In the **SAML v2 Integration details** section, copy the **Entity Id** and **Login URL**. + +Finish the configuration in Aiven +--------------------------------- + +Go back to the **Authentication** page in `Aiven Console `_ to enable the SAML authentication method: + +1. Select the name of the FusionAuth method that you created. + +2. In the SAML configuration section, click **Edit**. + +3. Toggle on **IdP login**. + +4. Add the configuration settings from FusionAuth: + +* Set the ``SAML IDP Url`` to the ``Login URL`` from FusionAuth. +* Set the ``SAML Entity ID`` to the ``Entity Id`` from FusionAuth. +* Paste the certificate from the ``Generating certificate`` in FusionAuth into the `SAML Certificate`` field. + +5. Click **Edit method** to save your changes. + +6. Toggle on **Enable authentication method** at the top of the page. + +You can use the **Signup URL** to invite new users, or the **Account link URL** for those that already have an Aiven user account. + + +.. image:: /images/platform/howto/saml/fusionauth/login-sso.png + :alt: Logging in to Aiven. + + +Troubleshooting +--------------- + +If you have issues, you can use the `SAML Tracer browser extension `_ to check the process step by step. diff --git a/images/platform/howto/saml/fusionauth/create-api-key.png b/images/platform/howto/saml/fusionauth/create-api-key.png new file mode 100644 index 0000000000..dee2df1c52 Binary files /dev/null and b/images/platform/howto/saml/fusionauth/create-api-key.png differ diff --git a/images/platform/howto/saml/fusionauth/grab-api-key.png b/images/platform/howto/saml/fusionauth/grab-api-key.png new file mode 100644 index 0000000000..24a2b62ba9 Binary files /dev/null and b/images/platform/howto/saml/fusionauth/grab-api-key.png differ diff --git a/images/platform/howto/saml/fusionauth/login-sso.png b/images/platform/howto/saml/fusionauth/login-sso.png new file mode 100644 index 0000000000..c1c1fe7d13 Binary files /dev/null and b/images/platform/howto/saml/fusionauth/login-sso.png differ