Overview
Internet2's NET+ offerings are built on top of identity services offered by participants in the InCommon Federation. InCommon provides a secure common trust fabric and rules of the road to foster the sharing of services and user data by its membership. This document will help orient you with InCommon identity practices in preparation for becoming a NET+ provider.
InCommon identifies an authoritative identity provider (IdP) for each organization and will supply that organization with the information they need in order to connect to your service provider (SP). Participants themselves are responsible for providing user data to you in a bilateral transaction that utilizes InCommon as substrate.
A federated identity transaction typically starts when a user is sent to their home IdP to authenticate, usually after attempting to access your application. The user authenticates as necessary after which user attributes are gathered about them. This information is packaged in a signed, encrypted SAML V2.0 assertion. These assertions are short-lived tokens generated dynamically each time a user wants to create a session at a service provider. Each assertion conveys authentication information and one or more attributes about the authenticated user.
The assertion is delivered to your SP according to the SAML V2.0 Web Browser SSO profile and processed by the SP to be used by the application to fulfill its identity requirements, for example, to authenticate the user, to create a local representation of the user, to authorize the user, etc. After the processing concludes, the user is granted access to the service.
Because every service is different, so too is every identity integration. This document is intended to be generally useful. As a result, portions of the following guidance, such as non-web integration or bulk provisioning, may not apply to your service.
Discovery and Authentication
Before a user can obtain an assertion, the user has to access their home identity provider with a destination service in hand. This may happen through your service interacting with the user, or through your service providing customers with enough information to help users initiate login events. Some deployments may support both approaches in order to allow flexibility in application access.
There is no uniform, "right" solution for initiating login. Making the right choice involves weighing the most elegant integration approach against the potential disruption of any existing user base. Getting discovery wrong will result in stranded users who would like to login for your application but are unable to figure out how to do so. Following are two sets of common discovery approaches, involving or not involving user interaction.
No User Interaction
These methods of session initiation rely on specific, unique ingress points to designate the right identity provider to use. These tend to work best for cloud applications that serve each organization in isolation from other customers, but less well for applications where users from different organizations need to interact.
A significant limitation to be addressed when deploying these methods is the impedance to user login if they access the application in the wrong fashion, for example, directly from a search engine. These methods rely on the user going to some sort of a campus portal as a starting point, a facility that some schools don't aggressively maintain or promote for general use by the entire population, or starting at the right URL from a perfectly executed(and interpreted) web search.
a) Dedicated URLs: The NET+ service exposes different URLs for each customer, such as https://university.netPlusPartner.com/ or https://netPlusPartner.com/University. These URLs trigger generation of an authentication request for the user to carry to the IdP configured for that URL.
b) Exposed Session Initiators: A NET+ service can also expose dedicated URLs for session initiation. The SP would make public a session initiation base, such as https://sp.netPlusPartner.com/Shibboleth.sso/Login. Links for each IdP are then built from that base, for example, https://sp.netPlusPartner.com/Shibboleth.sso/Login?entityID=https://idp.university.edu/. These complete session initiation links are then exposed to users, by a school's portal for example. This partially decouples your URL space from your login mechanism, leaving you with more flexibility to change your deployment without breaking customer integrations. This is NET+'s preferred approach within this category.
c) IdP-Initiated: Identity providers are capable of initiating access by sending the user to the SP with an assertion and destination URL in hand. This session initiation mechanism operates entirely outside the SP. This is mostly used by simple SP implementations that are not capable of issuing authentication requests themselves. Supporting this method in exclusion of all others will usually create usability issues regardless of how well it's done. Users like to bookmark, web search, and so forth, and none of these activities will be possible for NET+ users of your site if you only support IdP-initiated SSO.
There isn't much practical difference between these methods. Dedicated URLs and exposed session initiators are slightly preferable because they increase deployment flexibility by limiting the need for the IdP or third parties to know much about the SP.
User Interaction
Applications that serve diverse user communities as a collective population or want to accommodate user access from a variety of ingress points need to allow users to login after the user has already arrived at the application. The only way to consistently send the user to the right IdP to authenticate is to ask the user.
a) Discovery Services (DS): A discovery service exposes an interface to users by which they can choose a home IdP. Their selection is relayed to the SP, which then crafts an authentication request for the user to deliver to that IdP.
InCommon operates a discovery service for its members that you are welcome to utilize. This discovery service includes by default all members of InCommon. That list can be constrained by your SP to a subset of InCommon members who happen to be your customers; however, the list cannot be expanded by your SP to include customers who are not members of InCommon. If your user base is not InCommon or a subset thereof, you should probably not leverage InCommons DS.
It is fairly trivial to run your own DS, but non-trivial to optimize the user experience. If you intend to operate your own discovery service, please familiarize yourself with some of the prior work done in this area, particularly:
https://sites.google.com/site/publisherinterfacestudy/home
and then run your ideas by the NET+ Identity team for additional feedback and suggestions. This is NET+'s preferred approach within this category.
b) Email Address: There is no good question to pose to a user to determine a user's home domain. However, most users will be able to respond to the question, "What's your email address?" The answer can be cleaved off at the @ and used to guess the user's domain.
From InCommon's perspective, there are several drawbacks to this approach:
- The anti-pattern of asking users to enter their email address on a page to begin a login process promotes spear-phishing attacks.
- Users will often have multiple email addresses and exhibit confusion about which one they should use. Further, several schools either do not provide, or are contemplating not providing email addresses to students anymore.
- Users are confused about being prompted for their email address once and then prompted for a login name later, as they mentally tend to equate the two due to consumer site login practices.
- Users are confused by the lack of a password box alongside the email address, as they're not used to being prompted for just email address when initiating login. If a password box does exist, for example, to support local authentication as well with one interface, users will regularly enter their institutional passwords in that password box. This is another phishing hazard.
- The mapping of domains to IdPs is not bulletproof, and can be tricky. When using domains minted from email addresses for discovery, this problem becomes at least half yours to solve.
- Privacy is lost by prompting the user for their email address.
https://sites.google.com/site/oauthgoog/UXFedLogin
c) Buttons: Most consumer federated identity interactions are initiated by use of a branded button. This approach scales poorly to large numbers of customers or collaborators. We recommend against it in any deployment that must operate at scales greater than six (6) IdPs.
http://developer.yahoo.com/openid/bestpractices.html
Placement of Federated Identity Next to Local Authentication
Some NET+ deployments have existing user bases that authenticate using a username/email and password dialogue that is either embedded in pages or referred to via a login link. When the IdP discovery mechanism involves the SP interacting with the user, providing an adequate user experience for federated users with minimal disruption of local authentication takes some thought. For discovery mechanisms that don't interact with the user, the challenge is dealing with federated users that show up at your service directly and unauthenticated; your application's existing authentication interface generally doesn't need to be modified beyond adding some breadcrumbs to help these users get logged in.
For discovery mechanisms that do involve user interaction, from a federated identity perspective, it's great if you're able to treat the existing user base as just another federated user community that uses an IdP you operate for them. This ensures that discovery is the initial user interface when a user clicks "Login", maximizing the chances that federated users get back to their home IdP safe and sound. However, this is a confusing and additional step for local users, and often an unacceptable modification.
Next-best is placing local login behind a separate link. In this case, after requesting to login, the user will be presented with the option of federated identity or local identity. If the user selects local login, they will be presented with a username and password dialogue. If the user selects federated identity, they will be presented with a discovery interface from which to select a home IdP. The major challenge with this integration approach is presenting local login and federated login in a manner that users can successfully interpret, and there isn't much knowledge about how it's best done, beyond providing ways for users to backtrack if they select the wrong one.
A link to initiate federated login that is placed next to a username and password dialogue for local login is highly undesirable. This will routinely confuse and inadvertently phish users as they enter their home IdP username and password into the dialogue presented. This authentication attempt fails, of course, resulting in further user confusion. We ask NET+ vendors to please avoid this approach.
Authentication Quality and Levels of Assurance
When a user authenticates for your application, you can have confidence knowing that they used the same credentials that they use for other important services. Schools tend to do a good job of credentialing and authenticating users. Each IdP in InCommon is responsible for providing a statement describing how they perform a number of functions relevant to identity management in their Participant Operating Practices (POP) statement.
Level of Assurance (LoA) is one metric that may be used to gauge the quality of an authentication event, for example, how certain you are that this user is who you think they are. Qualification to assert authentication at a given LoA requires IdPs to meet a set of requirements defined by the Assurance program to reach InCommon Bronze or InCommon Silver certification.
http://www.incommon.org/assurance/index.html
Few schools are capable of meeting Silver or Bronze requirements today. This speaks more to the quality of the Assurance program than to the quality of standard InCommon identity management practices.
Unless your application is dealing with significantly sensitive information, you should maximize your customer base by accepting standard InCommon identities.
Attributes and Privileges
There is wide variation in attribute and privilege management capabilities amongst InCommon members. The best applications will accommodate this by offering multiple mechanisms to manage user information, privileges and provisioning.
Please bear in mind that your attribute requests are just that: requests. Every IdP is the ultimate arbiter of which attributes to release to which SPs. You should architect your application to require as few attributes as possible, and support as many attributes as practical.
Identifying Whom You're Talking To
The flexibility of the InCommon identity system allows for a variety of IdP hosting scenarios. In the typical case, a single IdP is owned by, operated by, and authoritative for a single organization. However, some IdP's are authoritative for multiple organizations(e.g. school systems aggregated under a single identity management platform). There are different indicators that help you ensure you're granting access to users from the intended organization.
Every IdP is identified by a unique string vetted by InCommon known as an entityID. URI's provide a unique namespace for allocation of entityID's. These URI's are typically URL's for most InCommon members, but some InCommon members use a URN. These strings are not necessarily resolvable nor parseable. Most SP's will expose the entityID to the application. This is the canonical way to know which IdP you're speaking with. The IdP entityID may be cross-referenced against the InCommon metadata in order to discover an organization name.
Some identity attributes include a domain context within which they are valid, a term known as "scope". For example, while eduPersonAffiliation may denote that a user is "staff", eduPersonScopedAffiliation conveys that the user is "staff@internet2.edu," a staff member of Internet2. If you are using Shibboleth software and InCommon, it will automatically validate that the asserting IdP is authoritative for the scopes of any scoped attributes received.
User Identifiers
InCommon IdP's can supply a variety of user identifiers which can be sorted into three main flavors: unique names, pseudonyms, and anonyms. A unique name takes a variety of forms but will uniquely identify a user. Pseudonyms are opaque names for a user that preserve a user's privacy, but persist as a user accesses your service time and time again. Anonyms grant anonymity.
Commonly Available Attributes
InCommon participants will generally be capable of supplying user data that is stored in either eduPerson, or inetOrgPerson (and its structural components). Some will also support SAML persistentId.
http://middleware.internet2.edu/eduperson/
http://www.ietf.org/rfc/rfc2798.txt
http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf
In practice, some attributes in the aforementioned object classes are more widely used than others. The most common attributes and loose definitions for them follow.
eduPersonPrincipalName: A unique identifier for the user that is usually human-legible and is of the form userid@domain. Reassignment is permitted and reassignment practices vary substantially throughout InCommon.
eduPersonAffiliation: A controlled vocabulary of attribute values that describe a user's affiliation with the school. Strong common definitions for these values don't exist because of heterogeneous definitions across higher ed. Schools are asked to populate it appropriately. Values student, staff, faculty, member, and library-walk-in are most commonly useful for NET+ services.
eduPersonScopedAffiliation: Same as eduPersonAffiliation, but scoped to a domain. This is often useful if a service is available to a specific community, for example, student@school.edu.
eduPersonEntitlement: An attribute that carries zero or more strings (typically URIs, which can be URNs or URLs) that identify either privileges a user has or sets/groups a user is a member of. If you would like to permit IdPs to manage privileges with respect to your service by sending appropriate attributes, you might specify a set of eduPersonEntitlement values that correspond to permission sets within your application. Alternatively, you might ask schools to evaluate some contractual ruleset that determines whether a user is eligible to access your application at all. The school would send an "is eligible under our contract" eduPersonEntitlement value to you.
mail: An email address for the user. May be multi-valued. 
cn: A display name for a user.
sn: A user's surname.
givenName: A user's first (and second, third, etc.) name.
displayName: A display name for a user.
persistentId (deprecated name, targetedId): A persistent, unique, opaque, non-reassignable identifier for the user. This identifier is generated once for each (user + IdP + SP), providing excellent privacy protection. Two drawbacks associated with the identifier are the lack of human legibility and relatively inconsistent support for it within InCommon. This should be supported as a primary identifier for your service, particularly for schools that feel uncomfortable supplying personally identifiable information.
Custom Attributes
InCommon participants can define custom attributes when necessary. While the attributes can convey any data desired, including rich XML structure or base64-encoded objects, most custom attributes carry a simple string as a value.
The use of custom attributes raises the barrier to entry for customers who wish to use your service. Please use existing, widely supported attributes whenever feasible.
If you decide a specific custom attribute is necessary, ensure that the attribute is defined with a unique namespace (URL preferred) under your control, with a concise and precise definition of attribute purpose and value space.
We suggest consulting with NET+ before requiring a custom attribute.
Privileges
InCommon members vary widely in their approach to management of privileges and permissions. Some schools would like to manage as many application privileges as possible centrally to leverage privilege management tools, consolidate privilege sets across applications, and improve auditing. Other schools don't have this infrastructure in place yet. The ideal integration will accommodate this diversity.
The preferred approach to privilege management offers, in parallel, a privilege management interface integrated directly into your service and the ability to accept attributes that represent privileges. Default attribute name/value pairs and the privileges they represent can be defined. However, because of variability among campuses, in an optimal implementation, which attributes yield which privileges is configurable by each customer. A simple rules engine matches configured names and values to zero or more roles that are meaningful within your application. This configuration is the customer's responsibility.
A simplified implementation of the preferred approach using static attribute/privilege mappings is second-best.
A basic implementation will handle all privilege management within the application.
Provisioning
Storing as little user information as reasonable within an application is an important NET+ design principle.
It's ideal if your application can provide full service to federated users without persisting any local user representation. If your application can do so, then you don't need any provisioning and you can move to the next section.
Provisioning for applications that need it can be roughly distinguished using the following question for demarcation: "Do you need to have a local representation of a user at any point before the user has accessed the application?"
If the answer to this second question is, "no, I don't need user data prior to that user authenticating," then it's recommended that your application implement dynamic, front-channel provisioning. This preserves privacy and limits the proliferation of user data, protecting users, schools, and you. Applications that must know users in advance will require back-channel provisioning.
Front-channel Provisioning
A typical front-channel provisioning workflow starts with the arrival of the user carrying a valid assertion from an IdP. The application will check to see whether the assertion contains a primary identifier associated with a known user.
If the user is recognized, the local user record is updated with information from the assertion if necessary, and the application uses either local or combined federated+local user data to grant the user access.
If the user is unrecognized, then a new user record is created using an identifier from the assertion as a key. After the record is created, the user is granted access.
Back-channel Provisioning
Back-channel provisioning is complicated by the lack of a successful, widely adopted standard. There are initiatives underway to change this status quo, such as SCIM and SPML.
The most common current approach is the implementation of custom provisioning API's or web services. A back-channel provisioning interface should support both singular and bulk operations. Wholesale data transfers using LDIFs or CSV files are also not uncommon. NET+ prefers vendors to use standards whenever feasible and encourages vendors to be poised to use emerging standards as they are finalized.
Deprovisioning
When user information is stored by applications, it generally needs to be purged from time to time, a process known in the identity world as deprovisioning. Deprovisioning in a technical sense generally involves either deleting or decommissioning and archiving user data. Whether to delete or archive depends on the terms under which the application is offered and the nature of the user data, so we can offer no general guidance.
Federated user deprovisioning can either be triggered by aging, e.g. removing users that haven't been seen in a given amount of time, or by exposing interfaces to the customer to allow the customer to remove users.
Aging is a process of removing all users that have not accessed a service within a given period of time, e.g. the last 6 months. This shares the same challenges as provisioning in a federated environment, compounded by the fact that while attempt to access can be interpreted by an application as an attempt to provision, lack of recent access doesn't always imply an attempt to deprovision.
Exposing a deprovisioning interface, like back-channel provisioning, is hampered by the lack of good standards. Most deprovisioning interfaces are also custom and are frequently implemented alongside the provisioning interface.
Error Handling
Federated error handling is a team sport. You will generally possess more information about an error condition than the IdP, but you will likely not possess the entire picture. You may be unable to resolve the problem yourself even if you can identify it.
When federated identity fails, it needs to fail gracefully and informatively. Your SP or application will need to handle and display identity-related error conditions.
Insufficient Attributes Received
InCommon has no control over the set of attributes any IdP is willing to send to your SP. If your application requires any user information beyond simple successful authentication of a mystery individual from that IdP, you will eventually receive incomplete attributes.
If your application can function with this reduced user information, it should do so while producing notification both to the user and to yourself indicating the insufficient set of attributes received. A pattern of insufficient user attribute release should be reported to the IdP.
If your application can't function with reduced user information, it should present an error page to the user with the problem and a resolution location, typically the administrator of the IdP from which the user came. InCommon provides a centralized error handling service for this purpose:
https://spaces.at.internet2.edu/display/InCCollaborate/Federated+Error+Handling
If the user assertion included all the correct attributes, but authorization was denied for some reason, the application should present an error page to the user with the problem and, if appropriate, a resolution location, which may be you.
Miscellaneous Failures
There are a plethora of miscellaneous errors that can occur in a federated identity transaction. Incorrect certificates or metadata and failed message security checks are a few of the things that can go wrong. These failures are uncommon after successful interoperability, but they do occur. You should have an auditing mechanism in place to detect and report these failures.
In the unlikely event of user misconduct, you are encouraged to submit a report to the technical contact listed in the metadata of the user's home institution. All technical contacts are listed on the InCommon Federation Info pages:
https://incommon.org/federation/info/
Please supply the assertion ID associated with the authentication event of the offending user. If you received any sort of persistent identifier for that user, you may elect to include that information in the notification and block access from that identifier on your end. It is always possible for an IdP and SP working in concert to determine the authenticated user associated with misbehavior regardless of whether any personally identifiable attributes were sent to the SP.
Logout
There is very little support for any form of federated- or single-logout capability within the InCommon Federation. Most applications should consider logout to be a local process that terminates in a warning message to users asking them to close their browsers if they want to finish logging out. For a discussion of why this is the current deployment paradigm, please read:
https://wiki.shibboleth.net/confluence/display/SHIB2/SLOIssues
Some schools expose a logout location to which you can redirect a user in order to clear their IdP session; others maintain a common page to display to users after logout occurs. Exposing a configurable option that redirects the user (upon completion of local logout at the SP/application) to a URL of the customer's choice is a best practice.
This is an evolving aspect of InCommon and additional functionality may be implemented in the future.
Non-Web Access
Many NET+ applications interact with customers entirely through web-based access, for example, HTTPS via a web browser. If your application interacts with customers in other ways, you will need to do more extensive integration work.
Some successful integrations will leverage the SAML 2.0 ECP specifications to directly interact with the IdP and the application. This permits the client to converse with the IdP to obtain a SAML assertion and play that assertion directly to the application. The SAML assertion is used to bootstrap into another session persistence mechanism.
Other successful integrations involving non-HTTPS access or native applications begin with a standard web authentication session that is then bridged into new protocols or applications. This bridge can take many forms depending on exactly what you're trying to wire together.
It's difficult to make specific recommendations due to the great variety of protocols and applications in the world. As long as your interfaces are only intended to be used by clients that you develop, then you can pick the most appropriate integration for your application. NET+ has no strong preferences here, but this may change with time in the event that application interfaces become more cosmopolitan and applications are developed that work with a suite of NET+ services.
Please review the below guidelines and then discuss proposed solutions with the NET+ identity team.
ECP
SAML includes a profile called ECP designed to make it easy for native clients to communicate directly with the IdP over HTTPS to authenticate and obtain SAML assertions. This requires some implementation work to teach the client to speak ECP, and some work to ensure your server understands it as well. Examples are available.
ECP support is not universal amongst InCommon sites, but enabling it is typically not difficult for the IdP administrators.
Bridges
If your client can be invoked by or integrate with a web browser, it's possible to bootstrap from the web session(which is almost always persisted using cookies) and the typically short-lived SAML assertion into a separate session that's persisted using a mechanism that is independent of the web browser or the initial SAML transaction.
OAuth 2.0 is a natural protocol for obtaining and playing such access tokens and NET+ prefers that vendors utilize the protocol when possible. OAuth supports a variety of token formats, including custom formats. However, it is explicitly architected for HTTP.
Other Protocols
Federated identity for other protocols is an area of active standards work, but there are few easily deployable solutions today. Successful integrations have been performed using many different protocols. Most of these integrations work via misappropriating existing fields in the protocol in one form or another.
For example, a bridge into FTP could work by populating a database at the FTP server with nonces for usernames and a common password and supplying those nonces to clients that were invoked through the federated identity interface. Alternatively, a SAML assertion could be sent somewhere in the protocol itself to a server in the know that could process it. The target protocol and your imagination are the only real limits.
If you need to enable a non-HTTP/HTTPS protocol, please speak with the NET+ identity team.
Programmatic Access (API's)
Some applications need to expose APIs to customers to allow for bulk or automated operations.
Implementation
Double-check with NET+
After you've parsed this document and, hopefully, constructed an integration plan for your application, we ask you to vet your thinking with the NET+ team before getting implementation underway. We'll include other participants, such as schools, in this validation process whenever necessary.
Testing with a Dummy IdP
During the implementation process, it can be helpful to test against a known, functioning IdP where you have an account. Internet2 operates a simple service for this known as "TestShib". It is accessed at:
Service Validation with Schools
After you've finished your implementation work and tested your SP successfully against a dummy IdP, it's finally time to engage the schools that sponsored your participation in the NET+ for real testing and service validation.