How To Become a SAML Service Provider

Question

My company currently develops a Java web application. A couple of our clients have internal SAML servers (identity providers?) and have requested that we integrate with them. So recently I've been reading up on it and playing around with OpenAM. After about 3 days of this, I have a general understanding of it, but there are still some gaps in my knowledge. My hope is that someone can clear this up for me.

So here's how I imagine the workflow of a user logging in.

Let's define our customers SAML server as https://their.samlserver.com. So a user comes to our web application for a resource that's protected. Let's say that URL is http://my.app.com/something.

So if I'm correct, my.app.com is what SAML defines as a Service Provider. Our application realizes that this user needs to log in. We then present a page like this to the user...

<script>JQuery Script to auto submit this form on ready</script> <form method="post" action="https://their.samlserver.com/Post/Servlet">     <input type="hidden" name="SAMLRequest" value="someBase64Data" />     <input type="submit" value="Submit" /> </form> 

And that someBase64Data should be base64 encoded version of this...

<samlp:AuthnRequest   xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"   xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"   ID="identifier_1"   Version="2.0"   IssueInstant="2004-12-05T09:21:59Z"   AssertionConsumerServiceIndex="0">  <saml:Issuer>http://my.app.com</saml:Issuer>  <samlp:NameIDPolicy    AllowCreate="true"    Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"/> </samlp:AuthnRequest> 

So my first couple questions.

What is the ID value suppose to be?

And why can I declare myself as an Issuer?

Does the Identity Provider know about me? Maybe this is that Circle of trust I've been seeing on OpenAM. And if it does know about me, how does it know about me and what does it need to know?

So after the user is forwarded that page, they are taken to a page provided by the IDP https://their.samlserver.com. They authenticate on that page and the IDP does it's magic to validate the authentication and look up the user. After the authentication is successful, the IDP sends back a <samlp:Response> defined here.

A few more questions.

First, how does the <samlp:Response> get back to my web application so I can check it?

And what should I be looking for in that response to validate that it was successful? What does a failure look like?

We currently use the email address (LDAP) to identify users, so we'll probably grab that from the response and use that in the same way we do now. Anything else I should be mindful of in that response?

So now that we've checked that response for validity, we can grant the user a session like we do currently. But when they want to log out, is there a workflow for that? Do I have to notify the IDP that the user has left?

And finally, there are a couple of topics that have been thrown around in my reading and I'm not sure how they fit into this workflow. They are Circle of trust, Tokens, and Artifacts.

Thanks for any help everyone. I've found a lot of information in the last couple days, and it's possible that I could piece them together after a bit more playing. But I have yet to find a straightforward "Here's the Post" workflow article yet. Maybe that's because I'm wrong on how this works. Maybe it's because this isn't that popular. But I really wanted to make sure that I got the workflow so I didn't miss a crucial step in something as important as user authentication.

Answer 1

In response to your specific questions:

1.) What is the "ID" value supposed to be?

• This should be a unique identifier for the SAML request. The SAML 2.0 specification states that it's really implementation specific how this is done, but makes the following recommendations:

The mechanism by which a SAML system entity ensures that the identifier is unique is left to the implementation. In the case that a random or pseudorandom technique is employed, the probability of two randomly chosen identifiers being identical MUST be less than or equal to 2 ^ -128 and SHOULD be less than or equal to 2 ^-160 in length. This requirement MAY be met by encoding a randomly chosen value between 128 and 160 bits in length.

2.) How does the IdP know about you?

• Your SP needs to be registered with the IdP. To accomplish this, the SAML specification defines a format for "SAML Metadata" which tells the IdP where your SAML receivers are, what your certificates are, attributes you exchange, etc. OpenAM likely dictates some minimum requirements for configuring a trusted SP. This varies in each product.

3.) Where's the Response go, and what to check?

• The Response will go to your Assertion Consumer Service (ACS) URL usually defined in the SAML Metadata you exchange from your SP with the IdP for initial setup. When you receive a SAML Response, you need to check many things - but most importantly, the SAML Status code should be "success", the inResponseTo ID's should match the request's sent ones and you must validate the digital signature on the Assertion. For that, you'll need to trust the IdP's public verification certificate, and you'll probably also want to do revocation checking.

4.) What about Logout?

• SAML 2.0 also defines a profile for Single LogOut (SLO). This will not only log you out of the SP, but also the IdP and potentially any other SP's you've established a session with. It has a similar request/response flow as Single Sign-On (SSO), and thus similar things to set up and check (status codes, signatures, etc.).

So in short - this can be quite complex to implement from scratch. It's best to use tried & true libraries and/or products like Ian suggests. Companies like his have invested hundreds of hours of developer time to implement according to the spec and test interoperability with other vendors.

Answer 2

If you're just trying to set a single Java application up as a Service Provider, you should consider using a Fedlet from either Oracle (as a standalone ) or ForgeRock ( bundled with OpenAM ). The ForgeRock Fedlet has some issues interacting with Shibboleth 2.2.1 as an Identity Provider, but I find it to be somewhat simpler to configure and more informative.

Each has explicit instructions contained in the README to help you deploy. Once the Fedlet is configured and communicating with the IDP, the success page shows you all the code you need to integrate federated SSO into your application. It does the background work of sending and receiving AuthnRequests and Responses.

Scott's answer responds quite well to the questions you had, but I think that trying to write code on your own that generates the SAML is reinventing the wheel. The Fedlet was designed with precisely this use case in mind.