SAML

What is SAML(Security Assertion Markup Language)

This is an XML-based standard for exchanging authentication and authorization data between an Identity Provider (IdP) and a service.
SAML is not used to access Google directly. It is used only to authenticate the user before the proxy allows internet access. Instead of maintaining usernames and passwords for every customer, the proxy trusts the customer's existing Identity Provider (IdP), such as Okta or Azure AD.

Why is SAML used?

Suppose Bob works for acme-corp
When Bob first opens https://google.com, the proxy does not know:
Who the user is, ie who is Bob
Which groups the user(Bob) belongs to
Whether the user(Bob) is authorized to use the internet
Instead of asking Bob for credentials itself, the proxy redirects him to the corporate IdP.
The IdP is already trusted by Acme Corp and knows Bob's identity, password, MFA status, and group memberships.

SAML Flow

%%{init: {'themeVariables': {'fontSize': '11px'}, 'sequence': {'actorMargin': 30, 'messageMargin': 15, 'boxMargin': 5, 'useMaxWidth': true}}}%%
sequenceDiagram
    autonumber
    actor Bob as Bob
    participant Browser
    participant FP as Forward Proxy
    participant Auth as Authentication Service
    participant IdP as Okta / Azure AD

    Bob->>Browser: Open https://google.com
    Browser->>FP: HTTP Request
    FP->>FP: User unknown — no session cookie
    FP-->>Browser: 302 Redirect to Auth Service
    Browser->>Auth: GET /login
    Auth-->>Browser: Redirect to IdP
    Browser->>IdP: GET Login Page
    IdP-->>Browser: Login Form
    Bob->>Browser: Username, Password, MFA
    Browser->>IdP: POST Credentials
    IdP->>IdP: Verify credentials & MFA
    IdP->>IdP: Create SAML Response
    IdP-->>Browser: SAML Response
    Browser->>Auth: POST SAML Response
    Auth->>Auth: Verify Signature on SAML response
Verify Expiry & Audience
Verify not replayed
    Auth->>Auth: Extract User + Groups
    Auth->>FP: Create Session
    FP->>FP: Generate Session cookie
    FP-->>Browser: Set Session Cookie
    FP-->>Browser: Redirect to google.com
    Browser->>FP: Request with nspatoken
    FP-->>Browser: Allow Internet Access

Bob enters:


Username : bob@acme.com
Password : ********
MFA      : Approved

The IdP verifies the credentials.

If authentication succeeds, the IdP creates a SAML Response and sends it back to the Authentication Service.

What is a SAML Response?

A SAML Response is an XML document sent by the IdP after successful authentication.
It contains:
Authentication status
One SAML Assertion
Digital Signature
Timestamp
Audience (who should trust it)
Think of it as a secure envelope sent from the IdP to the Authentication Service.


SAML Response
│
├── Status = Success
├── Assertion
├── Signature
└── Issue Time

What is a SAML Assertion?

The Assertion is the most important part of the SAML Response.
It is the IdP saying: "I have authenticated this user, and here are the user's identity and attributes."
It contains the actual user information (called claims)
For Bob, the assertion may contain:


<Assertion>

  User = bob@acme.com
  Name = Bob Smith
  Tenant = acme-corp
  Groups =
      Engineering
      VPNUsers
      Developers
  Authenticated = true
  LoginTime = 10:30 AM
  Expiry = 11:30 AM

</Assertion>

The real assertion is XML, but conceptually it contains the above information.

What does the Authentication Service do?

It does not trust the assertion blindly. It performs several validations:
Verify the IdP's digital signature.
Verify that the assertion has not expired.
Verify the audience is this Authentication Service.
Verify the assertion has not been replayed.
Extract user attributes.

After successful validation:
User = bob@acme.com
Groups = Engineering, Developers
Tenant = acme-corp


User   = bob@acme.com
Groups = Engineering, Developers
Tenant = acme-corp