Package com.sun.identity.saml2.profile

Class SPACSUtils

  • public class SPACSUtils
extends Object
    This class is used by a service provider (SP) to process the response from an identity provider for the SP's Assertion Consumer Service.

    • Method Detail

      • getResponse

        public static ResponseInfo getResponse​(jakarta.servlet.http.HttpServletRequest request,
                                       jakarta.servlet.http.HttpServletResponse response,
                                       String orgName,
                                       String hostEntityId,
                                       SAML2MetaManager metaManager)
                                throws SAML2Exception,
                                       IOException
        Retrieves SAML Response from http request. It handles three cases: 
         1. using http method get using request parameter "resID".
    This is the case after local login is done.
 2. using http method get using request parameter "SAMLart".
    This is the case for artifact profile.
 3. using http method post. This is the case for post profile.
        Parameters:
        request - http servlet request
        response - http servlet response
        orgName - realm or organization name the service provider resides in
        hostEntityId - Entity ID of the hosted service provider
        metaManager - SAML2MetaManager instance.
        Returns:
        ResponseInfo instance.
        Throws:
        SAML2Exception - if it fails in the process.
        IOException - if it fails in the process.

      • processResponse

        public static Object processResponse​(jakarta.servlet.http.HttpServletRequest request,
                                     jakarta.servlet.http.HttpServletResponse response,
                                     PrintWriter out,
                                     String metaAlias,
                                     Object session,
                                     ResponseInfo respInfo,
                                     String realm,
                                     String hostEntityId,
                                     SAML2MetaManager metaManager,
                                     SAML2EventLogger auditor)
                              throws SAML2Exception
        Authenticates user with Response. Auth session upgrade will be called if input session is not null. Otherwise, saml2 auth module is called. The name of the auth module is retrieved from SPSSOConfig. If not found, "SAML2" will be used.
        Parameters:
        request - HTTP Servlet request
        response - HTTP Servlet response.
        out - the print writer for writing out presentation
        metaAlias - metaAlias for the service provider
        session - input session object. It could be null.
        respInfo - ResponseInfo to be verified.
        realm - realm or organization name of the service provider.
        hostEntityId - hosted service provider Entity ID.
        metaManager - SAML2MetaManager instance for meta operation.
        auditor - a SAML2EventLogger auditor object to hook into tracking information for the saml request
        Returns:
        Object which holds result of the session.
        Throws:
        SAML2Exception - if the processing failed.

      • markAssertionAsConsumed

        public static void markAssertionAsConsumed​(Map smap)
                                    throws SAML2Exception
        Records the bearer assertions of a verified response as used up, so that a second submission of any of them is turned away by the one-time check in SAML2Utils.verifyResponse.

        Every bearer assertion the response carries is claimed, not only the one the session is built from. verifyResponse checks all of them against the one-time cache on the way in, and claiming just one left the rest replayable: an unsolicited response carrying two individually signed assertions could be submitted a second time with the spent one dropped.

        The claim on the in-memory cache is atomic: put reports the previous value under the key, so a request that finds one there has lost a race with a concurrent submission of the same assertion and is rejected. That holds within one JVM. Nothing compares and sets across the cluster - a node reads the SAML2 failover repository before accepting and writes to it afterwards, so two nodes handed the same response at the same time can both read nothing and both accept. The repository write is best effort; it closes the replay window across a restart, another node or a later request, not against a simultaneous one.

        Call this on every binding, as soon as the caller has committed to the response - before the session is created and before the service provider adapter runs, so that nothing done with the assertion happens while it is still replayable. The assertion is therefore spent even if the SSO that follows fails on something transient; recovery is to start SSO again, not to resubmit the response.

        "Committed to the response" is later than "verified it": SPACSUtils.processResponse hands a response it cannot map to a user back to the caller, which sends the user through a local login and then re-presents the same response - the same ResponseInfo, out of SPCache.responseHash - to processResponse again. An assertion claimed on the first of those passes would be refused on the second, so the claim goes after that decision. SAML2Proxy, which has no such re-entry, claims once the verified response has been stored and before the key that leads to it is handed out - late enough that an outage of the SAML2 token repository does not spend the assertion on a failure unrelated to it, early enough that nothing can redeem the key in the meantime.

        One gap remains with SAML2 failover switched off. SPCache.assertionByIDCache expires an entry on a fixed schedule - SAML2Constants.CACHE_CLEANUP_INTERVAL, 600s by default - while an assertion stays acceptable until its NotOnOrAfter plus assertionTimeSkew. An IdP that issues long-lived bearer assertions can outlast the marker. Enable SAML2 failover, which stores the marker for exactly as long - until NotOnOrAfter plus assertionTimeSkew - or keep the assertion lifetime inside the cleanup interval.

        Parameters:
        smap - the map returned by SAML2Utils.verifyResponse. It has to carry SAML2Constants.BEARER_ASSERTION_IDS, the bearer assertions of the response as assertion id to the instant in milliseconds until which it is accepted, which is how long its marker is stored. verifyResponse never reports a null there - it rejects a bearer subject confirmation that carries no NotOnOrAfter - but a map from anywhere else might, and such an id is claimed in this JVM and not written to the SAML2 token repository, there being no expiry to store it under. A map without that key is refused rather than partly claimed - see bearerAssertionsOf(Map).
        Throws:
        SAML2Exception - if any of the assertions had already been consumed, or if the map does not report any.

      • getNeedAttributeEncrypted

        public static boolean getNeedAttributeEncrypted​(boolean needAssertionEncrypted,
                                                SPSSOConfigElement spssoconfig)

      • setAttrMapInSession

        public static void setAttrMapInSession​(SessionProvider sessionProvider,
                                       Map attrMap,
                                       Object session)
                                throws SessionException
        Sets the attribute map in the session
        Parameters:
        sessionProvider - Session provider
        attrMap - the Attribute Map
        session - the valid session object
        Throws:
        SessionException - if a session error occurs

      • getRelayState

        public static String getRelayState​(String relayStateID,
                                   String orgName,
                                   String hostEntityId,
                                   SAML2MetaManager sm)
        Obtains relay state. Retrieves the relay state from relay state cache. If input relay state is null, retrieve it from SPSSOConfig.
        Parameters:
        relayStateID - relay state value received from http request.
        orgName - realm or organization name the service provider resides in
        hostEntityId - Entity ID of the hosted service provider
        sm - SAML2MetaManager instance.
        Returns:
        final relay state. Or null if the input relayStateID is null and no default relay state is configured.

      • getDefaultRelayState

        public static String getDefaultRelayState​(String orgName,
                                          String hostEntityId,
                                          SAML2MetaManager sm)
        Retrieves the default relay state from SPSSOConfig. This URL is administrator configured, so it needs no validation against the RelayState whitelist of the hosted entity.
        Parameters:
        orgName - realm or organization name the service provider resides in
        hostEntityId - Entity ID of the hosted service provider
        sm - SAML2MetaManager instance.
        Returns:
        the default relay state; or null if it is not configured or an error occurred during the retrieval process.

      • getIntermediateURL

        public static String getIntermediateURL​(String orgName,
                                        String hostEntityId,
                                        SAML2MetaManager sm)
        Retrieves intermediate redirect url from SP sso config. This url is used if you want to goto some place before the final relay state.
        Parameters:
        orgName - realm or organization name the service provider resides in
        hostEntityId - Entity ID of the hosted service provider
        sm - SAML2MetaManager instance.
        Returns:
        intermediate redirect url; or null if the url is is not configured or an error occured during the retrieval process.

      • prepareForLocalLogin

        public static String prepareForLocalLogin​(String realm,
                                          String hostEntityId,
                                          SAML2MetaManager sm,
                                          ResponseInfo respInfo,
                                          String requestURI)
        Saves response for later retrieval and retrieves local auth url from SPSSOConfig. If the url does not exist, generate one from request URI. If still cannot get it, (shouldn't happen), get it from SystemConfigurationUtil.
        Parameters:
        realm - Realm or organization name the service provider resides in.
        hostEntityId - Entity ID of the hosted service provider.
        sm - SAML2MetaManager instance to perform metadata operations.
        respInfo - The to be cached ResponseInfo.
        requestURI - The HTTP request URI.
        Returns:
        The local login url.

      • getSAMLAttributes

        public static List<Attribute> getSAMLAttributes​(Assertion assertion,
                                                boolean needAttributeEncrypted,
                                                Set<PrivateKey> privateKeys)
        Gets the attributes from an assert's AttributeStates.
        Parameters:
        assertion - The assertion from which to pull the AttributeStates.
        needAttributeEncrypted - Whether attributes must be encrypted (or else rejected).
        privateKeys - Private keys used to decrypt those encrypted attributes.
        Returns:
        a list of attributes pulled from the provided assertion.

      • processResponseForFedlet

        public static Map processResponseForFedlet​(jakarta.servlet.http.HttpServletRequest request,
                                           jakarta.servlet.http.HttpServletResponse response,
                                           PrintWriter out)
                                    throws SAML2Exception,
                                           IOException,
                                           SessionException,
                                           jakarta.servlet.ServletException
        Processes response from Identity Provider to Fedlet (SP). This will do all required protocol processing, include signature, issuer and audience validation etc. A map containing processing result will be returned.
        Here is a list of keys and values for the returned map:
        SAML2Constants.ATTRIBUTE_MAP -- Attribute map containing all attributes passed down from IDP inside the Assertion. The value is a java.util.Map whose keys are attribute names and values are java.util.Set of string values for the attributes.
        SAML2Constants.RELAY_STATE -- Relay state, value is a string
        SAML2Constants.IDPENTITYID -- IDP entity ID, value is a string
        SAML2Constants.RESPONSE -- Response object, value is an instance of com.sun.identity.saml2.protocol.Response SAML2Constants.ASSERTION -- Assertion object, value is an instance of com.sun.identity.saml2.assertion.Assertion SAML2Constants.SUBJECT -- Subject object, value is an instance of com.sun.identity.saml2.assertion.Subject SAML2Constants.NAMEID -- NameID object, value is an instance of com.sun.identity.saml2.assertion.NameID
        Parameters:
        request - HTTP Servlet request
        response - HTTP Servlet response.
        out - the print writer for writing out presentation
        Returns:
        Map which holds result of the processing.
        Throws:
        SAML2Exception - if the processing failed due to server error.
        IOException - if the processing failed due to IO error.
        SessionException - if the processing failed due to session error.
        jakarta.servlet.ServletException - if the processing failed due to request error.

      • getPrincipalWithoutLogin

        public static String getPrincipalWithoutLogin​(Subject assertionSubject,
                                              Assertion authnAssertion,
                                              String realm,
                                              String spEntityId,
                                              SAML2MetaManager metaManager,
                                              String idpEntityId,
                                              String storageKey)
                                       throws SAML2Exception
        Returns the username if there was one from the Assertion we were able to map into a local user account. Returns null if not. Should only be used from the SP side. Should only be called in conjuncture with the Auth Module. In addition, it performs what attribute federation it can. This method is a picked apart version of the "processResponse" function.
        Throws:
        SAML2Exception

      • getAttrs

        public static List<Attribute> getAttrs​(Assertion authnAssertion,
                                       boolean needAttributeEncrypted,
                                       Set<PrivateKey> decryptionKeys)
        Gets the attributes for this assertion in a new List.
        Parameters:
        authnAssertion - Assertion from which to reead the attributes.
        needAttributeEncrypted - Whether the attributes must be encrypted.
        decryptionKeys - The keys used to decrypt the attributes, if they're encrypted.
        Returns:
        a List of the attributes in this assertion.