Management authentication

Management Center uses one shared authentication mode for every installed Management Center application. Administrators choose either local credentials or an external SAML identity provider (IdP); the two modes cannot be active at the same time.

Note

The authentication mode is configured once for Management Center. It applies to all current and future Management Center applications; it is not configured separately for Access, Control, Portal, Password Reset, MCP, or another managed application.

Authentication model

The selected mode applies to the complete Management Center installation, including applications added after the authentication mode was configured.

• Passwd enables local username and password authentication.
• SAMLSP delegates authentication to an external SAML IdP and disables the local login flow.
• Exactly one enabled authenticator must be configured with context_path set to /mgmt/authn/login.
• Management Center does not fall back to local authentication when a SAML configuration is missing or invalid. The Management Center server stops instead of starting with a weaker authentication mode.

MCP uses the same authentication mode for browser-based login, device verification, and client approval. The agent-facing MCP endpoint continues to use its dedicated listener and port. See MCP administration for the listener configuration and OAuth flow.

Authorize administrators at the IdP

Management Center uses SAML for authentication, but does not map SAML users, groups, or attributes to separate Management Center roles. A user who successfully authenticates through the configured SAML IdP receives the same Management Center administrator authority as a user who signs in with local authentication.

The IdP must therefore decide who is allowed to access the Management Center service provider. Before enabling SAML, restrict the IdP application assignment or access policy to approved Management Center administrators. Deny all other users and groups, and apply the organisation's required multifactor authentication and conditional-access policies at the IdP.

Danger

Do not enable SAML while the Management Center service provider is available to every IdP user. Successful SAML authentication grants administrator access across all installed Management Center applications, including the ability to approve an MCP client. MCP client approval authorizes the client; it does not replace the IdP policy that authorizes the administrator.

Identify administrators by NameID

Management Center uses the NameID value from the SAML assertion subject as the administrator's user name. No other assertion attribute is used to identify the user. The NameID value is shown as the Administrator in the administrative event log and is recorded as the user name in successful login events.

Configure the IdP to release a persistent, human-recognisable NameID, for example the administrator's user principal name, e-mail address, or another stable account identifier.

Caution

Do not configure the Management Center service provider with a transient NameID (urn:oasis:names:tc:SAML:2.0:nameid-format:transient). A transient NameID is a new random value for every login, so the same administrator appears as a different user each time. The administrative event log then cannot be used to determine who performed an action, and the logged user name cannot be correlated with an account at the IdP.

Persistent pseudonymous formats such as urn:oasis:names:tc:SAML:2.0:nameid-format:persistent keep the same value between logins and remain usable for correlation, but they are opaque. Use one only if the organisation can map the value back to an account at the IdP.

Danger

Verify the external IdP configuration before enabling SAML. Keep operating-system or container access available so that the persistent configuration can be restored if the IdP is unavailable.

Persistent configuration

Management Center stores the selected authentication mode in:

<customer directory>/management-center/config/modules/authn.json

The file is created with local authentication during the first start. After creation, it is customer-owned and is not overwritten during a Management Center or application upgrade. SAML resources should be stored below <customer directory>/management-center/resources, and downloaded metadata is cached below <customer directory>/management-center/samlcache.

Include the complete management-center directory in normal backup and restore procedures. Replacing or omitting the customer directory also removes the persistent authentication configuration.

Configure external SAML authentication

Before starting, prepare:

• the externally reachable Management Center URL
• IdP metadata, either as a local XML file or a reachable URL
• an IdP application assignment or access policy limited to approved Management Center administrators
• an IdP NameID configuration that releases a persistent, recognisable identifier for each administrator
• a PKCS#12 keystore containing the SP signing key and certificate
• an SP metadata template containing the Assertion Consumer Service (ACS) URL

Stop Management Center

Stop the service before changing the authentication mode.

Back up the current configuration

Copy the persistent authn.json file to a safe location. This copy is the recovery path if the external IdP cannot be reached after the change.

Install the SAML resources

Place the IdP metadata, SP metadata template, and signing keystore in the persistent management-center/resources directory.

Configure the SAML authenticator

Replace authn.json with a SAML configuration based on the example below. Replace all example addresses, paths, aliases, and passwords with values for the installation.

Start and verify Management Center

Start the service and confirm that the log reports Management authentication mode: SAML.

authn.json

{
  "name": "AuthN",
  "config": {
    "http_listener": "default",
    "http_context": "/authn",
    "authenticators": [
      {
        "id": "login",
        "type": "SAMLSP",
        "display_name": "Management Center SAML SP",
        "metadata_cache": "data/customer/management-center/samlcache",
        "config": {
          "context_path": "/mgmt/authn/login",
          "failure_location": "/authn/failure.html",
          "logout_location": "/disco/",
          "metadata_output_directory": "data/customer/management-center/samlcache/",
          "metadata": {
            "path": "data/customer/management-center/resources/idp-metadata.xml"
          },
          "entity_id": "https://management.example.com",
          "metadata_file_path": "data/customer/management-center/resources/sp-template.xml",
          "validate_in_response_to": true,
          "validate_audience_restrictions": true,
          "validate_destination": true,
          "validate_authn_instant": true,
          "validate_session_timestamp": true,
          "sign_ref": [
            {
              "keystore": {
                "path": "data/customer/management-center/resources/saml-signing.p12",
                "password": "change-me",
                "alias": "management-center",
                "key_password": "change-me"
              }
            }
          ]
        }
      }
    ]
  }
}

Use a template such as:

sp-template.xml

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    entityID="https://management.example.com">
    <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:AssertionConsumerService
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="https://management.example.com/mgmt/authn/login"
            index="1" />
    </md:SPSSODescriptor>
</md:EntityDescriptor>

The IdP audience must match entity_id, and the SAML response destination must match the ACS location.

Select the metadata source

Configure exactly one metadata source for the external IdP.

Local file

Store the metadata below the persistent management-center/resources directory and reference the file:

"metadata": {
  "path": "data/customer/management-center/resources/idp-metadata.xml"
}

URL

Use a URL when Management Center must download the metadata:

"metadata": {
  "url": "https://idp.example.com/metadata"
}

Both http:// and https:// URLs are supported. The endpoint must return status 200; redirects are not followed by default. Successfully downloaded metadata is cached and can be used if a later refresh fails.

Caution

Use HTTPS with certificate validation or a locally installed metadata file in production. Metadata contains the IdP signing certificate, so metadata retrieved over unprotected HTTP can be replaced by an attacker with network access.

Return to local authentication

Returning to local authentication requires access to the Management Center filesystem or container volume.

Stop Management Center

Stop the service before changing the authentication mode.

Restore local authentication

Replace the persistent authn.json file with the local configuration below. Do not retain a SAMLSP entry alongside it.

Start and verify Management Center

Start the service and confirm that the log reports Management authentication mode: local. Verify local login before removing any SAML resources.

authn.json

{
  "name": "AuthN",
  "config": {
    "http_listener": "default",
    "http_context": "/authn",
    "authenticators": [
      {
        "id": "login",
        "type": "Passwd",
        "config": {
          "context_path": "/mgmt/authn/login",
          "_success_location": "/authn/success.html",
          "failure_location": "/authn/failure.html",
          "require_chain": false
        }
      }
    ]
  }
}

Test the configuration

1. Open a protected application from Management Center discovery.
2. Confirm that SAML mode redirects directly to the configured external IdP without displaying the local login form.
3. Complete authentication and confirm that the browser returns to Management Center.
4. Open at least one other installed Management Center application and confirm that it uses the same authenticated session.
5. Sign in twice as the same administrator and confirm that the administrative event log shows the same, recognisable Administrator value both times. A value that changes between logins indicates a transient NameID.
6. Confirm that previous local credentials cannot be used while SAML mode is active.
7. Attempt to sign in as a user who is not assigned to the Management Center application at the IdP, and confirm that the IdP denies access.
8. If MCP is enabled, start an MCP login or device-verification flow and confirm that the browser uses the same external IdP before returning to the requested MCP approval page.

If the SAML response is rejected, use the error identifier shown in the browser to find the corresponding server log entry. Common causes are an audience that differs from entity_id, an incorrect destination or ACS URL, expired assertions, and metadata endpoints that return a redirect instead of status 200.