Provide concrete guidance on picking a entityID

Closes:  #1659

docs/simplesamlphp-artifact-idp.md

@@ -35,7 +35,7 @@ Enabling artifact on the IdP
 
 To enable the IdP to send artifacts, you must add the `saml20.sendartifact` option to the `saml20-idp-hosted` metadata file:
 
-    $metadata['urn:x-simplesamlphp:example-idp'] = [
+    $metadata['https://example.org/saml-idp'] = [
         [....]
         'auth' => 'example-userpass',
         'saml20.sendartifact' => TRUE,
@@ -89,7 +89,7 @@ You may therefore have to add the webserver certificate to the metadata that you
 To do this, you need to set the `https.certificate` option in the `saml20-idp-hosted` metadata file.
 That option should refer to a file containing the webserver certificate.
 
-    $metadata['urn:x-simplesamlphp:example-idp'] = [
+    $metadata['https://example.org/saml-idp'] = [
         [....]
         'auth' => 'example-userpass',
         'saml20.sendartifact' => TRUE,

docs/simplesamlphp-authproc.md

@@ -99,7 +99,7 @@ The filters in `authproc.sp` will be executed at the SP side regardless of which
 Filters can be added both in `hosted` and `remote` metadata. Here is an example of a filter added in a metadata file:
 
 ```php
-'urn:x-simplesamlphp:example-idp' => [
+'https://example.org/saml-idp' => [
     'host' => '__DEFAULT_',
     'privatekey' => 'example.org.pem',
     'certificate' => 'example.org.crt',

docs/simplesamlphp-customauth.md

@@ -120,7 +120,7 @@ In that file you should locate the `auth`-option for your IdP, and change it to
 
     <?php
     /* ... */
-    $metadata['urn:x-simplesamlphp:example-idp'] = [
+    $metadata['https://example.org/saml-idp'] = [
         /* ... */
         /*
          * Authentication source to use. Must be one that is configured in

docs/simplesamlphp-ecp-idp.md

@@ -19,7 +19,7 @@ Enabling ECP Profile on the IdP
 
 To enable the IdP to send ECP assertions you must add the `saml20.ecp` option to the `saml20-idp-hosted` metadata file:
 
-    $metadata['urn:x-simplesamlphp:example-idp'] = [
+    $metadata['https://example.org/saml-idp'] = [
         [....]
         'auth' => 'example-userpass',
         'saml20.ecp' => true,

docs/simplesamlphp-googleapps.md

@@ -132,7 +132,7 @@ This is the configuration of the IdP itself. Here is some example config:
 
 ```php
 // The SAML entity ID is the index of this config.
-$metadata['urn:x-simplesamlphp:example-idp'] => [
+$metadata['https://example.org/saml-idp'] => [
 
     // The hostname of the server (VHOST) that this SAML entity will use.
     'host' => '__DEFAULT__',

docs/simplesamlphp-hok-idp.md

@@ -29,7 +29,7 @@ Enabling HoK SSO Profile on the IdP
 
 To enable the IdP to send HoK assertions you must add the `saml20.hok.assertion` option to the `saml20-idp-hosted` metadata file:
 
-    $metadata['urn:x-simplesamlphp:example-idp'] = [
+    $metadata['https://example.org/saml-idp'] = [
         [....]
         'auth' => 'example-userpass',
         'saml20.hok.assertion' => TRUE,

docs/simplesamlphp-idp.md

@@ -142,7 +142,7 @@ The SAML 2.0 IdP is configured by the metadata stored in
 This is a minimal configuration:
 
     <?php
-    $metadata['urn:x-simplesamlphp:example-idp'] = [
+    $metadata['https://example.org/saml-idp'] = [
         /*
          * The hostname for this IdP. This makes it possible to run multiple
          * IdPs from the same configuration. '__DEFAULT__' means that this one

docs/simplesamlphp-metadata-extensions-attributes.md

 SAML V2.0 Metadata Attribute Extensions
 =======================================
 
-<!--
-	This file is written in Markdown syntax.
-	For more information about how to use the Markdown syntax, read here:
-	http://daringfireball.net/projects/markdown/syntax
--->
-
 [TOC]
 
 This is a reference for the SimpleSAMLphp implementation of the [SAML
@@ -76,7 +70,7 @@ Examples
 
 If given the following configuration...
 
-    $metadata['https://www.example.com/saml/saml2/idp/metadata.php'] = [
+    $metadata['https://example.com/saml-idp'] = [
         'host' => 'www.example.com',
         'certificate' => 'example.com.crt',
         'privatekey' => 'example.com.pem',
@@ -91,7 +85,7 @@ If given the following configuration...
 ... will generate the following XML metadata:
 
 	<?xml version="1.0"?>
-	<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://www.example.com/saml/saml2/idp/metadata.php">
+	<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://example.com/saml-idp">
 	  <md:Extensions>
 		<mdattr:EntityAttributes xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
 		  <saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Name="urn:simplesamlphp:v1:simplesamlphp" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">

docs/simplesamlphp-metadata-extensions-rpi.md

@@ -72,7 +72,7 @@ Service Provider:
 
 Identity Provider:
 
-    $metadata['urn:x-simplesamlphp:example-idp'] = [
+    $metadata['https://example.org/saml-idp'] = [
         'host' => '__DEFAULT__',
         ...
         'RegistrationInfo' => [

docs/simplesamlphp-metadata-extensions-ui.md

 SAML V2.0 Metadata Extensions for Login and Discovery User Interface
 =============================
 
-<!--
-    This file is written in Markdown syntax.
-    For more information about how to use the Markdown syntax, read here:
-    http://daringfireball.net/projects/markdown/syntax
--->
-
-  * Author: Timothy Ace [tace@synacor.com](mailto:tace@synacor.com)
-
 [TOC]
 
 This is a reference for the SimpleSAMLphp implementation of the [SAML
@@ -209,7 +201,7 @@ Generated XML Metadata Examples
 
 If given the following configuration...
 
-    $metadata['https://www.example.com/saml/saml2/idp/metadata.php'] = [
+    $metadata['https://example.com/saml-idp'] = [
         'host' => 'www.example.com',
         'certificate' => 'example.com.crt',
         'privatekey' => 'example.com.pem',
@@ -259,7 +251,7 @@ If given the following configuration...
 ... will generate the following XML metadata:
 
     <?xml version="1.0"?>
-    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://www.example.com/saml/saml2/idp/metadata.php">
+    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://example.com/saml-idp">
       <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
         <md:Extensions>
           <mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">

docs/simplesamlphp-modules.md

@@ -154,7 +154,7 @@ this:
 To use this authentication source in a SAML 2.0 IdP, set the
 `auth`-option of the IdP to `'example-static'`:
 
-    'urn:x-simplesamlphp:example-idp' => [
+    'https://example.org/saml-idp' => [
       'host' => '__DEFAULT__',
       'privatekey' => 'example.org.pem',
       'certificate' => 'example.org.crt',

docs/simplesamlphp-reference-idp-hosted.md

@@ -18,7 +18,17 @@ Both files have the following format:
     ];
     /* ... */
 
-The entity ID must be a URI.
+The entity ID must be a URI, that is unlikely to change for technical or
+political reasons. We recommend it to be a domain name you own.
+The URL does not have to resolve to actual content, it's
+just an identifier. If your organization's domain is `example.org`:
+
+    https://example.org/saml-idp
+
+For guidance in picking an entityID, see
+[InCommon's best practice](https://spaces.at.internet2.edu/display/federation/saml-metadata-entityid)
+on the matter.
+
 
 The `host` option is the hostname of the IdP, and will be used to
 select the correct configuration. One entry in the metadata-list can
@@ -391,7 +401,7 @@ These are some examples of IdP metadata
 
     <?php
 
-    $metadata['urn:x-simplesamlphp:example-idp'] = [
+    $metadata['https://example.org/saml-idp'] = [
         /*
          * We use '__DEFAULT__' as the hostname so we won't have to
          * enter a hostname.
@@ -420,7 +430,7 @@ $republishTarget = $dom->createElementNS('http://eduid.cz/schema/metadata/1.0',
 $republishRequest->appendChild($republishTarget);
 $ext = [new \SAML2\XML\Chunk($republishRequest)];
 
-$metadata['urn:x-simplesamlphp:example-idp'] = [
+$metadata['https://example.org/saml-idp'] = [
     'host' => '__DEFAULT__',
     'certificate' => 'example.org.crt',
     'privatekey' => 'example.org.pem',

docs/simplesamlphp-sp.md

@@ -22,10 +22,20 @@ $config = [
     /* This is the name of this authentication source, and will be used to access it later. */
     'default-sp' => [
         'saml:SP',
-        'entityID' => 'https://sp1.example.org/',
+        'entityID' => 'https://myapp.example.org/',
     ],
 ];
 ```
+The entity ID must be a URI, that is unlikely to change for technical or
+political reasons. We recommend it to be a domain name that you own.
+Like above, if your organization's main domain is `example.org` and this SP is
+for the application `myapp`.  The URL does not have to resolve to actual
+content, it's just an identifier. Hence you don't need to and should not change
+it if the actual domain of your application changes.
+
+For guidance in picking an entityID, see
+[InCommon's best practice](https://spaces.at.internet2.edu/display/federation/saml-metadata-entityid)
+on the matter.
 
 For more information about additional options available for the SP,
 see the [`saml:SP` reference](./saml:sp).
@@ -37,11 +47,11 @@ remember to set the EntityID explicitly. Here is an example:
 ```php
     'sp1' => [
         'saml:SP',
-        'entityID' => 'https://sp1.example.org/',
+        'entityID' => 'https://myapp.example.org/',
     ],
     'sp2' => [
         'saml:SP',
-        'entityID' => 'https://sp2.example.org/',
+        'entityID' => 'https://myotherapp.example.org/',
     ],
 ```
 
@@ -64,6 +74,7 @@ Then edit your `authsources.php` entry, and add references to your certificate:
 ```php
     'default-sp' => [
         'saml:SP',
+        'entityID' => 'https://myapp.example.org/',
         'privatekey' => 'saml.pem',
         'certificate' => 'saml.crt',
     ],
@@ -81,9 +92,9 @@ metadata file:
 
 ```php
 <?php
-$metadata['https://example.com'] = [
-    'SingleSignOnService'  => 'https://example.com/simplesaml/saml2/idp/SSOService.php',
-    'SingleLogoutService'  => 'https://example.com/simplesaml/saml2/idp/SingleLogoutService.php',
+$metadata['https://example.org/saml-idp'] = [
+    'SingleSignOnService'  => 'https://example.org/simplesaml/saml2/idp/SSOService.php',
+    'SingleLogoutService'  => 'https://example.org/simplesaml/saml2/idp/SingleLogoutService.php',
     'certificate'          => 'example.pem',
 ];
 ```
@@ -120,7 +131,7 @@ $config = [
          * The entity ID of the IdP this should SP should contact.
          * Can be NULL/unset, in which case the user will be shown a list of available IdPs.
          */
-        'idp' => 'https://idp.example.com',
+        'idp' => 'https://example.org/saml-idp',
     ],
 ];
 ```
@@ -217,7 +228,7 @@ We can also request authentication with a specific IdP:
 
 ```php
 $as->login([
-    'saml:idp' => 'https://idp.example.org/',
+    'saml:idp' => 'https://example.org/saml-idp',
 ]);
 ```
 

modules/multiauth/docs/multiauth.md

@@ -50,7 +50,7 @@ authentication source:
 
     'example-saml' => [
         'saml:SP',
-        'entityId' => 'my-entity-id',
+        'entityId' => 'https://myapp.example.org',
         'idp' => 'my-idp',
     ],
 

modules/saml/docs/sp.md

@@ -239,8 +239,16 @@ Options
 `entityID`
 :   The entity ID this SP should use.
 
-:   If this option is unset, a default entity ID will be generated.
-    The generated entity ID will be a URL where the metadata of this SP can be downloaded.
+:   The entity ID must be a URI, that is unlikely to change for technical or political
+    reasons. We recommend it to be a domain name, like above, if your organization's main
+    domain is `example.org` and this SP is for the application `myapp`.
+    The URL does not have to resolve to actual content, it's
+    just an identifier. Hence you don't need to and should not change it if the actual domain
+    of your application changes.
+
+:   For guidance in picking an entityID, see
+    [InCommon's best practice](https://spaces.at.internet2.edu/display/federation/saml-metadata-entityid)
+    on the matter.
 
 `ForceAuthn`
 :   Force authentication allows you to force re-authentication of users even if the user has a SSO session at the IdP.
@@ -420,20 +428,15 @@ Here we will list some examples for this authentication source.
 
     'example-minimal' => [
         'saml:SP',
+        'entityID' => 'https://myapp.example.org',
     ],
 
 ### Connecting to a specific IdP
 
     'example' => [
         'saml:SP',
-        'idp' => 'https://idp.example.net/',
-    ],
-
-### Using a specific entity ID
-
-    'example' => [
-        'saml:SP',
-        'entityID' => 'https://sp.example.net',
+        'entityID' => 'https://myapp.example.org',
+        'idp' => 'https://example.net/saml-idp',
     ],
 
 ### Encryption and signing
@@ -442,6 +445,7 @@ Here we will list some examples for this authentication source.
 
     'example-enc' => [
         'saml:SP',
+        'entityID' => 'https://myapp.example.org',
 
         'certificate' => 'example.crt',
         'privatekey' => 'example.key',
@@ -457,6 +461,7 @@ Here we will list some examples for this authentication source.
 
     'example-attributes => [
         'saml:SP',
+        'entityID' => 'https://myapp.example.org',
         'name' => [ // Name required for AttributeConsumingService-element.
             'en' => 'Example service',
             'no' => 'Eksempeltjeneste',
@@ -479,6 +484,7 @@ Here we will list some examples for this authentication source.
 
     'example-acs-limit' => [
         'saml:SP',
+        'entityID' => 'https://myapp.example.org',
         'acs.Bindings' => [
             'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
         ],