apereo/cas · error · IllegalArgumentException

OpenID provider requires authority hint(s)

Error message

OpenID provider requires authority hint(s)

What it means

An OpenID Provider entity in an OIDC federation must list at least one authority hint (its superior entity). getWellKnownDiscoveryConfiguration() throws this IllegalArgumentException when role is OPENID_PROVIDER, discovery settings exist, but cas.oidc.federation.authority-hints is empty.

Solutions

  1. Add at least one superior entity ID to cas.oidc.federation.authority-hints
  2. Ensure hints reference valid entity IDs of the trust anchor/intermediate above this OP
  3. If the entity truly has no superior, change the role to TRUST_ANCHOR instead

Example fix

// before
cas.oidc.federation.role=OPENID_PROVIDER
# authority-hints empty
// after
cas.oidc.federation.authority-hints=https://ta.example.org
cas.oidc.federation.role=OPENID_PROVIDER
Defensive patterns

Strategy: validation

Validate before calling

if (List.of(OPENID_PROVIDER, INTERMEDIATE).contains(role) && oidcProperties.getFederation().getAuthorityHints().isEmpty()) {
    throw new IllegalStateException("Role " + role + " requires at least one authority hint");
}

Prevention

When it happens

Trigger: Deployment configured as OPENID_PROVIDER with OP discovery settings but cas.oidc.federation.authority-hints is unset or an empty list, while the well-known federation endpoint is initialized.

Common situations: Standalone OP being onboarded into a federation without adding its intermediate/trust-anchor to authority-hints; hints accidentally cleared during config refactor.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

        val error = retrieveInvalidIssuerError(request, response, OidcConstants.FETCH_FEDERATION_URL);
        if (error != null) {
            return error;
        }

        val role = oidcProperties.getFederation().getRole();
        val settings = serverDiscoverySettings.getIfAvailable();
        var issuer = oidcProperties.getCore().getIssuer();
        val metadata = new JSONObject();
        val authorityHints = oidcProperties.getFederation().getAuthorityHints().stream().map(EntityID::new).toList();
        if (settings != null) {
            if (role != OidcFederationRole.OPENID_PROVIDER) {
                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");
        }

View on GitHub (pinned to e7288fc434)