It is important to keep in mind that we are using WSKeys to provide authentication and authorization at the application level. This means that WSKey does not verify a user's rights, just the rights of the application. Some of our web services, such as those associated with WorldShare Management Systems, require that requests made to them can be attributed to a user. For example, who is the patron or librarian requesting the WMS Acquisitions system place an order for a particular book? In essence, these types of services require a valid User be identified, possess the appropriate rights to perform the requested action, and be passed as part of the request to the web service.

How does one “pass” a user identifier to a web service?

Without a valid user identifier the client cannot successfully interact with some of our web services. This means that a web service client, such as a script or other software application, must tell us on whose behalf it is acting or who is “driving” the script or software. In these cases, it is important to understand what the role of OCLC’s WSKey system is. In essence, WSKey acts as a secure pipe through which user identity is passed.

Typically, user identifier information is passed to a service as part of the HTTP Authorization Header. For example:

You’ll notice this is a not your typical username or username/password combination.

What is a user identifier at OCLC?

In order to understand user identifiers at OCLC, you first need to understand the concept of User. OCLC defines a User is a person at a particular institution. A single User can have multiple user identifiers. A user identifier corresponds to a particular system. As a result, a user identifier at OCLC is typically comprised of two key pieces of information:

principalID – the user id, similar to a username

principalIDNS – principal identity namespace representing a specific system at an institution

Karen is a student at Platform University where she has an account on the university network which knows her by an identifier 12345. She also has an account on the university grade systems that knows her as kac9876. This would result in two user identifiers

principalID – 12345

principalIDNS – urn:platformU:microsoft

and

principalID – kac9876

principalIDNS – urn: platformU:peoplesoft

Note that up to this point, I have been referring to my various User identifers in the context of a single institution, Platform University. The person Karen can also be staff at OCLC College. This User Karen@OCLC_College could have another set of user identifiers in the context of OCLC College. While all these user identifiers are, in theory, associated with the person Karen, currently we do not establish relationships between Users and a real world person such that two Users could be tied together through a single person. Therefore, institutional affiliation is a key component of User Authentication within our identity management systems. When talking about User authentication, institution is either:

the institution where the user will authenticate. This is for cases where the client does not yet have a User Identifier.

the institution where the user did authenticate. This is for cases where the client does have a User Identifier.

Most of these pieces of information about a User are not transparent or readily available to customers logged in OCLC’s systems. This presented a challenge for us because our initial WorldShare Platform implementation did not give clients a way to authenticate users or obtain user identity information. The result is that clients did not have a way to get user identity information to pass the web services that require it.

In order to overcome this issue, we initially had clients pass a single hard-coded user identifier for all interactions with a service. However, this was not an acceptable long term solution because it did not provide adequate attribution for actions taken. Essentially all web service use by a given institution could only be attributed to a single admin or super user account.

Exposing an infrastructure for user authentication

To deal with these issues we needed to implement infrastructure for authenticating users. We had two possible solutions:

allow clients to use our SAML-based Authentication System

implement an OAuth2 Authorization Server

While external systems can integrate with our SAML-based systems, we decided to add an OAuth2 Authorization Server to our infrastructure to provide a complementary method of authenticating users via external clients. There were three major reasons for this decision.

Using a SAML-based Authentication System requires each client application be given explicit permission to interact with the Authentication System. For institutions that belong to an SAML-based federation like InCommon, this configuration is already in place. For institutions that are not part of the SAML federation, the OAuth2 Authorization server provides the infrastructure for any client that has a WSKey to authenticate users.

SAML-based Authentication is geared toward a user community that desires a high level of security and enterprise level support. Many financial institutions and higher education institutions are familiar with the standard. In contrast, the OAuth2 standard has been widely adopted for web services in social network space. Google, Facebook, and a number of other tools use OAuth. By providing both options we’re able to support the needs of these different communities.

OAuth has authentication patterns that allow for users to login and allow clients to interact on their behalf in an asynchronous fashion. This functionality is not part of SAML.

The Authorization server allows clients to log users in to their appropriate identity provider at the relevant institution. Because this is built on our Identity Management infrastructure, only institutions that are configured in OCLC’s identity management infrastructure can use this tool. Additionally, because this infrastructure employs single sign-on, consuming web browsers must have cookies enabled. Clients that successfully log users in via the Authorization Server can retrieve a valid user identifier for the authenticated users.

For example, upon sending a user through an OAuth2 login flow, an external client will have a JSON object that contains a valid user identifier needed to interact with the OCLC web services that require it:

Stay tuned for upcoming posts on our WSKey access token patterns to learn more about how this works. Earlier this month we installed our Authorization server infrastructure in pilot form. Clients that wish participate in the pilot should contact us. We anticipate to making the Authorization server available to the entire community in August 2013.

Karen Coombs

Senior Product Analyst

We are a worldwide library cooperative, owned, governed and sustained by members since 1967. Our public purpose is a statement of commitment to each other—that we will work together to improve access to the information held in libraries around the globe, and find ways to reduce costs for libraries through collaboration. Learn more »