Chapter 6 Centralizing SAML Error Display in OpenSSO Enterprise 8.0 Update 1

A centralized error processing URL is now supported to display all error conditions caught during SAML versions 1.x and 2 protocol processing. (This URL does not handle external application errors, but only those thrown by OpenSSO when using the SAMLv1.x and SAMLv2 protocols.) By default, the error processing URL points to saml2error.jsp, a JavaServer Page (JSP) that ships with OpenSSO. saml2error.jsp can be found in the /saml2/jsp directory inside the exploded opensso.war.

• How Does it Work?

• Which Parameters are Sent?

• Configuring the Error Processing URL Attribute

• SAML Error Messages

How Does it Work?

The error processing URL provides the path to which a user agent is redirected or forwarded when a SAML processing error occurs. The Error Processing URL attribute is configured using the OpenSSO console. Out-of-the-box, saml2error.jsp is hosted within the OpenSSO WAR. It (or any customized page) can also be hosted with the external customer application.

• If the page is hosted within opensso.war, a forward is used to send the user agent to the URL. In this case, the value of the Error Processing URL attribute is /saml2/jsp/saml2error.jsp. (This is the default configuration.)

• If the page is hosted outside of opensso.war, an HTTP-REDIRECT or HTTP-POST (depending on the configuration) is used to send the user agent to the URL. In this case, the value of the Error Processing URL attribute is a URL like the following and must be modified as documented in Configuring the Error Processing URL Attribute.

  http://www.your-app.com/app/saml2error.jsp

Which Parameters are Sent?

Three query parameters that define the error condition are sent to the error processing URL.

• errorcode is the i18n key of the error message. See SAML Error Messages for a list.

• httpstatuscode is the HTTP status code of the error.

• message contains the details of the i18n error message.

Configuring the Error Processing URL Attribute

To Configure the Error Processing URL Attribute

1. Login to the OpenSSO console as administrator; by default, amadmin.

2. Click the Configuration tab.

3. Click the Global tab.

4. Click the Common Federation Configuration link.

5. Enter the appropriate URL as the value for the SAML Error Page URL attribute.

6. Enter the appropriate binding as the value for the SAML Error Page HTTP Binding attribute.

   The default binding is HTTP-POST. You may change this to HTTP-REDIRECT.

7. Click Save.

8. Log out of the console.

SAML Error Messages

• SAMLv2 Error Codes

• SAMLv1.x Error Codes

SAMLv2 Error Codes

• nullSPEntityID : Service provider entity identifier is blank.

• nullIDPEntityID : Identity provider entity identifier is blank.

• idpNotFound : Identity provider (using the SourceID in the artifact) is not found.

• requestProcessingError : Error processing AuthnRequest.

• failedToProcessSSOResponse : Failed to process the single sign-on response.

• nullInput : Blank input.

• requestProcessingMNIError : Error processing ManageNameIDRequest.

• nullRequestType : Request Type is not specified.

• nullSSOToken : No SSOToken is found.

• LogoutRequestProcessingError : Error processing LogoutRequest.

• LogoutResponseProcessingError : Error processing LogoutResponse.

• largeContentLength : Length of the content in the SOAP request is too long.

• errorMetaManager : Error getting an instance of the metadata manager.

• metaDataError : Error retrieving metadata.

• nullSessionProvider : Session Provider is not specified.

• SSOFailed : Single sign on failed.

• LogoutRequestCreationError : Error creating LogoutRequest.

• nullAssertionID : No AssertionID specified.

• failedToGetAssertionIDRequestMapper : Error retrieving the AssertionID request mapper.

• failedToAuthenticateRequesterURI : Failed to authenticate the requester using the URI binding.

• invalidAssertionID : Invalid AssertionID value.

• invalidAssertion : Invalid Assertion.

• unsupportedEncoding : Character encoding used is not supported.

• MissingSAMLRequest : SAMLRequest ID is missing from the HttpRequest.

• nullDecodedStrFromSamlResponse : Decoded string from LogoutResponse is null.

• nullIDPMetaAlias : Identity provider metaAlias is null.

• metaDataError : Error retrieving the metadata.

• invalidSOAPMessage : The SOAPMessage sent by the client is not valid.

• unableToCreateArtifactResponse : Unable to create a SAMLv2 ArtifactResponse.

• LogoutRequestCreationError : Error creating a LogoutRequest.

• UnableToRedirectToAuth : Unable to redirect to the Authentication Service URL.

• errorCreateArtifact : Error creating the Artifact.

• failedToSendECPResponse : Failed to send ECP response.

• notSupportedHTTPMethod : The specified single sign-on profile is not supported.

• missingArtifact : The SAMLArt is missing from the HttpRequest.

• errorObtainArtifact : Could not obtain the Artifact from the HttpRequest.

• failedToGetIDPSSODescriptor : Failed to get SSODescriptor element from the identity provider metadata.

• errorCreateArtifactResolve : Could not create an ArtifactResolve.

• errorInSOAPCommunication : Could not obtain the ArtifactResponse due to an error in SOAP communication.

• cannotFindIDP : Could not find the identity provider based on the Artifact string.

• cannotFindArtifactResolutionUrl : Could not find the identity provider's Artifact Resolution URL.

• soapError : Error occurred in SOAP communication.

• failedToCreateArtifactResponse : Failed to create the ArtifactResponse object.

• missingArtifactResponse : ArtifactResponse is missing from SOAPMessage.

• invalidSignature : Invalid signature in the ArtifactResponse.

• invalidInResponseTo : Invalid InResponseTo attribute in the ArtifactResponse.

• invalidIssuer : Invalid Issuer attribute in the ArtifactResponse.

• invalidStatusCode : Invalid StatusCode attribute in the ArtifactResponse.

• failedToCreateSOAPMessage : SOAPMessage was not created.

• failedToCreateResponse : Response was not created.

• assertionNotSigned : SAML Assertion is not signed.

• missingSAMLResponse : SAMLResponse is missing from the HttpRequest.

• errorObtainResponse : Couldn't obtain SAMLResponse from the HttpRequest.

• errorDecodeResponse : Error decoding the SAMLResponse in the HttpRequest.

• invalidHttpRequestFromECP : Invalid HttpRequest from the ECP.

• failedToProcessQueryRequest : Failed to process the query request.

• failedToCreateAssertionIDRequest : Could not create the AssertionIDRequest.

• nullPathInfo : No URI path information found in the request.

• invalidMetaAlias : Entity's metaAlias is invalid.

• failedToCreateAttributeQuery : Unable to create the AtributeQuery object.

• failedToCreateAuthnQuery : Unable to create the AuthnQuery object.

• nameIDMappingFailed : Name identifier mapping failed.

• failedToInitECPRequest : Failed to initiate the ECP request.

• singleLogoutFailed : Single logout failed.

• nullRequestUri : The request URI is not specified.

• invalidRequestUri : Unable to determine federation protocol based on the request URI.

• noRedirectionURL : No redirection URL is specified.

• readerServiceFailed : Reader service failed.

SAMLv1.x Error Codes

• untrustedSite : Site corresponding to the SiteID is not trusted.

• nullInputParameter : Input parameter is blank.

• invalidConfig : Invalid configuration

• missingTargetHost : Target host information is missing.

• nullTrustedSite : Trusted site is blank.

• errorCreateArtifact : Could not create the Artifact.

• targetForbidden : Access to target host is forbidden.

• failedCreateSSOToken : Did not create an SSOToken.

• missingTargetSite : Target site is missing.

• couldNotCreateResponse : Could not create the SAMLResponse.

• errorSigningResponse : Could not sign the SAMLResponse.

• errorEncodeResponse : Could not encode the SAMLResponse.

• missingSAMLResponse : The SAMLResponse is not there.

• errorDecodeResponse : Could not decode the SAMLResponse.

• errorObtainResponse : Could not get the SAMLResponse.

• invalidResponse : The SAMLResponse is invalid.

?