apereo/cas · error · IllegalArgumentException

Trust anchor requires no authority hints

Error message

Trust anchor requires no authority hints

What it means

A Trust Anchor sits at the top of a federation and by definition must not declare authority hints. getWellKnownDiscoveryConfiguration() throws this IllegalArgumentException when role is TRUST_ANCHOR but cas.oidc.federation.authority-hints is non-empty.

Solutions

1. Remove all entries from cas.oidc.federation.authority-hints for the trust anchor deployment
2. Confirm role=TRUST_ANCHOR is intentional (no superior entity)
3. If hints are required, this entity is not a trust anchor: set role to INTERMEDIATE or OPENID_PROVIDER

Example fix

// before
cas.oidc.federation.role=TRUST_ANCHOR
cas.oidc.federation.authority-hints=https://ta.example.org
// after
cas.oidc.federation.role=TRUST_ANCHOR
# authority-hints removed

if (role == OidcFederationRole.TRUST_ANCHOR && !oidcProperties.getFederation().getAuthorityHints().isEmpty()) {
    throw new IllegalStateException("Trust anchor must have no authority hints");
}

When it happens

Trigger: Deployment role set to TRUST_ANCHOR while leftover authority-hints entries remain in cas.oidc.federation config.

Common situations: An entity was demoted from intermediate/OP to trust anchor but hints were not removed; shared config template carries hints across roles; copy-pasted config from a subordinate deployment.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• OpenID provider requires authority hint(s)
• Intermediate requires authority hint(s)
• Federation role [ ] is not supported for Trust…
• No metadata defined for entity
• No federation keys defined for entity

AI-assisted analysis of apereo/cas@e7288fc434 (2026-09-08). Data as JSON: /api/errors/b3490a5c602830d8. Report an issue: GitHub.

Appendix: source

Thrown at support/cas-server-support-oidc-federation/src/main/java/org/apereo/cas/oidc/federation/web/OidcWellKnownFederationEndpointController.java:90

                throw new IllegalArgumentException("Federation role [" + role + "] is not supported for OpenID Provider");
            }
            issuer = settings.getIssuer();

            if (authorityHints.isEmpty()) {
                throw new IllegalArgumentException("OpenID provider requires authority hint(s)");
            }

            val json = JSONValue.parse(settings.toJson());
            metadata.put(EntityType.OPENID_PROVIDER.getValue(), json);

        } else if (role == OidcFederationRole.INTERMEDIATE) {
            if (authorityHints.isEmpty()) {
                throw new IllegalArgumentException("Intermediate requires authority hint(s)");
            }

        } else if (role == OidcFederationRole.TRUST_ANCHOR) {
            if (!authorityHints.isEmpty()) {
                throw new IllegalArgumentException("Trust anchor requires no authority hints");
            }

        } else {
            throw new IllegalArgumentException("Federation role [" + role + "] is not supported for Trust Anchor/Intermediate");
        }

        val federationMetadata = buildMetadata(issuer);
        metadata.put(EntityType.FEDERATION_ENTITY.getValue(), federationMetadata.toJSONObject());

        return buildEntityStatement(issuer, issuer, metadata, null, authorityHints);
    }
}

View on GitHub (pinned to e7288fc434)