SP registration: Difference between revisions

From RavenWiki
Jump to navigationJump to search
(Minor wording changes)
No edit summary
 
(25 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Shibboleth SPs normally need to have pre-arranged relationships with the Identity Providers (IdPs) against which they want to authenticate. This allows the IdPs to decide what information they want to release to which SPs. This is normally managed by joining one or more 'federations' and registering SPs with them. Federations are administrative organisations that save each SP from having to register individually with each IdP with which it wants to interwork.
{{New Docs}}
 
'''Shibboleth Service Providers (SPs) almost always need pre-arranged relationships with the Identity Providers (IdPs) against which they want to authenticate.'''
 
This allows the IdPs to decide what information they want to release to which SPs. This is normally managed by joining one or more 'federations' and registering SPs with them. Federations are administrative organisations that avoid each SP having to register individually with each IdP with which it wants to interwork.


Operators of SPs in the University currently have the following choices as far as registration is concerned.
Operators of SPs in the University currently have the following choices as far as registration is concerned.


==Remain Anonymous==
==Register in the 'Ucam federation'==
 
The members of the 'Ucam federation' are the Raven IdP and those local SPs that Raven has been configured to recognise. Such SPs won't automatically be able to authenticate users against any IdPs other than the one provided by Raven.
 
Anyone with a current Raven account can register and subsequently manage an SP in the Ucam Federation without further formality. Registrations are managed by the Shibboleth Metadata administration site at
 
  https://metadata.raven.cam.ac.uk/


The Raven IdP is unusual in that it will provide authentication and some attribute values to any SP even if it knows nothing about it. It is therefore possible to completely avoid registering an SP if it will only interact with Raven.
'''To register an SP you'll need to supply'''


The downside to this is that Raven will describe such a service as an 'Unknown Service Provider' when asking people for permission to release information to it, and only a limited number of attributes will be released (see [[Attributes released by the Raven IdP#Completely unregistered ('Anonymous')|Attributes released by the Raven IdP - Completely unregistered]]. In addition, attempts to use the Browser/Artifact profile will fail (with the SP reporting an 'opensaml::BindingException' with the reason 'Invalid HTTP method (POST)') for reasons that are explained [https://spaces.internet2.edu/display/SHIB/PostToArtifactHandler here].
* A short name for it
* Optionally a longer description
* The University institution (department, college, etc) responsible for the SP
* At least one email contact address of a person or role responsible for the SP - role addresses are greatly preferred
* A copy of the SAML metadata for the SP - see [[SP Metadata]] for information on generating metadata and why you need to be careful about using http: vs.  https:


However one of the attributes that is released carries the authenticated user's 'eduPerson Principal Name' which includes their CRSid. This may be sufficient for replicating UcamWebauth-based functionality.


An anonymous SP is unlikely to be able to authenticate users against any IdPs other than the one provided by Raven.
'''NOTES'''
::The Shibboleth Metadata administration site expects to receive metadata generated by the Shibboleth Consortium SP software. It should be possible to upload any syntactically-valid metadata, but in some cases this may need to be edited before submission. Unfortunately the site currently responds badly ('Internal server error') to some things it doesn't like, rather than producing a helpful error message. Changes you may need to make:


==Register in the 'Ucam federation'==
::* Remove any XML declaration at the start of the metadata (e.g. remove <?xml version="1.0" encoding="UTF-8"?>)
::* If the metadata consists of an <EntitiesDescriptor> element wrapping an <EntityDescriptor> then remove the <EntitiesDescriptor> element by deleting its opening and closing tags, but transfer any XML namespace declarations (attributes starting 'xmlns:') from the <EntitiesDescriptor> element to the <EntityDescriptor> element.
::* Remove any ID= attribute from the <EntityDescriptor> (only necessary if metadata has already been uploaded with the same ID)
 
 
SPs are automatically classified as 'internal' or 'external', based on the hostnames used in the various service endpoint URLs in the metadata. Internal sites (those that exclusively use hostnames ending .cam.ac.uk) automatically get access to [[Attributes released by the Raven IdP#University SPs | the extended attribute information available to SP operated by the University]]. External sites (all the rest) don't automatically get access to this extra information. This automatic classification can be administratively overridden in appropriate cases on application to Raven Support.
 
How we control access to these SP registrations is simple. The person who initially registers an SP automatically becomes an 'authorised user' with permission to subsequently modify or delete this registration. Users will see a list of the registrations that they are responsible for on the front page of the administration site.
 
Authorised users can add and remove further authorised users - every registration should have several current authorised users to guard against administrators leaving the University, being temporally unavailable, etc. The one limitation is that an authorised user can't remove themselves - they have to get another authorised users to do this for them. This helps to guard against changes that can't easily be undone.


The 'Ucam federation' consists of the Raven IdP and a set of local SPs that Raven has been explicitly configured to recognise. University SPs in the Ucam federation (or in the UK federation [[#UK federation|see below]]) receive a much larger list of attributes - see [[Attributes released by the Raven IdP#Registered SPs|Attributes released by the Raven IdP - Registered SPs]] and [[Attributes released by the Raven IdP#University SPs|Attributes released by the Raven IdP University SPs]]. Such SPs can also use the Browser/Artifact profile, but are still unlikely to be able to authenticate users against any IdPs other than the one provided by Raven.
Changes made on the administration site should be reflected on the the Raven IdP in around a minute.


To register an SP in the Ucam federation, the person taking responsibility for operating the web site should send an email to raven-support@ucs.cam.ac.uk containing the following:
'''SPs with no current authorised users and no working contact addresses may be de-registered without notice.'''


* A clear statement that registration in the Ucam federation is being requested
The aggregated UCam Federation metadata file is available at http://shib.raven.cam.ac.uk/ucamfederation-sp-metadata.xml.
* A name and email address of one or more people or roles responsible for the server. They can be identified as being 'technical', 'support', 'administrative', 'billing', or 'other'. This will default to 'technical' and the name and email address of the person sending the email.
* A short name (a few words at most) to identify the site.
* The URL of a web page providing a description of the organisation providing the service.
* A copy of the automatically generated metadata for your SP.


The default configuration files specify a an automatic metadata generator which will generate metadata matching your your configuration. You can access it it at
  http://''<host-name>''/Shibboleth.sso/Metadata
or (better, but only if your site supports https):
  https://''<host-name>''/Shibboleth.sso/Metadata
Please attach this metadata file to your email registration request: do not embed its contents within the email message.


Raven Support will contact the sender of the request and any additional addresses specified once the application has been accepted and the corresponding metadata loaded into Raven.


==Register in the 'UK federation'==
==Register in the 'UK federation'==
Line 39: Line 52:
Membership of the UK federation is subject to the [http://www.ukfederation.org.uk/library/uploads/Documents/rules-of-membership.pdf Rules of membership for the federation] which the University has accepted. Operators of SPs within the University must agree that their SPs will be operated within the rules before their SP can be registered in it.
Membership of the UK federation is subject to the [http://www.ukfederation.org.uk/library/uploads/Documents/rules-of-membership.pdf Rules of membership for the federation] which the University has accepted. Operators of SPs within the University must agree that their SPs will be operated within the rules before their SP can be registered in it.


The UK federation has more restrictive requirements than the Ucam federation. In particular it requires that the SP supports https:, at least for access to the various URl's used internally by Shibboleth, and that the SSL certificate used to protect both 'browser' access to the SP and the certificate used for direct communication between the SP and the IdP be issued by one of a number of approved global SPs. Self-signed certificates are not acceptable. See [[Using SSL and certificates]] for more information.
The UK federation has more restrictive requirements than the Ucam federation. In particular it requires that the SP supports https:, at least for access to the various URL's used internally by Shibboleth. See [[SSL, certificates and security with Shibboleth]] for more information.


Instructions on configuring an SP to work within the federation are available at  
Instructions on configuring an SP to work within the federation are available at  
Line 45: Line 58:
   http://www.ukfederation.org.uk/content/Documents/Setup2SP
   http://www.ukfederation.org.uk/content/Documents/Setup2SP


Once configured with the correct certificate installed, the person taking responsibility for operating the web site should send an email to raven-support@ucs.cam.ac.uk (not direct to the federation) containing the following:
Once configured with the correct certificate installed, the person taking responsibility for operating the web site should send an email to [mailto:raven-support@uis.cam.ac.uk raven-support@uis.cam.ac.uk] (not direct to the federation) containing the following:


* A clear statement that registration in the UK federation is being requested
* A clear statement that registration in the UK federation is being requested
* An undertaking to abide by the [http://www.ukfederation.org.uk/library/uploads/Documents/rules-of-membership.pdf Rules of membership for the federation]
* An undertaking to abide by the [http://www.ukfederation.org.uk/library/uploads/Documents/rules-of-membership.pdf Federation Rules]


and all the information listed towards the bottom of
and all the information listed towards the bottom of
Line 54: Line 67:
   http://www.ukfederation.org.uk/content/Documents/Register2SP
   http://www.ukfederation.org.uk/content/Documents/Register2SP


Raven Support will contact the sender of the request and any additional addresses specified once the application has been accepted by the UK federation and the corresponding metadata published and loaded into Raven.
See [[SP Metadata]] for information on generating metadata.
 
Raven Support will contact the sender of the request and any additional addresses specified once the application has been accepted by the UK federation and the corresponding metadata published.
 
The Raven IdP loads metadata for all UK federation SPs. There is no value, and some potential problems, in registering an SP in both the Ucam and UK federations. Administrators are advised to remove the Ucam federation registration for any site that they subsequently register in the UK federation once the site appears in the UK federation metadata file.
 
The aggregate UK federation metadata file is available at http://metadata.ukfederation.org.uk/ukfederation-metadata.xml (see [https://www.ukfederation.org.uk/content/Documents/OperationalInfo UK federation Operational Information] for more information). Caution: LARGE!
 
==Register in some other federation==
 
Other federations exist, in particular [http://www.incommonfederation.org/ InCommon] that provides similar facilities in the USA to those provided by the UK federation here. The University is not at present a member of any other federations and this may (depending on the relevant federation rules) prevent University SPs from being registered in them.
 
If a University SP needs to register in any such federations and action is needed centrally by the University to make this happen then the person responsible for the site should contact [mailto:raven-support@uis.cam.ac.uk raven-support@uis.cam.ac.uk] in the first instance. The process of joining a federation can be protracted involving as it does legally-binding contracts that have to be considered in detail, so as much notice as possible needs to be given. SP operators must accept that in some cases it may be impossible for the University to join some federations and that it may therefore be impossible to register their SP in them - SP operators are urged not to commit themselves to membership before they confirm if it is actually possible.
 
==Inter-working with arbitrary IdPs==
 
It is entirely possible for an SP to arrange to inter-work with one or more IdPs that are not part of any recognised federation, either instead of registering with recognised federations or alongside doing so. This is will involve coming to agreements with each IdP on Data Protection and other administrative issues, and then collecting and loading metadata describing each IdP into your SP. Instructions for doing this are beyond the scope of this document, but [mailto:raven-support@uis.cam.ac.uk Raven Support] may be able to advise.

Latest revision as of 11:41, 3 March 2020

We're working on improving Raven resources for developers and site operators.

Try out the new Raven documentation for size.

Shibboleth Service Providers (SPs) almost always need pre-arranged relationships with the Identity Providers (IdPs) against which they want to authenticate.

This allows the IdPs to decide what information they want to release to which SPs. This is normally managed by joining one or more 'federations' and registering SPs with them. Federations are administrative organisations that avoid each SP having to register individually with each IdP with which it wants to interwork.

Operators of SPs in the University currently have the following choices as far as registration is concerned.

Register in the 'Ucam federation'

The members of the 'Ucam federation' are the Raven IdP and those local SPs that Raven has been configured to recognise. Such SPs won't automatically be able to authenticate users against any IdPs other than the one provided by Raven.

Anyone with a current Raven account can register and subsequently manage an SP in the Ucam Federation without further formality. Registrations are managed by the Shibboleth Metadata administration site at

 https://metadata.raven.cam.ac.uk/

To register an SP you'll need to supply

  • A short name for it
  • Optionally a longer description
  • The University institution (department, college, etc) responsible for the SP
  • At least one email contact address of a person or role responsible for the SP - role addresses are greatly preferred
  • A copy of the SAML metadata for the SP - see SP Metadata for information on generating metadata and why you need to be careful about using http: vs. https:


NOTES

The Shibboleth Metadata administration site expects to receive metadata generated by the Shibboleth Consortium SP software. It should be possible to upload any syntactically-valid metadata, but in some cases this may need to be edited before submission. Unfortunately the site currently responds badly ('Internal server error') to some things it doesn't like, rather than producing a helpful error message. Changes you may need to make:
  • Remove any XML declaration at the start of the metadata (e.g. remove <?xml version="1.0" encoding="UTF-8"?>)
  • If the metadata consists of an <EntitiesDescriptor> element wrapping an <EntityDescriptor> then remove the <EntitiesDescriptor> element by deleting its opening and closing tags, but transfer any XML namespace declarations (attributes starting 'xmlns:') from the <EntitiesDescriptor> element to the <EntityDescriptor> element.
  • Remove any ID= attribute from the <EntityDescriptor> (only necessary if metadata has already been uploaded with the same ID)


SPs are automatically classified as 'internal' or 'external', based on the hostnames used in the various service endpoint URLs in the metadata. Internal sites (those that exclusively use hostnames ending .cam.ac.uk) automatically get access to the extended attribute information available to SP operated by the University. External sites (all the rest) don't automatically get access to this extra information. This automatic classification can be administratively overridden in appropriate cases on application to Raven Support.

How we control access to these SP registrations is simple. The person who initially registers an SP automatically becomes an 'authorised user' with permission to subsequently modify or delete this registration. Users will see a list of the registrations that they are responsible for on the front page of the administration site.

Authorised users can add and remove further authorised users - every registration should have several current authorised users to guard against administrators leaving the University, being temporally unavailable, etc. The one limitation is that an authorised user can't remove themselves - they have to get another authorised users to do this for them. This helps to guard against changes that can't easily be undone.

Changes made on the administration site should be reflected on the the Raven IdP in around a minute.

SPs with no current authorised users and no working contact addresses may be de-registered without notice.

The aggregated UCam Federation metadata file is available at http://shib.raven.cam.ac.uk/ucamfederation-sp-metadata.xml.


Register in the 'UK federation'

The UK federation provides federation services to the UK education sector. Members include universities, colleges and schools in the UK, and their suppliers. The University of Cambridge is a member of the UK federation and contact with it is managed by Management Liaison contacts forming part of Raven Support. The University can register SPs in the federation and such SPs can interwork with IdPs in peer organisations, opening up the possibility of authenticating people elsewhere in UK education to web sites in Cambridge.

Membership of the UK federation is subject to the Rules of membership for the federation which the University has accepted. Operators of SPs within the University must agree that their SPs will be operated within the rules before their SP can be registered in it.

The UK federation has more restrictive requirements than the Ucam federation. In particular it requires that the SP supports https:, at least for access to the various URL's used internally by Shibboleth. See SSL, certificates and security with Shibboleth for more information.

Instructions on configuring an SP to work within the federation are available at

 http://www.ukfederation.org.uk/content/Documents/Setup2SP

Once configured with the correct certificate installed, the person taking responsibility for operating the web site should send an email to raven-support@uis.cam.ac.uk (not direct to the federation) containing the following:

  • A clear statement that registration in the UK federation is being requested
  • An undertaking to abide by the Federation Rules

and all the information listed towards the bottom of

 http://www.ukfederation.org.uk/content/Documents/Register2SP

See SP Metadata for information on generating metadata.

Raven Support will contact the sender of the request and any additional addresses specified once the application has been accepted by the UK federation and the corresponding metadata published.

The Raven IdP loads metadata for all UK federation SPs. There is no value, and some potential problems, in registering an SP in both the Ucam and UK federations. Administrators are advised to remove the Ucam federation registration for any site that they subsequently register in the UK federation once the site appears in the UK federation metadata file.

The aggregate UK federation metadata file is available at http://metadata.ukfederation.org.uk/ukfederation-metadata.xml (see UK federation Operational Information for more information). Caution: LARGE!

Register in some other federation

Other federations exist, in particular InCommon that provides similar facilities in the USA to those provided by the UK federation here. The University is not at present a member of any other federations and this may (depending on the relevant federation rules) prevent University SPs from being registered in them.

If a University SP needs to register in any such federations and action is needed centrally by the University to make this happen then the person responsible for the site should contact raven-support@uis.cam.ac.uk in the first instance. The process of joining a federation can be protracted involving as it does legally-binding contracts that have to be considered in detail, so as much notice as possible needs to be given. SP operators must accept that in some cases it may be impossible for the University to join some federations and that it may therefore be impossible to register their SP in them - SP operators are urged not to commit themselves to membership before they confirm if it is actually possible.

Inter-working with arbitrary IdPs

It is entirely possible for an SP to arrange to inter-work with one or more IdPs that are not part of any recognised federation, either instead of registering with recognised federations or alongside doing so. This is will involve coming to agreements with each IdP on Data Protection and other administrative issues, and then collecting and loading metadata describing each IdP into your SP. Instructions for doing this are beyond the scope of this document, but Raven Support may be able to advise.