Skip to main content

Identity Provider (IdP) Mode

In SAML 2.0 (OASIS XML-based SSO standard), an Identity Provider authenticates users and issues signed XML assertions that Service Providers accept. Configure LumoAuth as a SAML IdP to provide SSO to applications like Salesforce, Box, Slack, AWS Console, or custom enterprise apps.

SP-Initiated SSO Flow​

In the most common flow, the user starts at the SP application, which redirects to LumoAuth for authentication.

7 / 7
  1. User to SP App: Access App
  2. SP App to LumoAuth: AuthnRequest (SAML Redirect)
  3. LumoAuth to User: LumoAuth Login Page
  4. User to LumoAuth: Authenticate (Credentials / MFA)
  5. LumoAuth to SP App: SAML Response (Signed Post)
  6. Note: Validate Assertion & Establish Session
  7. SP App to User: Access Granted / Redirect to Dashboard

IdP Metadata Endpoint​

GET /orgs/\{orgId\}/saml/idp/metadata

Returns the SAML IdP metadata as an XML document (the file that describes LumoAuth's sign-on endpoints, supported NameID formats and signing certificate). Provide this URL to SP applications to configure SAML SSO automatically.

Example Request​

curl https://app.lumoauth.dev/orgs/acme-corp/saml/idp/metadata

Response​

MIICo...
                
            
        
        
        
            urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
        
        
            urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

Single Sign-On Endpoint​

GET/POST /orgs/\{orgId\}/saml/idp/sso

Receives SAML AuthnRequests from Service Providers. Supports both HTTP-Redirect and HTTP-POST bindings.

HTTP-Redirect Binding (GET)​

ParameterRequiredDescription
SAMLRequestYesBase64 + DEFLATE encoded AuthnRequest
RelayStateNoOpaque state preserved through SSO
SigAlgIf signedSignature algorithm
SignatureIf signedRequest signature

HTTP-POST Binding (POST)​

ParameterRequiredDescription
SAMLRequestYesBase64 encoded AuthnRequest
RelayStateNoOpaque state preserved through SSO

Processing Flow​

  1. Decode and parse the AuthnRequest
  2. Validate the request (signature if required — see Per-SP Client Settings)
  3. If user is logged in, generate SAML Response immediately
  4. If user is not logged in, redirect to the login page, preserving the request
  5. After authentication, the user is sent to GET /orgs/{orgId}/saml/idp/sso/continue, which resumes the pending AuthnRequest
  6. Generate the signed SAML Response
  7. POST the Response to the SP's ACS URL

SAML Response Structure​

LumoAuth generates signed SAML Responses containing user assertions:

https://app.lumoauth.dev/orgs/acme-corp/saml/idp/metadata
    
    ...
    
    
        
    
    
    
        https://app.lumoauth.dev/orgs/acme-corp/saml/idp/metadata
        
        
            
                user@example.com
            
            
                
            
        
        
        
            
                https://sp.example.com
            
        
        
        
            
                user@example.com
            
            
                John
            
            
                Doe
            
        
        
        
            
                
                    urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

Configuration Guide​

Step 1: Add the SP Application​

  1. Navigate to Applications in your organization portal (the page that manages OAuth/OIDC and SAML applications)
  2. Click New application and choose SAML 2.0 as the protocol
  3. Enter the SP configuration:
  • Application name: Application display name
  • Entity ID (issuer): SP's unique identifier
  • Assertion Consumer Service (ACS) URL: Where to send SAML Responses
  1. Click Create application

The Create application page with the SAML 2.0 protocol selected

The full SAML form at /orgs/{orgId}/portal/applications/saml/create also sets the Single logout (SLO) URL, Default relay state, NameID format, NameID source, signing, encryption and the SP certificate in one step. Finish it with Create SAML application.

The New SAML application form

Step 2: Configure the SP Application​

Provide your IdP metadata to the SP application. Most SPs accept a metadata URL:

https://app.lumoauth.dev/orgs/{your-organization}/saml/idp/metadata

Step 3: Map User Attributes (optional)​

Each SAML application has an outbound attribute mapping that controls the user fields that LumoAuth emits in the assertion. The mapping is a JSON object of outgoing SAML attribute name → LumoAuth user field, where the user field must be one of email, name, id, username, or roles:

{
    "email": "email",
    "displayName": "name",
    "groups": "roles"
}

If you leave the mapping at its default, LumoAuth emits the user's email and display name twice. They appear under the standard emailaddress and name claim URIs (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/...) and under the LDAP object identifiers urn:oid:0.9.2342.19200300.100.1.3 (mail) and urn:oid:2.5.4.42.

Per-SP Client Settings​

Each SAML application (SP) exposes the following settings:

SettingDefaultDescription
nameIdSourceemailWhich user field supplies the NameID. One of email, id, username.
signResponsesEnabledSign the SAML Response element.
signAssertionsEnabledSign the assertion element inside the response.
encryptAssertionsDisabledEncrypt the assertion with the SP's public key (see Assertion Encryption). Requires the SP certificate.
assertionValiditySeconds300Assertion NotOnOrAfter window (5 minutes).
sessionLifetimeSeconds28800SAML session lifetime (8 hours).
defaultRelayState(none)RelayState used when the SP omits one.

On the SAML application form these are NameID source, Sign SAML responses, Sign SAML assertions, Encrypt assertions and Default relay state. Require signed AuthnRequests and the SP certificate (PEM) are in the same Security section.

The Security section of the SAML application form with the signing and encryption switches

Signed AuthnRequests are enforced by default

In IdP mode, LumoAuth requires the SP's AuthnRequest to be signed unless the client explicitly opts out. A client must either set signatureRequired = true (preferred), or set allowUnsignedAuthnRequests = true to accept unsigned requests. Unsigned acceptance is a deprecated opt-out, and every unsigned request that it accepts is audited.

Assertion Encryption​

When encryptAssertions is enabled for an SP, LumoAuth replaces the <saml:Assertion> in the Response with a <saml:EncryptedAssertion> (SAML 2.0 Core §2.3.4, XML Encryption):

LayerAlgorithm
Content encryptionhttp://www.w3.org/2009/xmlenc11#aes256-gcm (AES-256-GCM). Falls back to aes256-cbc only if the runtime cannot do GCM.
Key transporthttp://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p (RSA-OAEP with MGF1/SHA-1), wrapped to the SP certificate.

Processing order is sign, then encrypt. The assertion is signed first (if signAssertions is on), and the signed assertion is then encrypted. Finally the Response is signed (if signResponses is on), so the outer signature covers the ciphertext. Every signature references its own element by ID (<ds:Reference URI="#_…">), so the decrypted assertion verifies on its own.

The SP certificate configured on the application (certificate) is used both to verify signed AuthnRequests and as the encryption target. It must be an X.509 certificate with an RSA key of at least 2048 bits.

Fails closed

Enabling encryptAssertions without an SP certificate is rejected when the application is saved. If the certificate is later removed or is unusable, SSO for that SP fails with an error and a saml_response_error audit entry — LumoAuth never falls back to issuing a plaintext assertion.

The IdP metadata advertises the algorithms above in the <md:KeyDescriptor use="encryption"> element (<md:EncryptionMethod>), so SPs that read metadata can apply them automatically.

Salesforce​

Entity IDhttps://saml.salesforce.com
ACS URLhttps://login.salesforce.com/...
NameIDemailAddress (Federation ID)

Box​

Entity IDbox.net
ACS URLhttps://app.box.com/saml/...
NameIDemailAddress

Slack​

Entity IDhttps://slack.com
ACS URLhttps://your-workspace.slack.com/sso/saml
NameIDemailAddress

Certificate Management​

LumoAuth generates the organization's SAML signing certificate automatically the first time it is needed (for example when the IdP or SP metadata is first requested):

  • RSA 2048-bit key, SHA-256 signatures
  • Validity: 3 years from generation
  • One certificate per organization, used for both IdP and SP mode and published in both metadata documents

There is no portal page or API for rotating or importing the certificate. Note the expiry date shown in the metadata and plan a re-exchange of metadata with your SP applications before it expires.