SSO Setup Guide - Okta SSO

Environment Configuration

1. Create the App Integration

1. Sign in to your Okta Admin Console at your organization's Okta URL (e.g., https://yourorg.okta.com/admin)
2. Navigate to Applications → Applications
3. Click Create App Integration
4. Select SAML 2.0 as the sign-in method
5. Click Next

2. Configure General Settings

1. App name: Enter eezi-UAT (or eezi-PROD for production)
2. App logo (optional): Upload a logo if desired
3. App visibility: ☑️ Check Do not display application icon to users and Do not display application icon in the Okta Mobile app. eezi only accepts sign-ins that start at eezi (SP-initiated), so an Okta dashboard tile would not work — see the note in step 3.
4. Click Next

3. Configure SAML Settings

General Settings

• Single sign-on URL: Enter the ACS URL from the table above
  • UAT: `https://eezi-uat.auth.eu-west-1.amazoncognito.com/saml2/idpresponse`
  • Prod: https://sso.eezi.io/saml2/idpresponse
• ☑️ Check Use this for Recipient URL and Destination URL
• Audience URI (SP Entity ID): Enter the Identifier from the table above
  • UAT: urn:amazon:cognito:sp:eu-west-1_jrGoNRAfk
  • Prod: urn:amazon:cognito:sp:eu-west-1_2y5UMRUqJ
• Default RelayState: Leave blank
• Name ID format: Select EmailAddress
• Application username: Select Custom and enter String.toLowerCase(user.email) (eezi matches existing users on the lowercase email address)
• Update application username on: Select Create and update
• Don't change any of the Advanced Settings defaults.

Attribute Statements

Under Attribute Statements, add the following four statements exactly as shown. Names are case-sensitive; a missing or misspelled attribute will cause sign-in to fail.

• Leave Group Attribute Statements empty — eezi does not use group claims.
• Before continuing, click Preview the SAML Assertion and confirm that all four attributes are present with values and that the NameID is the user's email address in lowercase.

Click Next after configuring these settings.

4. Feedback Settings

Select the appropriate option for your use case (typically "I'm an Okta customer adding an internal app") and click Finish.

5. Retrieve SAML Metadata for eezi Support

After creating the application:

1. Navigate to the Sign On tab of your newly created app
2. In the SAML Setup section, locate the Metadata details
3. Right-click on Identity Provider metadata and copy the link address (this is your metadata URL)

Alternatively, you can view the metadata:

• Sign on methods → SAML 2.0 → View SAML setup instructions
• This page will show:
  • Identity Provider Single Sign-On URL
  • Identity Provider Issuer
  • X.509 Certificate (for download if metadata URL cannot be shared)

6. Share Details with eezi Support

Provide your eezi technical support contact with:

In your support ticket/email, include:

• The metadata URL
• Sign-On URL
• Issuer URL
• Your organization name
• Specify that it's for eezi UAT SSO (or PROD)

7. Assign Users and Groups

1. Navigate to the Assignments tab of your eezi application
2. Click Assign → Assign to People or Assign to Groups
3. Add every user or group that should access eezi UAT/PROD
4. Make sure you are assigned so you can test
5. Click Done

8. Testing & Go-Live

1. Wait for confirmation from eezi support that your metadata/certificate is loaded
2. Test: In a private browser window, open the eezi sign-in page (UAT: https://uat.eezi.io/sign-in/, Prod: https://eezi.io/sign-in/) and enter your work email. You should be redirected to Okta and then back into eezi. Don't test from the Okta dashboard — IdP-initiated sign-in is not supported.
3. Success? eezi will enable SSO for all assigned users
4. Communicate any future user-assignment changes to your eezi support contact

Important Notes

• Enabling SSO doesn't sign existing users out immediately
• Keep your assigned user list current; only assigned users can sign in via SSO
• Users must always start sign-in from the eezi sign-in page; opening eezi from the Okta dashboard (IdP-initiated) is not supported
• If Okta rotates its signing certificate, eezi will automatically pick it up via the metadata URL—no manual action required
• For production, repeat these steps using the PROD configuration values from the table at the top

Troubleshooting

If SSO is not working:

• Verify the Entity ID and ACS URL match exactly (including https:// and any trailing paths)
• Confirm the Name ID format is set to EmailAddress
• Check that users are assigned to the application in Okta
• Sign-in fails when launched from the Okta dashboard: this is expected — sign-in must start from the eezi sign-in page
• Signed in but name or email is missing or wrong: check the attribute statement names match the table in step 3 exactly (including http:// and letter case), then use Preview the SAML Assertion
• Duplicate or unlinked user: make sure the email attribute and application username are lowercased
• Verify that eezi support has confirmed configuration on their end
• Review Okta system logs (Reports → System Log) for SAML errors