After spending a few years as one of the pioneers of VMWare Identity Manager (VIDM), and speaking about identity a few times there is one thing that people often reach out to me about. They do great if the application is in the catalog, but once they get outside of that things get complicated. I will cover some basics, break down service provider (SP) metadata, take you through adding a non-conventional application, and give a brief demo of the SAML tracing tools that I use in Chrome.

SSO Basics

Its definitely useful to understand some of the core basics if you want to be successful. Let’s start with a few terms that you will see pretty frequently…

Identity Provider (IDP): VIDM is the identity provider, which simply means the service that will provide the authorization and authentication layer for your applications. VIDM has a database called a SCIM (System for Cross-Domain Identity Management) with users, groups, and applications that ensures the right people have the right access from the right locations.

Service Provider (SP): Service Provider is typically the application that you have setup in VIDM. Ideally, your SP will re-direct you to VIDM to authenticate your users and pass back the session to the application.

SAML: SAML aka Security Assertion Markup Language is an open standard used by identity providers to grant access to an application or set of applications. SAML 2.0 is a commonly-used standard for authentication that virtually all application use today.

SAML Assertion: The assertion is a bundle of SAML statements, including authentication information, attributes, and authorization information e.g. jon towles along with his username, email address, and phone number is allowed to log into Office 365. They can be signed, unsigned, encrypted, or signed and encrypted depending on the requirements of the application

SAML Response: The response is received from the SP after validating the SAML assertion. This can be signed or unsigned.

Entity ID: This is a globally unique identifier in every SAML system to map the application.

AuthnRequest: This is typically an authentication request from the SP to the IDP commonly found in the SAML statement.

SAML Flow

Some people benefit from a visual representation of how SAML works. I think the diagram below is very useful, which gives you a basic idea about how SSO works.

SP Metadata

Most people can configure Office 365 or Concur, but when you start getting generic applications it gets way more complicated. If you’re lucky, you can get metadata from the application/vendor to make life a bit easier, but sometimes you can’t even get that. We’re going to breakdown a typical SP Metadata file so you can make onboarding apps even easier.

We start with the Entity Descriptor, which as I mentioned earlier is the unique ID to map your application. You will see the xml namespace maps to SAML 2.0 metadata. You will use this entity ID when you add the application in VIDM. This is part of the checks and balances of SAML and it will be expected that the IDP and SP have mutually agreed on the entity ID.

This second line tells you what the application is asking for. These are key to correctly configuring your application. You must adhere to the rules or your attempts may fail. You can see the things it tells you like:

• I don’t want my Authn Requests signed
• I don’t want my Assertions signed
• I support SAML 2.0

The next section will contain your certificates, what protocols they support, and their usage. First we’ll focus on the signature which you can see below. This shows that the certificates are signed with RSA-SHA256 (which is a good thing!). That will matter later when you configure an application.

The second part is where it will tell you a certificate is for signing or encryption. The good news is that typically its the same certificate for both. You want to confirm they have a certificate in the metadata for encryption otherwise encrypted assertions won’t work for example. Before you ask, you should always encrypt any assertions that have confidential data such as employee ID in there.

The final part of the metadata has the most essential info in it. We’ll break down each.

SingleLogoutService is usually unnecessary. This URL is for handling logout protocol messages from the identity provider, but isn’t really used with VIDM. Typically logout should be handled on the SP especially considering most SPs don’t respect timeouts set by the identity provider. You will notice they have bindings for two different types of HTTP commands (Redirect and POST).

Name ID Format specifies the identity formats that are supported, which requires that you have an commonality between IDP and SP. Typically, applications are configured to user a specific format and it is almost always “unspecified” In my career, I had one application that was transient but most of the time its unspecified.

Assertion Consumer Service which is commonly known as the SSO URL, which is where your IDP would redirect after authentication. This is the consumer of your SAML data that will give you access to the application. It’s important to note that if an application is only IDP-initiated, you must originate at VIDM.

Configuring Applications in VIDM

On the initial page, you start out by naming the application. I strongly recommend setting the category. Its important to understand and be aware that with the intelligent hub and its catalog integration, its vital you name apps, provide compelling icons, and categorize them.

With SP Metadata

Ideally, you can just paste in your metadata and just finish the wizard and are good to go! I think we know life is usually not that easy!

One item that I do recommend checking is this one below. You need to understand how user accounts work in your application. If the user ID is an email address, you may need to pass that as the Name ID value like you see below:

The one other area you may need to configure are your custom attributes. Below are some examples of passing email, username, empID to the application. These attributes are used typically when your application supports using the SAML assertion to update user accounts.

Working from Scratch

Working from scratch is much more difficult, as I presume you might guess. If you read my breakdown on SP metadata, you have a good understanding on what you need to do.

You can see below, that I copied in the ACS URL to the first two fields (which is what you will do typically) and the Entity ID into the Application ID field. The username aka Name ID value sometimes will take some trial and error to figure out, but typically the rule of thumb is whatever you pass to the application it MUST be able to map that to a known user account.

The next part is your certificate actions. This is basically sign this, encrypt that, etc. What I set below, is what 80% of applications will require. Sometimes you have some jerk-face apps. This is usually trial and error because vendors on the other side aren’t usually great at helping on this.

One good thing to note is when you copy/paste certificates into the field you want to make sure you capture the proper syntax or the certificates won’t work. Typically what I look for is <ds:X509Certificate> and copy from that line to the closer e.g </ds:X509Certificate> similar to what you see if you open a certificate with Notepad++.

Beyond this, you would just configure custom attributes that you want to pass like I mentioned in the previous section. There are a few parts that I skipped over like relay or proxy but those won’t usually be required. From here, we can start talking about troubleshooting issues leveraging the SAML trace utilities.

Troubleshooting SSO with SAML Tracing

First, let’s start with the application which you can download from here

Simply, the application give you a SAML control panel inside of Chrome developer tools to debug SAML logins like you can see below. This is especially helpful when an application isn’t working as expected:

A SAML Trace looks like this:

The area you want to focus on is at the bottom showing the value of the attributes you are passing and the value of the NameQualifier. You are usually looking for an inaccurate value being passed to your application like the wrong employee ID or email address, etc. The big key is to disable encrypted asssertions for troubleshooting otherwise you can’t see what’s inside the SAML assertion.

Summing it All Up

I covered a ton of information in this article that may overwhelm some people who are new to identity. The idea is to visually give you a picture into the troubleshooting process when onboarding new applications. It’s about understanding how SAML works and crafting a recipe that gives you the seamless access that your users crave. Let’s some up a few of the best practices we covered:

• Only Sign the Response!
• Encrypt Assertions that contain data you don’t want available to the world.
• Only make apps visible in the catalog that are production-ready.
• Leverage Categories, compelling icons, and succinct names to drive user adoption.
• SAML 2 is the gold standard, but that will be changing in the near future (I didn’t cover this but be aware of it).
• SAML Trace is your friend.
• If the Metadata is unavailable don’t worry! You can configure it manually, but it could take some trial and error.