Document new endpoint format.

git-svn-id: http://simplesamlphp.googlecode.com/svn/trunk@2288 44740490-163a-0410-bde0-09ae8108e29a

docs/simplesamlphp-metadata-endpoints.txt

@@ -0,0 +1,70 @@
+Metadata endpoints
+==================
+
+This document gives a short introduction to the various methods forms metadata endpoints can take in simpleSAMLphp.
+
+The endpoints we have are:
+
+Endpoint                       | Indexed | Default binding
+-------------------------------|---------|----------------
+`ArtifactResolutionService`    | Y       | SOAP
+`AssertionConsumerService`     | Y       | HTTP-POST
+`SingleLogoutService`          | N       | HTTP-Redirect
+`SingleSignOnService`          | N       | HTTP-Redirect
+
+
+The various endpoints can be specified in three different ways:
+
+  * A single string.
+  * Array of strings.
+  * Array of arrays.
+
+
+A single string
+---------------
+
+    'AssertionConsumerService' => 'https://sp.example.org/ACS',
+
+This is the simplest endpoint format.
+It can be used when there is only a single endpoint that uses the default binding.
+
+
+Array of strings
+----------------
+
+    'AssertionConsumerService' => array(
+        'https://site1.example.org/ACS',
+        'https://site2.example.org/ACS',
+    ),
+
+This endpoint format can be used to represent multiple endpoints, all of which use the default binding.
+
+
+Array of arrays
+---------------
+
+    'AssertionConsumerService' => array(
+        array(
+            'index' => 1,
+            'isDefault' => TRUE,
+            'Location' => 'https://sp.example.org/ACS',
+            'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
+        ),
+        array(
+            'index' => 2,
+            'Location' => 'https://sp.example.org/ACS',
+            'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact',
+        ),
+    ),
+
+This endpoint format allows for specifying multiple endpoints with different bindings.
+It can also be used to specify the ResponseLocation attribute on endpoints, e.g. on `SingleLogoutService`:
+
+    'SingleLogoutService' => array(
+        array(
+            'Location' => 'https://sp.example.org/LogoutRequest',
+            'ResponseLocation' => 'https://sp.example.org/LogoutResponse',
+            'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
+        ),
+    ),
+

docs/simplesamlphp-reference-idp-remote.txt

@@ -93,6 +93,8 @@ The following options are common between both the SAML 2.0 protocol and Shibbole
 `SingleSignOnService`
 :   Endpoint URL for sign on. You should obtain this from the IdP. For SAML 2.0, simpleSAMLphp will use the HTTP-Redirect binding when contacting this endpoint.
 
+:   The value of this option is specified in one of several [endpoint formats](./simplesamlphp-metadata-endpoints).
+
 
 SAML 2.0 options
 ----------------
@@ -111,6 +113,8 @@ The following SAML 2.0 options are available:
 `SingleLogoutService`
 :   Endpoint URL for logout requests and responses. You should obtain this from the IdP. Users who log out from your service is redirected to this URL with the LogoutRequest using HTTP-REDIRECT.
 
+:   The value of this option is specified in one of several [endpoint formats](./simplesamlphp-metadata-endpoints).
+
 `SingleLogoutServiceResponse`
 :   Endpoint URL for logout responses. Overrides the `SingleLogoutService`-option for responses.
 

docs/simplesamlphp-reference-sp-remote.txt

@@ -121,6 +121,8 @@ The following SAML 2.0 options are available:
     This option is required - without it you will not be able to send
     responses back to the SP.
 
+:   The value of this option is specified in one of several [endpoint formats](./simplesamlphp-metadata-endpoints).
+
 `AttributeNameFormat`
 :   What value will be set in the Format field of attribute
     statements. This parameter can be configured multiple places, and
@@ -177,6 +179,8 @@ The following SAML 2.0 options are available:
     this SP. If the option isn't specified, this SP will not be logged
     out automatically when a single logout operation is initialized.
 
+:   The value of this option is specified in one of several [endpoint formats](./simplesamlphp-metadata-endpoints).
+
 `SingleLogoutServiceResponse`
 :   The URL logout responses to this SP should be sent. If this option
     is unspecified, the `SingleLogoutService` endpoint will be used as
@@ -314,6 +318,8 @@ The following options for Shibboleth 1.3 SP's are avaiblable:
     This option is required - without it you will not be able to send
     responses back to the SP.
 
+:   The value of this option is specified in one of several [endpoint formats](./simplesamlphp-metadata-endpoints).
+
 `NameQualifier`
 :   What the value of the `NameQualifier`-attribute of the
     `<NameIdentifier>`-element should be. The default value is the