Introduction
If you've worked with enterprise APIs, you've probably heard statements like:
- "Our application uses SAML SSO."
- "The Identity Provider will send a SAML Assertion."
- "Configure SAML between Okta and the application."
For many API developers, SAML feels like a mysterious XML-based protocol that's difficult to understand.
But here's the reality:
SAML is simply a secure way for one system to tell another system that a user has already been authenticated.
Even though OAuth 2.0 and OpenID Connect dominate modern cloud applications, thousands of enterprise applications—including SAP, Salesforce, Workday, Oracle, ServiceNow, and many internal corporate portals—still rely heavily on SAML.
In this article, we'll explain SAML from the ground up using simple examples and also discuss where it fits in modern API architectures.
What is SAML?
SAML (Security Assertion Markup Language) is an XML-based open standard used for exchanging authentication and authorization information between two parties.
In simple words:
SAML allows users to log in once and access multiple applications without entering their password again.
This is known as Single Sign-On (SSO).
Imagine this scenario:
Employee
|
| Login once
v
Corporate Identity Server
|
| "Yes, John is authenticated"
v
Salesforce
ServiceNow
Workday
Jira
SAP
The applications never ask for the user's password.
They simply trust the authentication performed by the identity provider.
Why Was SAML Created?
Before SAML existed, every application maintained its own login system.
Salesforce
Username + Password
SAP
Username + Password
Oracle
Username + Password
Jira
Username + Password
Users had to remember several passwords.
IT teams had to:
- Manage multiple user accounts
- Reset passwords
- Synchronize identities
- Handle security risks
SAML solved this problem by introducing a centralized authentication model.
The Three Main Players in SAML
Understanding these three components makes SAML much easier.
1. User
The person trying to access an application.
Example:
John
2. Identity Provider (IdP)
The system responsible for authenticating users.
Examples include:
- Okta
- Microsoft Entra ID (formerly Azure AD)
- Ping Identity
- ADFS
- Keycloak
The IdP verifies:
- Username
- Password
- MFA
- Corporate policies
3. Service Provider (SP)
The application the user wants to access.
Examples:
- Salesforce
- Workday
- SAP
- ServiceNow
- Internal applications
The Service Provider trusts the Identity Provider.
How SAML Authentication Works
Let's walk through the complete login flow.
User
|
| Open Salesforce
v
Salesforce
|
| Redirect user
v
Okta (Identity Provider)
User enters credentials
Okta authenticates
Okta creates SAML Assertion
User browser sends Assertion
Salesforce validates Assertion
User logged in
Notice something important:
Salesforce never sees the user's password.
Only Okta does.
What is a SAML Assertion?
A SAML Assertion is an XML document that contains authentication information.
Think of it as a digitally signed identity card.
Example:
<saml:Assertion>
<User>john@company.com</User>
<Authenticated>true</Authenticated>
<Role>Admin</Role>
<Department>Engineering</Department>
<Email>john@company.com</Email>
</saml:Assertion>
The assertion tells the application:
"I, the Identity Provider, confirm that John has successfully logged in."
What's Inside a SAML Assertion?
A typical assertion contains:
| Information | Description |
|---|---|
| User ID | User identity |
| User email | |
| Authentication time | When login occurred |
| Expiration time | Assertion validity |
| Roles | User permissions |
| Groups | Security groups |
| Digital Signature | Prevents tampering |
The digital signature is critical because it ensures nobody modifies the assertion.
SAML Authentication Flow (Step-by-Step)
+---------+
| User |
+---------+
|
| Access Application
v
+----------------+
| Service Provider|
+----------------+
|
| Redirect
v
+----------------+
| Identity Provider |
+----------------+
|
| Authenticate User
|
| Generate Assertion
v
+----------------+
| Browser |
+----------------+
|
| POST Assertion
v
+----------------+
| Service Provider|
+----------------+
|
| Validate Signature
|
| Grant Access
v
Application Opens
Why Does SAML Use XML?
SAML was created in the early 2000s.
At that time:
- XML was the standard for enterprise integration.
- SOAP web services were widely used.
- JSON wasn't yet popular.
That's why SAML messages are XML documents.
Today, newer standards like OpenID Connect use JSON and JWT instead.
SAML vs OAuth vs OpenID Connect
This is one of the most common areas of confusion.
| Feature | SAML | OAuth 2.0 | OpenID Connect |
|---|---|---|---|
| Purpose | Authentication | Authorization | Authentication |
| Format | XML | JSON | JWT |
| Used By | Enterprise apps | APIs | Modern web/mobile apps |
| Browser-based | Yes | Not necessarily | Yes |
| Mobile Friendly | Limited | Yes | Excellent |
| SSO | Yes | No | Yes |
A simple way to remember the difference:
- SAML answers: Who are you?
- OAuth answers: What can you access?
- OpenID Connect answers: Who are you? (using OAuth 2.0)
Where Does Apigee Fit?
Apigee itself doesn't authenticate users with SAML.
Instead, Apigee commonly integrates with enterprise identity systems.
A typical enterprise architecture looks like this:
User
↓
Browser
↓
Okta (SAML)
↓
Application
↓
OAuth Token
↓
Apigee
↓
Backend APIs
Typical flow:
- User authenticates using SAML.
- Application receives the SAML assertion.
- Application exchanges it for an OAuth access token.
- APIs behind Apigee validate the OAuth token.
- Backend services are accessed securely.
This bridges legacy enterprise authentication with modern API security.
Advantages of SAML
SAML offers several benefits for enterprise environments:
- Centralized authentication
- Single Sign-On (SSO)
- Reduced password fatigue
- Strong security with digital signatures
- Easier user provisioning
- Seamless integration with enterprise identity providers
- Mature and widely supported across enterprise software
Limitations of SAML
Despite its strengths, SAML has some drawbacks:
- XML messages are verbose.
- Configuration can be complex.
- Debugging XML assertions is challenging.
- Less suitable for mobile and SPA applications.
- Not designed specifically for APIs.
- Increasingly replaced by OpenID Connect for modern applications.
Real-World Example
Imagine you work at a multinational company.
You open:
- Salesforce
- Workday
- Jira
- SAP
Instead of logging into each application separately, you authenticate once through Okta.
Okta sends a signed SAML assertion to each application.
Each application trusts Okta and grants access immediately.
That's SAML-powered Single Sign-On in action.
Common Interview Questions
Is SAML used for authentication or authorization?
Primarily authentication, though it can also carry authorization-related attributes such as roles and groups.
Does SAML use JWT?
No.
SAML uses XML assertions.
Can APIs directly use SAML?
It's uncommon. APIs typically use OAuth 2.0 or JWT access tokens. If SAML is involved, it's often exchanged for an OAuth token before API calls.
Is SAML obsolete?
No.
Although many new applications adopt OpenID Connect, SAML remains deeply embedded in enterprise ecosystems and is expected to stay relevant for years.
Key Takeaways
- SAML stands for Security Assertion Markup Language.
- It enables Single Sign-On (SSO) across multiple applications.
- SAML uses XML assertions to share authentication information.
- The three main actors are the User, Identity Provider (IdP), and Service Provider (SP).
- SAML is widely used in enterprise software, while OAuth 2.0 and OpenID Connect are more common for APIs and modern web/mobile apps.
- In API platforms like Apigee, SAML often authenticates users at the application layer, with OAuth tokens securing API access downstream.
Final Thoughts
SAML may not be the newest identity standard, but it remains a cornerstone of enterprise authentication. If you're working with APIs, gateways like Apigee, or enterprise integrations, understanding SAML helps you connect legacy identity systems with modern API security.
Top comments (0)