diff --git a/website/integrations/services/phpipam/index.md b/website/integrations/services/phpipam/index.md new file mode 100644 index 000000000..a9a54d209 --- /dev/null +++ b/website/integrations/services/phpipam/index.md @@ -0,0 +1,214 @@ +--- +title: phpIPAM +--- + +Support level: Community + +## What is phpIPAM + +From https://phpipam.net/ + +:::note +phpipam is an open-source web IP address management application (IPAM). Its goal is to provide light, modern and useful IP address management. It is php-based application with MySQL database backend, using jQuery libraries, ajax and HTML5/CSS3 features. +::: + +## Preparation + +The following placeholders will be used: + +- `phpipam.company` is the FQDN of the phpipam. +- `authentik.company` is the FQDN of the authentik installation. +- `test-user[0-2]` in place of actual usernames +- `admin-permission-group` in place of your company naming convention +- `operator-permission-group` in place of your company naming convention +- `guest-permission-group` in place of your company naming convention + +:::note +This is based on authentik 2023.3.1 and phpIPAM 1.5.2 +Only settings that have been modified from default have been listed. +::: + +## authentik Configuration + +### Step 1 - User and Group creation + +You need to ensure users and groups exist before we proceed with the next steps. + +The groups are used for property mappings later to give the user the correct permission level in the application. For this documentation there is an example for each of the 3 main default permission levels and an easy way to visualise the differences between them. + +1. **Create test-user 0** + + - username: test-user0 + - Name: Test User0 + - Email: test-user0@domain.company + - path: users + +2. **Create test-user 1** + + - username: test-user1 + - Name: Test User1 + - Email: test-user1@domain.company + - path: users + +3. **Create test-user 2** + + - username: test-user2 + - Name: Test User2 + - Email: test-user2@domain.company + - path: users + +4. **Create all required groups (under _Directory/Groups_)** + + - admin-permission-group + - operator-permission-group + - guest-permission-group + +5. **Assign groups to users for testing** + + - admin-permission-group + - Select Directory -> Groups + - Select `admin-permission-group` + - Select Add Existing user + - Select test-user0 + - operator-permission-group + - Select Directory -> Groups + - Select `operator-permission-group` + - Select Add Existing user + - Select test-user1 + - guest-permission-group + - Select Directory -> Groups + - Select `guest-permission-group` + - Select Add Existing user + - Select test-user2 + +### Step 2 - Property Mapping creation + +In order to support automatic user provisioning (JIT) with phpIPAM, additional SAML attributes need to be passed. See [phpipam docs](https://github.com/phpipam/phpipam/blob/master/doc/Authentication/SAML2.md#automatic-user-jit-provisioning) for more details about specific attributes to pass. + +- Select Property Mappings +- Select Create -> SAML Property Mapping -> Next + +1. display_name + + - Name: phpipam-display-name + - SAML Attribute Name: display_name + - Expression: + + ```python + return user.name + ``` + +2. email + + - Name: phpipam-email + - SAML Attribute Name: email + - Expression: + + ```python + return user.email + ``` + +3. is_admin + + - Name: phpipam-is-admin + - SAML Attribute Name: is_admin + - Expression: + + ```python + return ak_is_group_member(request.user, name="admin-permission-group") + ``` + +4. groups + + - Name: phpipam-groups + - SAML Attribute Name: groups + - Expression: + + ```python + if ak_is_group_member(request.user, name="operator-permission-group"): + return "Operators" + elif ak_is_group_member(request.user, name="guest-permission-group"): + return "Guests" + ``` + +5. modules + - Name: phpipam-modules + - SAML Attribute Name: modules + - Expression: + ```python + if ak_is_group_member(request.user, name="operator-permission-group"): + return "*:2" + elif ak_is_group_member(request.user, name="guest-permission-group"): + return "*:1" + ``` + +![](./phpipam-property-mappings.png) + +### Step 3 - Provider creation + +- Select Create -> SAML Provider + - Name: phpipam-saml + - Authorization flow: `default-provider-authorization-explicit-consent` + - Protocol Settings: + - ACS URL: https://phpipam.company/saml2/ + - Issuer: https://authentik.company + - Service Provider Binding: Post + - Audience: https://phpipam.company/ + - Advanced Protocol Settings: + - Signing Certificate: authentik: Self-signed Certificate + - Verification certificate: Leave Blank + - Property Mappings: Select All Available + - NameID Property Mapping: authentik default SAML Mapping: Username + +![](./phpipam-saml-provider-protocol-settings.png) +![](./phpipam-saml-advanced-provider-protocol-settings.png) + +### Step 4 - Application creation + +Select Create + +- Name: phpipam-saml +- Provider: phpipam-saml + +Edit Policy Bindings to only allow users who have the groups assigned to them, access to login. Without this, any user can login and be given default no permissions in phpIPAM. + +Select ipam-saml application + +- Select Policy / Group / User Bindings + - Add `admin-permission-group` + - Add `operator-permission-group` + - Add `guest-permission-group` + +Leave all other settings as default +![](./ipam-saml-application-bindings.png) + +## phpIPAM Configuration + +Login as the local administrator account at `phpipam.company` +Select Authentication Methods +Select Create New -> SAML2 Authentication + +- Description: authentik +- Enable JIT: On +- Use advanced settings: Off +- Client ID: https://phpipam.company/ +- Strict Mode: Off +- IDP Issuer: https://authentik.company +- IDP Login url: https://authentik.company/application/saml//sso/binding/redirect/ +- IDP Logout url: https://authentik.company/application/saml//slo/binding/redirect/ +- IDP X.509 public cert: This will be the .pem contents of the cert used as the signing certificate + 1. To get this cert, access the authentik installation at authentik.company + 2. Select Applications -> Providers -> phpipam-saml + 3. Select Download signing certificate + 4. Paste in the contents of the signing certificate into if IDP X.509 field +- Sign Authn requests: Off + +Leave everything else as default. Save changes +![](./phpipam-auth-method-config.png) + +### Test login + +![](./ipam-saml2-login-location.png) +Browse to `phpipam.company`, select the SAML2 login hyperlink (or access directly from the authentik application menu) +From here, you should be able to login as each of the test-users and see the affects the saml attributes has with the permissions set. These can be fine tuned as needed by following the phpipam documentation, but should be enough to get a basic permissive installation working with authentik as the SAML provider. +![](./phpipam-automatic-user-creation-permissions.png) diff --git a/website/integrations/services/phpipam/ipam-saml-application-bindings.png b/website/integrations/services/phpipam/ipam-saml-application-bindings.png new file mode 100644 index 000000000..c56db64a1 Binary files /dev/null and b/website/integrations/services/phpipam/ipam-saml-application-bindings.png differ diff --git a/website/integrations/services/phpipam/ipam-saml2-login-location.png b/website/integrations/services/phpipam/ipam-saml2-login-location.png new file mode 100644 index 000000000..b92824c29 Binary files /dev/null and b/website/integrations/services/phpipam/ipam-saml2-login-location.png differ diff --git a/website/integrations/services/phpipam/phpipam-auth-method-config.png b/website/integrations/services/phpipam/phpipam-auth-method-config.png new file mode 100644 index 000000000..b3213af65 Binary files /dev/null and b/website/integrations/services/phpipam/phpipam-auth-method-config.png differ diff --git a/website/integrations/services/phpipam/phpipam-automatic-user-creation-permissions.png b/website/integrations/services/phpipam/phpipam-automatic-user-creation-permissions.png new file mode 100644 index 000000000..c3de1aa09 Binary files /dev/null and b/website/integrations/services/phpipam/phpipam-automatic-user-creation-permissions.png differ diff --git a/website/integrations/services/phpipam/phpipam-property-mappings.png b/website/integrations/services/phpipam/phpipam-property-mappings.png new file mode 100644 index 000000000..c628bc458 Binary files /dev/null and b/website/integrations/services/phpipam/phpipam-property-mappings.png differ diff --git a/website/integrations/services/phpipam/phpipam-saml-advanced-provider-protocol-settings.png b/website/integrations/services/phpipam/phpipam-saml-advanced-provider-protocol-settings.png new file mode 100644 index 000000000..1eca5555e Binary files /dev/null and b/website/integrations/services/phpipam/phpipam-saml-advanced-provider-protocol-settings.png differ diff --git a/website/integrations/services/phpipam/phpipam-saml-provider-protocol-settings.png b/website/integrations/services/phpipam/phpipam-saml-provider-protocol-settings.png new file mode 100644 index 000000000..d07f79563 Binary files /dev/null and b/website/integrations/services/phpipam/phpipam-saml-provider-protocol-settings.png differ diff --git a/website/sidebarsIntegrations.js b/website/sidebarsIntegrations.js index c2f32ab2c..7c67211b4 100644 --- a/website/sidebarsIntegrations.js +++ b/website/sidebarsIntegrations.js @@ -68,6 +68,7 @@ module.exports = { "services/opnsense/index", "services/pfsense/index", "services/pgadmin/index", + "services/phpipam/index", "services/powerdns-admin/index", "services/qnap-nas/index", "services/skyhigh/index",