SAML – the Security Assertion Markup Language is quite successful. SAML was born in 2002 out of OASIS, the somnolent standards body that enjoyed its heyday in the 2000’s forming so many of the XML-oriented standards like WS-BPEL, UDDI, UBL, and ODF. Today SAML enjoys success satisfying a key need in enterprises: browser-based single-sign across origins. Sign into www.mycompany.com and then later visit www.serviceprovider.com and get automatically authorized. The benefit is: people type in their passwords, just once.

SAML wasn’t designed for just that problem, or anyway, not for that specific problem. SAML was designed to address the general problem of exchanging claims securely. The summary on the first page of the spec says that SAML “defines the syntax and semantics for XML-encoded assertions about authentication, attributes, and authorization, and for the protocols that convey this information.” Hence the name, “Security Assertion Markup Language”. But in actual use, SAML is heavily oriented towards browser-based SSO.

In SAML, the claims or assertions are statements about people. When people (via apps or browser pages) make requests of systems – like “let me see this file”, or “let me transfer funds” – the system that receives this request can use trusted claims about the requester to make authorization decisions. The key is that the system needs to trust the claims, and the claims need to be relevant.

An example: If I go to the grocery store, I can present my debit card to the checkout person, to pay for my groceries. The card is basically a set of claims “asserted” by a bank about me:

1. that the person named on the card is a customer of the bank,
2. that the person named is authorized to use a particular account.

This set of assertions is also decorated with some other information, like valid dates, and the author of the claims. The author of the claims is a bank, and that bank is affiliated with a card payment network, in my case, Visa. Also: My debit card expires in a given month and year. The implicit rule is that all parties agree that the claims presented in the plastic card do not hold after that date. This card is good if the merchant trusts the bank, and Visa, and if the dates are valid. Some merchants want to insure that the person named on the card is the same as the person presenting the card, so they’ll ask for a government-issued picture ID that has the same name.

The SAML Analogue

SAML works in a similar way, except the set of claims is formatted digitally, in an XML document, rather than on a plastic card. The set of claims enclosed in a SAML token is general – it can be any set of claims about a person, or “subject”. Claims such as “Dino is male”, or “Dino has no tattoos”, or “Dino is of sound mind and body” are all acceptable. But more often the claims are statements that are relevant to information-processing organizations, such as “Dino is an employee of XYZ corp.” and then some detailed information such as “Dino’s email address is Dino@xyzcorp.com”, “Dino is a member of the Aviation group in XYZ”, and so on. In the general case these are claims about a person’s identity; SAML calls them “Attributes” of the subject. Statements not about the particular person don’t belong in SAML. “It is sunny today” may or may not be true but it is completely unrelated to me – the person in question aka “subject” – therefore not suitable as an attribute in a SAML assertion about me.

Such claims about me could be used by an organization or company to decide whether to grant service to me, when I request it. If my company, XYZ corp, has a partnership agreement with another company, LMN Corp, then when I present my claims to LMN, along with my request, LMN can take a decision on whether to grant my request.

How Trustworthy are your claims?

The claims in a SAML Assertion are just statements, coded in an XML document. Though SAML is a particularly florid and ornate language, it’s still XML, and anyone could create such a document. For a system to be able to rely on that information, to trust that information, there must be some assurance that the presented claims are bona-fide and originate from a trusted source, and also that they are valid at a given moment in time. At one point, “Dino is in the Eighth grade” was a true statement about me, but that statement is no longer true. SAML uses digital signatures based on public-key cryptography for the purpose of assurances of the author of the claims, and explicit time windows on claims (eg, NotBefore or NotOnOrAfter) to circumscribe the validity of such claims.

The “Relying Party” or RP examining a SAML Assertion SAML must verify the signature on the XML document, to insure that the claims can be trusted. The relying party must also evaluate the time windows on the claims. And then finally, the RP must evaluate the claims themselves. It may be that “Dino is a member of the recreation committee” does not grant me permission to see the early draft of the company’s 10-K filing. On the other hand if I am a senior director at the auditing firm, maybe “Dino is an employee at XYZ Auditors” and “Dino is a senior director” is a good enough claim to allow me to see or edit the document.

Simple in Concept, Complex in Execution

SAML is simple enough in principle. I’ve explained the broad strokes here, in just a few paragraphs. Of course, it builds on a large stack of technologies, starting with XML, XML Schema, XML namespaces, URIs, XML digital signatures, and X.509. That alone is a daunting set of technologies, though there is some relief in the maturity of the relevant specifications.

But the details about SAML itself have lead to additional complexity. First, the SAML 2.0 spec is 86 pages. Even there, it is not self-contained. One example: SAML has an element called an AuthnContextClassRef I’m guessing this implies “Authentication Context Class Reference”. For those of you scoring at home, that’s four nouns in a row. What exactly is this thing?

Helpfully, the OASIS spec defines this thing as

A URI reference identifying an authentication context class that describes the authentication context declaration that follows.

All clear? We now interrupt this essay to present a completely unrelated Dilbert comic.

In addition, the SAML spec document suggests, “See the Authentication Context specification [SAMLAuthnCxt] for a full description of authentication context information.” That document is itself an additional 70 pages. Ready to dive in?

This kind of complexity and standards-speak lead, even early on in the life of SAML, to complaints of impracticality from the people who had hoped to be able to use it. Even as early as 2003, just a few months after SAML 1.0 was launched, IBM, one of the original authors of the spec, was employing its partners to bravely assert that the idea that SAML was complex was a myth.

I can hear the wizard inveighing: Pay no attention to that AuthnContextClassRef!!

But the complaints about complexity were not academic. They were based on real-world attempts to get disparate implementations of “the standard” to interoperate. Even today, connecting an Identity Provider and a Relying Party via SAML is a challenge worthy of a platoon of IBM consultants. Have we got a mismatch in the AuthnContextClassRef? Well, we’re gonna have to figure out how to persuade the Relying Party to allow it, or to persuade the IdP to provide a different one. Have you got the wrong NameID Format? Transient, Permanent or Unspecified? Which side needs to give ground in this negotiation?

That’s what I mean when I call SAML “the standard that wasn’t.” It’s a standard, all right, but there are so many different options that despite the rigor of the specification, getting compliant systems to interoperate is still a huge challenge. Despite the challenges, the standard IS valuable – it works mostly, and it solves specific problems that many companies have. But it isn’t automatic.

Lessons for History

SAML is designed to address much more than browser-based single-sign on. But the lion’s share of adopters use SAML for just that, and only that.

There’s a lesson here regarding over-reach of standards: SAML could have been simpler, quicker to get adopted, and easier to use, had its designers restricted their design goals to addressing what 90% of people use it for today, anyway.

Why Bother?

But why am I even talking about SAML? My passion and intention is to work on APIs and enabling new interconnections. That’s why I’m at Apigee today. APIs means “SOAP on Steroids” or if you like, “all the benefits of SOAP without that unsightly residue”. It means getting better connections, faster, and allowing new customer experiences, better mobile apps, better connections between customers and companies. So if I am all about connecting systems with APIs, why do I care about SAML? Have I been sucked into a time-portal and time-warped back into 2007?

Ah, but no! See, the thing is with large companies, they move deliberately. Many still use SAML and still need any systems they install to integrate with their SAML-based Enterprise Identity system. So if I want to work with enterprises in helping them adopt APIs to supercharge their businesses, I need to get SAML working with the various web apps that enable API management and adoption. Get SAML integration done, then the enterprise can innovate with APIs. See?