Configure remote authentication with a preferred FQDN

Overview

F5 Insight uses an external URL for browser-facing authentication redirects during LDAP and SAML login flows. By default, F5 Insight uses the appliance IP address in these redirect URLs. If users access F5 Insight through a fully qualified domain name (FQDN), you should configure that FQDN as the external URL so that login redirects and callback URLs match the address in the browser.

Starting with F5 Insight 1.2.2, you can configure the external FQDN through the UI or the REST API. The CLI script f5insight-set-fqdn is still available as a fallback option.

Using an FQDN is recommended for:

  • TLS certificate hostname validation.
  • Better user experience (friendly login URLs).
  • Stable identity across IP changes.

You can configure the external FQDN using any of the following methods:

  • CLI — configure the FQDN directly from the appliance shell using the f5insight-set-fqdn script
  • UI — configure the FQDN through the F5 Insight web interface (added in 1.2.2)
  • API — configure the FQDN programmatically through the REST API (added in 1.2.2)

Why you need to configure the external FQDN

When users access F5 Insight through an FQDN, external authentication redirects must use that same FQDN. Without this configuration, redirect URLs may use the appliance IP address instead. For example:

Without FQDN configured:

https://10.145.x.x/api/auth/callback

With FQDN configured:

https://f5insights.example.com/api/auth/callback

Using the IP address in redirect URLs can cause:

  • Browser certificate errors (the TLS certificate does not match the IP address)
  • Invalid redirect URI errors from the identity provider
  • Failed LDAP or SAML login flows

Before you begin

  • Make sure DNS resolves your FQDN to the F5 Insight appliance IP address (for example, f5insights.example.com resolves to 10.145.x.x).
  • To configure the FQDN using the CLI, you need SSH access to the F5 Insight appliance and root privileges.
  • To configure the FQDN using the UI or API, you must be logged in as an Admin user.

FQDN format requirements

The external FQDN must be a valid, fully qualified domain name that uses HTTPS. These requirements apply to all three configuration methods (CLI, UI, and API).

Accepted formats

Value you enter Normalized result
f5insights.example.com https://f5insights.example.com
https://f5insights.example.com https://f5insights.example.com
https://f5insights.example.com:8443 https://f5insights.example.com:8443
https://f5insights.example.com/ https://f5insights.example.com

If you omit the scheme, F5 Insight defaults to HTTPS. Trailing slashes are removed automatically.

Rejected formats

The following values are rejected. The FQDN must not include a path, query string, user credentials, or HTTP scheme.

Rejected value Reason
http://f5insights.example.com HTTP is not supported; use HTTPS
10.145.19.180 IP addresses are not supported
f5insights Not a fully qualified domain name
https://f5insights.example.com/login Paths are not allowed
https://f5insights.example.com?debug=true Query strings are not allowed
https://user@f5insights.example.com User credentials are not allowed
f5insights.example.com other Contains extra characters
f5insights.example.com. Trailing dot is not allowed

Important

The external FQDN configuration is HTTPS only. F5 Insight redirects HTTP browser traffic to HTTPS automatically. Do not configure the external FQDN with an http:// scheme, because this causes redirect URI mismatches during external authentication.

Expected result

After the configuration completes (regardless of which method you use), external authentication redirects use the configured FQDN instead of the appliance IP address.

Example login redirect:

https://f5insights.example.com/ui/v2/login/...

Example callback URI:

https://f5insights.example.com/api/auth/callback

Configure the external FQDN using the CLI

Use the f5insight-set-fqdn script to configure the FQDN directly from the appliance shell.

Important

Run the set command with root privileges (for example, using sudo). The command updates the authentication configuration and restarts authentication-related services.

CLI prerequisites

  • f5insight-set-fqdn is available on the system.
  • helm and kubectl are installed and in PATH.
  • Kubeconfig access to the target cluster.
  • Existing Helm release (default: f5-insight in namespace f5-insight).

Defaults used by the command (unless overridden):

  • Namespace: f5-insight
  • Helm release: f5-insight
  • URL scheme: https
  • Default port: 443
  • Helm timeout: 10m
  • Safe mode: enabled

Show current remote auth values

Use show to inspect current FQDN-related values:

sudo f5insight-set-fqdn show

This displays key values such as:

  • zitadel.appBaseUrl
  • zitadel.config.externalDomain
  • zitadel.config.externalPort
  • zitadel.config.externalProtocol
  • zitadel.bootstrap.f5InsightsHostname

Set remote auth to your preferred FQDN

Choose your target name

Accepted target formats:

  • insight.example.com
  • insight.example.com:8443
  • https://insight.example.com
  • http://insight.example.com:8080

If no scheme is provided, the command uses https by default.

Apply the FQDN

Run set with your target:

sudo f5insight-set-fqdn set auth.example.com

For a custom port:

sudo f5insight-set-fqdn set https://auth.example.com:8443

The command:

  • Parses the target into scheme, host, and port.
  • Runs helm upgrade --reuse-values with remote auth overrides.
  • Patches CUSTOM_REQUEST_HEADERS on the login deployment.
  • Waits for rollout completion.

Confirm when prompted

The command prints the resolved values and asks for confirmation:

Apply these settings? [y/N]

To skip the prompt in automation, add --yes.

Optional modes

Dry run (preview only):

sudo f5insight-set-fqdn set auth.example.com --dry-run

Verify the configuration

Check values after apply:

sudo f5insight-set-fqdn show

You can also verify relevant Helm values directly:

NAMESPACE=f5-insight
HELM_RELEASE=f5-insight
export KUBECONFIG=/etc/rancher
sudo -E helm get values "${HELM_RELEASE}" -n "${NAMESPACE}" -o yaml \
  | grep -E "appBaseUrl|externalDomain|externalPort|externalSecure|externalProtocol|loginV2BaseUri|f5InsightsHostname|f5InsightsPort" -A1 || true

Troubleshooting

Issue Cause Solution
Command fails with permission error set requires root privileges Run with sudo.
Helm release not found Wrong namespace or release name Set NAMESPACE and HELM_RELEASE correctly, then retry.
Kubeconfig not found Default kubeconfig path not valid Export KUBECONFIG to a valid file. If using sudo, use sudo -E.
Login page still uses old host Rollout pending or browser cache Wait for rollout completion, then refresh browser cache and retest.
TLS warning in browser Certificate does not match new FQDN Install a certificate valid for the configured hostname.

Notes

  • The command preserves unrelated Helm settings by using --reuse-values.
  • Safe mode is enabled by default and disables DB/bootstrap init jobs plus hooks.
  • To check command usage at any time, run f5insight-set-fqdn --help.

Configure the external FQDN using the UI

  1. Log in to F5 Insight as an administrator.
  2. Navigate to Settings ‣ User Administration ‣ SSO Identity Providers.
  3. Locate the External URL section and review the current value.
  4. Enter your FQDN. For example: f5insights.example.com
  5. Select Apply.
  6. Wait for the configuration task to complete.
FQDN configuration task completed successfully

The SSO Identity Providers page showing the configured external FQDN.

Note

External authentication may be temporarily unavailable while the configuration task runs, because authentication-related services may restart. Wait for the task to complete before you attempt an LDAP or SAML login.

Example login redirect:

https://f5insights.example.com/ui/v2/login/...

Example callback URI:

https://f5insights.example.com/api/auth/callback

Configure the external FQDN using the API

You can also configure the external FQDN using the F5 Insight REST API.

Get the current FQDN configuration

GET /api/auth/fqdn

Example response:

{
  "configured": true,
  "current_url": "https://f5insights.example.com"
}

Set the external FQDN

POST /api/auth/fqdn
Content-Type: application/json

{
  "target": "f5insights.example.com"
}

Example response:

{
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "target": "https://f5insights.example.com",
  "status": "submitted"
}
Set the external FQDN

The configuration runs as an asynchronous task. Use the task ID to check the status.

Check the task status

GET /api/auth/fqdn/status/{task_id}

Example in-progress response:

{
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "state": "APPLY",
  "status": "RUNNING",
  "progress": 60
}
Check the task status

Example completed response:

{
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "state": "COMPLETED",
  "status": "SUCCESS",
  "progress": 100
}

Note

Refer to the F5 Insight API documentation for the full request and response schemas, additional status values, and authentication requirements.

Known limitations

  • The configured value must be a fully qualified domain name. IP addresses are not supported.
  • HTTP is not supported. The external FQDN must use HTTPS.
  • Only one FQDN configuration task can run at a time.
  • External authentication may be temporarily unavailable while the configuration task runs.