What is SAML?
SAML (Security Assertion Markup Language) is an XML-based standard for exchanging authentication and authorization data between an identity provider (IdP) such as Okta, and a service provider (SP) such as Box, Salesforce, G Suite, Workday, etc.
Okay, but what does it do, and why does it do it?
How does it do all of that?
Why isn't the custom SAML app I've configured in Okta working?
Deployment Best Practices
Common SAML Terms
SAML completely changes the method by which a user signs into a service. Once an SP (e.g. Box) is configured to authenticate via SAML, users attempting to access its service will no longer be prompted to enter a username or password specific to the SP they are logging onto (e.g. a Box username and password). Instead, an exchange between the SP and the configured IdP will occur that will grant or deny the user’s access to the SP. In other words, a user's credentials for the service are no longer verified by the service itself, but by the identity provider that has been configured to verify them on the service's behalf.
(Note: This document will refer to the IdP as “Okta” in examples from this point forward.)
There are two different sign-in flows for which authentication can be handled by SAML. The first method, known as an SP-initiated flow, occurs when the user attempts to sign onto a SAML-enabled SP via its login page or mobile application (for example, the Box application on an iPhone). Instead of prompting the user to enter a password, an SP that has been configured to use SAML will redirect the user to Okta. Okta will then handle the authentication either by prompting the user to log into Okta via a username and password, or via Desktop Single Sign On. If the user’s credentials are correct and the user has been granted access to the application on the Okta side, they will be redirected back to the SP as an authenticated user.
The second flow is known as an IdP-initiated flow. This occurs when the user logs into Okta (or launches Okta Mobile) and launches the SP application by clicking its chiclet from their Okta home page. If the user has an account on the SP side, they will be authenticated as a user of the application and will generally be delivered to its default landing page (their actual destination within the SP's site is customizable). If they do NOT currently have an account on the SP side, in some cases SAML can actually create the user's account immediately in a process known as Just In Time Provisioning (JIT - please consult our Provisioning Guide for more details)
Either authentication flow will provide an enhanced user experience when that user has already logged into Okta. If the user intends to perform IdP-initiated flows, that user can have any number of Chiclets on their Okta page for SAML-enabled applications and can access all of them without the need to enter more credentials. SP-initiated flows launched from a new tab of a browser will be able to access the token created when the user logged into Okta, which will result in an effortless, near-instantaneous authentication.
Both IdP and SP initiated authentication flows rely upon assertions that are passed to and from the user’s browser and URL’s on both the IdP and SP side that are specifically created to handle SAML traffic (known as endpoints). These assertions are in XML format and contain information that verifies who the identity provider is, who the user is, and whether the user should have access to the SP. At a basic level, a successful SP-initiated SAML flow occurs as follows:
SAML Flow diagram provided by Google
- The user (e.g. john@MyBusiness.com) navigates to the SP’s login page and begins to log in. Some SPs offer a link to "sign in using SSO" on the login page, whereas others can be configured to utilize SAML for all sign-on requests based upon the domain portion of the username (e.g. users@MyBusiness.com). SPs that utilize custom login pages (e.g. https://MyCompany.Dropbox.com) can often be configured to utilize SAML for ALL login attempts.
- The SP generates a SAML request and redirects the user to the Okta Single Sign-On URL endpoint with the request embedded. This endpoint is unique for each application within each Okta tenant.
- Once the user is redirected to Okta they’ll need to enter their Okta credentials, unless they had already authenticated into Okta in a previous session within the same browser. In either case, a successful authentication request will redirect the user back to the SP’s Assertion Consumer Service (ACS) URL with an embedded SAML response from Okta. At a minimum, the response will:
- Indicate that it is indeed from Okta and hasn’t been altered, and contain a digital signature proving such. This signature will be verified by the SP using a public key from Okta that was previously uploaded to the SP as a certificate.
- Indicate that the user has authenticated successfully into Okta
- Indicate who the user is via the NameID, a standard attribute used in SAML assertions.
- After the assertion is successfully parsed by the SP’s ACS, the user will then be sent to the SP’s default relay state, which is usually the same page they’d wind up if they’d simply logged into the SP with a username and password. As SPs such as G Suite and Office 365 host several different services, the default relay state will help dictate which specific service to send them to (for example, directly to Outlook Webmail instead of Office 365’s main landing page).
SAML Tracer, a free add-on available for Firefox, is an extremely useful tool in helping understand and troubleshoot SAML assertions. It allows you to extrapolate SAML assertions from your browsing session and examine them line-by-line.
More than likely, one of the URLs is simply incorrect. This is common because there's unfortunately not much of a standard as far as SAML terminology is concerned. For example, some vendors may refer to the Assertion Consumer Service or Entity ID by a term unique to them. Because of this discrepancy in terminology, it can sometimes be a challenge to simply discover what information the vendor is asking for, or what to do with the information they're providing.
To remove differing terminology from the equation, just remember that you will need the vendor/developer to provide you with the pieces of information to enter into the application on the Okta side:
- the application's specific URL that SAML assertions should be sent to (typically referred to as the ACS). In Okta, this is entered in the application's Single Sign On URL field.
- the Audience Restriction, which dictates the entity or audience the SAML Assertion is intended for. This field is frequently referred to as the Entity ID or Audience URI. It can technically be any string of data up to 1024 characters long, but is usually a URL that contains the Service Provider's name within, and is often simply the same URL as the ACS.
- the username format expected by the application (ie email address, first initial last name, etc)
The service provider will occasionally require that the assertion contain additional attributes such as first name, last name, department, etc to help identify the user. In such cases, be sure to ask the vendor to provide you with the Attribute Name (ie firstName, lastName) and Name Format (Unspecified, URI Reference, and Basic) for each required attribute.
You will also need to provide the vendor/developer with the following information from the Okta application (accessed via the "View Setup Instructions" in the application's Sign On tab):
- the Identity Provider Single Sign-On URL. The SP may refer to this as the SSO URL or SAML Endpoint. It's the only actual URL provided by Okta, so it's safe to say that any field on the Service Provider side that is expecting a URL will need this entered into it.
- the Identity Provider Issuer. This is often referred to as the Entity ID or simply "Issuer." The assertion will contain this information, and the SP will use it as verification.
- the x.509 Certificate. Some service providers allow you to upload this as file, whereas others require you paste it as text into a field.
Some other troubleshooting tips:
- We highly recommend installing SAML Tracer, a free and simple Firefox plugin that will capture and display SAML assertions. This can help determine whether the URL's are correct, whether the assertion is passing the required attributes, whether the username is as expected, etc.
- During initial setup, it's a fairly common mistake to enter the application's standard login page (e.g. https://account.box.com/login) in the Okta "Single Sign On URL" field, instead of entering the application's ACS (e.g. https://sso.services.box.net/sp/ACS.saml2). Since the standard login page cannot process SAML assertions, this will result in one of two issues:
- the user is directed to a page with a standard login prompt when they attempt to launch the application
- the user experiences an endless loop of being redirected to Okta, and then back to the application's normal login page (which can't handle SAML assertions), then back to Okta, etc. This can occur when the application utilizes a custom or "vanity" domain (ie https://MyCompany.my.salesforce.com) that is configured to redirect authentication to the IdP.
- A simple way to help verify whether you are entering the correct value in the Single Sign On URL field is to simply try to navigate to it from a browser. If the URL is indeed the vendor's ACS, you should receive an error of some sort because you are navigating to the page without sending an assertion to it. If a login prompt appears instead, it is very likely that you have an incorrect Single Sign On URL.
- If you receive an error message indicating that the username is invalid or not found, you'll first need to verify what username convention is expected on the SP side and then verify that Okta is indeed sending proper usernames in the assertion. You can verify what username the Okta application is sending by navigating to the application's "Assignments" tab and clicking the pencil icon next to an affected user. This will display the username that is being sent in the assertion, and will need to match the username on the SP side.
If you've installed SAML Tracer and use it to extract the SAML assertion, it will display the username as follows:<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">user@MyCompany.com</saml2:NameID>
- Begin by verifying the following information from the Service Provider you intend to integrate with Okta:
- whether standard login methods are disabled once SAML is activated, and if so, how to log in if SAML is disrupted
- if possible, it's best to create at least one "service account" on the SP side that can bypass SAML and access its admin console via their login page. This will allow a "back door" entry in the event that the SAML flow is interrupted for any reason. Some service providers (G Suite, for example) bypass SAML automatically if the user is a member of a particular administrator group.
- the endpoint information discussed above
- whether they support IDP and/or SP initiated authentication flows
- whether they support potentially useful features such as JIT Provisioning and Single Log Out (SLO)
- what attributes they expect to receive in the assertion
- whether they support encrypted assertions
- During the creation of the application, briefly document some key configurations such as the username format, additional attributes, configured features, etc.
- Familiarize yourself with tools such as Fiddler or the aforementioned SAML Trace utility to examine the SAML assertion