From 054dfda73f3e4df53840f24667876805e8680e5e Mon Sep 17 00:00:00 2001 From: Dewi Roberts Date: Mon, 26 May 2025 13:23:40 +0100 Subject: [PATCH] website/integrations: add push security (#14429) * Updates integrations sidebar and adds push security doc. WIP * Partially added push instructions * Added final instructions * Fixed broken link * Added few lines and changed formatting. * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Added note about login from push login URL, and added suggestions from Dominic * Applied suggestions from Dominic * Fixed verification cert line * Added note to recommend users follow the extra verificaton step * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Co-authored-by: Dominic R Signed-off-by: Dewi Roberts * Update website/integrations/services/push-security/index.mdx Signed-off-by: Tana M Berry * Update website/integrations/services/push-security/index.mdx Signed-off-by: Tana M Berry * Update website/integrations/services/push-security/index.mdx Signed-off-by: Tana M Berry * Update website/integrations/services/push-security/index.mdx Signed-off-by: Tana M Berry * Update website/integrations/services/push-security/index.mdx Signed-off-by: Tana M Berry * Update website/integrations/services/push-security/index.mdx Signed-off-by: Tana M Berry * Update website/integrations/services/push-security/index.mdx Signed-off-by: Tana M Berry * Update website/integrations/services/push-security/index.mdx Signed-off-by: Tana M Berry * moved resouces section to end of document --------- Signed-off-by: Dewi Roberts Signed-off-by: Tana M Berry Co-authored-by: Dominic R Co-authored-by: Tana M Berry --- .../services/push-security/index.mdx | 129 ++++++++++++++++++ website/sidebars/integrations.mjs | 1 + 2 files changed, 130 insertions(+) create mode 100644 website/integrations/services/push-security/index.mdx diff --git a/website/integrations/services/push-security/index.mdx b/website/integrations/services/push-security/index.mdx new file mode 100644 index 0000000000..20b006d18a --- /dev/null +++ b/website/integrations/services/push-security/index.mdx @@ -0,0 +1,129 @@ +--- +title: Integrate with Push Security +sidebar_label: Push Security +support_level: community +--- + +## What is Push Security + +> Push Security is a browser-based identity security platform that hardens and monitors your identity attack surface. Security teams can monitor and secure their entire identity attack surface (ISPM) and detect and block identity-based attacks (ITDR) such as advanced phishing techniques. +> +> -- https://pushsecurity.com/ + +## Preparation + +The following placeholders are used in this guide: + +- `authentik.company` is the FQDN of the authentik installation. + +:::note +This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. +::: + +## authentik configuration + +To support the integration of Push Security, you need to create property mappings and an application/provider pair in authentik. + +### Create property mappings + +Push Security requires separate first and last names for each user, but authentik provides the full name as a single string. To address this, create property mappings that split the full name into first and last names. + +1. Log in to authentik as an administrator, and open the authentik Admin interface. +2. Navigate to **Customization** > **Property Mappings** and click **Create**. + + - **Select type**: select **SAML Provider Property Mapping** as the property mapping type. + - **Configure the SAML Provider Property Mapping**: + + - **Name**: `givenname` + - **SAML Attribute Name**: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` + - **Expression**: + + ```python + return request.user.name.rsplit(" ", 1)[0] + ``` + +3. Click **Finish**. +4. Click **Create** to create the second property mapping. + + - **Select type**: select **SAML Provider Property Mapping** as the property mapping type. + - **Configure the SAML Provider Property Mapping**: + + - **Name**: `familyname` + - **SAML Attribute Name**: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` + - **Expression**: + + ```python + return request.user.name.rsplit(" ", 1)[-1] + ``` + +5. Click **Finish**. + +### Create an application and provider in authentik + +1. Log in to authentik as an admin, and open the authentik Admin interface. +2. Navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) + + - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. + - Take note of the application slug as it will be required later on. + - **Choose a Provider type**: select **SAML Provider** as the provider type. + - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. + - Temporarily set the **ACS URL** and **Audience** to `https://temp.temp` + - Set the **Service Provider Binding** to `Post`. + - Under **Advanced protocol settings**: + - Set an available signing certificate. + - **Property mappings**: + - Under **Selected User Property Mappings**, add the `givenname` and `familyname` property mappings created in the previous section. + +- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page. + +3. Click **Submit**. + +### Download the signing certificate + +1. Log into authentik as an administrator, and open the authentik Admin interface. +2. Navigate to **Applications** > **Providers** and click on the name of the newly created Push Security provider. +3. Click **Download** under **Download signing certificate**. The contents of this certificate will be required in the next section. + +## Push Security configuration + +1. Log in to the [Push Security administrator console](https://pushsecurity.com). +2. Go to **Settings** > **Organization**, then under **SAML Configuration**, click **Setup**. +3. Click **Get Started**, select **Custom SAML**, and click **Next**. +4. Copy both the **Single Sign-On URL** and the **Service Provider Entity URL**. You’ll need these values in the next section. +5. Click **Next**. +6. Choose **Manual**, and enter the following as the **Single Sign-On Login URL**: `https://authentik.company/application/saml//sso/binding/post/` +7. Click **Upload signing certificate**, and upload the certificate downloaded from authentik. +8. _(Optional but recommended)_ Under **Advanced Settings**, enable **Sign request**. Then download the verification certificate. You’ll need to import this into authentik. Refer to the [authentik certificate documentation](../../../docs/sys-mgmt/certificates#external-certificates) for guidance. +9. Click **Next**. +10. On the **Attribute Mapping** page, click **Next** without making changes. +11. Leave the **Test SSO** page open. You’ll return to it after completing the next section. + +## Reconfigure authentik provider + +1. Log in to authentik as an administrator, and open the authentik Admin interface. +2. Navigate to **Applications** > **Providers**, then find the newly created Push Security provider and click its **Edit** icon. +3. Under **Protocol settings**, set the following required configurations: + - **ACS URL**: set to the **Single Sign-On URL** copied from the previous section (e.g., `https://login.pushsecurity.com/login/callback?connection=saml-aaa...`). + - **Audience**: set to the **Service Provider Entity URL** copied from the previous section (e.g., `urn:auth0:production-pushsecurity:saml-aaa...`). + - _(Optional but recommended)_ add the verification certificate downloaded from Push Security in the previous section. +4. Click **Update**. + +## Verify Push Security configuration + +1. Return to the Push Security **Test SSO** page. +2. Click **Test Connection** and you should be redirected to the authentik login screen. +3. Enter your authentik credentials and log in. +4. If successful you will be redirected to Push Security and see a **Testing complete!** message. +5. On the **Test SSO** page, click **Enable Connection**. + +:::note +To enable users to enter their email on the Push Security login screen and be redirected to authentik, you will need to contact Push Security to enable the feature. This can be done from the Push Security admin console via **Settings** > **Organization** > **SAML Configuration**. +::: + +## Configuration verification + +To confirm that authentik is properly configured with Push Security, navigate to the authentik dashboard, and click on the Push Security application. You should be redirected to the Push Security admin console. + +## Resources + +- [Push Security SAML SSO Documentation](https://pushsecurity.com/help/10123#start) diff --git a/website/sidebars/integrations.mjs b/website/sidebars/integrations.mjs index 39a16afe12..7bbb75e6d1 100644 --- a/website/sidebars/integrations.mjs +++ b/website/sidebars/integrations.mjs @@ -95,6 +95,7 @@ const items = [ "services/plesk/index", "services/powerdns-admin/index", "services/proftpd/index", + "services/push-security/index", "services/qnap-nas/index", "services/rustdesk-pro/index", "services/semgrep/index",