simplesamlphp-reference-sp-remote.txt

SP remote metadata reference
============================

This is a reference for metadata options available for
`metadata/saml20-sp-remote.php` and `metadata/shib13-sp-remote.php`.
Both files have the following format:

    <?php
    $metadata = array(
        /* The index of the array is the entity ID of this SP. */
        'entity-id-1' => array(
            /* Configuration options for the first SP. */
        ),
        'entity-id-2' => array(
            /* Configuration options for the second SP. */
        ),
        /* ... */
    );
    ?>


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

The following options are common between both the SAML 2.0 protocol
and Shibboleth 1.3 protocol:

`attributes`
:   This should indicate which attributes an SP should receive. It is
    used by for example the `consent:Consent` module to tell the user
    which attributes the SP will receive, and the `core:AttributeLimit`
    module to limit which attributes are sent to the SP.

`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).

`base64attributes`
:   Whether attributes sent to this SP should be base64 encoded. The
    default is `FALSE`.

`description`
:   A description of this SP. Will be used by various modules when they
    need to show a description of the SP to the user.

:   This option can be translated into multiple languages in the same
    way as the `name`-option.

`name`
:   The name of this SP. Will be used by various modules when they need
    to show a name of the SP to the user.</p>

:   This option can be translated into multiple languages by specifying
    the value as an array of language-code to translated name:

        'name' => array(
            'en' => 'A service',
            'no' => 'En tjeneste',
        ),

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

:   Note that this option also exists in the IdP-hosted metadata. This
    entry in the SP-remote metadata overrides the option in the
    IdP-hosted metadata.

`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 IdP-hosted metadata. This
    entry in the SP-remote metadata overrides the option in the
    IdP-hosted metadata.


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

The following SAML 2.0 options are available:

`AssertionConsumerService`
:   The URL of the AssertionConsumerService endpoint for this SP.
    This option is required - without it you will not be able to send
    responses back to the SP.

`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 IdP-hosted metadata. This
    entry in the SP-remote metadata overrides the option in the
    IdP-hosted metadata.

`ForceAuthn`
:   Set this `TRUE` to force the user to reauthenticate when the IdP
    receives authentication requests from this SP. The default is
    `FALSE`.

`NameIDFormat`
:   The `NameIDFormat` this SP should receive. There are three values
    for NameIDFormat which is supported by simpleSAMLphp:

:   1.  `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`
    2.  `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
    3.  `urn:oasis:names:tc:SAML:2.0:nameid-format:email`

:   The `transient` format will generate a new unique ID every time
    the SP logs in.

:   The `persistent` and `email` formats will use the attribute
    specified in the `simplesaml.nameidattribute`-option as the value
    of the ID.

`SingleLogoutService`
:   The URL of the SingleLogoutService endpoint for this SP.
    This option is required if you want to implement single logout for
    this SP. If the option isn't specified, this SP will not be logged
    out automatically when a single logout operation is initialized.

`SingleLogoutServiceResponse`
:   The URL logout responses to this SP should be sent. If this option
    is unspecified, the `SingleLogoutService` endpoint will be used as
    the recipient of logout responses.

`SPNameQualifier`
:   SP NameQualifier for this SP. If not set, the IdP will set the
    SPNameQualifier to be the SP entity ID.

`certificate`
:   Name of certificate file for this SP. The certificate is used to
    verify the signature of messages received from the SP (if
    `redirect.validate`is set to `TRUE`), and to encrypting assertions
    (if `assertion.encryption` is set to TRUE and `sharedkey` is
    unset.)

`signresponse`
:   The default behaviour of simpleSAMLphp is to sign the Assertion
    element in the SAML 2.0 response sent to SPs. This option allows
    you to override this behaviour on a per SP basis. Set this to
    `TRUE` to sign the Response element. `FALSE` will make the SP sign
    the Assertion. If this option is unset, the value from
    `saml2.signresponse` in `config.php` will be used. That value is
    `FALSE` by default.

`simplesaml.nameidattribute`
:   When the value of the `NameIDFormat`-option is set to either
    `email` or `persistent`, this is the name of the attribute which
    should be used as the value of the `NameID`.

:   Typical values can be `mail` for when using the `email` format,
    and `eduPersonTargetedID` when using the `persistent` format.

`simplesaml.attributes`
:   Whether the SP should receive any attributes from the IdP. The
    default value is `TRUE`.

`attributeencodings`
:   What encoding should be used for the different attributes. This is
    an array which maps attribute names to attribute encodings. There
    are three different encodings:

:   -   `string`: Will include the attribute as a normal string. This is
        the default.

:   -   `base64`: Store the attribute as a base64 encoded string. This
        is the default when the `base64attributes`-option is set to
        `TRUE`.

:   -   `raw`: Store the attribute without any modifications. This
        makes it possible to include raw XML in the response.


### Encrypting assertions

It is possible to encrypt the assertions sent to a SP. Currently the
only algorithm supported is `AES128_CBC` or `RIJNDAEL_128`.

There are two modes of encryption supported by simpleSAMLphp. One is
symmetric encryption, in which case both the SP and the IdP needs to
share a key. The other mode is the use of public key encryption. In
that mode, the public key of the SP is extracted from the certificate
of the SP.

`assertion.encryption`
:   Whether assertions sent to this SP should be encrypted. The default
    value is `FALSE`.

`sharedkey`
:   Symmetric key which should be used for encryption. This should be a
    128-bit key. If this option is not specified, public key encryption
    will be used instead.


### 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 overrides the options set in `saml20-idp-hosted`.

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

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

**Example: Configuration for validating messages**

    'redirect.validate' => TRUE,
    'certificate' => 'server.crt',


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

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

`AssertionConsumerService`
:   The URL of the AssertionConsumerService endpoint for this SP.
    This endpoint must accept the SAML responses encoded with the
    `urn:oasis:names:tc:SAML:1.0:profiles:browser-post` encoding.
    This option is required - without it you will not be able to send
    responses back to the SP.

`NameQualifier`
:   What the value of the `NameQualifier`-attribute of the
    `<NameIdentifier>`-element should be. The default value is the
    entity ID of the SP.

`audience`
:   The value which should be given in the `<Audience>`-element in the
    `<AudienceRestrictionCondition>`-element in the response. The
    default value is the entity ID of the SP.

`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. This option overrides the
    option with the same name in the `shib13-idp-hosted.php` metadata
    file.