SAML SSO in Next.js: A Step-by-Step Guide for Okta, Google & Microsoft Entra

You’re in the right place! This step-by-step guide will walk you through setting up SAML SSO (Single Sign-On) in Next.js with major Identity Providers (IDPs) like Okta, Google Workspace, and Microsoft Entra.

What is SAML SSO?

SAML (Security Assertion Markup Language) is an XML-based authentication standard used for exchanging authentication and authorization data between an Identity Provider (IDP) and a Service Provider (SP).

SAML Authentication Flows

There are two main types of SAML authentication flows:

1. IDP-Initiated Flow:

• The user logs into the IDP dashboard and clicks on your application.
• The IDP sends a SAML assertion (signed XML) to the browser.
• The browser sends the XML to your app's callback URL for verification.

2. SP-Initiated Flow:

• The user visits the application login page and enters their email.
• The application detects the email and redirects the user to the IDP portal.
• The IDP authenticates the user and sends back a signed SAML assertion.

Setting Up SAML Metadata Exchange

To start off we need to know how to setup a SAML app with your app as a Service Provider and any known Identity Provider, the link here shows a sample configuration of hugging face with okta.
Refer : How to configure SAML SSO with Okta

SAML Configuration Steps:

Following is the configuration steps necessary between SP and IDP

1. Obtain the X.509 certificate from the IDP and store it on the SP.
2. Copy the Login URL from the IDP to the SP.
3. Copy the IDP Entity ID from the IDP to the SP.
4. Copy the SP Entity ID from the SP to the IDP.
5. Set up the callback URL on the SP and configure it in the IDP.

Verifying SAML Assertions (XML Signature Verification)

Now that we know the SAML flow , we must understand the XML verification.
The signed XML looks like this

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                ID="s20a470b3a4be603e0ddb4b6db20a66765ab18da3d"
                InResponseTo="s280b6ec55cc58adafa481657243b780fdad02af0e"
                Version="2.0"
                IssueInstant="2018-07-10T17:14:53Z"
                Destination="http://sp.example.com:9080/sp/AuthConsumer/metaAlias/idpproxy/sp"
                >
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">http://openam.example.com:8080/idpam</saml:Issuer>
    <samlp:Status xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
        <samlp:StatusCode xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                          Value="urn:oasis:names:tc:SAML:2.0:status:Success"
                          />
    </samlp:Status>
    <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                    ID="s2044666918b0c3db0bfa6bc84f54bbc997472272c"
                    IssueInstant="2018-07-10T17:14:53Z"
                    Version="2.0"
                    >
        <saml:Issuer>http://openam.example.com:8080/idpam</saml:Issuer>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
                <ds:Reference URI="#s2044666918b0c3db0bfa6bc84f54bbc997472272c">
                    <ds:Transforms>
                        <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                    <ds:DigestValue>R4YFpd+ZTx6ca50yVs7bH4Ehse8=</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue> 
Fare7CvWrv9HXC0C2RWkowkNVdQ4ubmRcrULYw6MSwwWp/f76Rvm+v1TZNScAOTIAEpkP01
4C1s0ZNpyM2XG88KWmaxd69tySDYWUocqfNlDFFmohWsasRfFv9HV7WLLPXy8w0ndnDEjX4FDGfm
wQLv64EintY/P/hcLH7fiTLKgsNDHMctlUKq0g==
</ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>
MIIDaD1lUENogXUM6JMqzSyEIm1XCOCL8rZJkZ781W5CwZhuJTNzV3
1sBREs8FaaCeksu7Y48BmkUqw6E9
</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
                         NameQualifier="http://openam.example.com:8080/idpam"
                         SPNameQualifier="http://sp.example.com:9080/sp"
                         >idpuser1</saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData InResponseTo="s280b6ec55cc58adafa481657243b780fdad02af0e"
                                              NotOnOrAfter="2018-07-10T17:24:53Z"
                                              Recipient="http://sp.example.com:9080/sp/AuthConsumer/metaAlias/idpproxy/sp"
                                              />
            </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions NotBefore="2018-07-10T17:04:53Z"
                         NotOnOrAfter="2018-07-10T17:24:53Z"
                         >
            <saml:AudienceRestriction>
                <saml:Audience>http://sp.example.com:9080/sp</saml:Audience>
            </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement AuthnInstant="2018-07-10T17:14:53Z"
                             SessionIndex="s2e2a25b53c0481abeac81738eb2fd49c164856201"
                             >
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
            </saml:AuthnContext>
        </saml:AuthnStatement>
        <saml:AttributeStatement>
            <saml:Attribute Name="uid">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     xsi:type="xs:string"
                                     >idpuser1</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="sn">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     xsi:type="xs:string"
                                     >user</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="cn">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     xsi:type="xs:string"
                                     >IDP user modified</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="mail">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     xsi:type="xs:string"
                                     >idpuser@example.com</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="givenname">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     xsi:type="xs:string"
                                     >ipd</saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>

Verification Steps:

• To verify this xml’s authenticity the application must use x.509 certificate that is issued during the apps SAML handshake , this is considered to be the public key
• The IDP has its own private key with which it arranges this XML document and signs it and pastes the hash in digest value.
• The SP arranges this xml document, uses its public key and checks the signature value and canonicalisation methods as found in the XML document and generates a hash.

<!-- The generated Hash -->
<ds:DigestValue>R4YFpd+ZTx6ca50yVs7bH4Ehse8=</ds:DigestValue>

<!-- Canonicalisation and Signature Algorithm -->
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />

• The hash generated with both keys must be the same to verify the authenticity of the signed xml

To know more about signed XML verification i found this Stack overflow QnA which showing Digitally signed XMLs
Refer: How to verify Digitally Signed XML File?

• Additional steps include verifying the IDP entity id in the xml shared during handshake.
  The validity time , NotOnBefore and NotOnAfter fields in XML to verify how long is the assertion valid for and thats it the user is authenticated

<!--XML Validity Period-->
<saml:Conditions NotBefore="2018-07-10T17:04:53Z" NotOnOrAfter="2018-07-10T17:24:53Z">
<!--IDP verification-->
<saml:Issuer>http://openam.example.com:8080/idpam</saml:Issuer>

You can Read more but i guess this is all the basics we need now for the implementation

The Front End

For the first part we are going to need a basic front end for our app (SP),that can accept the x509 certificate, IDP entity ID and the the login URL

Our Save button should save this info in our app database

Additionally we should expose our callback URL and a unique entity id of our own to be given to the IDP

Okta & JumpCloud SAML SSO Implementation :

Before Proceeding you need to create a SAML app for your application on okta and jumpcloud the steps are mentioned below
Okta : Create SAML app integrations
Jumpcloud : SSO using Custom SAML Application Connectors

To implement for okta and jumpcloud we create an api route with our exposed sign-on url (refer the above image), this is the url where IDP sends a signed XML request either by POST of HTTP redirect.

The code for SAML verification goes like this

import { NextResponse } from 'next/server';
import { DOMParser } from 'xmldom';
import * as fs from 'fs';
import * as xpath from 'xpath';
import {SignedXml} from 'xml-crypto';



  
export async function POST(request: any, { params }: any) {

    console.log("Request is ",request);
    const body = await request.formData();
    const samlResponse: string = body.get("SAMLResponse");
    const samlXml = Buffer.from(body.get("SAMLResponse"), 'base64').toString('utf-8');
    console.log(samlXml)
    const doc = new DOMParser().parseFromString(samlXml, 'text/xml');
    var signature = xpath.select(
        "//*[local-name(.)='Signature' and namespace-uri(.)='http://www.w3.org/2000/09/xmldsig#']",
        doc
    ) as Node[]; // Add type assertion to ensure it is an array of nodes
    if (signature.length > 0) {
        signature = signature[0]; // Access the first element if it exists
    } else {
        throw Error('Signature not found');
    }
    const issuer = await doc.getElementsByTagName('saml2:Issuer')[0]?.textContent || '';

    // query db to confirm existence of issuer
    const samlReocrds = await pool.query('SELECT * FROM samlConfigs where issuer_url = $1', [issuer]);
    if (samlReocrds.rowCount == 0) {
        return NextResponse.json({ message: 'Issuer not found' }, { status: 400 });
    }
    const db_issuer = samlReocrds.rows[0].issuer_url;

    // get certificate from db
    const bufffered_certif = Buffer.from(decrypt(samlReocrds.rows[0].idp_certificate));
    var sig = new SignedXml({publicCert: Buffer.from(decrypt(samlReocrds.rows[0].idp_certificate))});
    sig.loadSignature(signature);
        try {
        var res = sig.checkSignature(samlXml);
        console.log("saml vaidation is ",res);
        } catch (ex) {
        console.log(ex);
}
if (res===false){
return NextResponse.json({message: "SAML is tampered"},{status: 401})

    }
    
    const attributes = doc.getElementsByTagName("saml2:Attribute");
    const userId = doc.getElementsByTagName('saml2:NameID')[0]?.textContent || '';

// redirect to dashboard or do something 

return NextResponse.json( {msg: "Authentication Success !!!"} ,{ status: 200 });

}

The above code checks for the authenticy of the SAML Request.We receive the signed XML on our API route, do check as this will be base64 encoded.We use xpath and xmldom libraries here, the xmldom helps us extract the different tags in our XML, and xpath to extract the signature part from the signed xml.Use the xml-crypto library that here creates an instance of SignedXml with the x509 certificate stored in our database, use that with the signature extracted from XML and let the check signature function verify its authenticity

var sig = new SignedXml({publicCert: Buffer.from(decrypt(samlReocrds.rows[0].idp_certificate))});
    sig.loadSignature(signature);
        try {
        var res = sig.checkSignature(samlXml);
        console.log("saml vaidation is ",res);
        } catch (ex) {
        console.log(ex);
}
if (res===false){
return NextResponse.json({message: "SAML is tampered"},{status: 401})

    }

Additionally you can check other other parameters in the XML for authenticity such as

1. IDP Entity ID , this should match ID from out database
2. SP Entity ID, this should match the apps own ID
3. The time conditions that is NotBefore/NotOnAfter fields
4. NameID , the email id of the user that is being authenticated
5. Any other SAML claims

// check time conditions
const conditionsElement =
    doc.getElementsByTagName('saml2:Conditions')[0]
  if (conditionsElement) {
    // Get the NotBefore and NotOnOrAfter attributes
    const notBefore = conditionsElement.getAttribute('NotBefore');
    const notOnOrAfter = conditionsElement.getAttribute('NotOnOrAfter');

// your checking logic
}
//verify issuer , the IDP id from your DB
const issuer = doc.getElementsByTagName('saml2:Issuer')[0]?.textContent
// verify the presence of user
const userId = doc.getElementsByTagName('saml2:NameID')[0]?.textContent

After verification the User can be authenticated and be allowed to use your app. This marks the end of IDP initiated SSO with Jumpcloud and Okta.

Click on your app in the Okta dashboard and you are signed in

The SP initiated SSO with Okta and Jumpcloud is simple,
For each application these IDPs generate unique SSO URL, when you redirect the user to that URL you automatically take them to the IDPs authentication page from where after password verification the SAML callback flow continues

Add a redirect to the SSO URL Copied from IDP during setup and the application will now authenticate user using SP initiated SSO

Google Workspace SAML SSO Implementation :

The IDP initiated SSO is just the same as it is for Okta and Jumpcloud
But what really is different is the SP initiated SSO flow
To setup a google saml app refer here

Following code snippet helps in SP initiated SSO flow

const id = `_${uuidv4()}`;
const issueInstant = new Date().toISOString();
const assertionConsumerServiceURL = `${process.env.NEXT_PUBLIC_WEB_HOST}api/v1/users/samlCallbacks`;
const issuer = `${process.env.NEXT_PUBLIC_WEB_HOST}dashboard`;
const samlRequestXml = `
  <samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="${id}" Version="2.0" ProviderName="SP test" IssueInstant="${issueInstant}" Destination="${samlConfig.sso_url}" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" AssertionConsumerServiceURL="${assertionConsumerServiceURL}">
    <saml:Issuer>${issuer}</saml:Issuer>
    <samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" AllowCreate="true"/>
    <samlp:RequestedAuthnContext Comparison="exact">
      <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
  </samlp:AuthnRequest>
`;
samlRequest = base64Encode(samlRequestXml);

// Make a POST request to Google's SAML endpoint
const response = await fetch('sample-company-sso-url.google.com', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    SAMLRequest: samlRequest,
  }).toString(),
});

// Handle the response
if (response.ok) {
  const googleSAMLResponse = NextResponse.json(
    { ssoUrl: response.url }, // redirect to this new ssourl
    { status: 200 }
  return googleSAMLResponse;
  );

In the above code you make a XML request from your application to Google IDP with an XML containing your Callback URL and SP entity ID, Google will return a unique sign in url for the user where authentication can be redirected

Microsoft Entra SAML SSO Implementation :

Microsoft Entra woke up and decided to be weird
Refer for creating an Entra SAML App here

XML Verification

The IDP initiated flow works the same except Microsoft changed some XML tags where additional checks happen.

const issuer =
    //Extracting Issuer in google, Okta, Jumpcloud
    doc.getElementsByTagName('saml2:Issuer')[0]?.textContent ||
    // Extracting Issuer in Microsoft
    doc.getElementsByTagName('Issuer')[0]?.textContent

const conditionsElement =
    // Extracting Condtions in google, Okta, Jumpcloud
    doc.getElementsByTagName('saml2:Conditions')[0] ||
    // Extracting Conditions in Microsoft
    doc.getElementsByTagName('Conditions')[0];

const userId =
    // Extracting NameID in google, Okta, Jumpcloud
    doc.getElementsByTagName('saml2:NameID')[0]?.textContent ||
    // Extracting NameID in Microsoft
    doc.getElementsByTagName('NameID')[0]?.textContent

SP Initiated SSO

The SP Initiated SSO works a bit different here as well.
Like Google you create a XML and remove extra lines and spaces.
Further Deflate the XML string and bas64 encode it and create a encoded URL where the browser can be redirected.

const id = `_${uuidv4()}`;
const issueInstant = new Date().toISOString();
const assertionConsumerServiceURL = `mapp/api/v1/users/samlCallbacks`;
const issuer = `myapp/dashboard`;
const samlRequestXml = `
  <samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="${id}" Version="2.0" ProviderName="SP test" IssueInstant="${issueInstant}" Destination="${samlConfig.sso_url}" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" AssertionConsumerServiceURL="${assertionConsumerServiceURL}">
    <saml:Issuer>${issuer}</saml:Issuer>
    <samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" AllowCreate="true"/>
    <samlp:RequestedAuthnContext Comparison="exact">
      <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
  </samlp:AuthnRequest>
`;
samlRequest = base64Encode(samlRequestXml);

// Make a POST request to Google's SAML endpoint
const samlRequestXmlTrimmed = samlRequestXml
      .replace(/\s+/g, ' ') // Replace multiple spaces with a single space
      .replace(/>\s+</g, '><') // Remove spaces between XML tags
      .trim();

// deflate before encode
samlRequest = deflateRawSync(samlRequestXmlTrimmed).toString(
'base64');
samlRequest = encodeURIComponent(samlRequest);
// return the url , the front end will redirect to this url
return NextResponse.json(
  { ssoUrl: `sample-company-sso-url.microsoft.com?SAMLRequest=${samlRequest}` },
  // Redirect to Above ssourl
  { status: 200 }
)

Conclusion

This guide covers SAML authentication with Next.js backend, supporting Okta, Google Workspace, Microsoft Entra, and JumpCloud. With SP and IDP-initiated flows, signature validation, and metadata exchange, your application is enterprise-ready!

Source: Medium