Before we talk about Okta, we need the core idea: one trusted place proves who you are, and many apps believe it.

The problem SAML solves

Imagine a company with 60 different work apps. Without any shared login system, every app keeps its own list of usernames and passwords. Each employee must remember 60 passwords, or reuse the same one everywhere, which is dangerous. When someone forgets a password, the help desk gets a ticket. When someone leaves the company, an administrator must remember to remove that person from all 60 apps, one by one. If even one app is forgotten, a former employee may still be able to log in.

This pain has a name: password fatigue. It costs time, creates security holes, and makes onboarding and offboarding slow. The cure is single sign-on, usually shortened to SSO. With SSO, a person proves who they are once to one trusted system, and every connected app accepts that proof.

What SAML is

SAML stands for Security Assertion Markup Language. It is an open standard, which means it is a published set of rules that any company can follow so that different products can work together. SAML defines how one system can send a signed message to another system saying, “This person has been checked, and here is who they are.”

The word “markup language” means the message is written in XML, a text format that uses tags, similar to the way a web page uses HTML tags. People rarely read these messages by hand, but knowing they are structured text helps later when we talk about signatures and debugging.

A short history

The standards group OASIS published SAML 1.0 in 2002 and a small update, 1.1, in 2003. SAML 2.0 was approved in 2005 and merged ideas from several earlier efforts. That version is the one used almost everywhere today, and it is the version Okta supports for app sign-in. Okta itself was founded in 2009, and SAML was already one of the main ways enterprise software connected to identity services.

Okta does not sell a product literally called “SAML (Basic)”. The phrase is a friendly label for the standard, core way of connecting an app with SAML 2.0.

Inside the Okta Admin Console, an administrator adds an app by choosing Applications, then Create App Integration, and then picking a sign-in method. One of the choices is SAML 2.0. Once chosen, a short guided wizard asks for a handful of settings. The core settings are the web address where the app receives logins, the app’s unique name, the format of the user identifier, and any extra facts to send. When someone says “basic SAML in Okta”, they usually mean this core setup with those core settings.

Okta also offers more advanced options on the same screens. Examples are encrypting the message, enabling single logout, changing the signing algorithm, and setting special authentication context rules. You can use all of those later. A beginner can build a fully working SSO connection without touching any of them.

Two ways to add a SAML app

There are two paths, and both end with the same kind of SAML connection.

SAML compared with other sign-in methods in Okta

SAML is not the only option. The right choice depends on what the app supports.

SAML comes with its own small dictionary. Learn these twelve words and the rest of the topic becomes much easier.

A SAML login touches the person, their browser, the app, and several parts inside Okta. Seeing them on one map makes the whole system feel small.

The most important detail in SAML is that the app and Okta usually never talk to each other directly during a login. The person’s browser carries the messages back and forth. That is why SAML works even when the app sits in one company’s data center and Okta sits in another. The two sides only need to trust each other’s signatures, not connect over a private line.

flowchart LR
    U["User"] --> B["Web Browser"]
    B --> SP["Service Provider App"]
    B --> OS["Okta Sign-in Page"]
    subgraph TEN ["Okta Tenant"]
        OS --> POL["Authentication Policy and MFA"]
        POL --> UD["Universal Directory"]
        OS --> AI["SAML App Integration"]
        AI --> CERT["Signing Certificate"]
        AI --> LOG["System Log"]
    end
    UD --> EXT["Active Directory or HR Source"]
    

The parts inside Okta

Okta tenant. Your company gets its own private Okta space, called an org or tenant, with its own web address. Everything below lives inside it. Think of the tenant as your company’s own office inside a large shared building.

Universal Directory. This is Okta’s central list of people and their details: name, email, department, manager, and group memberships. It can be filled directly, or it can copy people from other systems such as Microsoft Active Directory or an HR system like Workday. It works like a company phone book that every other part consults.

SAML app integration. This is the object an administrator creates for each app. It stores the ACS URL, the Audience URI, the Name ID rules, and the attribute rules. It is like a customer file kept for one particular app, describing exactly how to write letters to it.

Assignments. An app integration only works for people who are assigned to it. An admin can assign individual users or whole groups. Groups are far easier to manage, because adding someone to a group instantly gives them every app that group is assigned. This is the guest list at the door of the app.

Authentication policy. Rules that decide how strongly a person must prove themselves before Okta issues an assertion. For a payroll app the rule might demand a second factor, such as a phone prompt. For a low-risk app it might be lighter. In older Okta screens this is called a sign-on policy. Think of a security guard who asks for more ID at the vault than at the lobby.

Signing certificate. Each SAML app integration uses a key pair to sign assertions. The private half stays inside Okta. The public half is shared with the app as a certificate. This is the wax seal.

End-user dashboard. The web page where a person sees tiles for every assigned app. Clicking a tile starts a login. This is the lobby with a signboard of every door the person may use.

System Log. A searchable record of what happened: who signed in, to which app, when, and whether it worked. This is the building’s security camera record, and it is the first place to look when a login fails.

There are two ways a login can start. The person can begin at the app, or begin at Okta. Both end the same way.

Flow one: starting at the app (SP-initiated)

This is the most common flow. The person types the app’s address, or clicks a bookmark, without logging in to Okta first.

sequenceDiagram
    participant U as User Browser
    participant S as Service Provider App
    participant O as Okta Identity Provider
    U->>S: Open the app address
    S-->>U: Redirect with a SAML request
    U->>O: Deliver the SAML request
    O-->>U: Show the sign-in page
    U->>O: Enter password and extra factor
    O-->>U: Return a form holding the signed assertion
    U->>S: Post the assertion to the ACS URL
    S->>S: Check signature, audience, and time window
    S-->>U: Create a session and open the app
    

Flow two: starting at Okta (IdP-initiated)

In this flow the person first signs in to Okta and clicks an app tile on the dashboard. Okta skips the app’s request, because the person has already made their choice. It creates the assertion straight away and sends it to the app’s ACS URL.

flowchart LR
    A["Person signs in to Okta"] --> B["Dashboard shows app tiles"]
    B --> C["Person clicks an app tile"]
    C --> D["Okta builds a signed assertion"]
    D --> E["Browser posts it to the app ACS URL"]
    E --> F["App validates and opens a session"]
    

The assertion is the heart of SAML. Knowing its parts tells you exactly what to check when something goes wrong.

An assertion is an XML document, but you can think of it as a form with labeled boxes. Each box answers a question the app needs answered before it trusts the person.

The time window

Assertions are meant to be used almost immediately. Okta marks each one with a start time and an end time, and the window is short, only a few minutes. If a thief copied an assertion, it would soon be useless. This also means the clocks on the app’s server and on Okta must agree closely. If the app’s clock is wrong by too much, it may think a fresh assertion is already expired.

The signature

Okta signs the assertion by default, and the administrator can also choose to sign the outer response. Signing uses a pair of keys. The private key signs and stays secret inside Okta. The public key, shared through the certificate, lets anyone check the seal but not create one. If a single character in the assertion is changed after signing, the check fails. That is how the app knows that a person did not edit their own group name on the way.

Encryption is a separate choice

Signing proves who wrote the message and that it was not changed. It does not hide the content. The message travels over HTTPS, so outsiders cannot read it on the wire, but the browser itself can see it. For extra privacy, Okta can optionally encrypt the assertion with the app’s public key, so only the app can open it. Most basic setups skip this and rely on signing plus HTTPS.

Here is the full journey for a custom app, from an empty screen to a working login. Labels may differ slightly on your screens.

flowchart TD
    A["Get the app's ACS URL and Entity ID from the vendor"] --> B["Create App Integration and choose SAML 2.0"]
    B --> C["General Settings: name and logo"]
    C --> D["Configure SAML: URLs, Name ID, attributes"]
    D --> E["Finish the wizard"]
    E --> F["Assign people or groups"]
    F --> G["Copy Okta SSO URL, Issuer and certificate"]
    G --> H["Paste them into the app's SSO settings"]
    H --> I["Test SP-initiated and IdP-initiated login"]
    

The core fields in plain words

The connection works only if the app can match the incoming person to an account it already has. That is the job of the Name ID and the attributes.

Choosing the Name ID

The Name ID is the app’s primary key for finding the person. Okta lets you pick its format. The usual choices are:

• EmailAddress. The person’s email is sent. Easy to understand, and what many apps expect.
• Unspecified. The app and Okta agree privately on what the value means. This is the most common default in Okta.
• Persistent. An opaque, never-changing code for the person, meaning a code that reveals nothing about them.
• Transient. A random code that changes at each login, used when the app should not recognize returning people.

Next, the Application username setting tells Okta which of its own fields to place into the Name ID. Typical choices are the Okta username or the primary email. Whatever you choose, it must match exactly what the app already has on file, including capital letters.

Attribute statements

Attribute statements are optional extra facts. You give each fact a name that the app expects, and you choose which Okta profile field supplies the value. Okta uses a small expression language for this, where something like user.email means “this person’s email”. For example, an app may need the names firstName, lastName and department. You then map each name to the matching Okta field.

Many apps use these facts for Just-In-Time provisioning. That means the first time a person logs in, the app creates their account automatically from the information in the assertion. This saves setup time, but it only creates accounts. It does not remove them. For automatic removal when a person leaves, the app needs a separate provisioning feature, often built on a standard called SCIM, which is a different topic from SAML.

Group attribute statements

Apps often grant roles based on group membership. A group attribute statement tells Okta to include the person’s group names in the assertion. Because a person may belong to hundreds of groups, you add a filter so that only relevant ones are sent. The filter can match groups that start with a prefix, equal an exact name, contain some text, or match a pattern. A common habit is naming groups with a shared prefix such as “app-slack-“, then filtering on that prefix.

A SAML connection has a life: it is created, used, changed, and eventually retired. So does each person who uses it.

Two sessions, not one

Beginners are often surprised to learn that there are two separate sessions. The first is the Okta session, which proves the person is signed in to Okta. The second is the app session, which the app creates after reading an assertion. They have independent lengths. If an employee is deactivated in Okta, a session that the app already opened may still be alive until it expires. That is why short app session lengths, and automatic deprovisioning where possible, matter for offboarding.

Signing out

Signing out of one place does not automatically sign out of the other. SAML includes an optional feature called Single Logout, or SLO, which lets one logout ripple to the other side. Okta can enable it for an app, but it requires careful setup on both sides and many apps do not support it well. A good beginner rule is to rely on sensible session lengths and treat SLO as an extra.

The certificate lifecycle

The signing certificate has an expiry date, usually many years away, which makes it easy to forget. When it nears expiry, the administrator generates a new certificate in Okta, gives the new public certificate to the app, and then makes the new one active. If the order is wrong, or the app is not updated in time, every login for that app fails at once. Rotation should be a planned calendar event, not a surprise.

SAML is strong when both sides do their checks. Most real incidents come from a missed check, not from broken math.

What the app must check on every login

• The signature. It must be valid and made with the certificate the app trusts for this Okta app.
• The issuer. The assertion must come from the exact Okta app the administrator configured.
• The audience. The assertion must name this app, and no other. This stops a letter meant for one app from being used at another.
• The recipient and destination. The delivery address inside the assertion must match the address that actually received it.
• The time window. The current time must be inside the start and end times, allowing only a very small clock difference.
• The request match. For SP-initiated logins, the reply must refer back to the request that the app really sent.
• No reuse. The unique ID of each assertion should be accepted only once, so a captured copy cannot be replayed.

What Okta adds on its side

Multi-factor authentication, or MFA, means proving identity with more than one kind of proof, such as a password plus a prompt on a phone. In Okta, the authentication policy for each app decides when MFA is required. Because SAML apps never see the password, strong checks done once at Okta protect every connected app. This is a big security win: you harden one door instead of sixty.

Okta also lets administrators limit access by network location, device state, and risk signals, all before an assertion is created. If the policy says no, no assertion is ever made.

Well-known attacks, in simple terms

Signature wrapping. An attacker hides a forged section inside a validly signed document, hoping the app checks one part and trusts another. Defense: use mature SAML libraries from trusted vendors and keep them updated, rather than writing signature code by hand.

Replay. An attacker captures a real assertion and sends it again. Defense: short time windows, request matching, and one-time IDs.

Redirect abuse. The RelayState is a value that sends the person somewhere after login. If an app blindly follows it, an attacker could bounce a person to a fake site. Defense: the app should only allow redirects to its own known pages.

Phishing. A fake sign-in page steals the Okta password. Defense: phishing-resistant factors, such as hardware keys or Okta FastPass, and training people to start at the real dashboard.

Protect the admins

Anyone who can edit a SAML app in Okta can change where assertions are sent. That makes administrator accounts the most valuable targets. Give admin rights to as few people as possible, require strong MFA for them, and review the System Log for admin changes.

When a login fails, the person sees a vague error. The real reason is almost always visible in two places: the Okta System Log and the SAML message itself.

The Okta System Log

The System Log records each sign-in attempt, including the person, the app, the time, the result, and the reason for failure. Administrators can search it by person or by app. Sign-in events to a SAML app appear as single sign-on events, and failures include a short reason. This is the first stop for any “it does not work for me” report.

Looking at the real message

Because SAML messages pass through the browser, a free browser extension named SAML Tracer can display them. It shows the request, the response, and the decoded assertion with every box filled in. Compare what Okta sent with what the app expects, and the difference is usually obvious. Treat these captures as sensitive, because they hold personal data.

Common problems and their usual cause

What to watch over time

• Success and failure rate per app. A sudden spike in failures for one app often means a certificate or configuration change.
• Certificate expiry dates for every SAML app. Keep a list and set a reminder well ahead of time.
• MFA failures for a single person across many apps, which can signal a stolen password.
• Administrator changes to SAML app settings, which should be rare and reviewed.

No technology is perfect. Knowing the trade-offs helps you choose SAML for the right jobs.

Trade-offs to think about

Teams that run SAML well share a few habits. Teams that struggle share a few mistakes.

Patterns that work

Anti-patterns to avoid

Common beginner mistakes

• Testing only as an administrator, so access problems for normal people are never seen.
• Forgetting to assign any group, then wondering why the tile does not appear.
• Choosing a Name ID that does not match the usernames stored in the app.
• Letting the certificate expire with no reminder.
• Mixing up the app’s Entity ID with Okta’s Issuer, which are two different names for two different parties.
• Leaving old test apps active in the production Okta org.

Once the basic connection works, a few extra topics decide whether it stays smooth at scale. Each one below is optional, and each can be added later.

Performance and scale

Building an assertion is a small piece of work: Okta looks up the person, applies the policy, fills in a few boxes, and signs the result. The slow part of a login is almost always the human, who types a password or approves a phone prompt. Because the app session lasts for hours, a person usually triggers only a handful of assertions per day. Even a company with fifty thousand employees creates a modest, steady flow of requests, with a spike each morning when everyone arrives. The busiest moment is the start of the working day, so test new apps outside that rush and avoid forcing every app session to expire at exactly the same hour.

Availability and reliability

Okta runs as a cloud service built to stay available, but your own setup still matters. Keep a record of every SAML app, who owns it, and which certificate it uses. Keep emergency access in each critical app. Have a written plan for what the help desk says if sign-in is slow. A good plan also lists which apps are essential during an outage, such as the pager tool that on-call engineers need, so those get a backup login first.

Single Logout

Single Logout asks every connected app to end its session when the person signs out of one place. It sounds perfect, but it needs both sides to support the same logout messages and to agree on how sessions are named. When one app ignores the request, the person believes they are signed out while one session remains open. Many teams skip it and choose short app sessions instead.

Assertion encryption

If you turn on encryption, the app must give Okta its public certificate, and Okta locks the assertion with it. Only the app’s private key can open it. This protects the content from the browser and from any tool that records traffic, at the cost of one more certificate to track and one more thing that can expire.

Signature and digest algorithms

Signing involves a math recipe, and Okta lets you choose the recipe. The common modern choice is based on the SHA-256 family, and it is a strong default. Pick something older only if an ancient app refuses anything else, and plan to upgrade that app.

Authentication context and forced login

Some apps ask Okta for a certain strength of login, or demand that the person log in again even if a session exists. Okta can honor this, which is helpful for sensitive actions such as approving a large payment. Use it sparingly, because every forced login adds friction for the person.

Provisioning with SCIM

SCIM is a separate standard for creating, updating, and removing accounts in an app automatically. Pairing SAML with SCIM gives the full lifecycle: SAML handles the login, and SCIM keeps the account list in step with Okta. When a person leaves, SCIM can disable their account inside the app immediately, which closes the gap left by long app sessions.

Okta as a service provider

So far Okta has been the identity provider. It can also be the receiving side, trusting another identity provider such as a partner company’s system. The same ideas apply with the roles reversed: Okta now publishes an ACS URL and an Entity ID, and the partner signs assertions that Okta checks. Knowing the basic pattern makes both directions easy to follow.

SAML shows up wherever many people use many business apps. These typical scenarios show how basic SAML in Okta is used in practice.

Well-known business apps such as Salesforce, Slack, Zoom, Box, Atlassian Cloud, Workday and ServiceNow all support SAML 2.0 for single sign-on, and Okta’s catalog contains pre-built connections for a very large number of apps like these. That means a company can connect them using the same basic pattern again and again.

SAML in Okta is, at heart, a trusted way for an identity provider to tell an app who a person is, using a signed message that the browser carries. The basic setup needs only a few values, and mastering those few values gives you the foundation for every more advanced feature.