Skip to main content

Managed Applications

Traefik Hub Managed Applications bring full GitOps workflow to application registration and credential management.

Traditionally, API consumers first needed to sign in to the API Portal and carry out several manual steps before their application could call the Gateway.

With Managed Applications the publisher declares the consumer’s application as a Kubernetes CRD and links it to a Managed Subscription. No portal login or other action is required from the consumer—the entire registration and credential lifecycle is handled on their behalf.

Key Concepts​

TermDescription
ApplicationLogical consumer (mobile app, backend, partner system). Identified by an App ID issued by your IdP.
ManagedApplicationDefines and manages application identities, ownership, and authentication credentials through GitOps workflows.
Self-Service ApplicationAn Application created by a developer via the portal. Managed Applications provide the GitOps alternative.
Managed SubscriptionGrants runtime access to APIs only to the ManagedApplications it references.
Self-Service SubscriptionAllows API consumers to subscribe their Applications to APIs—or entire API Bundles—directly from the API Portal.

How It Works​

  • The Hub Agent syncs the Managed Application + hashed Secret to the platform (for API key authentication) or validates LDAP credentials (for LDAP authentication).
  • During request-time Hub API Management matches the appId in the Managed Application and the ManagedSubscription rules.
  • Both valid credentials (API key, JWT, or LDAP) AND the application's subscription must be valid for the request to proceed. This zero-trust approach ensures credentials cannot be shared between applications.
  • If everything lines up, the call proceeds and the APIPlan quotas/rate-limits are enforced.

How to Use Managed Applications​

Define a ManagedApplication resource:

apiVersion: hub.traefik.io/v1alpha1
kind: ManagedApplication
metadata:
  name: weather-mobile
  namespace: apps
spec:
  appId: weather-mobile           # must match IdP client ID
  owner: 67f67907ee260b44336a952e # Hub user UUID (sub/externalID)
  notes: "For IOS & Android clients"
  apiKeys:
    - secretName: weather-mobile-key
      title: mobile-key
API Key Storage Options

The examples above demonstrate three different approaches for managing API keys:

Secret with data field: Uses base64-encoded values. The data field requires you to base64-encode the SHAKE-256 hash. This approach provides an extra layer of encoding but requires additional steps during key generation.

Secret with stringData field: Stores the raw SHAKE-256 hash directly without base64 encoding. Kubernetes automatically handles the base64 encoding when storing the secret. This approach is simpler and reduces the chance of encoding errors.

Inline value: Embeds the raw SHAKE-256 hash directly in the ManagedApplication resource. This approach eliminates the need for a separate Secret resource.

Choose the approach that best fits your security policies and operational preferences. The stringData approach typically offers the best balance of simplicity and security for most use cases.

Link that application to an API via ManagedSubscription:

apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
  name: weather-mobile-sub
  namespace: apps
spec:
  managedApplications:
    - name: weather-mobile
  apis:
    - name: weather-api
  apiPlan:
    name: standard-plan

Configuration Options​

FieldRequiredDescription
appIdYesUnique identifier for an application.
ownerYesHub user identifier of the application owner: use the OIDC sub, an external IdP externalID, or the long user ID visible in the Hub dashboard URL when you are using the built‑in Hub IdP.
notesNoFree-form notes for operators.
apiKeys[]NoDefines the API keys for the application. Up to 100 keyed items.
apiKeys[].titleNoHuman-readable key label shown in metrics.
apiKeys[].secretNameNo (One of secretName or value)Name of an Opaque Secret whose data.key field stores the SHAKE-256 hash of the raw key.
apiKeys[].valueNo (One of secretName or value)SHAKE-256 hash inline (max 4096 chars).
apiKeys[].suspendedNoSet true to disable this key without deleting.
Mutual exclusivity

Provide either secretName or value in each apiKeys[] item and not both.

When to Use Managed Applications​

  • Your organisation is fully GitOps and developers should not touch the portal.
  • App IDs already exist in your IdP (OIDC client IDs, external IDs) and must be recognised by the Gateway before a human ever logs in.
  • You want publishers (cluster admins / platform engineers) to issue or rotate API keys on behalf of consumers.
info
  • Duplicate App ID: If a Self-Service and Managed Application share the same App ID, the ManagedApplication version wins.
  • Static Analyzer: The Hub Static Analyzer warns whenever more than one ManagedApplication in the same namespace defines the same appId. When this occurs, Hub keeps only the ManagedApplication whose resource name comes first in alphabetical order and disregards the others.
Zero-Trust Security Model

API keys are bound to specific ManagedApplication resources and their subscriptions.

If you reuse the same API key across multiple ManagedApplication resources, each application must have its own valid ManagedSubscription to access an API. An application without a subscription will receive a 403 Forbidden response, even if another application using the same key has valid access.

This design prevents unauthorized access and ensures that API permissions are explicitly granted on a per-application basis, rather than relying solely on key possession.

Managed Application Experience in the API Portal​

The API Portal provides an interface for viewing managed applications. This allows you to see all applications and access their details.

Managed Applications in the API Portal

LDAP Applications​

When using LDAP authentication for API authentication, ManagedApplications work differently than with API key authentication.

How LDAP Applications Work​

With LDAP authentication configured via APIAuth:

  1. Applications authenticate using HTTP Basic Authentication with LDAP credentials
  2. The username from Basic Auth must match the appId in a ManagedApplication
  3. The ManagedApplication must have a valid ManagedSubscription granting API access
  4. No API keys are required—authentication is handled entirely by LDAP

LDAP Application Example​

apiVersion: hub.traefik.io/v1alpha1
kind: ManagedApplication
metadata:
  name: john-doe-app
  namespace: default
spec:
  appId: app.john.doe  # Machine user - authenticates API requests
  owner: john.doe      # Human user - manages app in portal
  notes: "Application for John Doe authenticated via LDAP"
  # No apiKeys needed - authentication done via LDAP

Service Account Example​

For service accounts or machine users in LDAP:

apiVersion: hub.traefik.io/v1alpha1
kind: ManagedApplication
metadata:
  name: inventory-service
  namespace: default
spec:
  appId: svc.inventory  # Must match LDAP service account username
  owner: platform.head
  notes: "Inventory microservice using LDAP service account"

LDAP Application Requirements​

When using LDAP authentication:

  • appId must match LDAP username: The appId field must exactly match the username in your LDAP directory
  • No API keys required: The apiKeys field should be omitted or empty
  • ManagedSubscription required: Applications still need a ManagedSubscription to access APIs
  • LDAP credentials for authentication: Applications authenticate using their LDAP username and password via HTTP Basic Auth

Making API Requests with LDAP​

Applications use HTTP Basic Authentication with their LDAP credentials:

curl -i https://api.example.com/products \
  -u john.doe:ldap-password \
  -H "Accept: application/json"

The authentication flow:

  1. Traefik Hub validates the LDAP credentials against the LDAP server
  2. Matches the username (john.doe) to the appId in the ManagedApplication
  3. Checks the ManagedSubscription for API access
  4. Applies APIPlan rate limits if configured
  5. Forwards the request to the backend service

Mixing Authentication Methods​

You can have different authentication methods across namespaces within the same workspace:

  • API Key namespace: Configure APIAuth with apiKey: {}, and ManagedApplications include apiKeys
  • LDAP namespace: Configure APIAuth with LDAP settings, and ManagedApplications omit apiKeys
  • JWT namespace: Configure APIAuth with JWT settings

Each namespace can only have one active authentication method (determined by the APIAuth resource with isDefault: true in that namespace). However, different namespaces within the same workspace can use different authentication methods simultaneously.

Related Content​