apereo/cas · error · IllegalArgumentException

Federation role [" + role + "] is not supported for Trust…

Error message

Federation role [" + role + "] is not supported for Trust Anchor/Intermediate

What it means

Thrown by getWellKnownDiscoveryConfiguration in the OIDC federation well-known endpoint controller when the requested federation entity role is neither TRUST_ANCHOR nor TRUST_INTERMEDIATE. Only these two roles can publish a federation_entity metadata document; other OidcFederationRole values (e.g. relying party / OP roles) are not valid for this endpoint. The controller rejects the request early rather than building an invalid entity statement.

Solutions

Change the request to use role=trust_anchor or the intermediate role value supported by the endpoint.
Inspect OidcFederationRole to see the exact set of roles accepted for federation_entity metadata.
If you need metadata for another role type, use the corresponding OIDC endpoint (e.g. discovery for the provider) instead of the federation well-known endpoint.
Upgrade CAS if you believe the role you passed should be supported but is not present in OidcFederationRole.

Example fix

// before
curl 'https://cas.example.org/oidc/.well-known/openid-federation?role=provider'
// after
curl 'https://cas.example.org/oidc/.well-known/openid-federation?role=trust_anchor'

Defensive patterns

Strategy: validation

Validate before calling

Set<String> supported = Set.of("trust_anchor", "trust_intermediate");
if (!supported.contains(requestedRole)) {
    throw new IllegalArgumentException("Unsupported federation role: " + requestedRole);
}

Prevention

Consult OidcFederationRole for the exact accepted role values before calling the endpoint.
Use an enum-typed client parameter instead of free-form strings.

When it happens

Trigger: Calling GET on the well-known federation endpoint with a role parameter that maps to an OidcFederationRole value other than OidcFederationRole.TRUST_ANCHOR or the intermediate role; a client passing a misnamed or unsupported role string that resolves to an unexpected enum member.

Common situations: Developers hand-crafting federation discovery URLs copy role names from other OIDC parts of CAS (e.g. 'provider' or 'rp') that are not federation-entity roles; typos in documentation; testing the endpoint against a role added in a newer CAS version but requesting an invalid one.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of apereo/cas@e7288fc434 (2026-09-08). Data as JSON: /api/errors/57a466c823c4df8b. 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:94

            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)