Before any field makes sense, you need to know who the players are and why they must share a few facts in advance.

The two players in every SSO login

Every SAML single sign-on login involves two systems. The first is the Identity Provider, usually shortened to IdP. This is the system that knows your users and checks their passwords and extra security steps. In this guide, Okta is the IdP. The second is the Service Provider, shortened to SP. This is the application the user actually wants to use, such as a learning portal, a ticketing tool, or a cloud console.

The user sits in the middle with a web browser. The browser carries messages between the IdP and the SP. The two systems never need to speak to each other directly during a login. That is a very important design choice, and it is the reason the two fields in this guide matter so much.

Why they must agree in advance

Because the browser carries the message, anyone could in theory try to hand an app a fake message, or hand an app a real message that was meant for a different app. To stop that, Okta and the app exchange a few facts once, during setup. Okta learns the exact address where the app wants to receive logins. The app learns the name Okta will stamp on every login message. Later, at login time, each side checks the other against those saved facts.

If the two sides do not agree, the login fails. It does not fail loudly with a helpful message in many cases. It often fails with a short, confusing error page. That is why learning these two values properly saves hours of debugging later.

SAML is the language Okta and the app speak. A few words from it will make the rest of this guide easy.

What SAML is

SAML stands for Security Assertion Markup Language. It is an open standard, first created in the early 2000s, that lets one system tell another system “this person has been checked, and here are some facts about them”. The version used almost everywhere today is SAML 2.0, finished in 2005. It is older than many popular login tools, and it is still the main choice for company logins to business software because it is stable and widely supported.

The words you will meet

How messages travel: bindings

A binding is simply a delivery method. With HTTP-Redirect, the message is squeezed into the web address itself, and the browser is sent to that address. This is used for short messages such as the login request. With HTTP-POST, the message is placed inside a hidden web form, and the browser submits the form automatically. This is used for the larger response, because it holds a signed assertion that is too big for an address. The ACS URL is exactly where that hidden form is submitted.

The trust comes from certificates

How does the app know the response truly came from Okta? Okta signs it with a private key, and the app holds the matching public certificate, which it received during setup. If the signature checks out, the app knows two things: the message really came from Okta, and nobody changed it on the way through the browser. The ACS URL and Audience URI work alongside this signature. The signature proves who wrote the message, and these two values prove where it was meant to go and who it was meant for.

ACS stands for Assertion Consumer Service. It is the front door of your application for SAML logins.

The definition

The ACS URL is a web address on your application, the Service Provider. It is the one place that is willing to accept a SAML response from Okta and turn it into a logged-in session. The word “consumer” means the app is the one that consumes, or uses, the assertion. When Okta finishes checking a user, it tells the browser to send the signed response to this address.

The ACS URL belongs to the application, not to Okta. The application’s makers decide what it is. For a ready-made product, the vendor gives you the value in their setup guide. For an app your own team builds, you choose it and your code must listen there. In Okta, you type that value into the field called Single sign-on URL.

What the ACS URL looks like

It is an ordinary web address, and it must use HTTPS in any real setup. Typical shapes include an address with a path such as /saml/acs, /sso/saml, or /auth/saml/callback. Some products include a unique identifier for your account inside it, so the address is different for every customer. Others use one fixed address for everyone. Neither style is better; they simply reflect how the vendor built the product.

Exact match matters

Okta and the app compare these addresses character by character. A trailing slash, a different capital letter, the word “http” instead of “https”, or a missing port number can all cause a mismatch. This is one of the most common causes of broken SSO, and it is almost always caused by a copy-and-paste slip. Wildcards are not allowed, so you cannot say “any address under this domain”.

One address or several

Most apps have exactly one ACS URL. A few large products publish more than one, for example one per region or one per binding. SAML metadata can number them with an index, so that a login request can say “use the second one”. Okta supports this idea through an option that lets the app request other single sign-on URLs, covered in a later chapter.

If the ACS URL answers “where does it go?”, the Audience URI answers “who is it for?”.

The definition

The Audience URI is the name that Okta writes inside the assertion to say which application the assertion was created for. In the SAML standard it is called the Audience, and it sits inside a section called the audience restriction. In practice, it carries the same value as the application’s Entity ID, which is why Okta labels the field Audience URI (SP Entity ID).

“Audience” is the same word used for a theatre audience: the people a performance is meant for. An assertion with an audience restriction says, in effect, “this proof is only for the application named here”. When the app receives it, the app compares that name to its own entity ID. If they match, the app continues. If they do not, the app must reject the assertion, even if the signature is perfect.

It is a name, not always an address

The word “URI” is a little misleading. A URI is a general kind of identifier. It can look like a web address, such as https://learn.acme-example.com/saml/metadata, or like a plain label, such as urn:amazon:webservices. The app does not need to host anything at that address. It is only a label that must match exactly. Many people waste time trying to open the Audience URI in a browser, when it was never meant to be opened.

Who decides the value

Like the ACS URL, the Audience URI is owned by the application. The vendor documents the value, or shows it on their SSO settings page, or publishes it inside their SAML metadata file. You copy it into Okta. Okta does not invent it. Okta only copies it into each assertion it creates for that app.

Why this field is a security feature

Without an audience check, an attacker or a careless user could take a valid assertion made for a low-risk app and present it to a high-risk app that trusts the same Okta. The audience restriction is what makes that fail. Each app only accepts assertions with its own name on them. We return to this in the security chapter.

The two values are easy to mix up. This chapter puts them next to each other, and adds the other values that travel with them.

The cousins: Recipient, Destination, and Issuer

Three other values travel with the ACS URL and Audience URI, and they often appear in the same Okta screen or the same error message. It helps to know them now.

In Okta, a single checkbox ties several of these together. It reads “Use this for Recipient URL and Destination URL”. When it is ticked, Okta copies the Single sign-on URL into both the Recipient and the Destination. This is correct for the vast majority of applications. Only a few unusual products need different values for each, and in that case you untick the box and fill them separately.

A walk through the Okta Admin Console when you create a custom SAML app. Button names can shift slightly between Okta releases, but the idea stays the same.

Other fields on the same screen

Beside the two key fields, the screen holds several settings that affect how these values behave. Default RelayState chooses the page the user lands on after login. Name ID format chooses how the user is named, with common choices such as email address, persistent, transient, or unspecified. Application username chooses which Okta profile value becomes the login name. In the advanced area you can choose whether the response and the assertion are signed, the signing algorithm, whether to encrypt the assertion, and which certificate to use. There is also the SAML Issuer ID, which controls the issuer name Okta writes.

Requestable SSO URLs

Below the Single sign-on URL, Okta offers an option to allow the app to request other SSO URLs. When you switch it on, you can list extra ACS addresses, each with an index number. This is useful when an application has several valid delivery addresses and decides at login time which one to use. If the app asks for an address that is not on the list, Okta refuses the request instead of delivering to an unknown place.

Pre-built apps do this for you

The Okta Integration Network, called the OIN, holds thousands of ready-made app templates. When you pick one, many of the fields are pre-filled or built from a small number of questions, such as your account name. The ACS URL and Audience URI are produced from your answers using patterns the vendor and Okta agreed on. For these apps, you rarely type either value by hand. For a custom or in-house app, you always do.

Let us zoom out and see every moving part in a typical Okta SAML setup, and where each value lives.

flowchart LR
  U["User and Web Browser"]
  subgraph SP["Service Provider - the Application"]
    A1["Login Entry Point"]
    A2["ACS Endpoint - the ACS URL"]
    A3["Saved Settings: Entity ID, Okta Issuer, Okta Certificate"]
  end
  subgraph IDP["Identity Provider - Okta"]
    O1["Okta SSO Endpoint"]
    O2["Sign-in and MFA Service"]
    O3["App Settings: Single sign-on URL, Audience URI"]
    O4["Signing Key"]
    O5["User Directory"]
  end
  U --> A1
  A1 --> O1
  O1 --> O2
  O2 --> O5
  O3 --> O4
  O4 --> U
  U --> A2
  A2 --> A3
    

Component by component

The browser is the courier. It carries the login request to Okta and carries the signed response back to the app. It is not trusted. It can be inspected and, in the wrong hands, tampered with, which is why signatures matter.

The login entry point on the app is the page or route that starts a login. For SP-initiated logins, it creates a request and sends the user to Okta. For some apps, it just redirects the user to Okta’s address without any request at all.

The ACS endpoint is the code on the app that listens at the ACS URL. It reads the response, checks the signature and every value inside, creates a session, and redirects the user into the app. This is the most security-sensitive piece of code in the whole integration.

Okta’s SSO endpoint is the address on Okta that receives login requests for your specific app. It includes an identifier unique to that app, so one Okta organization can host many SAML apps side by side.

The sign-in and multi-factor service checks the password and any extra proof, such as a phone prompt or a security key. The app never sees this step and never handles the password. That is one of the biggest benefits of SSO.

The app settings in Okta hold the Single sign-on URL and the Audience URI you typed. The signing key is the private key Okta uses to sign responses for the app. The directory holds users, groups, and profile facts.

This is the most common flow. The user starts at the application and is sent to Okta to prove who they are.

sequenceDiagram
  autonumber
  participant U as User Browser
  participant S as Service Provider
  participant O as Okta
  U->>S: Open the app page
  S->>U: Redirect to Okta with an AuthnRequest
  U->>O: Follow redirect to the Okta SSO address
  O->>O: Check the request ACS address against the app settings
  O->>U: Show sign-in page and ask for MFA
  U->>O: Enter password and approve MFA
  O->>O: Build assertion with Audience and sign it
  O->>U: Return a form targeting the ACS URL
  U->>S: Auto-submit form to the ACS URL
  S->>S: Check signature, Destination, Recipient, Audience, time
  S->>U: Create session and show the app
    

Step by step

Notice that the ACS URL shows up in two places. In step 2 the app may tell Okta where it wants the answer. In step 6 Okta actually delivers there. Okta only trusts the first if it matches the address you configured. This two-way agreement is what stops a forged request from redirecting a user’s proof to an attacker’s server.

Sometimes the user starts at Okta instead. This changes how the ACS URL and Audience URI are used.

sequenceDiagram
  autonumber
  participant U as User Browser
  participant O as Okta Dashboard
  participant S as Service Provider
  U->>O: Sign in to the Okta dashboard
  O->>U: Show app tiles
  U->>O: Click the app tile
  O->>O: Build assertion with no request to answer
  O->>U: Return a form targeting the configured ACS URL
  U->>S: Auto-submit form to the ACS URL
  S->>S: Validate the assertion
  S->>U: Create session and show the app
    

What is different

In an IdP-initiated login, the user first signs in to Okta’s dashboard and clicks a tile for the app. No request came from the app, so Okta has nothing to answer. Okta simply builds an assertion using the settings you saved and posts it to the configured Single sign-on URL. The app receives a response it never asked for. Many apps allow this. Some deliberately refuse it, because without a request number to match, the app has one fewer check against replayed responses.

Why several ACS addresses exist

Some products serve users from several regions or several customer-specific domains. A single account might have more than one valid delivery address. In Okta, you can switch on the option that allows the app to request other SSO URLs, then add each address with an index. At login, the app’s request can point to one of them by address or by index number. Okta delivers only to a listed address. The configured main Single sign-on URL is used for the default case and for IdP-initiated logins.

An assertion is born, signed, delivered, checked, and then expires within minutes. Knowing its life explains many strange failures.

What is inside the assertion

An assertion is organised in sections. The issuer section names Okta’s side. The signature section holds the digital seal. The subject section names the user, and holds the confirmation data that includes the Recipient, an expiry time, and the number of the request being answered. The conditions section holds the earliest and latest valid times and the audience restriction with the Audience URI. The authentication statement records when and how the user signed in. The attribute statement carries extra facts such as email, name, and groups.

Time matters

The assertion carries a “not before” time and a “not on or after” time. If the app’s clock is far from Okta’s clock, the app may think a fresh assertion is not yet valid or already expired. Apps normally allow a small difference, often a few minutes, called clock skew. Servers should keep their clocks in sync using a standard time service. Time errors look very much like address errors from the outside, so always rule them out.

The ACS endpoint is a checklist. Each item can fail on its own. Here is the usual order.

flowchart TD
  S["Response arrives at the ACS URL"]
  C1{"Signature valid with Okta certificate?"}
  C2{"Issuer matches saved Okta issuer?"}
  C3{"Destination equals this ACS URL?"}
  C4{"Recipient equals this ACS URL?"}
  C5{"Audience equals my Entity ID?"}
  C6{"Current time inside valid window?"}
  C7{"Request number matches, assertion not seen before?"}
  OK["Create session and log user in"]
  NO["Reject with an error"]
  S --> C1
  C1 -->|yes| C2
  C1 -->|no| NO
  C2 -->|yes| C3
  C2 -->|no| NO
  C3 -->|yes| C4
  C3 -->|no| NO
  C4 -->|yes| C5
  C4 -->|no| NO
  C5 -->|yes| C6
  C5 -->|no| NO
  C6 -->|yes| C7
  C6 -->|no| NO
  C7 -->|yes| OK
  C7 -->|no| NO
    

The checks in simple words

Two things stand out. First, three checks compare against values you typed into Okta: the Destination, the Recipient, and the Audience. Those come from the two fields in this guide. Second, any one failed check ends the login. The app does not “mostly” accept a response.

Where the error message appears

Because the failure happens inside the app, the user sees the app’s own error page, not Okta’s. Wording varies a lot from one product to another. Some say the audience is not valid. Others say the recipient does not match, or give a generic message such as “SSO failed”. Check the app’s own logs, since they usually name the exact check that failed.

The pattern is the same everywhere, but each vendor picks different values. Here are well-known examples and what to learn from each.

These values are not paperwork. Each one closes a real attack path.

Threat 1: using a login at the wrong app

Suppose a user has a valid assertion for a minor app, such as a lunch-menu tool. If a high-value app, such as the payroll system, accepted any assertion from the same Okta, a malicious owner of the lunch tool could replay the user’s assertion at payroll and log in as that user. The audience check blocks this. The payroll app only accepts assertions with its own name on them. This is sometimes called a token substitution or confused-audience attack.

Threat 2: sending a login to the wrong place

If an attacker could trick Okta into delivering an assertion to an address the attacker controls, they would capture the user’s proof. Okta defends against this by delivering only to the configured Single sign-on URL, or to a listed requestable URL. The app defends by checking the Destination and Recipient. Together this is the delivery check.

Threat 3: replay and tampering

A captured response could be submitted again later. Defences include the short expiry, the request-number check on SP-initiated logins, and a stored list of used assertion numbers. Tampering is stopped by the signature. A weakness called XML signature wrapping tries to hide forged content next to the signed part, so good SAML libraries must check that the part they read is the part that was signed. This is a strong reason never to write your own SAML code when a maintained library exists.

Good security habits for these fields

Certificate rotation

Okta’s signing certificate does not last forever. When it nears its end date, you create a new one in Okta and give the app the new public certificate. If the app is not updated in time, every login fails at the signature check. Plan the change with an overlap, and put the expiry date in a shared calendar, because this is one of the most common causes of surprise SSO outages.

When SSO breaks, you need to see what Okta sent and what the app expected. These are the tools and habits that find the problem fast.

Where to look

A calm way to troubleshoot

Common symptoms and likely causes

Monitoring for the long term

Good teams do not wait for users to complain. They watch for a rise in failed SSO events for a given app in the Okta log, and they set an alert. They keep a list of every SAML app with its ACS URL, Audience URI, certificate expiry date, and owner. They test SSO after any change to the app’s domain, load balancer, or certificate. Even a simple weekly look at the failure count will catch most problems before a big group of users is locked out.

Some habits keep SSO calm for years. Others cause a crisis at the worst moment.

Patterns worth copying

Anti-patterns to avoid

A short, practical checklist you can use every time you set up a SAML app in Okta.

Before you start

• Read the vendor’s current SAML setup page, and note the ACS URL, the entity ID, and any special notes.
• Ask whether the vendor offers a metadata file or link. Prefer it over typing.
• Decide who will own the app, and who will renew the certificate.
• Confirm whether the app needs IdP-initiated login, SP-initiated login, or both.

While you configure

• Paste values from the source. Never retype them from a screenshot.
• Keep the Recipient and Destination box ticked unless the vendor says otherwise.
• Pick the Name ID format that the app expects, and set the application username to match.
• Send only the attributes the app needs. Less data means less risk.
• Use the assertion preview before assigning real users.

After you finish

• Test with an assigned user in a clean private browser window, for both login directions.
• Record the values and certificate expiry in your registry.
• Set an alert for repeated failed SSO events in the Okta log.
• Plan certificate renewal at least a month before expiry.

Mistakes seen again and again

The strict matching of the ACS URL and Audience URI is both a strength and a nuisance. Here is the honest picture.

Trade-offs to think about

• Security versus convenience: IdP-initiated logins are friendly for users but have less protection against replay. Choose per app.
• Simplicity versus flexibility: one ACS URL is simple. Several requestable URLs allow regional or branded setups, but need careful upkeep.
• Typed values versus metadata: typing is quick for a single app. Metadata exchange takes slightly longer at the start but removes many errors.
• Shared versus unique audience names: shared names save effort and weaken security. Unique names cost a little more bookkeeping and add real safety.

How this compares with OpenID Connect

Okta also supports OpenID Connect, often shortened to OIDC, a newer way to do SSO built on a different design. It has close cousins of both values. The redirect URI plays a role like the ACS URL: it is the registered address where the login result is delivered, and it must match exactly. The client ID plays a role like the Audience URI: it names the app that the token is meant for. If you understand these two SAML values well, the OIDC ideas will feel familiar. SAML is still very common for older and enterprise software, while OIDC is common for newer web and mobile apps.

Many “mystery” mismatches have nothing to do with Okta. They come from the network layers that sit in front of your application.

The app sometimes does not know its own address

In a modern cloud setup, users do not talk straight to your application servers. Their request first meets a CDN, a web firewall, or a load balancer, and only then reaches the app. A common design is called TLS termination: the load balancer handles the secure HTTPS connection, then passes the request on to the app over plain HTTP inside the private network. The app, looking only at the connection it received, may believe its own address starts with “http” and has an internal host name. If the app builds its ACS URL from what it sees, the result will not match the public address you typed into Okta.

The usual fixes

Caching and the ACS endpoint

A content delivery network is built to remember pages. The ACS endpoint must never be remembered. Each response is unique to one user and one moment. Configure the CDN to pass POST requests to the app and to skip caching for the whole SAML path. Otherwise, one user’s login may be served wrongly to another, or a login may fail because the app never received the request.

Many servers behind one address

With several app servers behind a load balancer, the browser may reach a different server for the second step than the first. For SP-initiated logins, the app remembers the request number it sent. For replay protection, it remembers assertion numbers it has seen. If each server keeps its own private memory, a response can arrive at a server that never saw the request, and a good login will be refused. The fix is to keep that small memory in a shared place, such as a shared cache or database, with a short expiry.

So far we focused on the two values that come from the app. The trust only works if the app also saves the values that come from Okta.

The three things the app needs from Okta

After you finish creating the app in Okta, the Sign On tab shows the details the application must be told. Many apps accept them all at once through a metadata link or file. Others ask for each item separately.

Do not mix up the two sets of values

A very common error is to swap the two sets. The app’s ACS URL and Audience URI go into Okta. Okta’s sign-on address, issuer, and certificate go into the application. Each side stores what the other side gave it. It helps to write both sets on a small sheet with the headings “We give Okta” and “Okta gives us”.

Name ID and attributes: who is the user?

One more part of the response matters to the app: the name of the user. The Name ID is the main identifier, such as an email address. The application must match it to an account in its own system. If the app expects an email address but Okta sends a different format, the app will say it cannot find the user, even though everything else is correct. Extra attributes, such as first name and group, are matched by their exact attribute name. A tiny spelling difference means the app sees nothing. These settings are not the ACS URL or the Audience URI, but they are often the very next problem after you fix those two.

The ACS endpoint is a small piece of code, but it can face a huge crowd all at once. Here is how to keep it fast and how to handle failures.

The morning rush

Logins are not spread evenly across the day. At the start of a work shift or the start of an exam, thousands of people may open the app within the same few minutes. Each of them triggers one trip to Okta and one post to the ACS URL. The ACS endpoint has real work to do on each one: it decodes the text, parses the XML, checks a digital signature, checks several values, may decrypt the assertion, and creates a session. Checking a signature uses noticeable computing power, so a login spike is a CPU spike.

Ways to keep it healthy

• Scale out: run several app servers behind a load balancer, and add more before known busy times.
• Keep the endpoint light: do the validation, create the session, and redirect. Leave heavy work, such as loading large profiles or sending emails, for after the redirect.
• Reuse parsed settings: load Okta’s certificate and the saved values once and keep them in memory, rather than reading them from a database on every login.
• Use a shared, expiring memory: for request numbers and used assertion numbers, with a lifetime a little longer than the assertion’s validity.
• Set sensible session lengths: a longer app session means fewer logins and less load, but a slightly longer window after a user is removed. Choose with your security team.
• Limit body size sensibly: allow enough for a normal response, and refuse anything wildly bigger, which is likely abuse.

What if Okta is unavailable?

The application only needs Okta at the moment of login. Users who already have an app session usually keep working until the session ends, because the app does not call Okta for each page. New logins, however, cannot succeed. Good teams plan for this. They keep a protected emergency way in for a few administrators, such as a local account with a very strong password and extra controls, and they test it. They also watch Okta’s status page and set a clear message to show users when sign-in is down.

Other failure scenarios

A quick reference for every term used in this guide, in plain words.

Short answers to the questions people ask most.

If you remember only a handful of ideas from this guide, make them these.