If the STS must be able to map the identity/claims he must know from which security domain (realm) to which security domain. The latter is defined by a RealmParser implementation. Options could be based the TCP Port as each realm runs in a different JVM or based on the URI like (.../STS/<myrealm>/...). The source realm must be encoded in the retrieved token which is possible with a SAML token (or X509). The SAMLRealmCodec interface provides customization to tell the STS how to parse the realm in the SAML token. This could be done by using an individual cert/pk for each security domain where the realm is encoded in the DN.
Currently, the TokenProvider has only access to the principal of the token passed in the WS-Sec header but he requires access to the realm as well.
The TokenIssueOperation is called when the SAML assertion is valid and the issuer of this token is trusted by this STS realm instance. Then, the TokenIssueOperation must parse the realm of the SAML token (SAMLRealmCodec) and get the its own realm (RealmParser). If it's equal don't do anything as right now. If different, figure out what kind of relationship is defined between the two realms (principal oder claims mapping), do the mapping.
TokenProviderParameters provides a new attribute "mappedPrincipal" attribute (new) where the mapped id is stored. I'd like to wrap the security token used for authentication in the WS-Sec header in a ReceivedToken thus any TokenProvider has access to it (optional).
The subject provider will first check whether there is a mappedPrincipal set before falling back to the principal attribute.