apereo/cas · error · MessageDecodingException

Missing providerId

Error message

Missing providerId

What it means

The IdP-initiated (unsolicited SSO) profile requires the providerId request parameter identifying the SP entityID. If the parameter is missing or blank, decoding cannot proceed and MessageDecodingException is thrown.

Solutions

1. Append providerId=<SP entityID> to the unsolicited SSO URL.
2. Fix templates/links that construct the IdP-initiated SSO URL.
3. Check reverse proxy configuration for query-string rewriting/stripping.
4. Confirm you are using the correct endpoint with the expected parameter name.

Example fix

// before
/cas/idp/profile/SAML2/Unsolicited/SSO?shire=https://sp/acs
// after
/cas/idp/profile/SAML2/Unsolicited/SSO?providerId=https://sp.example.org/metadata&shire=https://sp/acs

val providerId = request.getParameter(SamlIdPConstants.PROVIDER_ID);
if (StringUtils.isBlank(providerId)) throw new IllegalStateException("providerId query parameter required for unsolicited SSO");

try {
    return controller.handleUnsolicitedSsoRequest(request, response);
} catch (MessageDecodingException e) {
    response.sendError(400, "providerId parameter is required");
}

When it happens

Trigger: Hitting /idp/profile/SAML2/Unsolicited/SSO (or similar) without providerId, or with providerId= empty, in the HTTP request.

Common situations: Hand-crafted or bookmarked SSO links missing the parameter; gateway/proxy stripping query parameters; integration docs followed incorrectly.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• No providerId parameter given in unsolicited SSO…
• Unable to resolve SP ACS URL for AuthnRequest construction
• Unable to resolve service provider assertion consumer…
• No Certificates provided
• Public and private keys do not match

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

Appendix: source

Thrown at support/cas-server-support-saml-idp-web/src/main/java/org/apereo/cas/support/saml/web/idp/profile/SamlIdPInitiatedProfileHandlerController.java:172

                providerId, SAMLConstants.SAML2_POST_BINDING_URI);
            val acs = facade.getAssertionConsumerService(SAMLConstants.SAML2_POST_BINDING_URI);
            shire = Optional.ofNullable(acs)
                .map(service -> StringUtils.isBlank(service.getResponseLocation())
                    ? service.getLocation()
                    : service.getResponseLocation()).orElse(null);
        }
        if (StringUtils.isBlank(shire)) {
            LOGGER.warn("Unable to resolve service provider assertion consumer service URL for AuthnRequest construction for entityID: [{}]", providerId);
            throw new MessageDecodingException("Unable to resolve SP ACS URL for AuthnRequest construction");
        }
        return shire;
    }

    protected String extractProviderId(final HttpServletRequest request) throws MessageDecodingException {
        val providerId = request.getParameter(SamlIdPConstants.PROVIDER_ID);
        if (StringUtils.isBlank(providerId)) {
            LOGGER.warn("No providerId parameter given in unsolicited SSO authentication request.");
            throw new MessageDecodingException("Missing providerId");
        }
        return providerId;
    }
}

View on GitHub (pinned to e7288fc434)