From 76af77c4a4de6fd35b18c66a4d7de0029acfa916 Mon Sep 17 00:00:00 2001
From: Olav Morken <olav.morken@uninett.no>
Date: Tue, 11 May 2010 07:39:25 +0000
Subject: [PATCH] Document new endpoint format.
git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@2288 44740490-163a-0410-bde0-09ae8108e29a
---
docs/simplesamlphp-metadata-endpoints.txt | 70 +++++++++++++++++++++
docs/simplesamlphp-reference-idp-remote.txt | 4 ++
docs/simplesamlphp-reference-sp-remote.txt | 6 ++
3 files changed, 80 insertions(+)
create mode 100644 docs/simplesamlphp-metadata-endpoints.txt
diff --git a/docs/simplesamlphp-metadata-endpoints.txt b/docs/simplesamlphp-metadata-endpoints.txt
new file mode 100644
index 000000000..87aa4d4e4
--- /dev/null
+++ b/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',
+ ),
+ ),
+
diff --git a/docs/simplesamlphp-reference-idp-remote.txt b/docs/simplesamlphp-reference-idp-remote.txt
index 96cd6bdfc..e24666c2c 100644
--- a/docs/simplesamlphp-reference-idp-remote.txt
+++ b/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.
diff --git a/docs/simplesamlphp-reference-sp-remote.txt b/docs/simplesamlphp-reference-sp-remote.txt
index ddd929014..f0b9916c8 100644
--- a/docs/simplesamlphp-reference-sp-remote.txt
+++ b/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
--
GitLab