Skip to main content

SSO / SAML Integration

NirmIQ supports enterprise Single Sign-On (SSO) using SAML 2.0, enabling seamless authentication through your organization's identity provider.

Overview​

SAML SSO allows your team to:

  • Log in once using corporate credentials
  • Centralize user management in your IdP
  • Automate user provisioning and deprovisioning
  • Enforce corporate security policies
  • Simplify access for employees

Supported Identity Providers​

NirmIQ works with any SAML 2.0 compliant identity provider:

  • Okta
  • Azure Active Directory (Azure AD)
  • Google Workspace
  • OneLogin
  • PingIdentity
  • JumpCloud
  • Auth0
  • ADFS (Active Directory Federation Services)

Prerequisites​

Before configuring SSO:

  1. Admin access to NirmIQ (Organization Admin role)
  2. Admin access to your identity provider
  3. Verified domain (optional but recommended)

Configuration Steps​

Step 1: Get NirmIQ SP Metadata​

  1. Log in to NirmIQ as an Organization Admin
  2. Go to Admin → SSO Settings
  3. Note the following values:
    • SP Entity ID: https://api.nirmiq.com/sso/sp/{org_id}
    • ACS URL: https://api.nirmiq.com/sso/acs/{org_id}
  4. Download the SP Metadata XML file

Step 2: Configure Your Identity Provider​

Add NirmIQ as a new SAML application in your IdP:

For Okta​

  1. Admin → Applications → Create App Integration
  2. Select SAML 2.0
  3. App name: "NirmIQ"
  4. Single sign-on URL: {ACS URL from Step 1}
  5. Audience URI: {SP Entity ID from Step 1}
  6. Name ID format: Email
  7. Attribute statements:
    • email → user.email
    • firstName → user.firstName
    • lastName → user.lastName

For Azure AD​

  1. Enterprise Applications → New Application → Create your own
  2. Name: "NirmIQ"
  3. Set up single sign-on → SAML
  4. Basic SAML Configuration:
    • Identifier: {SP Entity ID}
    • Reply URL: {ACS URL}
  5. User Attributes & Claims:
    • Required claim: emailaddress

For Google Workspace​

  1. Admin Console → Apps → SAML Apps → Add App
  2. Name: "NirmIQ"
  3. ACS URL: {ACS URL from Step 1}
  4. Entity ID: {SP Entity ID from Step 1}
  5. Name ID: Basic Information > Primary Email

Step 3: Get IdP Metadata​

From your identity provider, obtain:

  1. IdP Entity ID (Issuer URL)
  2. SSO URL (Single Sign-On Service URL)
  3. X.509 Certificate (for signature verification)

Most IdPs provide a metadata URL or downloadable XML file.

Step 4: Configure NirmIQ​

  1. Go to Admin → SSO Settings
  2. Enter your IdP details:
    • IdP Entity ID: Paste the issuer URL
    • SSO URL: Paste the sign-on URL
    • Certificate: Paste the X.509 certificate (PEM format)
  3. Configure user provisioning:
    • Auto-provision users: Enable to create accounts automatically
    • Default role: Role for newly provisioned users
  4. Click Save Configuration
  5. Toggle Enable SSO

Step 5: Configure Domain Mapping (Optional)​

To enable automatic SSO discovery based on email domain:

  1. Go to Admin → SSO Settings → Domain Mapping
  2. Add your corporate domain(s):
    • Example: company.com, subsidiary.com
  3. Save

Users with these email domains will see "Sign in with SSO" automatically.

Testing SSO​

Test Login​

  1. Open an incognito/private browser window
  2. Go to NirmIQ login page
  3. Enter an email from your configured domain
  4. Click Sign in with SSO (or you'll be redirected automatically)
  5. Complete authentication in your IdP
  6. Verify you're logged into NirmIQ

Troubleshooting Test​

If login fails:

  1. Check Admin → SSO Settings → Debug Logs
  2. Common issues:
    • Certificate mismatch
    • Incorrect ACS URL
    • Time synchronization issues
    • Missing required attributes

User Provisioning​

Just-in-Time (JIT) Provisioning​

When enabled, NirmIQ creates user accounts automatically:

  1. User authenticates via IdP
  2. NirmIQ receives SAML assertion
  3. If user doesn't exist, account is created with:
    • Email from assertion
    • Name from attributes (if provided)
    • Default role from configuration
  4. User is logged in

Attribute Mapping​

Map IdP attributes to NirmIQ user fields:

NirmIQ FieldCommon IdP Attributes
Emailemail, emailAddress, mail
First NamefirstName, givenName
Last NamelastName, surname, sn
Rolerole, groups (custom mapping)

Deprovisioning​

When a user is removed from your IdP:

  • They can no longer authenticate via SSO
  • Their NirmIQ account remains (for audit purposes)
  • Admin can manually deactivate if needed

Security Settings​

Allowed Email Domains​

Restrict SSO to specific email domains:

  1. Go to Admin → SSO Settings
  2. Under Allowed Domains, add domains
  3. Only users with matching emails can authenticate

Single Logout (SLO)​

If your IdP supports Single Logout:

  1. Configure SLO URL in NirmIQ settings
  2. When users log out of NirmIQ, they're also logged out of IdP
  3. When users log out of IdP, NirmIQ session ends

User Experience​

Login Flow​

With domain mapping:

  1. User enters email
  2. System detects SSO domain
  3. Automatic redirect to IdP
  4. User authenticates
  5. Redirect back to NirmIQ

Without domain mapping:

  1. User clicks "Sign in with SSO"
  2. Selects or enters organization
  3. Redirect to IdP
  4. User authenticates
  5. Redirect back to NirmIQ

Existing Password Users​

Users with existing password-based accounts:

  • Can link their account to SSO
  • After linking, can use either method
  • Organization can require SSO-only

Best Practices​

1. Test Thoroughly​

  • Test with multiple user types
  • Verify attribute mapping
  • Check error scenarios

2. Communicate to Users​

  • Announce SSO availability
  • Provide instructions for first login
  • Explain password vs SSO options

3. Plan for Fallback​

  • Keep at least one admin with password access
  • Document emergency access procedures

4. Monitor Usage​

  • Review SSO login statistics
  • Check for failed authentications
  • Audit user provisioning

5. Regular Certificate Rotation​

  • IdP certificates expire
  • Update NirmIQ when rotating
  • Test after updates

Audit Logging​

All SSO events are logged:

  • Login attempts (success/failure)
  • User provisioning
  • Configuration changes
  • Certificate updates

View logs at Admin → SSO Settings → Audit Log

FAQ​

Can users still log in with passwords?​

By default, yes. You can disable password login for SSO users in organization settings.

What happens if SSO is down?​

Admins with password access can still log in. Consider keeping emergency admin accounts.

Can we have multiple IdPs?​

Currently, each organization can configure one IdP. Contact support for multi-IdP requirements.

How do I migrate existing users to SSO?​

Existing users can link their accounts:

  1. Log in with password
  2. Go to Profile → Security
  3. Link SSO account
  4. Future logins can use SSO