External authentication and role-based access control

Overview

F5 Insight supports external authentication, enabling enterprise customers to integrate with their existing identity infrastructure for centralized user management and secure access control.

Previous releases called the built-in System admin account the Local admin account. F5 Insight now supports external authentication, so users can log in with identity-provider credentials and role-based access control.

Known authentication issues

Important

If there’s any risk of username collisions, don’t use local and external users together. Keep external usernames distinct from all local usernames.

Don’t use admin as the username for an external account. F5 Insight always assigns Admin to admin, regardless of remote role mappings. You can’t assign Operator or Viewer to that username.

When a local and an external username collide, you can no longer manage the local user or reset the local password. For example, after an external admin login, the local admin account disappears from the user list.

For Microsoft Active Directory (AD), the full user principal name (UPN) is a workaround to avoid collisions with local usernames. Verify that the UPN doesn’t match a local username. See Configure Active Directory.

Note

Reset Password appears for all users, including external users, but password resets apply only to local users. Manage external passwords through your identity provider.

What’s new

Feature Description
External Authentication Authenticate users via corporate LDAP or SAML identity providers
Supported LDAP Providers OpenLDAP, Microsoft Active Directory (AD)
Supported SAML Providers Ping, Okta
Role-Based Access Control (RBAC) Three predefined roles - Admin, Operator, Viewer - controlling access to features and API endpoints
Role Mapping Map external identity provider groups to F5 Insight roles

Authentication methods

F5 Insight supports four authentication methods: System, Local, Machine users, and External. Previous releases called System mode Local mode.

System authentication

System authentication uses the built-in administrator account created during installation. The System admin account can use the UI and API. Treat this account as root-level.

Attribute Details
Username admin
Password Configured during system setup (SSH password)
Access Level Full administrator access
Access scope UI and API, with root-level system privileges
Limitation Single user only; no role differentiation

Important

Use System authentication only for system-level tasks. The admin account has root-level privileges. Only the System admin account can transfer files with SCP, use SSH, or use the serial console. Use this account for break/fix and troubleshooting.

Local authentication

Local authentication uses the Insight authentication service to manage human users and roles. Local users can use the UI only. Use Local or External authentication for routine access instead of the System account.

Attribute Details
Authentication service Insight authentication service
Access scope UI only, controlled by application roles
More information Local authentication and role-based access control

Machine users

Machine users use service credentials for API and automation access. Machine users can use the API only. For details, see Machine users.

External authentication

External authentication uses credentials managed by a corporate identity provider. External users can use the UI only. Role mapping controls their application-level permissions.

Provider Type Supported Providers Protocol Description
LDAP OpenLDAP, Microsoft Active Directory LDAP v3 Directory-based authentication using LDAP credentials
SAML Ping, Okta SAML 2.0 Single Sign-On (SSO) authentication via SAML identity providers

Note

Custom identity provider implementations outside of the supported LDAP (OpenLDAP, Microsoft Active Directory) and SAML (Ping, Okta) providers are not supported in this release.

Login flows

Login screen

After an external authentication provider is configured and activated, the F5 Insight login screen displays additional log-in options:

  • Local Login: Username and password fields for UI access. Use the System admin account in System mode or a local user in Local mode.
  • External Login: One or more buttons labeled “Sign in with <Provider Name>” for each configured external provider.

The provider name displayed on the login screen corresponds to the name configured by the administrator during provider setup. Machine users authenticate through the API and don’t use the login screen.

Local user login

  1. Navigate to the F5 Insight login page (https://<f5-insight-ip>).
  2. Enter the local username and password.
  3. Select Sign In.
  4. Upon successful authentication, you are redirected to the F5 Insight dashboard.

LDAP login

See LDAP login in the LDAP authentication guide.

SAML login

See SAML login in the SAML authentication guide.

Note

By default, remote authentication uses an IP address for login page links and external auth endpoints. Use f5insight-set-fqdn to set a stable hostname instead. Using an FQDN is recommended for TLS certificate hostname validation, better user experience (friendly login URLs), and stable identity across IP changes. For more information, see Remote Authentication FQDN.

Session management

Behavior Details
Access Token Expiry Tokens expire after 5 minutes
Automatic Refresh Tokens are refreshed automatically in the background. No user action required
Session Timeout If token refresh fails, you are redirected to the login page
Logout Select the logout option to end your session

Note

Access tokens are stored in browser memory only and are never persisted to local storage, ensuring enhanced security.

Configuring identity providers (administrator only)

Important

You must be logged in as an Admin user to configure identity providers.

LDAP

The LDAP provider supports these directories:

  • OpenLDAP
  • Microsoft Active Directory

For setup, certificates, and troubleshooting, see LDAP authentication.

SAML

The SAML provider supports these identity providers:

  • Okta
  • Ping

For shared provider settings and the Okta procedure, see SAML authentication.

Managing identity providers

Action Steps
View Providers Navigate to Settings > User Administration > SSO Identity Providers to view all configured providers
Activate Provider Select Activate on a configured provider to enable it on the login page
Deactivate Provider Select Deactivate to remove the provider from the login page without deleting the configuration
Edit Provider Select the provider and update the configuration fields, then select Save Changes
Delete Provider Select the provider and select Delete to remove the configuration
Test Provider Use the Validate option to test the provider configuration before activating

For LDAP connection testing and validation, see LDAP authentication.

API configuration

Identity providers can also be managed using the F5 Insight REST API.

Identity Provider Endpoints

Method Endpoint Description
GET /auth/identity-providers List all configured identity providers
POST /auth/identity-providers/ldap Create a new LDAP provider
POST /auth/identity-providers/saml Create a new SAML provider
GET /auth/identity-providers/{id} Get details of a specific provider
PUT /auth/identity-providers/ldap/{id} Update an LDAP provider
PUT /auth/identity-providers/saml/{id} Update a SAML provider
DELETE /auth/identity-providers/{id} Delete a provider
POST /auth/identity-providers/{id}/activate Activate a provider
POST /auth/identity-providers/{id}/deactivate Deactivate a provider
POST /auth/identity-providers/validate Test a provider configuration

Note

Refer to the F5 Insight API Documentation for detailed request/response schemas, payload examples, and authentication requirements.

Role-Based Access Control (RBAC)

F5 Insight enforces Role-Based Access Control (RBAC) to manage what each user can access and perform within the platform.

Predefined roles

Role Description Access Level
Admin Full system access including user management, device configuration, and all settings Full read/write access to all features and API endpoints
Operator Device configuration and troubleshooting Read/write access to devices, provisioning, telemetry, and system management. No access to User Administration
Viewer Read-only access for monitoring and observation View-only access to dashboards, devices, and configurations. Cannot add, edit, or delete resources

Role permissions matrix

Admin Role - Full Access

Feature Area GET POST PUT/PATCH DELETE
Device Management Yes Yes Yes Yes
Telemetry Yes Yes Yes Yes
AI Integrations Yes Yes Yes Yes
Provisioning Yes Yes Yes Yes
System Management Yes Yes Yes Yes
License Management Yes Yes Yes Yes
User Management Yes Yes Yes Yes
Dashboards Yes Yes
Audit Console Yes Yes
Chat Management Yes Yes Yes Yes

Operator Role - Operational Access

Feature Area GET POST PUT/PATCH DELETE
Device Management Yes Yes Yes No
Telemetry Yes Yes Yes No
AI Integrations Yes Yes PUT only No
Provisioning Yes Yes PUT only No
System Management Yes Yes No No
License Management No No No No
User Management No No No No
Dashboards Yes Yes
Audit Console No No No No
Chat Management Yes Yes Yes No

Viewer Role - Read-Only Access

Feature Area GET POST PUT/PATCH DELETE
Device Management Yes No No No
Telemetry Yes No No No
AI Integrations Yes No No No
Provisioning Yes No No No
System Management Yes No No No
License Management Yes No No No
User Management No No No No
Dashboards Yes Yes
Audit Console No No No No
Chat Management No No No No

Role assignment

Important

Previously, external users were automatically assigned Viewer when no role was found. F5 Insight now blocks access instead. To grant read-only access, explicitly map a group to Viewer.

Scenario Assigned Role
Local admin user Always Admin
External user with the username admin Always Admin, regardless of remote role mappings
External user with a matching group attribute Role as per group-to-role mapping (Admin, Operator, or Viewer)
External user with no group attribute configured No role; access denied
External user with no matching group-to-role mapping No role; access denied

UI access by role

Feature / Section Admin Operator Viewer
Dashboards View - Yes View - Yes View - Yes
Devices - View Yes Yes Yes
Devices - Add/Edit/Delete Yes Add/Edit - Yes, Delete - No No
User Administration Yes No No
System Settings Yes Yes (limited) View-only / limited
AI Chat Yes Yes No / view-only if UI allows history
F5 Insight Upgrade Yes No No

Role mapping (administrator only)

Role mapping determines which F5 Insight role an external user receives upon login. Roles are assigned based on group attributes configured on the LDAP or SAML identity provider.

Navigate to Settings > User Administration > Role > Role Mapping

How role mapping works

  1. Configure group membership in your LDAP directory or group attributes in your SAML identity provider.
  2. When an external user logs in, F5 Insight resolves LDAP group memberships or reads the SAML group values from the authentication response.
  3. F5 Insight matches the resolved group names or asserted values to configured role mappings (Admin, Operator, or Viewer).
  4. The user receives access based on the mapped role. If no role is found, access is blocked instead of defaulting to Viewer.

The username admin is an exception to role mapping. See Known authentication issues.

Configuring role mapping

  1. Log in to F5 Insight as an administrator.

  2. Navigate to Settings > User Administration > Role > Role Mapping.

  3. Select the configured identity provider (LDAP or SAML).

  4. In Grouped Resource Attribute, enter the group value to match:

    • OpenLDAP: Enter the exact group CN, such as f5-admin. Matching is case-sensitive. The cn= prefix is optional, and anything after the first comma is ignored.
    • Active Directory: Enter the exact group CN, such as F5 Admins. Matching is case-sensitive. The cn= prefix is optional, and anything after the first comma is ignored.
    • SAML: Enter the exact asserted group or role value, such as admins from the groups attribute. Enter the value, not the attribute name. Matching is case-sensitive. LDAP prefix and comma handling don’t apply to SAML values.

  5. Map the group value to an F5 Insight role:

IdP Group Attribute Value F5 Insight Role
(configured by admin, example, f5-admin) Admin
(configured by admin, example, f5-operator) Operator
(configured by admin, example, f5-viewer) Viewer
(no attribute or unmatched value) No role; access denied
  1. Select Save.

Modifying or deleting role mappings

Action Steps Impact
Modify Mapping Navigate to Role Mapping, update the group attribute or role assignment, select Save. Changes take effect on the user’s next login
Delete Mapping Select the mapping, select Delete Mapping Users without another matching role mapping are denied access on their next login

Troubleshoot external access denied

If an external user cannot access F5 Insight because no role is found:

  1. Verify that the user belongs to a group mapped to an F5 Insight role. Map the group to Viewer if read-only access is required.
  2. For OpenLDAP or AD, compare the group CN and its exact casing with Grouped Resource Attribute. The cn= prefix is optional, and anything after the first comma is ignored. For AD, check the user’s memberOf values.
  3. For OpenLDAP without memberOf memberships, verify the ou=groups,<BASE_DN> search base and the member or memberUid membership values. Use your configured Base DN for <BASE_DN>. If the search base doesn’t exist, review the group-base warning.
  4. For SAML, verify that the asserted groups or memberOf value matches the configured role mapping.
  5. For LDAP or AD, use Test Connection to check connectivity and configuration. If an operation times out, check directory reachability and server responsiveness.

Role mapping API endpoints

In this release, roles are read-only: GET /auth/roles and GET /auth/roles/{role_id}. No create role, update role, or edit permissions APIs.

Method Endpoint Description
GET /auth/roles List all available roles
POST /auth/roles Create a custom role (not available in this release)
GET /auth/roles/{role_id} Get role details and permissions
PUT /auth/roles/{role_id} Update a role
PUT /auth/roles/{role_id}/permissions Update role permissions

Checking your permissions

Any authenticated user can check their current permissions using the UI or API.

Viewing your permissions

Your assigned role and permissions are visible in the UI based on the features and actions available to you.

Use the following API endpoints to programmatically check your permissions:

Method Endpoint Description
GET /auth/me/permissions View your current role and permissions
POST /auth/permissions/check Check if you have permission for a specific action

Understanding access denied responses

HTTP Status Code Meaning Action
401 Unauthorized Your session has expired or your token is invalid Log in again
403 Forbidden You do not have permission to perform this action Contact your administrator to request the appropriate role