SAML SSO with Okta¶

Step-by-step guide to integrate Faraday's SAML SSO with Okta.

Prerequisites: Faraday commercial edition, Okta developer/admin account. See SAML for general SAML configuration reference.

Note: This guide covers SAML 2.0 integration. For LDAP-based Okta authentication, see the LDAP with Okta guide.

Configuration Summary¶

Replace <domain> with your Faraday server's FQDN throughout.

Step-by-Step Setup¶

Step 1 — Access Okta Admin Console¶

1. Navigate to Okta.
2. Log in with a user account that has administrative privileges.
3. Open the Admin console.

Step 2 — Create a SAML App Integration¶

1. In the Admin console, go to Applications → Applications.
2. Click Create App Integration.
3. Select SAML 2.0 as the Sign-in method.
4. Click Next.

Step 3 — Set General Settings¶

1. Enter the name of your integration (e.g., "Faraday").
2. Optionally upload a logo.
3. Click Next.

Step 4 — Configure SAML Settings¶

1. On the Configure SAML tab, enter:

   Field	Value
   Single Sign On URL	https://<domain>/_api/saml/acs
   Audience Restriction	https://<domain>/_api/saml/metadata.xml

2. In the Attribute Statements section, add:

   Name	Value
   username	user.email

3. Click Next.

Step 5 — Complete App Creation¶

1. On the final step, select the options that suit your organization.
2. Click Finish.

Step 6 — Copy IdP Credentials¶

1. On your app's page, go to the Sign On tab.

2. In the Settings section, locate the SAML setup information:

   Okta Field	Faraday Setting
   Identity Provider Single Sign-On URL	sso_url (SSO URL)
   Identity Provider Issuer	identity_id (Identity ID)
   X.509 Certificate	idp_certificate (IdP Certificate — click Download)

3. Click Save.

Step 7 — Assign Users¶

1. Go to the Assignments tab of your Okta app.
2. Click Assign and select users or groups who should have access.
3. Click Done.

Step 8 — Generate SP Certificates¶

On your Faraday server, generate the Service Provider certificate pair:

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 1825 -out certificate.pem

• certificate.pem → SP Certificate in Faraday settings
• key.pem → SP Private Key in Faraday settings

Step 9 — Configure Faraday¶

Apply the settings via CLI:

faraday-manage settings -a update saml

Fill in the prompts:

Alternatively, configure via the Web UI at Preferences → Authentication → SAML.

Step 10 — Restart Faraday¶

systemctl restart faraday-server

Step 11 — Test the Integration¶

1. Open the Faraday login page.
2. Click the SSO button labeled with your display_name.
3. Authenticate with your Okta credentials.
4. Verify you are redirected back to Faraday with an active session.

Attribute Mapping¶

Okta sends SAML assertions containing user attributes defined in the Attribute Statements section of the SAML configuration.

The mapping configured in Step 4 sends user.email as the username attribute. Ensure attribute_identifier in Faraday matches the Name field.

Common Okta Attribute Values¶

Group Attribute Statement (Optional)¶

To enable group-based role mapping in Faraday, add a Group Attribute Statement in the Okta SAML configuration:

Then set admin_group in Faraday to the Okta group name that should map to admin access.

Troubleshooting¶

References¶

• Okta: Build a Single Sign-On (SSO) Integration