Skip to content
SteveTechArcSteveTechArc Courses

the Relay State

Module 6 of 7 in the chapter Salesforce as the Service Provider: SAML, chapter 6 of Securing Salesforce: Identity and Access. Each module stands on its own.

The question this module answers: Priya clicked a link to one record. After all those redirects, how does she end up on that record, and not on Home?

Section titled “The link in the email”

Here’s a common one. Priya gets an email: “Can you look at this opportunity before the meeting?” She clicks the link. It goes straight to one opportunity in Salesforce. That’s called a deep link: a link to a page inside an app, not its front door.

She isn’t logged in yet. So the instance sends her to the login server, the login server sends her to the identity provider, she signs in, and she’s sent back. Four redirects. And at the end, she should be looking at that opportunity.

So here’s the question. Her original link has been through all those redirects. What carries it?

It has to be in every step

Section titled “It has to be in every step”

The relay state. It’s a value that travels alongside the SAML messages, holding the page she asked for. Salesforce describes it as a parameter “passed to the IDP” with the SAML request, that “controls where users are redirected after a successful login” (S5).

And here’s the part that matters. The relay state has to be in step two, in step three, in step four and in step five. If any step doesn’t pass it on, it isn’t there at the end.

The relay state rides every arrow The same four lanes as the SP-initiated flow. Step 1: Priya opens a link to one opportunity from an email; Salesforce's instance has no session, remembers the page she asked for and redirects her with it. Step 2: the login server writes the SAML request and puts the page in the relay state. Step 3: the browser takes the SAML request and the relay state to the identity provider, which must send the relay state back unchanged; this is the step that most often drops it. Step 4: the browser posts the SAML response and the relay state; Salesforce checks the response and reads the relay state, then redirects her to that page with a session. Step 5: she goes straight to the opportunity, not Home. Footnote: drop the relay state at any step, and she lands on Home instead. {"author": "Steve Simpson", "blueprint": "1.0.0", "builder": "standard 1.58.0", "built": "2026-11-03", "id": "DGM-IAM-SP-05", "rights": "\u00a9 2026 Twinshark LLC. All rights reserved.", "template": "cells 0.5.0", "theme": "stevetecharc 1.4.0"} PRIYA'S BROWSER THE IDENTITY PROVIDER SALESFORCE'S LOGIN SERVER SALESFORCE'S INSTANCE 1. Opens a link to one opportunity, from an email No session yet remembers the page she asked for 2. Goes to the login server carrying the page Writes the request and puts the page in the relay state 3. Goes to the identity provider SAML request + relay state The login screen must send the relay state back, unchanged 4. Hands over the response SAML response + relay state Checks it and reads the relay state 5. Straight to the opportunity not Home The opportunity the page she asked for asks for the opportunity redirect + the page follows, with the page SAML request + relay state SAML request + relay state SAML response + relay state SAML response + relay state redirect to the page + session asks for the opportunity the opportunity Drop the relay state at any step, and she lands on Home instead. HOW TO READ IT the step that most often drops it she lands where she meant to © 2026 Twinshark LLC · stevetecharc.com
Click to enlarge

Salesforce writes it, and Salesforce reads it at the end. But in the middle, the identity provider has to take it in and give it back unchanged. That’s the step where it most often gets lost. And if it comes back empty, Salesforce does the only thing it can: “the user is redirected to the Salesforce Home page by default instead of the originally requested resource” (S5).

From Priya’s point of view, she clicked a link to an opportunity and ended up on Home. She has to go and find it herself. It isn’t a security problem. It’s just annoying, and in a big org, people notice.

Test knowledge. In my experience, know the relay state: it’s what carries the original page through a SAML login, so a deep link lands on the page the user asked for.

Why it gets lost

Section titled “Why it gets lost”

Salesforce’s own article on an empty relay state points to one cause: how the messages are sent. Salesforce uses a form post during the SAML exchange, and if the identity provider’s address is set up to receive a plain link (a GET request) instead, the relay state comes back empty (S5). Their suggestion is to match the two: the Service Provider Initiated Request Binding in the single sign-on setting (POST or Redirect, module 3) and what the identity provider expects.

When a deep link lands on Home, this is how I’d check it: open a SAML tracer (module 4), click the deep link in a private window, and look for the relay state in the request going out and in the response coming back. Wherever it disappears, that’s the side to fix.

Starting at the identity provider

Section titled “Starting at the identity provider”

In the IdP-initiated flow from module 2, there’s no link and no request. Priya clicked a button on the app launcher. So where should she land?

By default, Home. But the identity provider can add a relay state itself. Salesforce’s way to do it is to add &RelayState= and the page to the end of the identity provider’s link for Salesforce (S4). So an app launcher button could open Salesforce straight onto a dashboard, or a particular app.

One rule: the page must be inside your org, written as a path, not a full address to somewhere else. A relay state pointing outside Salesforce fails with an “Invalid Page Redirection” error (S4). That’s a good rule, too. It stops anyone using your login to send people off to another site.

A small example

Section titled “A small example”

Salesforce’s own article uses /00O/0 as the relay state, which lands the user on the Reports tab, because 00O is the start of every report’s ID (S5). Every type of record has a short code like that at the start of its IDs. You’ll meet it again whenever you build links into Salesforce.

What’s next

Section titled “What’s next”

Module 7: what to do when single sign-on doesn’t work at all.

What an architect decides here

Section titled “What an architect decides here”
  • Which deep links matter: emails, other apps and bookmarks that point into Salesforce.
  • The binding, POST or Redirect, agreed with the identity provider so the relay state survives.
  • Where IdP-initiated logins land, if not Home, and the relay state that does it.

Explore

Section titled “Explore”

Follow Me

© 2023–2026 Twinshark LLC. All rights reserved. · Content Use

Privacy notice

SteveTechArc is independent and is not affiliated with, sponsored by, or endorsed by Salesforce, Inc. Salesforce and related marks are trademarks of Salesforce, Inc.

Educational content, shared as is. Not professional, legal or financial advice. Salesforce changes several times a year, so check current Salesforce documentation before you rely on any platform detail.