SSO Configuration

Overview

First Orion supports IdP-Initiated Single Sign-On (SSO) using the SAML 2.0 protocol. This allows your organization's users to authenticate through your Identity Provider (IdP) and access the First Orion Customer Portal without separate credentials.

This guide covers general SAML configuration requirements and provides step-by-step instructions for Okta and Microsoft Entra ID.

Prerequisites

1. Contact [email protected] to initiate SSO setup. First Orion will confirm your account is SSO-eligible and provide any tenant-specific details (e.g., roleId, businessId, or resellerId values).
2. You must have administrator access to your Identity Provider.
3. This is an IdP-Initiated flow — users launch the First Orion app from your IdP's app dashboard/portal. SP-initiated SSO is NOT currently supported.

SAML Configuration Reference

(These values are the same regardless of which IdP you use)

Optional Attribute Statements

No custom attributes are required. The following optional attributes can be included:

• roleId - UUID provided by First Orion. Overrides the default user role (See Defaults Section).
• businessId — UUID identifying the business the user belongs to. Overrides the default businessId (See Defaults Section).
• resellerId — UUID identifying the reseller associated with the user.

Defaults

When no custom attributes are sent for a user, the following defaults from your
SSO configuration are applied.

• roleId: Business Admin
• businessId: The default business configured for your SSO integration. If no
  default is set, users must have a businessId attribute in your IdP.
• resellerId: The reseller associated with your account, as configured by
  First Orion during SSO setup.

Integration: OKTA

Step 1 — Create a New SAML Application

1. In the Okta Admin Console, go to Applications > Applications > Create App Integration.
2. Select SAML 2.0 and click Next.
3. Enter an App Name (e.g., "First Orion Portal") and optionally upload a logo. Click Next.

Step 2 — Configure SAML Settings
On the "Configure SAML" screen, enter:

• Single sign-on URL: https://portal.firstorion.com/app/saml/SSO
• Use this for Recipient URL and Destination URL: Checked
• Audience URI (SP Entity ID): https://portal.firstorion.com/app/saml/metadata
• Name ID format: EmailAddress
• Application username: Email
• Default RelayState: (leave blank)

Step 3 — (Optional) Add Custom Attributes
Under Attribute Statements, add any of the optional attributes listed in the
SAML Configuration Reference above (e.g., roleId, businessId, resellerId) with
the UUIDs provided by First Orion.

Step 4 — Export Metadata and Send to First Orion

1. After saving, go to the Sign On tab of the application.
2. Click "Identity Provider metadata" to download the metadata.xml.
3. Send the metadata.xml to [email protected].

Step 5 — Assign Users

1. Go to the Assignments tab.
2. Assign users or groups who should have access to First Orion.

Integration: Microsoft Entra ID (Azure AD)

Step 1 — Register an Enterprise Application

1. In the Azure portal, go to Microsoft Entra ID > Enterprise Applications > New Application.
2. Click "Create your own application."
3. Name it (e.g., "First Orion Portal"), select "Integrate any other application you don't find in the gallery (Non-gallery)", and click Create.

Step 2 — Set Up SAML SSO

1. Go to Single sign-on > SAML.
2. In Basic SAML Configuration, click Edit and enter:
   • Identifier (Entity ID): https://portal.firstorion.com/app/saml/metadata
   • Reply URL (ACS URL): https://portal.firstorion.com/app/saml/SSO
   • Sign on URL: (leave blank — IdP-initiated)
   • Relay State: (leave blank)
   • Logout URL: (leave blank)
3. Click Save.

Note: Leave Sign on URL blank since this is IDP-initiated SSO.

Step 3 — Configure User Attributes & Claims

1. In the Attributes & Claims section, click Edit.
2. Ensure the Unique User Identifier (Name ID) is set to user.mail with format "Email address."
3. (Optional) Add claims for any of the optional attributes listed in the
   SAML Configuration Reference above (e.g., roleId, businessId, resellerId)
   with the UUIDs provided by First Orion.

Step 4 — Download Federation Metadata and Send to First Orion

1. In the SAML Signing Certificate section, download Federation Metadata XML.
2. Send the file to [email protected].

Step 5 — Assign Users and Groups

1. Go to Users and groups > Add user/group.
2. Assign the appropriate users or security groups.

Troubleshooting

"Invalid Audience" error - Verify the Audience URI is exactly https://portal.firstorion.com/app/saml/metadata with no trailing slash.

"User not found" error - The SAML Subject (Name ID) must be the user's email address. Confirm the Name ID format is set to EmailAddress.

Assertion signature failure - Ensure you sent the most recent metadata.xml to First Orion after any certificate rotations.

Users land on a login page instead of SSO - First Orion only supports IdP-Initiated SSO. Users must launch the app from the IdP portal, not from portal.firstorion.com directly.

Role not applied correctly - Verify the roleId attribute name is lowercase and the value matches the UUID provided by First Orion.

FAQ

Q: Does First Orion support SP-initiated SSO?
A: No. Only IdP-initiated SSO is supported at this time.

Q: What SAML binding is used?
A: HTTP-POST.

Q: Are custom claims/attributes required?
A: No. The only required assertion value is the user's email as the Subject/Name ID. The roleId, businessId, and resellerId attributes are all optional. See the Defaults section for fallback behavior.

Q: What is the default user role?
A: Business Admin. Override it by sending the roleId attribute with a UUID provided by First Orion.