Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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:

  1. Teach your service about SURFconext, i.e. configure relevant SURFconext configuration parameters in your software;
  2. 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:

  1. Using metadata (RECOMMENDED)
  2. 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:

-----BEGIN CERTIFICATE-----
MIIDyzCCArOgAwIBAgIJAMzixtXMUH1NMA0GCSqGSIb3DQEBBQUAMHwxCzAJBgNV
BAYTAk5MMRAwDgYDVQQIDAdVdHJlY2h0MRAwDgYDVQQHDAdVdHJlY2h0MRUwEwYD
VQQKDAxTVVJGbmV0IEIuVi4xEzARBgNVBAsMClNVUkZjb25leHQxHTAbBgNVBAMM
FGVuZ2luZS5zdXJmY29uZXh0Lm5sMB4XDTExMDEyNDEwMTg1N1oXDTIxMDEyMzEw
MTg1N1owfDELMAkGA1UEBhMCTkwxEDAOBgNVBAgMB1V0cmVjaHQxEDAOBgNVBAcM
B1V0cmVjaHQxFTATBgNVBAoMDFNVUkZuZXQgQi5WLjETMBEGA1UECwwKU1VSRmNv
bmV4dDEdMBsGA1UEAwwUZW5naW5lLnN1cmZjb25leHQubmwwggEiMA0GCSqGSIb3
DQEBAQUAA4IBDwAwggEKAoIBAQDMJ6v+f3owS3KR5IXSil+3XFwGvCVeYx3jDOFK
AnwvXlDpTu+t730b8/spHtlopyJVAlb6qBIPN7R4TGTLqiu0zebYsYx/PtqCk5cb
u9qs3h+p2BBoTXVwXA/ZYi0tqtxp04hcNrRj1TAgLyC0S+KASTF+zzccAcjTBid5
EMioo+YllgSEobWJ4X33XVRqNrikAPDsNmDrdKUi257JSO2xhVIG5lbtmDaL5ORC
D56oRmVdp7VQTEQ3Yass8J5Rn+Ub6WmRBYeG+KzFBvtyBput2o0/gvtJn9L+NWeD
B0LyUPaUYG/X4GF14FcmFQfz7I5jBCNHtPcLJbPYbZKQNhz/AgMBAAGjUDBOMB0G
A1UdDgQWBBS9QqP8gtMM6nm4oYzNbgqhEDP1aDAfBgNVHSMEGDAWgBS9QqP8gtMM
6nm4oYzNbgqhEDP1aDAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQBH
2qyYwLwesIOxUTj+NJ0VXRBDH8VecNLiUUs9Np4x8A0pxLvlNnv5TdJAruEg1LSV
mAqqPUdAB2m7CKDeUVM9cwOB7vqelV2GNgOfevXi+DZRMffyyE8qyIcnTqvDOgcR
8qGTPSVT+SIsOkV9bYrjltrbnal7cJermsA8SC5w/pjLaOHI1xIZHquZzymWoN3Z
fz2CQg2r5o+AURYd74GrHhHqVa9VrdWtcimB+vTQQihoLt8YciehpJjOMpx2D66e
FfpC8ix31RRdjAVIo1y33h1yU3gEHePDbOthZE+lpXi2WJqO85H85LqJOtgn2WPI
3P2Tx32Cq1WXCYkxLaPI
-----END CERTIFICATE-----

You can also download the certificate file here:

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.

  • No labels