raia cX · Section
Enterprise SSO & SAML
Connect your identity provider so members sign in with company credentials, with role mapping, provisioning, and SSO enforcement.
Audience: Organization owners, organization administrators, and identity-provider administrators.
How SSO works
Single sign-on, or SSO, lets your identity provider authenticate a user for raia CX. Your identity provider is the system your company uses to manage employee identities and sign-in policies.
raia CX acts as the service provider. Your company's system acts as the identity provider, often abbreviated IdP. They exchange identity information using SAML 2.0.
A typical sign-in follows these steps:
- A member chooses SSO in raia CX or opens a connection's direct login URL.
- raia sends the member to the identity provider.
- The identity provider authenticates the member according to its sign-in policies.
- The identity provider sends a signed SAML assertion to raia.
- raia validates the response, identifies the user, and evaluates organization access and role assignment.
- If required, the member confirms their email address and completes their profile.
- raia opens the member's session.
Authentication establishes who the user is. Authorization determines which organization and role the user can access. SSO can supply role information, but raia's organization roles and other access controls still govern what the user can do.
Creating an SSO connection does not automatically require all members to use it. Activation and enforcement are separate settings.
Before you begin
Have the following ready:
| Requirement | Why you need it |
|---|---|
| Org Owner or Org Admin access in raia CX | Create, configure, test, and manage the organization's SSO connections. |
| Administrator access to your identity provider | Create or configure a SAML application and assign users to it. |
| IdP metadata URL or metadata XML | Import the provider's settings and public signing certificates. You can also enter settings manually. |
| A test identity assigned to the SAML application | Validate the actual attributes and role information your provider sends. |
| A decision about role assignment | Choose raia entitlements, custom attribute mappings, or an allowed default role. |
| DNS access, if using verified domains | Verify domain ownership for email-based discovery and optional domain restrictions. |
The current enterprise connection workflow supports SAML. OIDC appears as Coming soon and cannot be selected.
Use your provider's generic SAML application workflow. Product-specific setup screens may differ; the raia field mappings in this guide apply regardless of the provider's terminology.
Create an SSO connection
- Select the correct organization in raia CX.
- Open Settings → Security.
- In Enterprise Single Sign-On, select Add connection if the organization does not yet have one.
- Enter a descriptive name, such as
Company SSOorCorporate Entra. - Keep SAML selected and select Create.
After the first connection is created, manage connections from Settings → SSO. Connection names must be unique within the organization, ignoring capitalization.
The connection initially has Draft status.
| Status | Meaning |
|---|---|
| Draft | Setup is in progress. Administrative test login is available once the required IdP settings and certificate are present. |
| Active | Members can use the connection for production sign-in. |
| Inactive | The configuration remains saved, but production sign-in through the connection is disabled. |
The connection page contains four tabs:
| Tab | What it controls |
|---|---|
| Configuration | Connection name, identity-provider settings, signing certificates, and raia service-provider values. |
| Users & roles | Provisioning, profile attributes, role mapping, and related access settings. |
| Domains | Verified domains attached to this connection for discovery and optional sign-in restrictions. |
| Testing | Saved test results, identity information, role resolution, and activation readiness. |
An organization can have multiple SSO connections. raia permits up to 20 connections per organization and prevents duplicate IdP Entity IDs within the same organization.
Exchange settings with your identity provider
Copy raia values into the identity provider
On the Configuration tab, locate Service provider. Copy the generated values exactly.
| raia field | Common identity-provider field | Purpose |
|---|---|---|
| Entity ID | Identifier, Audience URI, SP Entity ID | Identifies this raia SAML connection. |
| ACS URL | Reply URL, Assertion Consumer Service URL, Single sign-on URL | Receives the SAML response using HTTP POST. |
| Metadata URL | SP metadata URL | Provides raia's SAML service-provider metadata. |
| Login URL | Sign-on URL, application launch URL | Starts sign-in through this raia connection. |
Provider terminology varies. A field named “Single sign-on URL” may mean the raia ACS URL, while the IdP's own sign-on endpoint is a different URL. Check whether the field describes the service provider or the identity provider.
Use the values displayed by your connection rather than constructing production URLs yourself. Each connection has its own identifier and URLs.
For reference, raia generates these paths:
Entity ID: {API_BASE_URL}/auth/saml/{CONNECTION_ID}/metadata
Metadata URL: {API_BASE_URL}/auth/saml/{CONNECTION_ID}/metadata
ACS URL: {API_BASE_URL}/auth/saml/{CONNECTION_ID}/callback
Login URL: {API_BASE_URL}/auth/saml/{CONNECTION_ID}These are templates. CONNECTION_ID is the connection's generated identifier, not its display name or the organization's brand URL slug.
Import identity-provider metadata into raia
- Under Identity provider, select Import from IdP.
- Choose Metadata URL or Paste XML.
- Enter the provider's metadata URL or paste its metadata XML.
- Select Parse.
- Review the Entity ID, Sign-on URL, optional Logout URL, and certificates.
- Select Apply to save the imported configuration.
Parsing alone does not save the configuration.
If URL import fails because the metadata endpoint is inaccessible, obtain the XML from your IdP administrator and use Paste XML.
Metadata import is an administrative action. Do not assume that raia periodically refreshes settings or certificates from the metadata URL.
Enter settings manually
Alternatively, enter and save:
| Field | Requirement |
|---|---|
| Entity ID | Required for an active connection. Must match the IdP issuer. |
| Sign-on URL | Required for an active connection. raia sends users here to authenticate. |
| Logout URL | Optional configuration field. See the logout limitation below. |
Then add the IdP's public signing certificate in Certificates. You can paste the certificate or select Upload PEM file.
Use a public X.509 signing certificate in PEM/Base64 form. Do not upload the IdP's private key. Certificates must be parseable and unexpired; duplicate certificates are rejected.
SAML settings to confirm with your IdP administrator
- Send the SAML response to the generated ACS URL using HTTP POST.
- Set the audience to the exact raia Entity ID.
- Send a signed assertion. Signing only the outer response does not meet the adapter's requirement for signed assertions.
- Include a stable, non-transient NameID and an email attribute.
- Assign the test user and intended production users to the SAML application.
raia does not currently provide a SAML assertion-decryption key or an AuthnRequest-signing key. Coordinate with raia if your provider requires encrypted assertions or signed authentication requests.
Logout limitation: The UI can store a Logout URL, but the reviewed SAML flow does not implement SAML Single Logout. Signing out of raia should not be treated as signing out of the identity provider or other company applications.
Configure user attributes
Open Users & roles → User profile attributes.
raia uses SAML attributes to obtain the member's email, first name, and last name. The fields contain the names of attributes sent by the IdP, not a user's actual profile values.
| raia field | Default attribute name |
|---|---|
| Email attribute | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
| First name attribute | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname |
| Last name attribute | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname |
raia also tries common alternatives:
| Profile value | Supported fallback attribute names |
|---|---|
email, mail | |
| First name | firstName, givenName, givenname |
| Last name | lastName, surname, sn |
Run a test login before changing these mappings. If raia cannot resolve a field, use the exact attribute name shown in the test result.
NameID and email are separate requirements
NameID is the identifier raia uses to recognize the same identity on later sign-ins. Prefer a stable identifier that does not change when a person's name or email changes.
- Missing NameID blocks activation and production sign-in.
- Transient NameID is rejected because it changes between sessions.
- Email-format and unspecified-format NameIDs produce advisory test warnings rather than automatically blocking activation.
- Email must still resolve separately; do not rely on NameID alone to supply the email field.
Changing a NameID for an existing person can create an identity conflict. Coordinate such changes with raia support before rolling them out.
Configure roles and provisioning
Choose how raia assigns a role
For the organization receiving the sign-in, raia evaluates:
- A valid raia entitlement for that organization.
- The first matching custom attribute rule.
- The configured default role, only if fallback is enabled.
- Otherwise, rejection because no role could be resolved.
An entitlement for another organization does not prevent raia from evaluating custom mappings for the current organization.
Option A: Map an existing IdP attribute
Use this when your provider already sends groups, application roles, or another suitable attribute.
- Open Users & roles → Role mapping.
- Select Add custom mapping.
- Enter the attribute's exact name.
- Enter the expected value.
- Choose the raia role.
- Repeat for other groups or values.
- Drag rules into the required priority order and select Save.
Example:
| Priority | Attribute | Value | raia role |
|---|---|---|---|
| 1 | groups | raia-administrators | Org Admin |
| 2 | groups | raia-managers | Org Manager |
| 3 | groups | raia-users | Org User |
The first matching custom rule wins. Put the rule that should take precedence first.
Attribute names must match the provider's output. Value comparisons ignore leading/trailing whitespace and capitalization. A rule can match any value in a multi-valued attribute; it is an equality match, not a substring or regular-expression match.
raia permits up to 100 custom mapping rules per connection.
Option B: Send raia entitlements
Use this when you want the identity provider to explicitly state the raia organization and role.
The default Entitlement attribute is:
https://raia2.com/SAML/Attributes/RoleThis URI is an attribute identifier. It is not a webpage or endpoint to configure or visit.
Each value must follow this format:
raia:org:{ORGANIZATION_UUID}:role:{ROLE}For example, using an illustrative organization UUID:
raia:org:11111111-1111-4111-8111-111111111111:role:copilot_userUse the actual organization's UUID, not its name, brand slug, or SSO connection ID. The role mapping table provides entitlement values you can copy.
| UI role | Entitlement role value | Available as a default fallback |
|---|---|---|
| Org Owner | owner | No |
| Org Admin | admin | No |
| Org Manager | manager | Yes |
| Org User | user | Yes |
| Copilot Admin | copilot_admin | Yes |
| Copilot User | copilot_user | Yes |
| Guest | guest | Yes |
Use the exact lowercase role values shown above. Send one intended role per organization per user to avoid ambiguous assignments.
Provisioning settings
Configure these under Users & roles → Provisioning, then select Save.
| Setting | Default for a new connection | Behavior |
|---|---|---|
| Just-in-time provisioning | On | Allows a successful SSO sign-in to create a user and add organization membership without a prior invitation. Role resolution and other access checks still apply. |
| Role sync | On | Applies the resolved organization role on successful sign-in, including changes to an existing member's role. |
| Allow sign-in if a role cannot be resolved | Off | When enabled, uses the selected default role if no entitlement or mapping resolves a role. Off corresponds to strict mode. |
| Default role | Guest | Used only when fallback is enabled. Org Admin and Org Owner cannot be default fallback roles. |
| Force authentication | Off | Asks the IdP to authenticate the user again instead of reusing its existing session. This is a request to the IdP, not a separate raia MFA setting. |
| Allow SSO only for verified domains on this connection. | Off | Limits SSO to email domains that are verified and attached to this connection. |
| Accept entitlements from another organization's SSO login | Off | Enables advanced shared-certificate access across organizations. See section 11 before enabling it. |
Existing users, invitations, and inactive memberships
- JIT enabled: Eligible users can join through SSO without an invitation.
- JIT disabled: Users must already belong to the organization or have a pending invitation for the asserted email address.
- Inactive membership: SSO does not reactivate the membership. An administrator must address it.
- Role sync disabled: Existing members keep their organization role. When a pending invitation is consumed, its role is preserved.
- Strict mode with role sync disabled: An existing active member of the sign-in organization can keep their current role even when the assertion resolves no new role. This exception does not replace the role-resolution requirement for activation.
Role sync can change privileged roles. Test the intended role for administrators and owners before requiring SSO.
SSO provisions and evaluates access during sign-in. It is not continuous directory synchronization or automatic removal of memberships when an IdP group changes.
Add optional discovery domains
A discovery domain helps raia find the right SSO connection when someone enters their email address on the general sign-in page.
For example, a verified and attached company.example domain can help users with that email domain discover the organization's SSO connection.
A discovery domain is not required to activate SSO or use a direct SSO login link.
Verify and attach a domain
- Open Settings → Domains.
- Add the email domain.
- Open its verification action.
- Copy the generated DNS TXT record name and value.
- Publish the record with your DNS provider.
- Select Check DNS in raia.
- After verification succeeds, open the SSO connection's Domains tab.
- Add the verified domain to the connection.
Keep the TXT record published. raia periodically checks the record and can remove verified status when the record is no longer present.
Public mailbox domains such as gmail.com cannot be attached as discovery domains.
Discovery versus restrictions
| Configuration | Effect |
|---|---|
| Verified domain attached; restriction off | Helps route sign-in. Other email domains may still authenticate if all other requirements are satisfied. |
| Verified domain attached; restriction on | Only matching verified email domains on this connection can use it. |
| No discovery domain | Share the direct Login URL or the organization's dedicated login page. |
Domain matching is exact. Verify and attach a subdomain separately if users sign in with addresses on that subdomain.
The restriction cannot be enabled without an attached verified domain. While enabled, the connection's domain controls prevent removal of its last verified discovery domain.
Enabling the restriction can block existing users, including contractors whose email addresses are outside the attached domain list. Loss of DNS verification can also affect sign-in when the restriction is enabled.
Invitation-domain restrictions in organization security settings are separate from these SSO connection settings.
Test and activate the connection
Run a test login
- Save the IdP configuration, signing certificate, and intended role settings.
- Select Test login.
- Authenticate at the identity provider with a representative test user.
- Return to the connection's Testing tab.
- Review the resolved identity, attributes, assigned role, and warnings.
Test login inspects the SAML response and records the result. It does not create the test user's raia account, change their membership, or establish their production sign-in session.
A successful SAML round trip is not the same as being ready to activate. The result must contain the identity and role information raia requires.
Review role mapping
After capturing a test result, use Preview role mapping under Users & roles to inspect the role that would be assigned from the captured attributes.
The preview identifies whether the role came from an entitlement, a custom mapping, or the default role. It can also show rejected target organizations, invalid entitlements, and unmatched mapping values.
Previewing does not save edited mapping rules. Save the intended configuration and run a fresh test login after making changes.
Activation requirements
raia requires:
- An IdP Entity ID and Sign-on URL.
- At least one unexpired signing certificate.
- A retained test-login result.
- No blocking identity warnings, such as missing email, missing NameID, or transient NameID.
- A role that resolves for the connection's own organization.
Once these conditions are met, select Activate.
raia retains up to three recent test results for 30 days. Clear results removes saved results and observed attribute values. Run a fresh test when no usable result remains.
Validate production sign-in
After activation, use a separate browser session to test the member-facing Login URL. Confirm that:
- The expected user is authenticated.
- Email confirmation and profile completion work when required.
- The user enters the intended organization with the correct role.
- JIT, invitations, and domain restrictions behave as intended.
This production check is necessary because administrative test login does not run the full account-creation and onboarding flow.
Require SSO for your organization
After production sign-in works, open Settings → Security → Enterprise Single Sign-On.
Require SSO
Turn on Require SSO and confirm the change.
Non-owners must satisfy an active SSO connection for this organization before they can enter it. This also applies when they are already signed in to raia through another method and try to switch into the organization.
Organization owners remain exempt unless owner enforcement is also enabled.
Require SSO for owners
With Require SSO enabled, turn on Require SSO for owners if owners must also authenticate through SSO.
This removes password and social sign-in options from the organization's branded login page. Your own session may need an SSO sign-in before you can continue using the organization.
Test owner access and agree on an account-recovery process before enabling this setting.
Enforcement rules
- At least one active SSO connection is required before enforcement can be enabled.
- Owner enforcement requires organization SSO enforcement.
- Turning off Require SSO also turns off owner enforcement.
- The final active connection cannot be deactivated or deleted while SSO is required.
- Having an SSO identity linked to an account is not enough by itself: the current session must satisfy the organization's SSO requirement.
- Membership in another organization does not automatically satisfy this organization's SSO requirement.
Enforcement controls access to the organization. It does not give a member additional permissions beyond their raia role and other access controls.
How members sign in
Organization login page
Share the Login page URL shown on the connection page.
If no dedicated page exists, configure the organization's URL slug under Settings → Brand. Then copy the generated login-page URL.
For one available connection, the button reads Sign in with SSO. When multiple connections are shown, buttons use the connection names.
Direct connection link
Share the Login URL under Service provider to start sign-in through a specific connection.
General sign-in page
Members can enter their email on the general sign-in page. Where a verified attached domain identifies available SSO connections, raia presents the relevant sign-in choices. Multiple matches may require the user to choose an organization or connection.
If a connection is not discovered, use its direct login link or the organization's login page.
First-time email confirmation
raia may show Confirm your identity and send a six-digit code to the email address supplied by the identity provider.
This generally occurs when the identity has not confirmed that email and the organization has not verified ownership of its domain. A later email change can also trigger confirmation.
Enter the code and select Confirm. Use Resend code if needed. Confirmation expires after 10 minutes; an expired or exhausted confirmation requires restarting SSO sign-in.
This step is separate from any MFA performed by the identity provider.
Complete your profile
A newly provisioned user with an incomplete profile is prompted to:
- Supply a missing first or last name.
- Enter a mobile number in international format.
- Accept the terms displayed in the form.
- Verify the phone number using the received code.
The enterprise SAML profile-completion flow does not ask the user to create a raia password.
Switching organizations
If the next organization requires SSO that the current session has not satisfied, raia prompts the user to authenticate with an active connection for that organization.
Use SSO across multiple organizations
Each raia organization configures its own connection. A shared identity provider can serve multiple organizations, but sharing the provider's name or issuer alone does not establish cross-organization trust.
There are two distinct outcomes:
- Provisioning membership: A sign-in can create or update eligible memberships in additional organizations.
- Satisfying SSO enforcement: Entering an organization that requires SSO can still require authentication through that organization's own active connection.
Enable cross-organization provisioning deliberately
For a target organization to accept access information from another organization's sign-in:
- The target must have an active SAML connection.
- Its connection must contain the certificate that actually validated the incoming assertion.
- Accept entitlements from another organization's SSO login must be enabled on the target connection.
- The target must resolve a role from an entitlement or custom attribute mapping.
- Its membership status and JIT/invitation rules must permit the user.
A default fallback role is not used to grant access to another organization through this flow.
The email-domain restriction is checked on the connection receiving the actual sign-in. Do not use a target connection's domain restriction as a substitute for controlling cross-organization grants. A failed grant to an additional organization can be skipped while sign-in to the original organization succeeds.
Example entitlement attribute with two separate values:
Attribute: https://raia2.com/SAML/Attributes/Role
Value 1: raia:org:11111111-1111-4111-8111-111111111111:role:user
Value 2: raia:org:22222222-2222-4222-8222-222222222222:role:copilot_userReplace both illustrative UUIDs with actual organization IDs.
This setting creates a broad trust relationship among organizations using the validating certificate. Explicit entitlements or mappings can grant privileged roles, including Org Owner. Enable it only when those organizations and their administrators are within your intended trust boundary.
When rotating a shared certificate, coordinate the update across every organization participating in this trust relationship.
Maintain or remove a connection
Rotate signing certificates
raia supports multiple certificates on one connection so certificates can overlap during a rollover.
- Obtain the new public signing certificate from the IdP administrator.
- Add it to the connection before the old certificate is retired.
- Coordinate switching the IdP to the new certificate.
- Run Test login and a production sign-in check using the new signing configuration.
- Remove the old certificate after confirming the transition.
An active connection cannot have its last stored certificate removed. Keep a valid replacement available and monitor the expiry information shown in the UI.
Update settings
Update the relevant section and select Save. An active connection cannot have its Entity ID or Sign-on URL cleared.
Treat changes to issuer, certificates, user identifiers, mappings, and domain restrictions as access-affecting changes. Retest representative users after updating them.
Deactivate
Select Deactivate to stop production sign-ins through that connection while keeping its configuration.
If it is the last active connection and the organization requires SSO, activate a replacement or turn off enforcement first.
Delete
Deleting removes the connection and its associated certificate records, SSO identity links, and discovery-domain associations. It also removes that connection's recorded SSO sign-in methods from stored sessions.
Deletion is not a user-offboarding operation: it does not itself delete users or their organization memberships.
Recreating a connection generates a different connection identifier and new service-provider URLs. Update the IdP configuration and repeat testing before use.
Offboard a member
Disable the person's access in the identity provider and manage their raia membership as part of your offboarding process. Do not assume that removing an IdP assignment instantly terminates an existing raia session or deletes a membership.
Identity provider setup guides
These guides show where raia's values go in common identity providers. Start each one after you have created an SSO connection in raia and opened its Configuration tab. Provider menus change over time, so use your provider's current documentation if a label differs.
In every provider you will:
- Copy raia's Entity ID and ACS URL into the provider.
- Send the member's email, first name, and last name as attributes.
- Assign the application to the people or groups who should use raia.
- Bring the provider's metadata or certificate back into raia.
- Run Test login in raia before activating.
Use an email address as the NameID where possible. It keeps each member's identity stable and matches the default raia attributes.
Okta
- In the Okta Admin Console, go to Applications → Applications and select Create App Integration.
- Choose SAML 2.0 and select Next.
- Name the app (for example, "raia CX"), optionally upload a logo, and select Next.
- Under SAML Settings, enter:
- Single sign-on URL: raia's ACS URL. Leave Use this for Recipient URL and Destination URL checked.
- Audience URI (SP Entity ID): raia's Entity ID.
- Name ID format: EmailAddress.
- Application username: Email.
- Under Attribute Statements, add:
email→user.emailfirstName→user.firstNamelastName→user.lastName
- Optional: under Group Attribute Statements, add a group attribute (for example,
groups, filter Matches regexraia.*) if you plan to map groups to raia roles. - Select Next, choose the feedback option, and select Finish.
- On the app's Sign On tab, copy the Metadata URL (or view and copy the metadata XML).
- On the Assignments tab, assign the people or groups who should use raia.
- In raia, select Import from IdP, paste the metadata URL or XML, select Parse, review, and select Apply.
Microsoft Entra ID (Azure AD)
- In the Microsoft Entra admin center, go to Identity → Applications → Enterprise applications and select New application.
- Select Create your own application, name it (for example, "raia CX"), choose Integrate any other application you don't find in the gallery, and select Create.
- Open Single sign-on and choose SAML.
- In Basic SAML Configuration, select Edit and enter:
- Identifier (Entity ID): raia's Entity ID.
- Reply URL (Assertion Consumer Service URL): raia's ACS URL.
- Sign on URL: raia's Login URL (optional).
- Save. In Attributes & Claims, confirm the defaults:
- Unique User Identifier (Name ID) →
user.mailoruser.userprincipalname, format Email address. emailaddress,givenname, andsurnameclaims are included. These match raia's default attribute names, so no raia changes are usually needed.
- Optional: select Add a group claim if you plan to map groups to raia roles. Entra sends group object IDs by default; use those IDs in your raia role mappings, or choose cloud-only group display names where available.
- In SAML Certificates, copy the App Federation Metadata Url, or download Federation Metadata XML.
- Go to Users and groups and assign the people or groups who should use raia.
- In raia, select Import from IdP, paste the metadata URL or XML, select Parse, review, and select Apply.
If a user's mail value is empty in Entra, sign-in will fail because raia cannot find an email address. Fill in the mail field or send user.userprincipalname as the email claim.
Google Workspace
- In the Google Admin console, go to Apps → Web and mobile apps.
- Select Add app → Add custom SAML app.
- Name the app (for example, "raia CX") and select Continue.
- On Google Identity Provider details, select Download Metadata (or copy the SSO URL, Entity ID, and Certificate). Select Continue.
- On Service provider details, enter:
- ACS URL: raia's ACS URL.
- Entity ID: raia's Entity ID.
- Start URL: raia's Login URL (optional).
- Name ID format: EMAIL. Name ID: Basic Information → Primary email.
- Select Continue. On Attribute mapping, add:
- Primary email →
email - First name →
firstName - Last name →
lastName
- Optional: under Group membership, choose groups and name the app attribute (for example,
groups) if you plan to map groups to raia roles. - Select Finish. Open the app, select User access, and turn it ON for everyone or for the organizational units or groups that should use raia. Changes can take a few minutes to apply.
- In raia, select Import from IdP → Paste XML, paste the downloaded metadata, select Parse, review, and select Apply. You can also enter the SSO URL, Entity ID, and certificate manually.
OneLogin
- In OneLogin, go to Applications → Applications and select Add App.
- Search for SAML Custom Connector (Advanced) and select it. Name the app and select Save.
- On the Configuration tab, enter:
- Audience (EntityID): raia's Entity ID.
- Recipient: raia's ACS URL.
- ACS (Consumer) URL Validator: raia's ACS URL, with regular-expression characters escaped (or
.*for testing only). - ACS (Consumer) URL: raia's ACS URL.
- Login URL: raia's Login URL (optional).
- SAML nameID format: Email. SAML signature element: Response or Both.
- On the Parameters tab, add
email(Email),firstName(First Name), andlastName(Last Name), checking Include in SAML assertion for each. Set NameID value to Email. - Optional: add a
groupsor roles parameter if you plan to map them to raia roles. - Save. On the SSO tab, copy the Issuer URL (metadata URL) or select More Actions → SAML Metadata to download XML.
- Assign the app to the right users or roles.
- In raia, select Import from IdP, paste the metadata URL or XML, select Parse, review, and select Apply.
JumpCloud
- In the JumpCloud Admin Portal, go to SSO Applications and select Add New Application.
- Choose Custom Application, then select Manage Single Sign-On (SSO) and Configure SSO with SAML. Name it and save.
- On the SSO tab, enter:
- IdP Entity ID: a unique value for your organization (for example,
jumpcloud-raia). - SP Entity ID: raia's Entity ID.
- ACS URLs: raia's ACS URL.
- SAMLSubject NameID: email. SAMLSubject NameID Format: emailAddress.
- Signature Algorithm: RSA-SHA256. Choose to sign the Assertion or Response.
- Login URL: raia's Login URL (optional).
- Under Attributes, add
email→ email,firstName→ firstname, andlastName→ lastname. - Optional: check Include group attribute and name it (for example,
groups) if you plan to map groups to raia roles. - On the User Groups tab, bind the groups who should use raia, then save.
- Open the app again and select Export Metadata.
- In raia, select Import from IdP → Paste XML, paste the metadata, select Parse, review, and select Apply.
Other SAML 2.0 providers
Most other providers, such as PingFederate, PingOne, ADFS, Duo, and Keycloak, follow the same pattern:
| Provider setting | Value from raia |
|---|---|
| Audience, SP Entity ID, Relying party identifier | Entity ID |
| ACS URL, Reply URL, Assertion Consumer Service | ACS URL (HTTP POST binding) |
| SP metadata import | Metadata URL |
| Default relay or start URL | Login URL |
Send email, first name, and last name as attributes, sign responses or assertions with RSA-SHA256, then import the provider's metadata into raia. If your provider requires encrypted assertions or signed authentication requests, contact raia before you begin.
After any provider setup
- In raia, run Test login with an assigned test user.
- Review the attributes raia received. If email or name is missing, update the attribute names in Users & roles → User profile attributes to match exactly.
- If you sent groups, set up role mapping and review how the test user's role resolves.
- Resolve any activation blockers, then activate the connection.
Troubleshooting
| Message or symptom | What to check |
|---|---|
| SSO connection not found | Use a current login link. A deleted and recreated connection has different URLs. |
| SSO is not ready | Finish configuration and activate the connection. Draft and inactive connections do not allow production sign-in. |
| Identity provider response was rejected | Compare the issuer, audience/Entity ID, ACS URL, and signing certificate. Ensure assertions are signed and assertion timing is valid. |
| No user identifier received | Configure the IdP to send a stable NameID. |
| Temporary identifier cannot be used | Replace transient NameID with a stable identifier. |
| No email address received | Inspect the test attributes and set the correct Email attribute. NameID alone is insufficient. |
| Email domain is not allowed | Check the connection's domain restriction and attached verified domains. Use an approved account or have the administrator review the policy. |
| No account in this organization | JIT is disabled and no eligible membership or pending invitation exists for the email. |
| Membership is inactive | Ask an administrator to reactivate the membership if access should be restored. |
| Role is not allowed / No organization role assigned | Verify the entitlement's organization UUID and role value, or correct custom mappings. Enable a suitable default only if that is the intended access policy. |
| Organization is full | The API has returned a user-limit condition. Ask the organization administrator or raia support to check the applicable account limit. |
| This email is already linked | A different NameID is already linked to that user on this connection. Contact support before changing identity configuration. |
| SSO session expired | Restart sign-in from the current login page; do not reuse an old redirect. |
| This sign-in was already used | The SAML response has already been consumed. Start a new sign-in. |
| Too many SSO attempts | Wait and retry. Repeated attempts are rate limited. |
| Confirmation code is incorrect | Enter the newest code. If the flow expires or attempts are exhausted, start sign-in again. |
| No SSO option after entering email | Verify the connection is active and the exact email domain is verified and attached. Try the direct Login URL. |
| Test login succeeds but activation is blocked | Review blocking identity warnings and confirm a role resolves for this organization. Save changes and run a fresh test. |
| Test login succeeds but a member cannot sign in | Check JIT/invitation eligibility, inactive membership, domain restrictions, email confirmation, and profile completion in a production login. |
| Wrong role is assigned | Entitlements take precedence. For custom mappings, the first matching rule wins. Check Role sync when testing existing users. |
| Sign-in immediately returns after logging out | The IdP may still have an active session. Force authentication requests a fresh IdP sign-in; raia does not currently support SAML Single Logout. |
| Cannot disable or delete a connection | It may be the last active connection while Require SSO is enabled. Establish a replacement or disable enforcement first. |
| Cannot remove a certificate | An active connection must retain at least one certificate. Add a replacement before removing the last one. |
| Cannot remove a discovery domain | The connection may require verified domains and this is its last verified domain. Add another or review the restriction first. |
When contacting support, include the organization name, connection name or ID, approximate time of the failure, exact displayed error, and whether it happened during test or production sign-in. Share any diagnostic identity data through the support channel requested by raia; do not include passwords, private keys, session tokens, or complete SAML responses in ordinary screenshots.
Frequently asked questions
Is enterprise SSO the same as Sign in with Google or Microsoft?
No. Enterprise SSO is a SAML connection configured for a raia organization. The existing social sign-in buttons use separate authentication flows. Social sign-in does not by itself satisfy an organization's SAML enforcement requirement.
Does enabling SSO disable password login?
Activating a connection adds SSO as an option. Require SSO makes it necessary for non-owners to enter the organization. Require SSO for owners extends that requirement to owners and removes password/social options from the organization's branded login page.
Does SSO apply my company's MFA policy?
The identity provider performs its configured authentication checks. Configure the intended MFA policy there. The Force authentication toggle is a request for fresh authentication; it is not an MFA-policy editor. raia may separately require email confirmation or profile completion.
Do users need an invitation?
With JIT enabled, eligible users can join through successful SSO without an invitation. With JIT disabled, an existing membership or pending invitation is required.
Can contractors use personal email addresses?
They can potentially use SSO through a direct link or organization login page when the IdP permits them, role/provisioning requirements are satisfied, and the connection does not restrict sign-in to verified attached domains. Public mailbox domains cannot be used as discovery domains, and mailbox confirmation may be required.
Does a verified email domain grant organization access?
No. Domain discovery helps locate a connection. Identity validation, role resolution, provisioning rules, and membership status determine access. Domain verification also affects whether an email-confirmation challenge is required.
Are IdP group changes applied immediately?
Role sync evaluates attributes during successful sign-in. The reviewed feature does not include continuous group synchronization or SCIM provisioning/deprovisioning.
Does raia automatically download replacement certificates?
The reviewed flow imports metadata when an administrator chooses Parse and Apply. Manage certificate rollover explicitly.
Can users start from the identity provider's application portal?
raia supports IdP-initiated SAML responses without RelayState for active connections. Test this path with your provider. If the provider sends RelayState, raia expects a valid state value issued by raia; an arbitrary provider-configured value will be rejected. The direct raia Login URL provides the standard raia-initiated path.
Rollout checklist
- [ ] Select the correct raia organization and create a clearly named connection.
- [ ] Copy the generated service-provider values into the IdP.
- [ ] Import or enter the IdP settings and public signing certificate.
- [ ] Configure stable NameID, email, and profile attributes.
- [ ] Define and test role mappings or entitlements.
- [ ] Confirm the intended JIT, Role sync, and default-role settings.
- [ ] Verify and attach domains if discovery or domain restriction is needed.
- [ ] Complete Test login and resolve activation blockers.
- [ ] Activate the connection.
- [ ] Test production sign-in for a new user, existing user, and administrator/owner.
- [ ] Verify email confirmation and phone/profile completion where applicable.
- [ ] Share the organization's login page or direct connection Login URL.
- [ ] Enable Require SSO when member access has been verified.
- [ ] Enable owner enforcement only after owner access and recovery procedures are confirmed.
- [ ] Record certificate-expiry dates and assign responsibility for rollover.