Enabling SAML single sign-on (SSO) 

Overview

This article walks an admin through:

• SSO (SAML 2.0) setup (IdP configuration + NodaFi settings)

• Automated provisioning (SCIM 2.0) setup (IdP → NodaFi)

• Provisioning mappings (locations, groups, roles) and troubleshooting

NodaFi supports SAML 2.0 for authentication and SCIM 2.0 for provisioning. Core values used by both systems are provided below. See the “Arcades” note at the end if you’re configuring a second product. For the official API endpoints used by NodaFi, see the configuration tables below.

Prerequisites

• NodaFi Administrator role for the tenant you are configuring.

• IdP Administrator access (Azure AD / Okta / OneLogin / etc.).

• Enterprise plan

• Your NodaFi subdomain (example: acme for acme.nodafi.com).

• SSO (SAML) must be enabled & saved in NodaFi before enabling SCIM.

Quick reference — NodaFi SAML & SCIM values

(Replace {your-subdomain} with your subdomain.)

Part 1 — Single Sign-On (SAML 2.0)

A. Gather NodaFi SAML details

Before you configure the IdP, note the values above (Entity ID, ACS, Sign-on URL). Example: if your subdomain is acme, ACS = https://api.nodafi.com/api/v1/auth/login/sso/acme.

B. Configure your Identity Provider

Below are concise step sequences for the most common IdPs. Use the IdP’s console to paste the NodaFi values where required.

Azure AD (Microsoft Entra ID)

1. Create app: Azure Portal → Microsoft Entra ID → Enterprise Applications → + New application → Create your own → name "NodaFi" → Non-gallery → Create.

2. Sign-on method: Select SAML.

3. Basic SAML Configuration (Edit):

   • Identifier (Entity ID): nodaFi

   • Reply URL (ACS): https://api.nodafi.com/api/v1/auth/login/sso/{your-subdomain}

   • Sign on URL: https://{your-subdomain}.nodafi.com/auth/login

   • (Optional) Relay state: https://{your-subdomain}.nodafi.com/staff/tickets

4. Attributes & Claims: Map at minimum: email → user.mail. Add givenname, surname, phone. If you plan to auto-assign roles, add role or group/claim that maps to role value.

5. Certificate: Download the Certificate (Base64) and copy contents (including -----BEGIN CERTIFICATE----- / -----END CERTIFICATE-----) into NodaFi.

6. Login URL: Copy the IdP SAML Login URL (IdP Entry Point) and paste into NodaFi’s IdP Entry Point field.

Tip: In Azure, under Group Claims you can emit group names (recommended) instead of GUIDs — this makes mapping easier.

Okta

1. Create app: Okta Admin → Applications → Create App Integration → SAML 2.0.

2. General: App name: “NodaFi”.

3. SAML Settings:

   • Single sign-on URL: https://api.nodafi.com/api/v1/auth/login/sso/{your-subdomain}

   • Audience (SP Entity ID): nodaFi

   • Name ID format: EmailAddress

   • Application username: Email

4. Attribute statements: email, givenname (user.firstName), surname (user.lastName), phone (user.primaryPhone)

5. Finish: Save, open Sign On tab → View SAML instructions → copy Identity Provider Single Sign-On URL and X.509 Certificate for NodaFi settings.

OneLogin

1. Add app: OneLogin → Applications → Add App → SAML Custom Connector (Advanced).

2. Basic: Display Name: “NodaFi”.

3. SSO settings:

   • ACS (Consumer) URL: https://api.nodafi.com/api/v1/auth/login/sso/{your-subdomain}

   • Audience: nodaFi

   • SAML nameID format: Email

4. Parameters: Add mappings for email, givenname, surname, phone.

5. Credentials: On the SSO tab copy the SAML 2.0 Endpoint (HTTP) and download the X.509 Certificate.

If you use a different IdP, configure the same SAML settings (Entity ID = nodaFi, ACS = https://api.nodafi.com/api/v1/auth/login/sso/{your-subdomain}, POST binding), map email and other attributes, supply the IdP certificate and entry point URL into NodaFi.

C. Configure NodaFi for SSO

1. Log into NodaFi as an Administrator → Settings → Company Settings → Authentication.

2. In SSO (SAML 2.0): Toggle Enable SAML-based Single Sign-On → ON.

3. Enter IdP details:

   • IdP Entry Point URL: paste IdP Login URL (e.g., Azure login URL).

   • X.509 Certificate: paste full certificate text (including BEGIN/END).

4. Save Authentication Settings.

5. Test: Open an incognito window → https://{your-subdomain}.nodafi.com/auth/login → choose SSO and attempt login via IdP.

Part 2 — Automated User Provisioning (SCIM 2.0)

SCIM lets your IdP auto-create, update, and deactivate users in NodaFi.

Prerequisite: SAML SSO must be enabled and saved before enabling SCIM.

A. Enable SCIM in NodaFi

1. Settings → Company Settings → Authentication.

2. Scroll to SCIM Provisioning → Click Enable SCIM Provisioning.

3. Copy the Tenant URL (example https://api.nodafi.com/scim/v2/{your-subdomain}) and the Bearer Token (token is shown once). Store token securely.

   • If you lose the token you must disable & re-enable SCIM to get a new token.

B. Configure IdP provisioning (examples)

Azure AD

1. In the Enterprise Application → Provisioning → Get started.

2. Provisioning mode: Automatic.

3. Enter Tenant URL and Secret Token (Bearer token), then Test Connection (should succeed).

4. Mappings: Edit user mappings so Azure attributes map to SCIM attributes. Example mappings:

   • userPrincipalName → userName

   • objectId → externalId

   • displayName → displayName

   • givenName → name.givenName

   • surname → name.familyName

   • mail → emails[type eq "work"].value

   • telephoneNumber → phoneNumbers[type eq "work"].value

   • Soft delete expression → active (true/false)

5. Scope: Choose Sync only assigned users and groups (recommended) or Sync all users and groups.

6. Start provisioning: Turn Provisioning Status to On and save.

Okta

1. In the NodaFi app → Provisioning tab → Configure API Integration.

2. Enable API integration. Enter SCIM Base URL and API Token, Test API Credentials.

3. Under To App, enable Create users, Update user attributes, Deactivate users.

4. Assignments: assign users/groups to the application to control who syncs.

C. SCIM attributes & best practices

Minimum attributes to provision a user:

• userName (login/email)

• name.givenName, name.familyName

• emails[type="work"].value

• active (boolean) — for provisioning/deprovisioning

• externalId (IdP GUID) — recommended as matching precedence #1 so changes to email do not break account linking.

Best practice: Use externalId as the stable matching attribute if your IdP supports it. Scope the sync to assigned users/groups to avoid accidentally provisioning entire directories.

Provisioning Mappings (Locations, Groups, Roles)

After SCIM is enabled you can map IdP groups / attributes to NodaFi entities.

Location mappings

• Auto-match by name: If IdP group names match NodaFi location names (case-insensitive), enable auto-match.

• Explicit mapping: Add manual mappings when names differ.

• Default location: A fallback location for unmatched users.

• All Locations group: Define the IdP group name that should grant access to all locations (default "All Locations").

Group mappings

• Auto-match groups by name or create explicit mappings from IdP group → NodaFi group (teams used for ticket routing).

Role mappings

Map IdP values or groups to NodaFi permission roles:

Examples:

• IdP Group Managers → NodaFi Admin

• Claim role=technician → NodaFi Staff
  Set a Default role (e.g., End User) for unmatched users.

Troubleshooting

SSO (SAML)

SCIM

Azure AD specifics

• If group claims appear as GUIDs, change Group Claims to emit names or use explicit mapping to match GUIDs to NodaFi locations/groups.

• First Azure sync can take ~20–40 minutes; subsequent syncs are incremental.

Testing checklist (run before going live)

• SSO login works (test in incognito).

• New user provisioned via SCIM appears in NodaFi with correct attributes.

• User role matches role mappings.

• User location access matches mappings.

• User group membership appears as expected.

• Deactivating user in IdP deactivates in NodaFi.

• Updating attributes in IdP is reflected in NodaFi.

Advanced examples

Role mapping (sample)

• IdP group SiteAdmins → NodaFi role Admin

• Claim groups contains NorthWarehouse → map to NodaFi Location North Warehouse

Sample SCIM mapping