Authentication

Optional provider-based authentication for transform server endpoints. Disabled by default.

Scope and runtime boundary

This authentication layer validates request-time identity tokens or assertions on transform server endpoints. When AuthSettings.enabled is True, this covers every v3 endpoint by default -- discovery/assets endpoints (listing transforms, entities, icons, etc.) as well as transform execution endpoints (run, delete run, run status/results, prompt response) -- not just execution. /health is always exempt so liveness/readiness probes keep working regardless of auth configuration. Use public_paths (a comma-separated allowlist, empty by default) if you need to exempt specific paths -- for example /swagger or /openapi.json -- from auth while keeping it enabled everywhere else. See "public_paths" in the Configuration table below.

If your deployment uses Keycloak, a gateway, or another identity broker, terminate SSO upstream and forward the original bearer JWT/OIDC token or SAML assertion to the SDK. The built-in auth path validates generic JWTs, OIDC tokens, and SAML assertions against configured provider trust material.

This page covers identity token/assertion validation only. Validated identity is exposed to transform code through the transform run context (context.identity, context.auth_claims, and context.auth_payload) when a transform is executed.

This validation runs before a transform is scheduled -- in strict mode, a rejected credential means no TransformMiddleware or transform code runs at all for that request. See "Where this fits in the request chain" in Transform Middlewares for the full ordering, and Deploying Behind a Reverse Proxy for how this layer relates to SSO termination and other checks at the proxy/gateway.

Configuration

All settings use the MALTEGO_SERVER_AUTH_ prefix for environment variables.

Provider URL meanings

token_origin and provider_type are separate settings. token_origin describes whose credential the SDK is expected to validate: upstream SSO (sso) or a Maltego ID/light token (maltego_id). provider_type describes how the SDK validates the credential wire format: jwt, oidc, or saml.

Do not infer SSO vs Maltego ID from issuer, token shape, or the presence of SAML. Brokered and native credentials can overlap at the wire level.

provider_url is intentionally generic. Its meaning depends on provider_type:

jwt

provider_url is a JWKS URL.

oidc

provider_url is an OIDC issuer URL or .well-known/openid-configuration URL. Discovery provides the canonical issuer and JWKS URL.

saml

provider_url is a SAML IdP metadata URL. SAML metadata is XML metadata, not JWKS. It provides the IdP entity ID and signing certificate(s).

SAML assertions or responses may include a Signature element and a certificate in their own KeyInfo. The SDK does not trust that certificate by itself. When a SAML signature is present and verify_signature is enabled, signature verification uses trusted IdP metadata from provider_url or the explicitly configured saml_idp_cert. If the decoded SAML XML has no Signature element, the SDK skips signature verification and still applies the configured issuer, audience, recipient, and time-bound checks.

When using saml_idp_cert directly, also configure issuer unless the certificate is intentionally shared across every issuer you want to trust. The certificate proves which key signed the assertion; issuer constrains which IdP entity the assertion is allowed to claim.

Propagated auth headers

When SDK auth is enabled, a gateway or identity broker can propagate both the upstream SSO credential and the Maltego ID credential. The SDK does not infer which one to validate from token shape. It selects the credential from token_origin and validates it with provider_type. If token_origin is not configured for a custom validator, Authorization is preferred, and maltego-identity-authorization is accepted when no bearer token is present.

Authorization

Carries the upstream SSO bearer token or assertion. This header is used only when token_origin=sso.

maltego-identity-authorization

Carries the Maltego ID/light token. The value may be either a raw token or Bearer <token>. This header is used when token_origin=maltego_id or by custom validator setups without token_origin when no Authorization credential is present. Authorization is not used as a fallback for Maltego ID.

maltego-upstream-identity-method

Required only when SDK auth validates an upstream SSO credential from Authorization. Accepted values are OIDC and SAML case-insensitively. Missing, unknown, or mismatched values fail before validator selection for SSO credentials. provider_type=oidc and provider_type=jwt require OIDC; provider_type=saml requires SAML. This header is not required or used for maltego-identity-authorization.

If these headers cross a browser CORS boundary, include them in the proxy or ingress Access-Control-Allow-Headers allowlist. The built-in SDK CORS middleware allows requested headers when SDK CORS is enabled, but external proxies often require an explicit list. See the "Server Configuration" article's CORS section in this folder.

Examples

Generic JWT from upstream SSO:

export MALTEGO_SERVER_AUTH_ENABLED=true
export MALTEGO_SERVER_AUTH_TOKEN_ORIGIN=sso
export MALTEGO_SERVER_AUTH_PROVIDER_TYPE=jwt
export MALTEGO_SERVER_AUTH_PROVIDER_URL=https://id.example.com/.well-known/jwks.json
export MALTEGO_SERVER_AUTH_ISSUER=https://id.example.com/
export MALTEGO_SERVER_AUTH_AUDIENCE=my-transform-server

OIDC from upstream SSO:

export MALTEGO_SERVER_AUTH_ENABLED=true
export MALTEGO_SERVER_AUTH_TOKEN_ORIGIN=sso
export MALTEGO_SERVER_AUTH_PROVIDER_TYPE=oidc
export MALTEGO_SERVER_AUTH_PROVIDER_URL=https://id.example.com/realms/customer
export MALTEGO_SERVER_AUTH_AUDIENCE=my-transform-server

SAML from upstream SSO:

export MALTEGO_SERVER_AUTH_ENABLED=true
export MALTEGO_SERVER_AUTH_TOKEN_ORIGIN=sso
export MALTEGO_SERVER_AUTH_PROVIDER_TYPE=saml
export MALTEGO_SERVER_AUTH_PROVIDER_URL=https://idp.example.com/metadata
export MALTEGO_SERVER_AUTH_AUDIENCE=https://transform.example.com
export MALTEGO_SERVER_AUTH_RECIPIENT=https://transform.example.com/run

Maltego ID OIDC:

export MALTEGO_SERVER_AUTH_ENABLED=true
export MALTEGO_SERVER_AUTH_TOKEN_ORIGIN=maltego_id
export MALTEGO_SERVER_AUTH_PROVIDER_TYPE=oidc
export MALTEGO_SERVER_AUTH_PROVIDER_URL=https://auth.maltego.example/realms/maltego
export MALTEGO_SERVER_AUTH_AUDIENCE=my-transform-server

Static SAML certificate:

export MALTEGO_SERVER_AUTH_ENABLED=true
export MALTEGO_SERVER_AUTH_TOKEN_ORIGIN=sso
export MALTEGO_SERVER_AUTH_PROVIDER_TYPE=saml
export MALTEGO_SERVER_AUTH_SAML_IDP_CERT="$(cat idp-signing-cert.pem)"
export MALTEGO_SERVER_AUTH_ISSUER=https://idp.example.com/metadata

Precedence

Configuration sources (highest to lowest priority):

1. Environment variables
2. .env file
3. CLI arguments (--auth-enabled, --auth-provider-type, etc.)
4. Code (AuthSettings(...))

Usage

Via run_server:

from maltego.server import run_server, AuthSettings, AuthMode

run_server(
    settings=my_settings,
    auth_settings=AuthSettings(
        enabled=True,
        mode=AuthMode.STRICT,
        token_origin="sso",
        provider_type="oidc",
        provider_url="https://id.example.com/realms/customer",
    ),
)

Auth Flow

1. Parse Authorization, maltego-identity-authorization, and maltego-upstream-identity-method.
2. Select the credential from token_origin: sso uses Authorization; maltego_id uses maltego-identity-authorization. If token_origin is not configured, prefer Authorization and fall back to maltego-identity-authorization only when no bearer credential is present.
3. For token_origin=sso, require maltego-upstream-identity-method and reject missing or mismatched metadata before validator selection. For token_origin=maltego_id, do not require or use this SSO method header.
4. Validate the selected credential with the configured provider_type.
5. If no selected credential is present, allow the legacy Maltego-API-Key fallback when supplied.
6. Return 401/403 if no accepted credential is present or validation fails in strict mode.

Identity claim mapping

After a token or assertion is validated, the SDK builds context.identity from a normalized claim set. Built-in validators map JWT/OIDC claims and SAML NameID/email attributes into the same shape.

Unverified auth claims

Set MALTEGO_SERVER_AUTH_EXPOSE_UNVERIFIED_CLAIMS=true or AuthSettings(expose_unverified_claims=True) only when transform code needs to inspect a raw bearer JWT/OIDC or SAML payload for diagnostics or provider-specific logic. This diagnostic exposure can be enabled independently of auth validation; MALTEGO_SERVER_AUTH_ENABLED may remain false.

When enabled, the SDK decodes syntactically valid compact JWT payloads or SAML assertions without verifying their signature, issuer, audience, time bounds, or any other claim. The decoded payload is available as request.state.unverified_auth_claims and context.unverified_auth_claims. Malformed tokens do not fail the request because of this feature; the decoded value is left unset.

These claims are not trusted. The SDK never populates context.identity, request.state.identity, request.state.auth_claims, or request.state.rate_limit_key from unverified auth claims. Use context.identity or context.auth_claims only after validation succeeds, or return trusted identity claims from a custom validator.

Validation rules

• strict mode rejects missing or invalid bearer tokens/assertions. warn mode logs validation failures for all provider types and lets the request continue without setting context.identity, context.auth_claims, or context.auth_payload.
• Maltego-specific claims such as organization, credits, roles, and maltego_id are extracted when present but are not required.
• Issuer validation only runs when configured, or when trusted metadata provides an issuer for OIDC/SAML.
• Audience validation only runs when configured.
• SAML recipient validation only runs when configured.
• verify_signature is enabled by default. For JWT/OIDC credentials, that means the compact JWT signature is required and verified against trusted JWKS material. For SAML credentials, that means the XML signature is verified when the decoded assertion or response contains a Signature element. Unsigned SAML continues through issuer, audience, recipient, and time-bound checks. If a SAML Signature element is present, validation fails closed when no trusted metadata/certificate is available.
• The built-in SAML validator does not implement replay detection. It validates the assertion against configured trust, audience, recipient, issuer, and time checks. Deployments that require one-time-use SAML assertions should enforce replay protection upstream or in a custom validator backed by shared storage such as Redis.

Auth Problem Details

In strict mode, auth failures return RFC 9457 Problem Details with Content-Type: application/problem+json. The HTTP status code and body status member always match. The SDK returns this error format directly for auth failures; clients do not need to opt in with an Accept header.

Common response fields:

type
title
status
detail
instance
error_code
auth_origin
provider_type
reason
refresh_required
retryable

Status and error code mapping:

Expired OIDC/JWT SSO credential example:

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired"

{
  "type": "urn:maltego-transforms:problem:auth:token-expired",
  "title": "Authentication token expired",
  "status": 401,
  "detail": "The authentication token has expired. Obtain a fresh SSO credential and retry the request.",
  "instance": "/v3/transforms/acme.example/run",
  "error_code": "auth.token_expired",
  "auth_origin": "sso",
  "provider_type": "oidc",
  "reason": "expired",
  "refresh_required": true,
  "retryable": false
}

Expired SAML SSO assertion example:

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
WWW-Authenticate: Bearer error="invalid_token", error_description="The SAML assertion expired"

{
  "type": "urn:maltego-transforms:problem:auth:assertion-expired",
  "title": "SAML assertion expired",
  "status": 401,
  "detail": "The SAML assertion has expired. Re-authenticate through the upstream SSO provider and retry the request.",
  "instance": "/v3/transforms/acme.example/run",
  "error_code": "auth.assertion_expired",
  "auth_origin": "sso",
  "provider_type": "saml",
  "reason": "expired",
  "refresh_required": true,
  "retryable": false
}

Missing credentials example:

{
  "type": "urn:maltego-transforms:problem:auth:credentials-missing",
  "title": "Authentication credentials missing",
  "status": 401,
  "detail": "No accepted authentication credential was provided.",
  "instance": "/v3/transforms/acme.example/run",
  "error_code": "auth.credentials_missing",
  "auth_origin": "sso",
  "provider_type": "oidc",
  "reason": "missing",
  "refresh_required": false,
  "retryable": false
}

Invalid credentials example:

{
  "type": "urn:maltego-transforms:problem:auth:credentials-invalid",
  "title": "Invalid authentication credentials",
  "status": 401,
  "detail": "The authentication credential is invalid for this transform server.",
  "instance": "/v3/transforms/acme.example/run",
  "error_code": "auth.credentials_invalid",
  "auth_origin": "sso",
  "provider_type": "jwt",
  "reason": "invalid",
  "refresh_required": false,
  "retryable": false
}

Access denied example:

{
  "type": "urn:maltego-transforms:problem:auth:access-denied",
  "title": "Access denied",
  "status": 403,
  "detail": "The authenticated principal is not allowed to access this transform.",
  "instance": "/v3/transforms/acme.example/run",
  "error_code": "auth.access_denied",
  "auth_origin": "sso",
  "provider_type": "oidc",
  "reason": "access_denied",
  "refresh_required": false,
  "retryable": false
}

Provider unavailable example:

{
  "type": "urn:maltego-transforms:problem:auth:provider-unavailable",
  "title": "Authentication provider unavailable",
  "status": 503,
  "detail": "The authentication provider could not be reached. Retry the request later.",
  "instance": "/v3/transforms/acme.example/run",
  "error_code": "auth.provider_unavailable",
  "auth_origin": "sso",
  "provider_type": "oidc",
  "reason": "provider_unavailable",
  "refresh_required": false,
  "retryable": true
}

Internal auth error example:

{
  "type": "urn:maltego-transforms:problem:auth:internal-error",
  "title": "Authentication error",
  "status": 500,
  "detail": "An internal authentication error occurred.",
  "instance": "/v3/transforms/acme.example/run",
  "error_code": "auth.internal_error",
  "auth_origin": "sso",
  "provider_type": "oidc",
  "reason": "internal_error",
  "refresh_required": false,
  "retryable": false
}

Problem type reference:

urn:maltego-transforms:problem:auth:credentials-missing / auth.credentials_missing

The request did not include a bearer token or accepted API key. This happens before token validation. refresh_required is false and retryable is false.

urn:maltego-transforms:problem:auth:token-expired / auth.token_expired

A JWT/OIDC credential failed exp validation. refresh_required is true and retryable is false. In the expected OIDC broker flow, Keycloak normally refreshes or exchanges the upstream token before the SDK receives it; this SDK response is the fallback if an expired credential reaches the transform server.

urn:maltego-transforms:problem:auth:assertion-expired / auth.assertion_expired

A SAML assertion is past NotOnOrAfter. refresh_required is true and retryable is false. SAML has no refresh token; clients usually redirect through the SSO broker to obtain a new assertion.

urn:maltego-transforms:problem:auth:credentials-invalid / auth.credentials_invalid

The credential is malformed or failed signature, issuer, audience, or recipient checks. refresh_required is false and retryable is false.

urn:maltego-transforms:problem:auth:access-denied / auth.access_denied

The credential is authentic, but a custom validator or policy denied access. refresh_required is false and retryable is false.

urn:maltego-transforms:problem:auth:provider-unavailable / auth.provider_unavailable

Required JWKS, OIDC metadata, SAML metadata, or SAML signing material was unavailable. refresh_required is false and retryable is true.

urn:maltego-transforms:problem:auth:internal-error / auth.internal_error

The SDK hit an unexpected auth error. Details are intentionally generic. refresh_required is false and retryable is false.

Deprecated OIDC aliases

Existing OIDC-specific names are accepted as temporary compatibility aliases and emit deprecation warnings.

MALTEGO_SERVER_AUTH_MODE=log_only is also accepted as a deprecated alias for MALTEGO_SERVER_AUTH_MODE=warn.

Custom Validators

Implement TokenValidator or subclass a built-in validator for provider specific checks. Custom validators should return normalized identity claims consumed by Identity.from_claims(). Existing tuple-returning validators are still supported. New validators should return AuthValidationSuccess and AuthValidationFailure so normalized identity claims, validated provider claims, and raw provider payload details stay separate.

After validation succeeds, transforms can read normalized identity from context.identity, validated provider-specific claims from context.auth_claims, and raw parsed provider details from context.auth_payload.

from maltego.auth import AuthSettings, AuthValidationFailure, JWTTokenValidator, set_auth_settings
from maltego.auth.validator import ValidationErrorKind

class MyProviderValidator(JWTTokenValidator):
    async def validate_token(self, token: str):
        result = await super().validate_token(token)
        if isinstance(result, AuthValidationFailure):
            return result
        if result.auth_claims.get("tenant") not in {"allowed-tenant"}:
            return AuthValidationFailure(
                ValidationErrorKind.INVALID_CLAIMS,
                "Tenant not allowed",
            )
        return result

settings = AuthSettings(
    enabled=True,
    provider_type="jwt",
    provider_url="https://id.example.com/.well-known/jwks.json",
    validator_factory=lambda s: MyProviderValidator(s),
)
set_auth_settings(settings)

Richer result shape:

from maltego.auth import AuthValidationFailure, AuthValidationSuccess
from maltego.auth.validator import ValidationErrorKind


class MySAMLValidator:
    async def validate_token(self, token: str):
        assertion = validate_my_saml_assertion(token)
        if not assertion.tenant:
            return AuthValidationFailure(
                ValidationErrorKind.INVALID_CLAIMS,
                "Missing tenant",
            )


        return AuthValidationSuccess(
            identity_claims={
                "iss": assertion.issuer,
                "sub": assertion.name_id,
                "email": assertion.email,
            },
            auth_claims={
                "tenant": assertion.tenant,
                "groups": assertion.groups,
            },
            protocol="saml",
            raw_payload={"assertion_id": assertion.assertion_id},
        )


    async def close(self):
        pass

Accessing Identity in Transforms

When auth is enabled, identity is available via context.identity:

@register_transform()
async def my_transform(input_entity: Phrase, context: MaltegoContext):
    if context.identity:
        print(f"User: {context.identity.sub}")


    if context.auth_claims:
        print(f"Groups: {context.auth_claims.get('groups', [])}")


    print(f"Rate key: {context.rate_limit_key}")

API Reference

Static reference for the maltego.auth classes used above. Hand-written from the SDK source (src/maltego/auth/) so the published article remains a self-contained reference.

AuthSettings

maltego.auth.AuthSettings

Authentication settings for JWT/OIDC/SAML token validation. A Pydantic BaseSettings model. All fields can be overridden via environment variables using the MALTEGO_SERVER_AUTH_ prefix; see the Configuration table above for the full field list, defaults, and env-var mapping. Configuration source priority (highest to lowest) is: environment variables, .env file, CLI arguments, then values passed to the constructor in code.

Three fields (oidc_issuer_url, oidc_jwks_uri, oidc_audience) and jwt_leeway also exist for backward compatibility only -- see "Deprecated OIDC aliases" above; use provider_type/provider_url/audience/ token_leeway instead in new configuration.

AuthMode

maltego.auth.AuthMode

An enum of authentication modes determining how validation failures are handled:

• STRICT ("strict") -- invalid or missing tokens result in a 401/403 response.
• WARN ("warn") -- invalid tokens are logged but the request proceeds.
• LOG_ONLY -- deprecated alias for WARN, kept for backward compatibility.

Identity

maltego.auth.Identity

A normalized auth identity extracted from JWT claims. Provides a stable, consistent structure for downstream middleware and transforms, built from Keycloak/OIDC JWT claims. Constructed via the Identity.from_claims(claims) classmethod rather than directly.

It also exposes an is_anonymous property (true when sub is empty or equals the all-zero placeholder UUID) and a to_dict() method for serialization.

TokenValidator

maltego.auth.TokenValidator

A Protocol (structural interface), not a concrete class -- implement it to create a custom authentication backend. Two async methods are required:

• async validate_token(self, token: str) -- validates a bearer token and extracts claims. Returns AuthValidationSuccess, AuthValidationFailure, or the historical 3-tuple (error_kind, error_message, claims) for backward compatibility.
• async close(self) -- closes any resources held by the validator (HTTP clients, connections, etc.).

Built-in validators that satisfy this protocol include JWTTokenValidator, OIDCTokenValidator, and the SAML validator referenced elsewhere in this article.

AuthValidationSuccess and AuthValidationFailure

maltego.auth.AuthValidationSuccess and maltego.auth.AuthValidationFailure

Structured result types returned by TokenValidator.validate_token(). Both are dataclasses and both remain iterable (yielding the legacy 3-tuple shape) for compatibility with older tuple-returning validators.

AuthValidationSuccess fields:

AuthValidationFailure fields:

OIDCTokenValidator

maltego.auth.OIDCTokenValidator

An async OIDC token validator. Subclasses JWTTokenValidator: it performs OIDC discovery (fetching .well-known/openid-configuration and the resulting JWKS URI), then delegates JWT signature and claim validation back to JWTTokenValidator.

Constructor:

This class is normally selected automatically when provider_type=oidc; construct it directly only when building a fully custom validator_factory.

ValidationErrorKind

maltego.auth.validator.ValidationErrorKind

An enum categorizing token/assertion validation errors for HTTP status mapping. Used as the error_kind field of AuthValidationFailure.