Using simplesamlphp as an identity provider

Transcription

1 Andreas Åkre Solberg Table of Contents Thu Jun 19 08:20: simplesamlphp documentation... 1 Enabling the Identity Provider functionality... 1 Authentication modules... 1 Configuring the LDAP authentication module... 2 Configure the tlsclient authenticaiton module... 3 Configuring the multi-ldap authenticaiton module... 3 Setting up a SSL signing certificate... 4 Configuring metadata for an SAML 2.0 IdP... 4 Configuring SAML 2.0 IdP Hosted metadata... 4 Configuring SAML 2.0 SP Remote metadata... 6 Configuring metadata for a Shibboleth 1.3 IdP... 8 Test IdP... 9 Support... 9 A. Writing your own authentication module... 9 Authentication API... 9 simplesamlphp documentation This document is part of the simplesamlphp documentation suite. List of all simplesamlphp documentation [ 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 A, Writing your own authentication module. 1

2 These authentication modules are included: Using simplesamlphp auth/login.php auth/login-ldapmulti.php auth/login-feide.php auth/login-radius.php auth/login-auto.php This is the standard LDAP backend authentication module. It uses LDAP configuration from the config.php file. This authentication module lets you connect to multiple LDAPs depending on the home organization selected by the user. A multi-ldap module which looks up the users in LDAP, first searching for edupersonprincipalname. This authentication module will authenticate users against an RADIUS server instead of LDAP. 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>)...) 2

3 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 1. 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 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/logintlsclient.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. 3

4 Setting up a 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: 4

5 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: host privatekey certificate auth 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. Name of private key file in PEM format, in the certs directory. Name of certificate file in PEM format, in the certs directory. Which authentication module to use. Default: auth/login.php, the LDAP authentication module. Optional metadata fields privatekey_pass requireconsent authority attributemap attributealter userid.attribute AttributeNameFormat Passphrase for the private key. Set to true if you want to require user's consent each time attributes are sent to an SP. 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. Mapping table for translating attribute names. For further information, see the Advances Features document. Table of custom functions that injects or modifies attributes. For further information, see the Advances Features document. 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. 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 5

6 3. Default value: urn:oasis:names:tc:saml:2.0:attrnameformat:basic Some examples of values specified in the SAML 2.0 Core Specification: urn:oasis:names:tc:saml:2.0:attrnameformat:unspecified urn:oasis:names:tc:saml:2.0:attrnameformat:uri (Used as default in Shibboleth 2.0) urn:oasis:names:tc:saml:2.0:attrnameformat: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 <simplesamlphproot>/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 <simplesamlphproot>/saml2/idp/singlelogoutservice.php Fields for signing authentication requests 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. By default, simplesamlphp will not sign the HTTP-REDIRECT LogoutRequest. To activate signing, set the request.signing parameter to true. The signing will use the same privatekey/certificate as used for signing the AuthnResponse. request.signing Boolean, default false. Example 2. Example of configured signed requests 'request.signing' => 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' => ' 6

7 'SingleLogoutService' 'attributes' 'name' ), => ' => array(' ', 'edupersonprincipalname'), => 'Example service provider', Parameter details: Mandatory metadata fields index in the $metadata array AssertionConsumerService Entity ID of the given SP. Here: saml2sp.example.org. 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 NameIDFormat SPNameQualifier AttributeNameFormat 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. Set it to the default: transient. SP NameQualifier for this SP. If not set, the IdP will set the SPNameQualifier to be the SP entity ID. 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:attrnameformat:basic Some examples of values specified in the SAML 2.0 Core Specification: urn:oasis:names:tc:saml:2.0:attrnameformat:unspecified urn:oasis:names:tc:saml:2.0:attrnameformat:uri (Used as default in Shibboleth 2.0) urn:oasis:names:tc:saml:2.0:attrnameformat: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. 7

8 simplesaml.nameidattribute attributemap attributealter attributes simplesaml.attributes name description request.signing certificate ForceAuthn assertion.enctyption sharedkey userid.attribute If the NameIDFormat is set to , then the 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. Mapping table for translating attribute names. For further information, see the Advances Features document. Table of custom functions that injects or modifies attributes. For further information, see the Advances Features document. Array of attributes sent to the SP. If this field is not set, the SP receives all attributes available at the IdP. Boolean, default true: Send an attribute statement to the SP. A descriptive name of the SP. (Used in the consent module) A longer description of the SP. (Not used) Boolean, default false. Defines whether this IdP should require signed requests from this SP. Name of certificate file for verifying the signature when request.signing is set to true. Set this true to force authentication when receiving authentication requests from this SP. The default is false. Boolean, default false. Defines whether this IdP shoul encrypt assertions to this SP. 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. 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. 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 8

9 Test IdP Using simplesamlphp configuration is very similar to configuring SAML 2.0 metadata; please find information in the previous chapter. To test the IdP, it is best to configure two hosts with simplesamlphp, and use the SP demo example to test the IdP. Tip Support 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. 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) [ List of all available simplesamlphp documentation [ Join the simplesamlphp user's mailing list [ Visit and contribute to the simplesamlphp wiki [ A. 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 incomming URL: RelayState: URL where the user is sent after authentication within the plugin. RequestID: ID of an incomming request. 9

10 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 be used. 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. 10