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, allowing for a Single Sign-On (SSO) experience.
 

Okay, but what does it do, and why does it do it?

SAML completely changes how a user signs into a SAML-supported site or service. Once an SP (for example, Box or Salesforce) 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 into (for example, a Box username and password). Instead, an exchange between the SP and the configured IdP will occur that will verify the user's identity and permissions and then grant or deny that user’s access to the SP. In other words, instead of using user credentials (like a password) to verify a user, a SAML-configured service verifies that user's identity with the IdP.  Of course, this assumes the user has already logged into the IdP with a username and password (and ideally multi-factor authentication as well!).

(NOTE: This document will refer to the IdP as “Okta” in examples from this point forward.)

There are two different sign-in flows that SAML can handle for authentication. The first method, 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 configured to use SAML will redirect the user to Okta. Okta will then handle the authentication by prompting the user to log into Okta or via Desktop Single Sign On (DSSO). 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 a verified 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 tile 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 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 tiles 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 browser tab can access the token created when the user logs into Okta, resulting in an effortless, near-instantaneous authentication.
 

How does it do all of that?

Both IdP and SP-initiated authentication flows rely upon assertions that are passed between the user’s browser and URLs 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

1. The user (for example, 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 made from usernames with a particular domain (for example, MyBusiness.com). SPs that utilize custom login pages (for example, https://MyCompany.Dropbox.com) can often be configured to utilize SAML for ALL login attempts.

2. 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.

3. Once the user is redirected to Okta, they will need to enter their Okta credentials, unless they have 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:

   1. Indicate that it is indeed from Okta and has not been altered, and contains 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.

   2. Indicate that the user has authenticated successfully into Okta

   3. Indicate who the user is via the NameID, a standard attribute used in SAML assertions.

4. After the SP’s ACS successfully parses the assertion, the user will be sent to the SP’s default relay state, which is usually the same page they would wind up on if they had 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 tools are available online. These tools can be extremely useful for understanding and troubleshooting SAML assertions. They allow the extrapolation of SAML assertions from a browsing session and examination line-by-line.  

If unable to install browser extensions, an alternate option is to collect a browser log file (normally called HAR files). One HAR log has been extracted; the SAML Token request and/or SAML Token response need to be collected within the logs. Once collected, they can be decoded with https://samltool.io/ (samltool.io is brought by Auth0/Okta). (HAR file will show the desired SAML workflow and contain the SAML tokens, which contain the data needed to triage SAML assertions as well)

Why does the custom SAML app I have configured in Okta not work?

An incorrect URL is a common cause of support cases. This is common because there is, 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 are providing.

To remove differing terminology from the equation, just remember that at a basic level, the vendor/developer will need to provide the following information to enter into the custom application that has been created in the Okta organization:

1. The application's specific URL to which SAML assertions from Okta should be sent (typically referred to as the ACS). In Okta, this is entered in the application's Single Sign On URL field.  Remember that this will likely not be the same URL as the application's basic login page, which generally cannot receive or process SAML assertions.

2. The Audience Restriction dictates the entity or audience the SAML Assertion is intended for. This field is frequently referred to as the "Entity ID" or "Audience URI" by vendors. It can technically be any string of data up to 1024 characters long but is usually in the form of a URL that contains the Service Provider's name and is often simply the same URL as the ACS.

3. The username format the application expects (that is, the 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, ask the vendor to provide the Attribute Name (that is, firstName, lastName) and Name Format (Unspecified, URI Reference, and Basic) for each required attribute.

The vendor/developer will also need to be provided with the following information from the Okta application (accessed via the View Setup Instructions button in the application's Sign On tab):

1. The Identity Provider Single Sign-On URL. The SP may refer to this as the "SSO URL" or "SAML Endpoint." It is the only actual URL Okta provides when configuring a SAML application, so it is safe to say that any field on the Service Provider side expecting a URL will need this entered into it.

2. 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.

3. The x.509 Certificate. Some service providers allow the upload of this as a file, whereas others require the certificate to be pasted as text into a field.

Some other troubleshooting and testing tips:

• Finding a SAML Tracer tool that will capture and display SAML assertions. This can help determine whether the URLs are correct, whether the assertion is passing the required attributes, whether the username is as expected, etc.
• A browser log file can be collected (HAR Log) when replicating a SAML workflow. Once the HAR log is collected, the SAML request and SAML response tokens within the HAR logs must be collected. Once the SAML tokens have been located, they can be decoded using https://samltool.io/ (samltool.io is brought by Auth0/Okta). Once SAML tokens are decoded, one will be able to determine whether the passed URLs are correct, whether the assertion is passing the required attributes, whether the username is as expected, etc.

• During initial setup, it is a fairly common mistake to enter the application's standard login page (for example, https://account.box.com/login) in the Okta "Single Sign On URL" field instead of entering the application's ACS (for example, 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 cannot handle SAML assertions), then back to Okta, etc. This can occur when the application utilizes a custom or "vanity" domain (that is https://MyCompany.my.salesforce.com) configured to redirect authentication to the IdP.

  • A simple way to verify that the correct value is being entered in the Single Sign On URL field is to try to navigate to it from a browser. If the URL is indeed the vendor's ACS, an error should be received because navigation to the page occurs without sending an assertion to it. If a login prompt appears instead, it is likely an incorrect Single Sign-On URL.

• If an error message is received indicating that the username is invalid or not found, the first step is to verify what username convention is expected on the SP side and then verify that Okta is indeed sending proper usernames in the assertion. 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 being sent in the assertion and will need to match the username on the SP side.

If an in-browser extension tool has been installed and used to extract the SAML assertion (or has decoded SAML Tokens with samltool.io ), it will display the username as follows :

• <saml2:NameIDFormat="urn:oasis:names:tc:SAML:1.1:nameidformat:unspecified">user@MyCompany.com</saml2:NameID>

Deployment Best Practices

Begin by verifying the following information from the Service Provider that is planned to integrate with Okta:

• Whether standard login methods are disabled once SAML is activated, and if so, if there is another way for users to log in traditionally (using a username and password) if Okta authentication is disrupted.

  • If possible, it is best to create at least one "service account" on the SP side that can bypass SAML and access its admin console via its login page. This will allow a "back door" entry if 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 SAML attributes do they expect to receive in the assertion

Okta also recommends familiarizing with tools such as SAML Tracer tools, HAR files, and or any browser/network trace tool that will allow review and examination of the SAML assertions 

If in contact with Okta Support, support will occasionally require log collection to be provided in order to troubleshoot. They will normally request HAR files to be uploaded to support cases, as they will automatically sanitize all sensitive information once uploaded to the case. 

Summary of Common SAML Terms:

Assertion: data provided by the IdP that supplies one or more of the following statements to a service provider:

• Authentication statements assert that the user specified in the assertion did authenticate successfully and what time they did so.

• Attribute statements supply attribute values pertaining to the user.  The NameID attribute is required and specifies the username, but other attributes can be manually configured as well.

• Authorization decision statements declare that a request to allow the assertion subject to access the specified resource has been granted or denied.

Assertion Consumer Service (ACS): the service provider's endpoint (URL) responsible for receiving and parsing a SAML assertion.  Remember that some service providers use a different term for the ACS.  In the Okta SAML template, this is entered in the Single Sign On URL field.

Attribute: a set of data about a user, such as a username, first name, employee ID, etc.

Audience Restriction: a value within the SAML assertion that specifies who (and only who) the assertion is intended for.  The "audience" will be the service provider and is typically a URL, but can technically be formatted as any string of data.  If this value is not provided by the SP, try using the ACS.

Default Relay State: the URL that users will be directed to after a successful authentication through SAML.

Endpoint: the URLs that are used when Service Providers and Identity Providers communicate with one another.

Entity ID: a globally unique name for an Identity Provider or a Service Provider.  A unique Okta Entity ID is generated for each application and is referred to as the Identity Provider Issuer in the Okta application's Setup Instructions.

Identity Provider (IdP): the authority that verifies and asserts a user's identity and access to a requested resource (the "Service Provider").

Metadata: a set of information supplied by the IdP to the SP, and/or vice versa, in XML format.

• SP-supplied metadata will typically provide the ACS, the Audience Restriction, the NameID format, and an x.509 certificate if the assertion needs to be encrypted.  At this time, SP-supplied metadata files cannot be imported into Okta.

• IdP-supplied metadata will provide the Single Sign On URL, the Entity ID, and the x.509 certificate file required by the SP to decrypt the assertion.

NameID: an attribute within the assertion that is used to specify the username.

Service Provider (SP): the hosted resource or service the user intends to access, such as Box, Workday, Salesforce, a custom application, etc.

Single Sign On URL: the endpoint dedicated to handling SAML transactions.  In the Okta SAML template setup screen, the SSO URL refers to the service provider's ACS.