simplesamlphp-idp.txt

SimpleSAMLphp as an Identity Provider
===========================================

<!-- 
	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
-->

  * Version: `$Id$`

simpleSAMLphp documentation
---------------------------


This document is part of the simpleSAMLphp documentation suite.

-  
    [List of all simpleSAMLphp documentation](http://rnd.feide.no/view/simplesamlphpdocs)


This document assumes that you already have a installation of
simpleSAMLphp. Before you continue, make sure all the required
entries in the check list at the bottom is showing green light.

Enabling the Identity Provider functionality
--------------------------------------------

Edit `config.php`, and enable either the SAML 2.0 IdP or the Shib
1.3 IdP, depending on your needs. By default, SAML 2.0 SP IdP
functionality is enabled. Here is an example of SAML 2.0 IdP
enabled:

    'enable.saml20-sp'  => false,
    'enable.saml20-idp' => true,
    'enable.shib13-sp'  => false,
    'enable.shib13-idp' => false,

Authentication modules
----------------------

In the `www/auth` directory, each file represents an authentication
module. The IdP hosted metadata configuration specifies which
authentication module to use for that specific IdP. You can
implement your own authentication module, see
[Appendix&nbsp;A, *Writing your own authentication module*](#sect.customauth).

These authentication modules are included:

auth/login.php
:   This is the standard LDAP backend authentication module. It
    uses LDAP configuration from the `config.php` file.

auth/login-ldapmulti.php
:   This authentication module lets you connect to multiple LDAPs
    depending on the home organization selected by the user.

auth/login-feide.php
:   A multi-LDAP module which looks up the users in LDAP, first
    searching for `eduPersonPrincipalName`.

auth/login-radius.php
:   This authentication module will authenticate users against an
    RADIUS server instead of LDAP.

auth/login-auto.php
:   This module will automatically login the user with some test
    details. You can use this to test the IdP functionality if you do
    not have

:   This module is not completed yet. Work in progress.

auth/login-cas-ldap.php
:   Authentication via CAS, followed by attribute lookup in LDAP.

auth/login-tlsclient.php
:   Authentication via client certificates. (using the apache SSL
    module)


## Configuring the LDAP authentication module

The LDAP module is found in `auth/login.php`.

If you want to perform local authentication using this server,
using the LDAP authentication plugin, the following parameters
should be configured in `config/ldap.php`:

-  
    `auth.ldap.dnpattern`: Which DN to bind to. `%username%` is
    replaced with the user name typed in.

-   `auth.ldap.hostname`: Host name of the LDAP server

-  
    `auth.ldap.attributes`: Search parameter to LDAP. List of
    attributes to be extracted. Set this option to `null` to retrieve
    all attributes available.

-  
    `auth.ldap.enable_tls`: Will perform `ldap_start_tls()` after
    creation the connectino to the LDAP server.


### Searching for the user's DN

It is possible to search for the DN of the user by matching the
username provided by the user against one or more attributes. This
feature is configured by the following options in
`config/ldap.php`:

-  
    `auth.ldap.search.enable`: Whether searching for the user's DN
    should be enabled. Set this to `TRUE` to enable searching.

-  
    `auth.ldap.search.base`: The DN we should search for the user in.

-  
    `auth.ldap.search.attributes`: The attributes we shoule match the
    username against. This can be a single attribute, in which case it
    should be a string, or multiple attributes, in which case it should
    be an array of strings.

    If this is multiple attributes, they will be joined into a search
    query with the following form:
    `(|(<attr1>=<username>)(<attr2>=<username>)...)`

-  
    `auth.ldap.search.username`: The user we should authenticate to the
    LDAP server as before searching. Leave this as `NULL` if it isn't
    necessary to authenticate to the server before searching.

-  
    `auth.ldap.search.password`: The password for the user selected
    with the `auth.ldap.search.username` option.


**Example&nbsp;1.&nbsp;Configuring LDAP for searching**

    $config = array (
      'auth.ldap.hostname' => 'ldap.example.org',
      'auth.ldap.attributes' => NULL,
      'auth.ldap.enable_tls' => FALSE,
    
      /* Enable searching. */
      'auth.ldap.search.enable' => TRUE,
    
      /* The base DN for the search. */
      'auth.ldap.search.base' => 'cn=users,dc=example,dc=org',
    
      /* The user can authenticate using the uid or the email address. */
      'auth.ldap.search.attributes' => array('uid', 'mail'),
    
      'auth.ldap.search.username' => 'uid=authsearch,cn=server,dc=example,dc=org',
      'auth.ldap.search.password' => 'secret',
    );

## Configure the tlsclient authenticaiton module

Configure apache like this:

     SSLEngine On
        SSLCertificateFile    /etc/ssl/private/bridge.pem
        SSLCertificateKeyFile /etc/ssl/private/bridge.key
        SSLCertificateChainFile    /etc/ssl/certs/sureserverEDU.pem
        SSLOptions +StdEnvVars +ExportCertData
        KeepAliveTimeout 60
        SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
        
        SSLCACertificateFile "/etc/ssl/private/tlsclienttest-ca.crt"
        SSLVerifyClient optional
        SSLVerifyDepth  1

And, then configure the identity provider to use the authentication
module: `auth/login-tlsclient.php`.

## Configuring the multi-LDAP authenticaiton module

The module is found in `auth/login-ldapmulti.php`.

## Note

Documentation will be added later. For now, contact the author.

## Configuring the 'login-CAS-LDAP' module for authentication

If you want to connect your identity provider using either CAS or
CAS in combination with LDAP (for attribute retrieval), you may use
the login-cas-ldap module. It is found in
`auth/login-cas-ldap.php`.

The following parameters should be configured in
config/cas-ldap.php:

-  
    make an entry for each identity provider using the identity ID as
    key

-  
    you should make a sub entry with 'cas' as key and the following
    parameters:

    login
    :   the url of the login service of the CAS server



We recomment you always use 'renew=true'v to be able to comply with
a SAML2 'force-auth' request. In addition you may configure either
a 'validate' or a 'serviceValdate' (simpleSAMLphp supports both CAS
ver.1 and ver.2).

'validate' is the CAS ver.1 YES/NO\\r\<username>style validation
which only returns a user name to simpleSAMLphp and which requires
subsequent use of LDAP to retrieve the attributes. The value of
this parameter is the url of the validate service of the CAS
server.

'serviceValidate' is the url of the CAS servers' ver.2 validation.
In some cases the CAS server returns attributes in non-standard XML
format. The login-cas-ldap module allows you to map a list of
attribute names to Xpath expressions which are returned to
simpleSAMLphp from the auth-module. The list is named 'attributes'
(see example for further information).

If you want to use LDAP for retrieving attributes you should make
sub entry with 'ldap' as key and the following parameters:

servers
:   a space separated list of urls in OpelLDAP format (see
    example)

starttls
:   (set to true to secure (encrypt) the LDAP connection)

searchbase
:   the starting point for the LDAP search (simpleSAMLphp always
    uses sub-tree search)

searchattributes
:   an array of attribute names to search for (when used in this
    combination with CAS only one value is needed)

dnpattern
:   a pattern for a dn for the user where %username% is replaced
    with the actual user name for constructing the dn of the users'
    entry. If used no search for the user is performed and the
    constructed dn is used in stead.

attributes
:   the list of attributes retrieved from the users' entry

priv\_user\_dn (optional)
:   the dn of a priviliged user who is allowed to search and read
    the whole LDAP sub-tree for the user if anonynous search and read
    is not allowed

priv\_user\_pw (optional)
:   the password of the priviiliged user


Samle configuration:

    $casldapconfig = array (
        'idpentityid.example.org' => array(
            'cas' => array(
                'login' => 'https://idpentityid.example.org/cas/login',
                'validate' => 'https://idpentityid.example.org/cas/validate',
            ),
            'ldap' => array(
                'servers' => 'idpentityid.example.org',
                'enable_tls' => false,
                'searchbase' => 'dc=example,dc=org',
                'searchattributes' => 'uid',
                'attributes' => array('cn', 'mail'),
            ),
        ),
        'idpentityid2.example.org' => array(
            'cas' => array(
                'login' => 'https://idpentityid2.example.org/login',
                'validate' => 'https://idpentityid2.example.org/validate',
            ),
            'ldap' => array(
                'servers' => 'ldap://idpentityid2.example.org',
                'enable_tls' => false,
                'searchbase' => 'ou=users,dc=example,dc=org',
                'searchattributes' => array('uid', 'mail'), # array for being able to login with either uid or mail.
                'attributes' => null,
                'priv_user_dn' => 'uid=admin,ou=users,dc=example,dc=org',
                'priv_user_pw' => 'xxxxx',
            ),
        ),
    
    );


Setting up an SSL signing certificate
------------------------------------

For test purposes, you can skip this section, and use the
certificate included in the simpleSAMLphp distribution.

For a production system, you must generate a new certificate for
your IdP.

## Warning

The certificate that follows the simpleSAMLphp distribution must
*NEVER* be used in production, as the private key is also included
in the package and can be downloaded by anyone.

Here is an examples of openssl commands to generate a new key and a
selfsigned certificate to use for signing SAML messages:

    openssl genrsa -des3 -out server2.key 1024 
    openssl rsa -in server2.key -out server2.pem
    openssl req -new -key server2.key -out server2.csr
    openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt

The certificate above will be valid for 60 days.

## Note

simpleSAMLphp will only work with RSA and not DSA certificates.


Configuring metadata for an SAML 2.0 IdP
----------------------------------------

To setup a SAML 2.0 IdP you must configure two metadata files:
`saml20-idp-hosted.php` and `saml20-sp-remote.php`.

## Configuring SAML 2.0 IdP Hosted metadata

This is the configuration of the IdP itself. Here is some example
config:

    // The SAML entity ID is the index of this config.
    'idp.example.org' => array(
    
     // The hostname of the server (VHOST) that this SAML entity will use.
     'host'            => 'sp.example.org',
     
     // X.509 key and certificate. Relative to the cert directory.
     'privatekey'      => 'server.pem',
     'certificate'     => 'server.crt',
     
     // Authentication plugin to use. login.php is the default one that uses LDAP.
     'auth'             => 'auth/login.php',
     'authority'        => 'login',
    ),

Parameter details:

### Mandatory metadata fields

index in the `$metadata` array
:   The entity ID of the IdP. In this example: `idp.example.org`.

:   simpleSAMLphp supports dynamic entityIDs that matches a URL
    where simpleSAMLphp automatically generates metadata for the hosted
    entity. To enable this functionality, set the index to be
    `__DYNAMIC:1__`. The index needs to be unique, so when you have
    multiple entries, increase the integer after the colon. When the
    index `__DYNAMIC:1__` is used, the resulting generated entity
    becomes something like:

:   https://sp.example.org/simplesaml/saml2/idp/metadata.php

host
:   Host name of the server running this IdP. One of your metadata
    entries can have the value `__DEFAULT__`. A default entry will be
    used when no other entry matches the current hostname.

privatekey
:   Name of private key file in PEM format, in the `certs`
    directory.

certificate
:   Name of certificate file in PEM format, in the `certs`
    directory.

auth
:   Which authentication module to use. Default:
    `auth/login.php,`the LDAP authentication module.


### Optional metadata fields

privatekey\_pass
:   Passphrase for the private key.

requireconsent
:   Set to true if you want to require user's consent each time
    attributes are sent to an SP.

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.

attributemap
:   Mapping table for translating attribute names. For further
    information, see the *Advances Features* document.

attributealter
:   Table of custom functions that injects or modifies attributes.
    For further information, see the *Advances Features* document.

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

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

    3. 
        Default value:
        `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` (Used as default
        in Shibboleth 2.0)

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

    -   You can define your own value.


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.

privacypolicy
:   This is an absolute URL for where an user can find a
    privacypolicy. If set, this will be shown on the consent page.
    `%SPENTITYID%` in the URL will be replaced with the entity id of
    the service the user is accessing.


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

redirect.sign
:   Boolean, default `false`. To turn on signing of logout requests
    and logout responses, set this flag to true.

:   This option can be overridden by the `redirect.sign` option in
    `saml20-sp-remote`.

redirect.validate
:   Boolean, default `false`. To turn on validation of received
    authentication requests, logout requests and logout responses, set
    this flag to true.

:   This option can be overridden by the `redirect.validate` option
    in `saml20-sp-remote`.


**Example&nbsp;2.&nbsp;Example of configuration for signed messages**

     'redirect.sign' => true,

## Configuring SAML 2.0 SP Remote metadata

In the file `saml20-sp-remote.php`, you configure all SPs that you
trust. Here is an example:

    /*
     * Example simpleSAMLphp SAML 2.0 SP
     */
    'saml2sp.example.org' => array(
     'AssertionConsumerService' => 'https://saml2sp.example.org/simplesaml/saml2/sp/AssertionConsumerService.php', 
     'SingleLogoutService'      => 'https://saml2sp.example.org/simplesaml/saml2/sp/SingleLogoutService.php',
     
     'attributes'               => array('email', 'eduPersonPrincipalName'),
     'name'                     => 'Example service provider',
    ),

Parameter details:

### Mandatory metadata fields

index in the `$metadata` array
:   Entity ID of the given SP. Here: `saml2sp.example.org`.

AssertionConsumerService
:   URL of this SAML 2.0 endpoint. Ask the SP if you are uncertain.
    You may find the endpoint URL in SAML 2.0 metadata received from
    the SP.


### Optional metadata fields

SingleLogoutService
:   URL of this SAML 2.0 endpoint. Ask the SP if you are uncertain.
    You may find the endpoint URL in SAML 2.0 metadata received from
    the SP.

NameIDFormat
:   Set it to the default: `transient`.

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

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

    3. 
        Default value:
        `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` (Used as default
        in Shibboleth 2.0)

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

    -   You can define your own value.


base64attributes
:   Boolean, default `false`: Perform base64 encoding of attributes
    sent to this SP. This parameter must be set according to what the
    SP expects.

simplesaml.nameidattribute
:   If the `NameIDFormat` is set to `email`, then the email address
    is extracted from the attribute with this name. E.g. if
    `simplesaml.nameidattribute` is set to uid, and the authentcation
    module provides an attribute named `uid`, this attribute value is
    set as the NameID.

attributemap
:   Mapping table for translating attribute names. For further
    information, see the *Advances Features* document.

attributealter
:   Table of custom functions that injects or modifies attributes.
    For further information, see the *Advances Features* document.

attributes
:   Array of attributes sent to the SP. If this field is not set,
    the SP receives all attributes available at the IdP.

simplesaml.attributes
:   Boolean, default `true`: Send an attribute statement to the
    SP.

name
:   A descriptive name of the SP. This can be a string, or an
    associative array with language code => translation pairs.

description
:   A longer description of the SP. This can be a string, or an
    associative array with language code => translation pairs.

certificate
:   Name of certificate file for verifying the signature when
    `redirect.validate` is set to `true`.

ForceAuthn
:   Set this `true` to force authentication when receiving
    authentication requests from this SP. The default is `false`.

assertion.enctyption
:   Boolean, default `false`. Defines whether this IdP shoul
    encrypt assertions to this SP.

sharedkey
:   Used for optional symmetric encryption of assertions. Currently
    the algorithm is hardcoded to AES128\_CBC/RIJNDAEL\_128 which uses
    up to 128 bit for the passphrase/key. If you want to use a
    sessionkey which is encrypted by this idp's private key do not
    specify a sharedkey.

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

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.

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. `%SPENTITYID%` in the URL will be replaced with the
    entity id of this service provider.


### 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
:   Boolean, default `false`. To turn on signing of logout requests
    and logout responses, set this flag to true.

:   This option overrides the `redirect.sign` option in
    `saml20-idp-hosted`.

redirect.validate
:   Boolean, default `false`. To turn on validation of received
    authentication requests, logout requests and logout responses, set
    this flag to true.

:   This option overrides the `redirect.validate` option in
    `saml20-idp-hosted`.


**Example&nbsp;3.&nbsp;Example of configuration for validating messages**

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





Configuring metadata for a Shibboleth 1.3 IdP
---------------------------------------------

In the file `shib13-idp-hosted.php`, you configure metadata for the
Shibboleth 1.3 IdP. In the file `shib13-sp-remote.php`, you
configurethe list of trusted SPs using the Shibboleth 1.3 protocol.
This configuration is very similar to configuring SAML 2.0
metadata; please find information in the previous chapter.

## Scoped attributes

It is possible to configure some attributes to be scoped, and
include the Scope-attribute on the attribute values. This is
enabled by setting the `scopedattributes`-option in either
`shib13-sp-remote.php` or `shib13-idp-hosted.php`. If both are
defined, the SP configuration is used.

This option is an array of the names of attributes which should be
treated as scoped. The matching is case-sensitive. A scoped
attribute will be split on the first `@`-sign, and the first part
will be used as the attribute value, while the last part will be
used as the scope.

    /*
     * Example of scopedattributes option. Will use scoped attribute for eduPersonPrincipalName.
     */
    'scopedattributes' => array('eduPersonPrincipalName'),




Test IdP
--------

To test the IdP, it is best to configure two hosts with
simpleSAMLphp, and use the SP demo example to test the IdP.

## Tip

To make the initial test up and running with minimal hassle, use
the login-auto if you do not want to setup a user storage, and use
the included certificate so you do not need to create a new one.

Support
-------

If you need help to make this work, or want to discuss
simpleSAMLphp with other users of the software, you are fortunate:
Around simpleSAMLphp there is a great Open source community, and
you are welcome to join! The forums are open for you to ask
questions, contribute answers other further questions, request
improvements or contribute with code or plugins of your own.

-  
    [simpleSAMLphp homepage (at Feide RnD)](http://rnd.feide.no/simplesamlphp)

-  
    [List of all available simpleSAMLphp documentation](http://rnd.feide.no/view/simplesamlphpdocs)

-  
    [Join the simpleSAMLphp user's mailing list](http://rnd.feide.no/content/simplesamlphp-users-mailinglist)

-  
    [Visit and contribute to the simpleSAMLphp wiki](https://ow.feide.no/simplesamlphp:start)



A. IdP-first setup
------------------

If you do not want to start the SSO flow at the SP, you may use the IdP-first setup. To do this, redirect the user to the SSOService endpoint on the IdP with one parameter `spentityid` that match the SP EntityId that the user should be logged into.

Here is an example of such an url:

	https://sp.example.org/simplesaml/saml2/idp/SSOService.php?spentityid=dev.andreas.feide.no

When the IdP-first flow is used an extra parameter is needed in the `saml20-sp-hosted` metadata. This is the `RelayState` parameter that tells the SP which URL to redirect the user to after the user is successfully authenticated. This typically is the frontpage of your application. An example of this can be:

	'RelayState' => '/',


B. Writing your own authentication module
----------------------------------------------

You can write your own authentication module. Just copy one of the
files in the www/auth directory and play with it, then configure an
IdP to use that module with the auth parameter in the metadata. The
file must support incoming URL parameters, massage the session
object with login state information and return to the RelayState,
and that is all you need to do!

## Tip

Instead of changing the code of the builtin authentication module,
copy it into a new file and edit that. That way, your module will
not be replaced or in conflict when you upgrade simpleSAMLphp to a
newer version.

## Authentication API

The authentication plugin should be placed in the `auth`
directory.

The following parameters must be accepted in the incoming URL:

-  
    `RelayState`: URL where the user is sent after authentication
    within the plugin.

-   `RequestID`: ID of an incoming request.


The initSSO.php takes in addition the following parameters:

-  
    `idpentityid`: This is the entityid of the IdP to authenticate
    with. This parameter is optional, if not set the default for this
    host will be used.

-  
    `spentityid`: This is which SP config to use. This parameter is
    optional, if not set the default for this host will be used.


In hosted IdP metadata there is a config parameter auth that will
tell simpleSAML which authentication plugin that can beu sed.

## Tip

The authentication API is pretty basic. The easiest way to
understand how it works is to look at one of the existing plugins
that is located in the auth directory of your installation.