DEV Community

Cover image for Understanding SAML 2.0: A Practical Guide to Enterprise SSO with Java Examples
Sanjay Ghosh
Sanjay Ghosh

Posted on

Understanding SAML 2.0: A Practical Guide to Enterprise SSO with Java Examples

#saml #security #java #oauth2

Learn how SAML 2.0 enables Enterprise Single Sign-On, how IdPs and SPs communicate, what a SAML Assertion contains, how digital signatures protect it, and how to explore these concepts using Java examples.

🚀 Introduction

Have you ever logged into one enterprise application and then opened another application without being asked for your username and password again?

You were probably experiencing Single Sign-On (SSO).

In many enterprise environments, SSO is implemented using Security Assertion Markup Language (SAML).

SAML can initially look complicated because it involves XML, Identity Providers, Service Providers, assertions, certificates, signatures, browser redirects, and several different messages.

But the basic idea is actually quite straightforward:

An Identity Provider authenticates the user and provides a trusted assertion about that user to an application.

The application, known as the Service Provider, validates that assertion and decides whether to create a session for the user.

In this article, we'll walk through that process step by step.

We'll look at:

  • What SAML 2.0 is
  • Why enterprises use SAML
  • Identity Provider (IdP) and Service Provider (SP)
  • The SAML SSO authentication flow
  • What a SAML Assertion contains
  • Authentication and Attribute Statements
  • Digital signatures
  • Base64 encoding
  • How the browser participates in the process
  • Authentication vs. authorization
  • SAML vs. OAuth 2.0 and JWT
  • Security considerations
  • Java examples that demonstrate the core concepts
  • A complete Java simulation of the SAML flow

The Java examples used in this article are available in my GitHub repository:

SAML Java Examples

https://github.com/knowledgebase21st/Software-Engineering/tree/dev/security/saml

I also maintain a more comprehensive SAML reference in my Software Engineering Knowledge Base, which covers the concepts, flow diagrams, assertion structure, security considerations, and Java examples:

https://clockwiseknowledge.com/se/saml.html

Before diving into the individual SAML components, let's first look at the complete picture. The following overview shows how SAML enables Enterprise Single Sign-On and how the Identity Provider, Service Provider, and SAML Assertion fit together.

🔎 SAML at a Glance

SAML at a Glance

🔐 What Is SAML?

SAML, or Security Assertion Markup Language, is an XML-based standard for exchanging security information between an Identity Provider (IdP) and a Service Provider (SP).

The OASIS SAML 2.0 standard defines XML-encoded assertions about authentication, attributes, and authorization, together with protocols used to exchange that information.

A simplified view looks like this:

                    SAML

       +---------------------------+
       |    Identity Provider      |
       |           IdP             |
       +-------------+-------------+
                     |
                     | SAML Assertion
                     |
                     v
       +---------------------------+
       |    Service Provider       |
       |           SP              |
       +---------------------------+
Enter fullscreen mode Exit fullscreen mode

The important distinction is:

The IdP authenticates the user.

The SP consumes and validates the information provided by the IdP.

For example:

User
 |
 | Login
 v
Identity Provider
 |
 | Authentication
 | MFA
 |
 | Signed SAML Assertion
 v
Service Provider
 |
 | Validate Assertion
 v
Application Access
Enter fullscreen mode Exit fullscreen mode

This separation of responsibilities is one of the fundamental ideas behind SAML-based enterprise SSO.

🏢 Why Is SAML Popular in Enterprise SSO?

Imagine a company has 50 different applications.

Without SSO, users may have to maintain separate credentials for:

CRM
HR System
Payroll
Cloud Console
Development Tools
Project Management
Email
Internal Applications
Enter fullscreen mode Exit fullscreen mode

With SAML SSO, authentication can be centralized.

                 +----------------+
                 |      User      |
                 +-------+--------+
                         |
                         v
                 +---------------+
                 |      IdP      |
                 | Authentication|
                 +-------+-------+
                         |
              +----------+----------+
              |          |          |
              v          v          v
             App A      App B      App C
              SP         SP         SP
Enter fullscreen mode Exit fullscreen mode

The Identity Provider becomes the central authority for authentication.

It can also integrate with mechanisms such as:

  • Password authentication
  • Multi-factor authentication
  • Smart cards
  • Biometrics
  • Enterprise directories
  • Conditional access policies

The Service Providers don't need to independently authenticate the user.

👥 The Three Important Participants

Before looking at the SAML protocol, let's understand the three main participants.

1. User

The person trying to access an application.

For example:

john.doe@company.com
Enter fullscreen mode Exit fullscreen mode

2. Identity Provider — IdP

The Identity Provider is responsible for authenticating the user.

Examples include enterprise identity platforms such as:

  • Microsoft Entra ID
  • Okta
  • Ping Identity
  • ADFS
  • Google Workspace

The IdP authenticates the user and generates a SAML Response containing a SAML Assertion.

3. Service Provider — SP

The Service Provider is the application the user wants to access.

Examples might include:

  • Salesforce
  • Workday
  • GitHub Enterprise
  • Internal enterprise applications
  • Cloud applications

The SP trusts the configured Identity Provider and validates the SAML Response.

🔄 The SAML SSO Flow

Now let's look at what actually happens.

Suppose a user wants to access:

https://application.example.com
Enter fullscreen mode Exit fullscreen mode

The user hasn't authenticated yet.

The simplified flow is:

User
 |
 | 1. Access application
 v
Service Provider
 |
 | 2. Authentication Request
 v
Identity Provider
 |
 | 3. Authenticate User
 |
 | 4. Create Signed Assertion
 v
Browser
 |
 | 5. SAML Response
 v
Service Provider
 |
 | 6. Validate Assertion
 v
Application Access
Enter fullscreen mode Exit fullscreen mode

Let's walk through each step.

Step 1 — User Accesses the Application

The user opens the protected application.

https://application.example.com
Enter fullscreen mode Exit fullscreen mode

The application is the Service Provider.

The SP determines that the user doesn't have a valid application session.

Instead of asking the user for another password, it initiates the SAML authentication flow.

Step 2 — The SP Sends an Authentication Request

The Service Provider sends a SAML Authentication Request, commonly called an AuthnRequest, to the Identity Provider.

Conceptually:

Browser
   |
   v
Service Provider
   |
   | AuthnRequest
   v
Identity Provider
Enter fullscreen mode Exit fullscreen mode

The request tells the IdP that the application wants the user authenticated.

Step 3 — The IdP Authenticates the User

The Identity Provider now authenticates the user.

This could involve:

Username + Password
        +
MFA
Enter fullscreen mode Exit fullscreen mode

or another authentication mechanism.

The important point is that the Service Provider doesn't need to handle the user's enterprise credentials directly.

The IdP is responsible for authentication.

Step 4 — The IdP Creates a SAML Assertion

After successful authentication, the IdP creates a SAML Assertion.

A SAML Assertion is an XML document containing statements about the authenticated user.

For example:

<saml:Assertion>

    <saml:Issuer>
        https://identity-provider.example.com
    </saml:Issuer>

    <saml:Subject>
        <saml:NameID>
            john.doe@company.com
        </saml:NameID>
    </saml:Subject>

    <saml:AuthnStatement>
        Authentication Method = MFA
    </saml:AuthnStatement>

    <saml:AttributeStatement>

        Email = john.doe@company.com

        Department = Engineering

        Role = Administrator

    </saml:AttributeStatement>

</saml:Assertion>
Enter fullscreen mode Exit fullscreen mode

This is a simplified educational example. A production SAML Assertion contains additional elements and security information.

🧩 What Is Inside a SAML Assertion?

A SAML Assertion can contain different types of statements.

Authentication Statement

The Authentication Statement describes the authentication event.

It can contain information such as:

  • Authentication time
  • Authentication method
  • Session information

For example:

Authentication Method = MFA
Authentication Time = 2026-08-15T10:30:00Z
Enter fullscreen mode Exit fullscreen mode

Attribute Statement

An Attribute Statement contains information about the user.

For example:

Email       = john.doe@company.com
Department  = Engineering
Role        = Administrator
Group       = Developers
Enter fullscreen mode Exit fullscreen mode

The Service Provider can use these attributes when determining what application functionality the user should receive.

Authorization Decision Statement

SAML also defines authorization decision statements.

Conceptually:

User
 |
 | Permission
 v
Protected Resource
Enter fullscreen mode Exit fullscreen mode

However, it's important not to confuse authentication and authorization.

We'll come back to this distinction shortly.

🔍 Understanding the Important XML Elements

Let's examine the major elements in our simplified Assertion.

<Issuer>

Identifies the entity that issued the assertion.

<saml:Issuer>
    https://identity-provider.example.com
</saml:Issuer>
Enter fullscreen mode Exit fullscreen mode

The Service Provider needs to know who issued the assertion.

<Subject>

Identifies the subject of the assertion—the user.

<saml:Subject>
    <saml:NameID>
        john.doe@company.com
    </saml:NameID>
</saml:Subject>
Enter fullscreen mode Exit fullscreen mode

<NameID>

Provides an identifier for the user.

It might be:

john.doe@company.com
Enter fullscreen mode Exit fullscreen mode

or an employee ID or another configured identifier.

<Conditions>

Conditions constrain when and where the assertion can be accepted.

For example:

<saml:Conditions>

    <saml:AudienceRestriction>

        <saml:Audience>
            https://application.example.com
        </saml:Audience>

    </saml:AudienceRestriction>

</saml:Conditions>
Enter fullscreen mode Exit fullscreen mode

The idea is important:

The assertion should not simply be accepted by any application.

The Service Provider validates the assertion against the expected conditions.

<AuthnStatement>

Provides information about how and when the user was authenticated.

<saml:AuthnStatement>
    Authentication Method = MFA
</saml:AuthnStatement>
Enter fullscreen mode Exit fullscreen mode

<AttributeStatement>

Provides user attributes.

<saml:AttributeStatement>

    Email = john.doe@company.com

    Department = Engineering

    Role = Administrator

</saml:AttributeStatement>
Enter fullscreen mode Exit fullscreen mode

✍️ Why Is the SAML Assertion Digitally Signed?

This is one of the most important security concepts in SAML.

The Identity Provider signs the SAML Assertion using its private key.

The Service Provider uses the corresponding public key to verify the signature.

Conceptually:

             Identity Provider

              Private Key
                   |
                   v
          +-------------------+
          | Sign Assertion    |
          +---------+---------+
                    |
                    | Signed Assertion
                    v
             Service Provider
                    |
                    v
              Public Key
                    |
                    v
          +-------------------+
          | Verify Signature  |
          +-------------------+
                    |
             Valid Signature?
              /           \
            Yes            No
             |              |
             v              v
        Trust Identity    Reject
Enter fullscreen mode Exit fullscreen mode

If an attacker modifies the Assertion after it has been signed, signature verification should fail.

For example, suppose the original assertion contains:

Role = User
Enter fullscreen mode Exit fullscreen mode

An attacker changes it to:

Role = Administrator
Enter fullscreen mode Exit fullscreen mode

The cryptographic signature no longer matches the modified document.

The Service Provider should reject the assertion.

🔐 Digital Signature ≠ Encryption

A digital signature provides integrity and authenticity.

It does not automatically mean that the assertion is encrypted.

This distinction is important.

Digital Signature
        |
        +--> Detect modification
        +--> Verify origin/authenticity

Encryption
        |
        +--> Protect confidentiality
        +--> Prevent unauthorized reading
Enter fullscreen mode Exit fullscreen mode

SAML can support encryption, but signing and encryption solve different security problems.

🌐 What Does the Browser Do?

One of the interesting aspects of browser-based SAML SSO is that the browser participates in transporting the SAML Response.

A simplified flow is:

IdP
 |
 | SAML Response
 v
Browser
 |
 | POST
 v
SP / ACS Endpoint
Enter fullscreen mode Exit fullscreen mode

The browser is essentially transporting the response between the IdP and the SP.

It is not the trusted authority that authenticates the user.

The Service Provider validates the received SAML information.

📦 What Is a SAML Response?

The SAML Response is the protocol message returned to the Service Provider.

Conceptually:

<samlp:Response>

    <saml:Issuer>
        https://identity-provider.example.com
    </saml:Issuer>

    <saml:Assertion>

        ...

    </saml:Assertion>

</samlp:Response>
Enter fullscreen mode Exit fullscreen mode

The Response can contain the SAML Assertion.

The exact structure depends on the SAML profile and configuration.

Where Does Base64 Encoding Come In?

SAML messages transported through browser-based bindings may be Base64 encoded.

This is an important distinction:

Base64 is encoding, not encryption.

For example:

SAML XML
   |
   | Base64 Encode
   v
Encoded Data
   |
   | Transport
   v
Service Provider
   |
   | Base64 Decode
   v
SAML XML
Enter fullscreen mode Exit fullscreen mode

Anyone who has the Base64 data can decode it.

Therefore, Base64 should never be considered a security mechanism.

The security of SAML comes from mechanisms such as:

  • Digital signatures
  • HTTPS
  • Assertion validation
  • Trusted certificates
  • Audience validation
  • Time/condition validation

☕ Exploring SAML with Java

Now let's move from concepts to code.

I've created several small Java programs that demonstrate the fundamental pieces of SAML.

The source code is available here:

GitHub — SAML Java Examples

https://github.com/knowledgebase21st/Software-Engineering/tree/dev/security/saml

The examples include:

CreateSAMLAssertion.java
ParseSAMLAssertion.java
SAMLBase64Encoding.java
XMLDigitalSignatureExample.java
SAMLFlowSimulation.java
Enter fullscreen mode Exit fullscreen mode

The goal isn't to build a production SAML implementation from scratch.

Instead, the examples are intentionally small so that individual concepts can be understood independently.

Example 1 — Creating a SAML Assertion

The first example is:

CreateSAMLAssertion.java
Enter fullscreen mode Exit fullscreen mode

It demonstrates how a simplified SAML Assertion can be represented as an XML document.

The example focuses on elements such as:

Issuer
Subject
Authentication Statement
Attribute Statement
Enter fullscreen mode Exit fullscreen mode

Conceptually:

Java Program
     |
     v
Create XML
     |
     v
SAML Assertion
Enter fullscreen mode Exit fullscreen mode

This is useful for understanding the structure of the assertion before dealing with a complete enterprise SAML implementation.

Source:

https://github.com/knowledgebase21st/Software-Engineering/blob/dev/security/saml/CreateSAMLAssertion.java

Example 2 — Parsing a SAML Assertion

The next example is:

ParseSAMLAssertion.java
Enter fullscreen mode Exit fullscreen mode

This example demonstrates how Java's DOM parser can read an XML-based SAML Assertion and extract information such as:

  • User
  • Issuer
  • Authentication method
  • Attributes

Conceptually:

SAML XML
   |
   v
DOM Parser
   |
   +----> Issuer
   |
   +----> NameID
   |
   +----> Authentication
   |
   +----> Attributes
Enter fullscreen mode Exit fullscreen mode

This is useful because a Service Provider needs to inspect and validate information contained in the received SAML message.

Source:

https://github.com/knowledgebase21st/Software-Engineering/blob/dev/security/saml/ParseSAMLAssertion.java

Example 3 — Base64 Encoding and Decoding

The third example is:

SAMLBase64Encoding.java
Enter fullscreen mode Exit fullscreen mode

It demonstrates the encoding and decoding process.

Conceptually:

SAML XML
   |
   v
Base64 Encode
   |
   v
Encoded SAML
   |
   v
Base64 Decode
   |
   v
SAML XML
Enter fullscreen mode Exit fullscreen mode

Again, remember:

Base64 != Encryption
Enter fullscreen mode Exit fullscreen mode

Base64 changes the representation of the data; it does not make the data confidential.

Source:

https://github.com/knowledgebase21st/Software-Engineering/blob/dev/security/saml/SAMLBase64Encoding.java

Example 4 — XML Digital Signature

The fourth example is:

XMLDigitalSignatureExample.java
Enter fullscreen mode Exit fullscreen mode

This example demonstrates the cryptographic concept behind SAML digital signatures.

It demonstrates:

  • RSA key generation
  • Digital signing
  • Signature verification

The conceptual flow is:

                RSA Key Pair

          +---------------------+
          |                     |
          | Private Key         | Public Key
          |                     |
          +----------+----------+
                     |
                     v

               Sign XML
                  |
                  v
             Signed XML
                  |
                  v
             Verify XML
                  |
             +----+----+
             |         |
           Valid     Invalid
             |         |
             v         v
          Trust      Reject
Enter fullscreen mode Exit fullscreen mode

This example is particularly useful for understanding why the Service Provider can trust a SAML Assertion after successful signature verification.

Source:

https://github.com/knowledgebase21st/Software-Engineering/blob/dev/security/saml/XMLDigitalSignatureExample.java

Example 5 — Simulating the Complete SAML Flow

The final example is:

SAMLFlowSimulation.java
Enter fullscreen mode Exit fullscreen mode

This example brings the individual concepts together and simulates the overall SAML SSO process.

The flow is represented as:

1. User requests application
          |
          v
2. Service Provider
          |
          v
3. Authentication Request
          |
          v
4. Identity Provider
          |
          v
5. User Authentication
          |
          v
6. Create SAML Assertion
          |
          v
7. Sign Assertion
          |
          v
8. SAML Response
          |
          v
9. Service Provider
          |
          v
10. Validate Assertion
          |
          v
11. Create Session
          |
          v
12. Access Granted
Enter fullscreen mode Exit fullscreen mode

The source code is available here:

https://github.com/knowledgebase21st/Software-Engineering/blob/dev/security/saml/SAMLFlowSimulation.java

This example is particularly useful because it connects the individual concepts into one complete story.

🔎 Authentication vs. Authorization

SAML discussions often lead to confusion between these two concepts.

They are related, but they are not the same.

Authentication

Authentication answers:

Who are you?

Examples:

Username + Password
MFA
Certificate
Biometrics
Smart Card
Enter fullscreen mode Exit fullscreen mode

The Identity Provider typically performs the authentication.

Authorization

Authorization answers:

What are you allowed to do?

For example:

User = john.doe

Role = Administrator

Permissions:
    Read
    Write
    Delete
Enter fullscreen mode Exit fullscreen mode

The Service Provider typically applies application-specific authorization policies.

A useful way to remember the distinction is:

Authentication
      |
      v
"Who are you?"
      |
      v
Authorization
      |
      v
"What can you access?"
Enter fullscreen mode Exit fullscreen mode

🆚 SAML vs OAuth 2.0 vs JWT

These technologies are frequently mentioned together, but they solve different problems.

SAML OAuth 2.0 JWT
Primary role Enterprise SSO / federation Authorization Token format
Typical format XML Protocol / bearer tokens JSON
Enterprise SSO Very common Not its primary purpose Not a protocol
Web applications Common Common Common
APIs Less common Very common Very common
Digital signatures Common Depends on token/mechanism Commonly used

One important correction to a common misconception:

JWT is a token format, not an authentication protocol by itself.

OAuth 2.0 is primarily an authorization framework.

SAML is commonly used for enterprise identity federation and browser-based SSO.

🛡️ SAML Security Considerations

SAML involves identity information, so validation is critical.

A Service Provider should not simply decode a SAML Response and trust whatever it contains.

Important checks include:

1. Verify the Digital Signature

The SP should verify the signature against a trusted IdP certificate.

2. Validate the Issuer

The SP should verify that the assertion came from the expected Identity Provider.

3. Validate the Audience

The SP should ensure that the assertion is intended for that Service Provider.

4. Validate Time Conditions

Expired assertions should be rejected.

5. Use HTTPS

SAML messages should be transported over secure channels.

6. Protect the IdP Private Key

The private signing key is extremely sensitive.

If an attacker obtains it, the trust relationship can be severely compromised.

7. Rotate Certificates

Certificates should be managed and rotated according to organizational security policies.

8. Consider Replay Protection

A previously valid SAML message should not be accepted repeatedly outside its intended validity window.

SAML implementations and toolkits provide mechanisms for handling message identifiers and replay protection.

🧠 The Most Important Thing to Understand

If you remember only one thing from this article, remember this:

The IdP authenticates the user.

The IdP creates a signed assertion.

The browser transports the response.

The SP validates the assertion.

The SP creates the application session.
Enter fullscreen mode Exit fullscreen mode

Or even more simply:

             AUTHENTICATION
                    |
                    v
                   IdP
                    |
             Signed Assertion
                    |
                    v
                   SP
                    |
              AUTHORIZATION
                    |
                    v
              Application
Enter fullscreen mode Exit fullscreen mode

That mental model makes the rest of SAML much easier to understand.

🔗 Explore the Java Examples

All five Java examples are available in my GitHub repository:

SAML Java Examples

https://github.com/knowledgebase21st/Software-Engineering/tree/dev/security/saml

They are intentionally small and focused on individual concepts:

CreateSAMLAssertion.java
        |
        +--> Create simplified Assertion

ParseSAMLAssertion.java
        |
        +--> Parse XML Assertion

SAMLBase64Encoding.java
        |
        +--> Encode / Decode

XMLDigitalSignatureExample.java
        |
        +--> Sign / Verify

SAMLFlowSimulation.java
        |
        +--> Complete SSO Flow
Enter fullscreen mode Exit fullscreen mode

📚 Go Deeper: SAML Reference

This article takes a practical, engineering-focused approach to understanding
SAML 2.0 and Enterprise Single Sign-On.

If you'd like a more structured reference covering the concepts in greater
depth, I've also created a dedicated SAML Authentication page in my
Software Engineering Knowledge Base.

The reference page covers:

  • SAML Authentication and Single Sign-On (SSO)
  • Identity Provider (IdP) and Service Provider (SP)
  • Detailed SAML authentication flow
  • SAML Assertions and their XML structure
  • Authentication, Attribute, and Authorization statements
  • Digital signatures and signature verification
  • Authentication vs. Authorization
  • SAML vs. OAuth 2.0 vs. JWT
  • SAML security best practices
  • Java examples for parsing, encoding, signing, and simulating SAML flows

🔗 SAML Authentication — Software Engineering Knowledge Base

https://clockwiseknowledge.com/se/saml.html

The Java examples discussed in this article are also available in the
accompanying GitHub repository:

💻 SAML Java Examples

https://github.com/knowledgebase21st/Software-Engineering/tree/dev/security/saml

📖 References and Further Reading

🎯 Conclusion

SAML can initially seem complicated because there are many pieces involved: Identity Providers, Service Providers, Authentication Requests, Responses, Assertions, XML, certificates, digital signatures, browser redirects, and validation rules.

But once the flow is understood, the architecture becomes much clearer.

The central idea is simple:

Authenticate once with a trusted Identity Provider and securely communicate that authentication result to the application.

The Identity Provider authenticates the user and creates a SAML Assertion.

The assertion contains information about the authenticated identity and can include attributes needed by the application.

The Identity Provider signs the assertion.

The browser transports the SAML Response.

The Service Provider validates the response and assertion before creating an application session.

This separation allows enterprises to centralize authentication while allowing many applications to participate in a common SSO infrastructure.

And that is the real value of SAML:

one trusted identity system, many applications, and a standardized way to communicate authentication information between them.

If you're working with enterprise Java applications, identity platforms, application security, or distributed systems, understanding this flow is well worth the effort.

Happy learning! 🚀

Top comments (0)