Introduction

This page describes the steps a service provider needs to go through in order to interface with SURFconext to externalize their user authentication. This is just the technical procedure. An introduction to SAML can be found on Wikipedia. The SAML profile supported by SURFconext is the Interoperable SAML 2.0 Web Browser SSO Deployment Profile.

This page will describe the relevant configuration for the service provider and how to request a connection.

To connect your service to SURFconext you need to do two things:

Teach your service about SURFconext, i.e. configure relevant SURFconext configuration parameters in your software;
Tell us about your service so we can configure it in SURFconext, i.e. provide a link to your service's metadata;

SAML

The authentication protocol used is SAML 2.0. This means that the service provider will trust SURFconext to authenticate users and provide (signed) data with user information to the service provider that can be trusted. In the remainder of this document, if we refer to 'SAML' we mean SAML 2.0.

If a user is successfully authenticated using SAML, you can get more information about the user by inspecting the attributes of the user. Most of the attributes are self-explanatory (such as the attributes givenName and displayName, but other attributes may need more explanation about their intended use cases. Please contact surfconext-beheer@surfnet.nl if you have questions about how to best use attributes.

How to configure SURFconext as my Identity Provider

SURFconext is a so called 'hub-and-spoke' federation. There is only one IdP for your SP to connect to. There are two ways to configure SURFconext as an Identity Provider to your service provider:

Using metadata (RECOMMENDED)
Manually

Using Metadata

The SAML metadata for the SURFconext IdP can be downloaded here. This will use SURFconext to provide "Where Are You From" functionality, i.e.: make the user select their home institution from the list of institutes that are allowed to access your service.

If you want to provide your own "WAYF", e.g. to "brand" the user interface or connect to multiple federations you can use the metadata containing all IdPs connected to SURFconext which can be found here. See section on IdP discovery for more information on this.

For other, specialized versions of the metadata look here.

The same metadata can be used for connecting to both the Do-It-Yourself/ testing platform as well as to the production platform.

Manual configuration

If there is no metadata import functionality available in the service provider's software, the SSO endpoint and certificate need to be configured manually:

SSO endpoint: https://engine.surfconext.nl/authentication/idp/single-sign-on
Certificate:

You can also download the certificate file here:

PEM format

The SSO endpoint is used by your SAML software to send an AuthnRequest to. The certificate is used to verify the SAML assertion sent to your ACS (see below).

If your software only needs the certificate fingerprint, like for example in simpleSAMLphp, you also use the fingerprint of the certificate instead:

$ openssl x509 -inform PEM -in SURFconext.pem -noout -fingerprint
SHA1 Fingerprint=A3:6A:AC:83:B9:A5:52:B3:DC:72:4B:FC:0D:7B:BA:62:83:AF:5F:8E

How to tell SURFconext about your service

In order for us to configure your server we would like to receive your metadata URL. That way we can easily configure your service and you'll be able to update the metadata without telling us about any changes. If you cannot provide a link to metadata containing the information below we at least we need to have the following information:

Service Entity ID;
Assertion Consuming Service URL, accepting HTTP POSTs over HTTPS with a trusted and valid SSL certificate;
Technical contact information:
- Given name;
- Family name;
- E-mail address;
Name of the service;
The attribute your service requires including the reason why the attribute is required (see below for a list of available attributes);
A description of your service (what is it, what does it do, why would someone want to use it, ...);
Attach a logo of your service. Size: 500x300px, png-format with transparent background.
(OPTIONAL) A list of custom attributes required or attribute mapping between our attributes and yours (NOT RECOMMENDED).

Send this information to surfconext-beheer@surfnet.nl and we'll get back to you when it is configured. This usually takes two to three working days.

Once this is done the basics should work and you should be able to authenticate to your service using SURFconext. Initially your service will be placed in TEST mode where you can play around with some identity providers configured for testing (see Do-It-Yourself Platform). Moving your service to production will require additional information (see: TODO).

Your (SP) Metadata

Below is a metadata example file for a service using simpleSAMLphp. It will tell SURFconext about the Entity ID, the ACS, the required (and optional) attributes and the (technical) contact information:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://frkosp.wind.surfnet.nl/simplesamlphp/module.php/saml/sp/metadata.php/default-sp">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol">
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://frkosp.wind.surfnet.nl/simplesamlphp/module.php/saml/sp/saml2-logout.php/default-sp"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://frkosp.wind.surfnet.nl/simplesamlphp/module.php/saml/sp/saml2-acs.php/default-sp" index="0"/>
    <md:AttributeConsumingService index="0">
      <md:ServiceName xml:lang="en">FrKoSP</md:ServiceName>
      <md:ServiceDescription xml:lang="en">This is FrKoSP's demonstration service</md:ServiceDescription>
      <md:RequestedAttribute Name="urn:mace:dir:attribute-def:mail" isRequired="true"/>
      <md:RequestedAttribute Name="urn:mace:dir:attribute-def:displayName"/>
    </md:AttributeConsumingService>
  </md:SPSSODescriptor>
  <md:ContactPerson contactType="technical">
    <md:GivenName>François</md:GivenName>
    <md:SurName>Kooman</md:SurName>
    <md:EmailAddress>francois.kooman@surfnet.nl</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>

Attributes

The following attributes can be included in the response from SURFconext to the service provider. They contain information about the authenticated user. This will make it possible for the service to for instance show the "displayName" of the user in the interface or determine the affiliation of the user for authorization. For instance a student has a different view than a teacher.

Attribute	Attribute (OID)	Example	Remarks
`urn:mace:dir:attribute-def:displayName`	`urn:oid:2.16.840.1.113730.3.1.241`	John Doe	Usually this is equal to `cn`.
`urn:mace:dir:attribute-def:mail`	`urn:oid:0.9.2342.19200300.100.1.3`	john@example.org	This attribute can contain multiple email addresses.
`urn:mace:dir:attribute-def:sn`	`urn:oid:2.5.4.4`	Doe
`urn:mace:dir:attribute-def:cn`	`urn:oid:2.5.4.3`	John Doe
`urn:mace:dir:attribute-def:givenName`	`urn:oid:2.5.4.42`	John
`urn:mace:dir:attribute-def:eduPersonPrincipalName`	`urn:oid:1.3.6.1.4.1.5923.1.1.1.6`	john_doe@example.org	This is not necessarily a valid email address!
`urn:mace:terena.org:attribute-def:schacHomeOrganization`	`urn:oid:1.3.6.1.4.1.1466.115.121.1.15`	example.org
`urn:mace:dir:attribute-def:uid`	`urn:oid:0.9.2342.19200300.100.1.1`	john_doe	You should not use this for (unique) user identification purposes in your service!
`urn:mace:dir:attribute-def:eduPersonAffiliation`	`urn:oid:1.3.6.1.4.1.5923.1.1.1.1`	student	Supported values: `employee`, `student` and `affiliate`.
`urn:mace:dir:attribute-def:isMemberOf`	`urn:oid:1.3.6.1.4.1.5923.1.5.1.1`	urn:collab:org:surf.nl	Contact us before you want to use this attribute!

In order to uniquely identify a user the persistent Name ID value can be used. This value can be extracted from the Name ID and is also available in the attribute urn:mace:dir:attribute-def:eduPersonTargetedID (urn:oid:1.3.6.1.4.1.5923.1.1.1.10) if the SAML software does not support extracting Name ID values.

Currently we convert schacHomeOrganization to the wrong OID. The correct value is urn:oid:1.3.6.1.4.1.25178.1.2.9. This will be fixed soonish.

UID is the unique identifier of the user at the home institution, it is not unique for all users in SURFconext! Use eduPersonTargetedID (preferred) or eduPersonPrincipalName if you need to uniquely identify users.

A service provider SHOULD only at most request the following attributes, requesting these and any other attributes MUST BE accompanied by an explanation of why they are needed:

urn:mace:dir:attribute-def:displayName
urn:mace:dir:attribute-def:mail
urn:mace:dir:attribute-def:cn
urn:mace:dir:attribute-def:eduPersonAffiliation
urn:mace:terena.org:attribute-def:schacHomeOrganization

The attributes are available in both human readable format and OID format. See also this eduGAIN recommendation.

Ultimately it is up to the identity provider and service provider to agree on a set of attributes to be released by the IdP, SURFconext only mediates. However, it is strongly recommend to stick to the above attributes as they are standardized and ensure greater interoperability.

Provisioning

Assuming some kind of user administration is required at your service, the recommended way to deal with people logging in through SURFconext is that on first login an account is automatically created for the user and bound to the (persistent) Name ID value in the SAML assertion.

Some service providers will offer additional APIs or web interfaces to manually configure user accounts and also delete (deprovision) them. It is highly undesirable that the (proprietary) API needs to be used to (manually) create user accounts before users are able to login.

Group API

If your services want to make use of group information available through the SURFconext API please request this as well. More information about the API can be found at API.

Page tree

Attributes in SURFconext