apereo/cas · error · STSException

Unknown realm: [ ]

Error message

Unknown realm: [{}]

What it means

UriRealmParser.parseRealm extracts a realm from the request URI's last path segment and validates it against the configured realm map. If the extracted realm is blank or not a key in realmMap it logs this warning and throws STSException("Unknown realm: ..."). Unlike the other entries here, this one does throw — the request fails.

Solutions

1. Add the requested realm name to the realmMap configuration (cas.authn.ws-sts.realm.*, UriRealmParser map) or fix the client URL to use an existing realm key.
2. Verify the exact realm string in the URL matches a map key (case-sensitive per containsKey).
3. Catch STSException on the client and inspect the message to learn which realm string was parsed.
4. If the endpoint should be realm-less, use a realm parser/endpoint configuration that returns null instead of parsing.

Example fix

// before
realmMap = Map.of("RealmA", propsA); // client calls /ws/sts/RealmB
// after
realmMap = Map.of("RealmA", propsA, "RealmB", propsB);

String realm = uri.substring(uri.lastIndexOf('/') + 1);
if (!configuredRealms.containsKey(realm)) {
    throw new IllegalArgumentException("Realm not configured: " + realm);
}

try {
    claims = claimsHandler.retrieveClaimValues(claims, params);
} catch (STSException e) {
    if (e.getMessage().startsWith("Unknown realm")) {
        // inspect e.getMessage() for the parsed realm, fix URL or config
    }
    throw e;
}

When it happens

Trigger: STS endpoint URL whose last segment (e.g. /ws/sts/MyRealm) is not present in the configured realmMap, or a URI with fewer than two segments so no realm can be parsed.

Common situations: Client pointed at the wrong STS realm path; realm renamed in config but clients still use the old URL; typo in the URL path; request sent to a non-realm STS endpoint.

Related errors

• Invalid logo uri from an unknown host
• Invalid policy uri from an unknown host
• Unknown realm:
• No security token could be retrieved for service
• Realm [ ] doesn't match with configured realm [ ]

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

Appendix: source

Thrown at support/cas-server-support-ws-sts-api/src/main/java/org/apereo/cas/support/realm/UriRealmParser.java:35

 */
@Slf4j
@RequiredArgsConstructor
public class UriRealmParser implements RealmParser {

    private final Map<String, RealmProperties> realmMap;

    @Override
    public String parseRealm(final Map<String, Object> messageContext) throws STSException {
        val url = (String) messageContext.get("org.apache.cxf.request.url");
        val st = new StringTokenizer(url, "/");
        var count = st.countTokens();
        if (count <= 1) {
            return null;
        }
        count--;
        val realm = getRealm(st, count);
        if (StringUtils.isBlank(realm) || !realmMap.containsKey(realm)) {
            LOGGER.warn("Unknown realm: [{}]", realm);
            throw new STSException("Unknown realm: " + realm);
        }

        LOGGER.debug("URI realm parsed: [{}]", realm);
        return realm.trim();
    }

    private static String getRealm(final StringTokenizer st, final int count) {
        var realm = StringUtils.EMPTY;
        for (var i = 0; i < count; i++) {
            realm = st.nextToken();
        }
        return realm.toUpperCase(Locale.ENGLISH);
    }
}

View on GitHub (pinned to e7288fc434)