We have put together documentation that will provide you with in-depth information and helpful resources that will help you get started. The documentation is intended for anyone deploying an IdP or adding a SP to the Federation and provides a combination of extensible code and good practice methodologies across topics such as:

• Protocol and Software Guidelines
• AAF policy
• Identity Providers
• Service Providers
• Attributes
• Levels of Assurance
• FAQ
• AAF Email discussion lists

To access this content please see http://wiki.aaf.edu.au/tech-info/home

There are several steps to getting your Service registered in the AAF and thus your service metadata included in metadata.

Step 1 - Register your Organization in the Federation Registry

For PRODUCTION: Go to https://manager.aaf.edu.au/federationregistry/

For TESTING: Go to https://manager.test.aaf.edu.au/federationregistry/

Select "Register New Organization" and follow the prompts.

Step 2 - Wait for Organization to be approved.

You will receive several emails in this step, included will be

• Notification of Approval of new orgainzation
• Notification of creation of a new AAF VHO Account
  (which you can use to admin the organization and service)
• Invitation to become Admin of your VHO Section
  (See: http://www.aaf.edu.au/guidelines/virtual-home-organisation-vho/ for details)

Step 3 - Register your Service in the Federation Registry

For PRODUCTION: Go to https://manager.aaf.edu.au/federationregistry/

For TESTING: Go to https://manager.test.aaf.edu.au/federationregistry/

Select "Register new Service Provider" and follow the prompts.

Step 4 - Wait for the Service Provider to be approved.

Again you will receive an email in this step,

• Notification of Approve of the new Service Provider. The email will include a link which you can follow to become the Service Provider administrator.

Step 5 - Test your service.

Approximately 30 minutes after the Service Provider has been approved the SP Metadata will appear in the federation Metadata. It will take a little longer for the Metadata to be consumed by Identity providers, allow up to 24 hours for all IdPs to refresh their metadata.

You can use your AAF VHO account to perform initial testing of your service.

Step 6 - Announcing you service to the AAF

The AAF can assist you announcing your service, or if you have specific customers you would want to notify them through your own channels.

                Three versions of the AAF Metadata for the production and test federations are now being extracted from the Federation Registry and signed ready for use by IdP and SP.
 
                All are downloadable from https://manager.aaf.edu.au/metadata/[document] and https://manager.test.aaf.edu.au/metadata/[document] for the production and test federations respectively. e.g https://manager.aaf.edu.au/metadata/metadata.aaf.signed.complete.xml
 
 
                1. Default metadata – [metadata.aaf.signed.xml] provide minimal details required to operate the federation – suitable for all IdPs and SPs (Shib 1.3.x and 2.x). No change required to existing IdPs and SPs to use this version
 
                2. Complete metadata  - [metadata.aaf.signed.complete.xml] provides the complete metadata generated for the federation. This is only suitable for Shibboleth 2.x. It will not work with earlier Shibboleth 1.3.x version.  It is recommended all new deployments and existing Shibboleth 2.x deployments move to this version. For existing deployments this will require a minor change to configuration.
 
                3.  Metadata for MAMS Autograph / ShARPE – [metadata.aaf.signed.noext.xml] is minimal metadata that is known to work with IdPs that use the MAMS Autograph and / or ShARPE tools.
 
                All three metadata files in each federation are signed with a unique private key and can thus be verified using the certificate available at https://manager.aaf.edu.au/metadata/metadata-cert.pem for production or https://manager.test.aaf.edu.au/metadata/metadata-cert.pem for test.
 
                The metadata site itself is protected with an AUSCert certificate.

Adapted from the folk at Internet 2 via: https://spaces.internet2.edu/display/SHIB2/IdPTroubleshootingCommon...

org.opensaml.xml.XMLConfigurator: Configuration file does not validate against schema org.xml.sax.SAXParseException: UndeclaredPrefix: Cannot resolve 'xt:DEFAULT' as a QName: the prefix 'xt' is not declared.

OpenSAML requires an xml parser that supports JAXP 1.3 and DOM3. The JVM is currently configured to use the Sun XML parser, which is known to be buggy and can not be used with OpenSAML. Please endorse a functional JAXP library(ies) such as Xerces and Xalan. For instructions on how to endorse a new parser see http://java.sun.com/j2se/1.5.0/docs/guide/standards/index.html

This error is always because you did not not endorse Xerces and Xalan. If you think you did then you have made a mistake, perhaps because your application container isn't doing what you think it's doing (for example, Tomcat "helpfully" overrides the default location of the endorsed library directory).

edu.internet2.middleware.shibboleth.idp.profile.AbstractSAMLProfileHandler: No return endpoint available for relying party ...

This is caused by one of three issues:

• There is no metadata, for the relying party, available to the Identity Provider and such metadata is required for the IdP to determine where to send a response. Specifically, this occurs in a SAML 2 request when the service provider sends an assertion consumer service index within a message (as the IdP is required to look up the URL associated with that index within metadata).
• The service provider specifies a particular response endpoint but the IdP, in the IDP_HOME/conf/handler.xml, is not configured to support the binding required by that endpoint. For example if the SP requires the IdP send a response back by means of an artifact but the IdP does not support artifacts.
• A generalized case of the previous issue. The Service provider does not specify a particular response endpoint, but the IdP does not support any of bindings listed in the service providers metadata. For example, the IdP is configured to support POST and Redirect and the service provider metadata indicates it only supports POST-SimpleSign and Artifact.

SAML 2 SSO profile is not configured for relying party

This usually indicates a metadata problem, which results in the IdP assigning the incoming request to the category of an "anonymous" relying party. By default, anonymous requests are not handled, so indeed the SAML 2 profile is not configured in that case. To fix it, supply correct/valid metadata for the requesting SP to the IdP. If you do have metadata, it's broken or invalid in some way. Check the idp-process.log for warning messages indicating why it was unacceptable.

In rare cases, you could encounter this error if you change default settings such that particular SPs are not allowed to use that profile. Of course, in that case, the error may be perfectly normal.

org.opensaml.ws.security.SecurityPolicyException: Rejecting replayed message ID '1' from issuer https://your.sp.example.org/shibboleth-sp

This SAML authentication request has already been presented once and you're presenting it again. This is not allowed for security reasons. You should ask your SP to issue a fresh one, and avoid using the "back" button of some browsers.

org.opensaml.ws.security.SecurityPolicyException: Message was rejected due to issue instant expiration

This error is caused when the SAML authentication request received by the IdP was issued too long ago. The machine running the IdP or SP has a clock that is wrong, or you took a very long time to get from your SP to the IdP for some reason. You should always run ntpd and know that VM's will tend to have severe clock issues.

edu.internet2.middleware.shibboleth.idp.authn.AuthenticationEngine: User HttpSession did not contain a login context. Unable to return to authentication engine

This error occurs when the servlet container loses the login context and the user's session across requests to the IdP through the authentication process.

If this error occurs constantly after every authentication, possible causes are:

• The most likely cause of this is:omission of TLS/SSL https:// protection of either the SSO handler or the authentication handler. Both must be protected with SSL or the servlet container will lose the session at some point.
• Erroneous metadata entries which point to /idp/Authn/RemoteUser  or /idp/Authn/UsernamePassword rather than /idp/profile/Shibboleth/SSO produce this error.
• The other known cause is a misconfiguration of a machine with more than one host name. If the host name changes, the session is lost. So, make sure either you only have one hostname or your configure your servlet container(e.g. Tomcat's server.xml) to only use one.

If this error is encountered only occasionally by some users, possible causes are:

• Most likely, the user has set a bookmark for the page https://your.idp.example.org/idp/Authn/UserPassword After successful authentication, the IdP of course doesn't know where to send the user in such a case.
• The user's web browser doesn't accept/send cookies
• You are running Tomcat earlier than 6.0.17. From IdP version 2.1.3, at least Tomcat 6.0.17 is required, otherwise it won't work with certain browsers like Internet Explorer and Chrome.

edu.internet2.middleware.shibboleth.idp.authn.AuthenticationException: No principal name returned from authentication handler.

Upon receipt of an authentication request, an SSO handler will redirect the user to the appropriate authentication handler to login. The authentication handler must set the username and then send the user back to the identity provider's SSO handler. If the authentication handler sends the user back to the SSO handler but fails to set the username, this error will result. Investigate why the authentication handler that was used would have sent back no username, such as omitting protection for the RemoteUser location.

org.opensaml.ws.security.provider.MandatoryAuthenticatedMessageRule: Inbound message issuer was not authenticated.

This rule requires that the peer system entity (e.g an SP from the perspective of the IdP) that is the issuer of the SAML protocol message be authenticated. This happens typically within another prior security policy rule or rules that process for example client TLS certificates or a digital signature over the message (either XML message signature or raw/blob binding-specific signature). Look for log messages indicating failures in these rules to determine the exact cause of the failure.

Common specifc reasons are:

1. Protocol message is delivered over SOAP binding (e.g an attribute query or artifact resolve message) and the client TLS cert is either not present in the request or is not trusted. The former is often caused by incorrect configuration of the web server's and/or servlet container's SSL/TLS endpoint. The latter is often a result of required trust information in metadata for the peer being absent or invalid.
2. Protocol message was delivered over a front-channel binding such as HTTP POST or Redirect, and the message was either not signed or the signature was invalid. The former is because the peer did not sign the message. The latter is often a result of required trust information in metadata for the peer being absent or invalid.

edu.internet2.middleware.shibboleth.idp.profile.saml2.AbstractSAML2ProfileHandler: Unable to construct encrypter, caused by: org.opensaml.xml.security.SecurityException: Could not resolve key encryption credential

If the IdP is configured to encrypt assertions or name ID's to a particular SP, the metadata for the SP (as held by the IdP) must contain the public key that will be used for key encryption. This key encryption key (usually a public key or certificate) must be represented in metadata within the EntityDescriptor/SPSSODescriptor/KeyDescriptor for the SP in question. The KeyDescriptor must either omit the 'use' attribute or have a value of 'use="encryption"'. The KeyInfo contained within the KeyDescriptor must contain either the SP's certificate in an X509Data/X509Certificate element, or must contain the SP's raw public key value in a KeyValue element.

No peer endpoint available to which to send SAML response

This is caused when the IdP has enough information to process an incoming authentication request but can't determine a suitable SP endpoint to send the response back to.

If prior log messages indicate that null metadata is being used, the IdP does not have the SP's metadata and will attempt to construct an endpoint location. For the Shibboleth SSO profile, the endpoint will have a location of the ACS (the shire parameter on the original GET request) and the binding is one of the outgoing bindings supported by the IdP. For the SAML2 SSO profile, the ACS URL is used as the endpoint location. A requested binding the IdP supports will be used; if there is no match, then this defaults to the first binding listed in the IdP'sconfiguration. If all of that fails, this error results.

If the IdP does have the SP metadata, then the SP does not have a named ACS for any of the bindings configured in the IdP.

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'shibboleth.RelyingPartyConfigurationManager': Invocation of init method failed; nested exception is edu.internet2.middleware.shibboleth.common.service.ServiceException: Configuration was not loaded for shibboleth.RelyingPartyConfigurationManager service, error creating components.

This indicates a syntactic or logical error in a config file. Often this is due a configuration element containing a reference to another element which is not present (perhaps commented out).

The bean name (e.g. shibboleth.RelyingPartyConfigurationManager) will often indicate the file in which the error is located. The relationships are defined in service.xml, currently as follows:

• shibboleth.RelyingPartyConfigurationManager: relying-party.xml
• shibboleth.AttributeResolver: attribute-resolver.xml
• shibboleth.AttributeFilterEngine: attribute-filter.xml
• shibboleth.HandlerManager: handler.xml

javax.naming.PartialResultException: Unprocessed Continuation Reference(s)

When using Microsoft Active Directory as a source of attribute data via the LDAP data connector, be aware of AD-specific configuration and deployment issues.

Error processing profile request java.lang.ClassCastException: org.opensaml.saml1.core.impl.RequestImpl cannot be cast to org.opensaml.saml2.core.AttributeQuery

This indicates that the SP being connected to is attempting to make a SAML1 back-channel attribute request to a SAML2 endpoint.  It is usually caused by improperly configured IdP endpoints at the federation.  Some federations do not support SAML2 yet and trying to "fool" them by putting the 2.0 endpoints into their 1.0 fields will not work.