simplesamlphp-reference-idp-hosted.txt

IdP hosted metadata reference
=============================

This is a reference for the metadata files
`metadata/saml20-idp-hosted.php` and `metadata/shib13-idp-hosted.php`.
Both files have the following format:

    <?php
    $metadata = array(
        /* The index of the array is the entity ID of this IdP. */
        'entity-id-1' => array(
            'host' => 'idp.example.org',
            /* Configuration options for the first IdP. */
        ),
        'entity-id-2' => array(
            'host' => '__DEFAULT__',
            /* Configuration options for the default IdP. */
        ),
        /* ... */
    );
    ?>

The entity ID should be an URI. It can, also be on the form
`__DYNAMIC:1__`, `__DYNAMIC:2__`, `...`. In that case, the entity ID
will be generated automatically.

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
have the host `__DEFAULT__`. This entry will be used when no other
entry matches.


Common options
--------------

`auth`
:   Which authentication module should be used to authenticate users on
    this IdP.
<!--
`authority`
:   Who is authorized to create sessions for this IdP. Can be
    `login` for LDAP login module, or `saml2` for SAML 2.0 SP.
    Specifying this parameter is highly recommended.
-->

`authproc`
:   Used to manipulate attributes, and limit access for each SP. See
    the [authentication processing filter manual](http://rnd.feide.no/content/authentication-processing-filters-simplesamlphp).

`certificate`
:   Certificate file which should be used by this IdP, in PEM format.
    The filename is relative to the `cert/`-directory.

`host`
:   The hostname for this IdP. One IdP can also have the `host`-option
    set to `__DEFAULT__`, and that IdP will be used when no other
    entries in the metadata matches.

`privacypolicy`
:   This is an absolute URL for where an user can find a
    privacypolicy. If set, this will be shown on the consent page.

:   Note that this option also exists in the SP-remote metadata, and
    any value in the SP-remote metadata overrides the one configured
    in the IdP metadata.

`privatekey`
:   Name of private key file for this IdP, in PEM format. The filename
    is relative to the `cert/`-directory.

`privatekey_pass`
:   Passphrase for the private key. Leave this option out if the
    private key is unencrypted.

`userid.attribute`
:   The attribute name of an attribute which uniquely identifies
    the user. This attribute is used if simpleSAMLphp needs to generate
    a persistent unique identifier for the user. This option can be set
    in both the IdP-hosted and the SP-remote metadata. The value in the
    sp-remote metadata has the highest priority. The default value is
    `eduPersonPrincipalName`.

:   Note that this option also exists in the SP-remote metadata, and
    any value in the SP-remote metadata overrides the one configured
    in the IdP metadata.


SAML 2.0 options
----------------

The following SAML 2.0 options are available:

`AttributeNameFormat`
:   What value will be set in the Format field of attribute
    statements. This parameter can be configured multiple places, and
    the actual value used is fetched from metadata by the following
    priority:

:   1.  SP Remote Metadata

    2.  IdP Hosted Metadata

:   The default value is:
    `urn:oasis:names:tc:SAML:2.0:attrname-format:basic`

:   Some examples of values specified in the SAML 2.0 Core
    Specification:

:   -   `urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified`

    -   `urn:oasis:names:tc:SAML:2.0:attrname-format:uri` (The default
        in Shibboleth 2.0)

    -   `urn:oasis:names:tc:SAML:2.0:attrname-format:basic` (The
        default in Sun Access Manager)

:   You can also define your own value.

:   Note that this option also exists in the SP-remote metadata, and
    any value in the SP-remote metadata overrides the one configured
    in the IdP metadata.

`SingleSignOnService`
:   Override the default URL for the SingleSignOnService for this
    IdP. This is an absolute URL. The default value is
    `<simpleSAMLphp-root>/saml2/idp/SSOService.php`

:   Note that this only changes the values in the generated
    metadata and in the messages sent to others. You must also
    configure your webserver to deliver this URL to the correct PHP
    page.

`SingleLogoutService`
:   Override the default URL for the SingleLogoutService for this
    IdP. This is an absolute URL. The default value is
    `<simpleSAMLphp-root>/saml2/idp/SingleLogoutService.php`

:   Note that this only changes the values in the generated
    metadata and in the messages sent to others. You must also
    configure your webserver to deliver this URL to the correct PHP
    page.

`saml20.sign.response`
:   Whether `<samlp:Response> messages should be signed.
    Defaults to `TRUE`.

:   Note that this option also exists in the SP-remote metadata, and
    any value in the SP-remote metadata overrides the one configured
    in the IdP metadata.

`saml20.sign.assertion`
:   Whether `<saml:Assertion> elements should be signed.
    Defaults to `TRUE`.

:   Note that this option also exists in the SP-remote metadata, and
    any value in the SP-remote metadata overrides the one configured
    in the IdP metadata.


### Fields for signing and validating messages

simpleSAMLphp only signs authentication responses by default.
Signing of logout requests and logout responses can be enabled by
setting the `redirect.sign` option. Validation of received messages
can be enabled by the `redirect.validate` option.

These options set the default for this IdP, but options for each SP
can be set in `saml20-sp-remote`. Note that you need to add a
certificate for each SP to be able to validate signatures on
messages from that SP.

`redirect.sign`
:   Whether logout requests and logout responses sent from this IdP
    should be signed. The default is `FALSE`.

`redirect.validate`
:   Whether authentication requests, logout requests and logout
    responses received sent from this IdP should be validated. The
    default is `FALSE`


**Example: Configuration for signed messages**

     'redirect.sign' => true,


Shibboleth 1.3 options
----------------------

The following options for Shibboleth 1.3 IdP's are avaiblable:

`scopedattributes`
:   Array with names of attributes which should be scoped. Scoped
    attributes will receive a `Scope`-attribute on the
    `AttributeValue`-element. The value of the Scope-attribute will
    be taken from the attribute value:

:   `<AttributeValue>someuser@example.org</AttributeValue>`

:   will be transformed into

:   `<AttributeValue Scope="example.org">someuser</AttributeValue>`

:   By default, no attributes are scoped. Note that this option also
    exists in the SP-remote metadata, and any value in the SP-remote
    metadata overrides the one configured in the IdP metadata.


Examples
--------

These are some examples of IdP metadata

### Minimal SAML 2.0 / Shibboleth 1.3 IdP ###

    <?php
    $metadata = array(
        /*
         * We use the '__DYNAMIC:1__' entity ID so that the entity ID
         * will be autogenerated.
         */
        '__DYNAMIC:1__' => array(
            /*
             * We use '__DEFAULT__' as the hostname so we won't have to
             * enter a hostname.
             */
            'host' => '__DEFAULT__',

            /* The private key and certificate used by this IdP. */
            'certificate' => 'server.crt',
            'privatekey' => 'server.pem',

            /* The authentication source for this IdP. Must be one
             * from config/authsources.php.
             */
            'auth' => 'example-userpass',
        ),
    );
    ?>