# Okta SAML
Learn how to integrate Fiddler with Okta for seamless Single Sign-On (SSO) authentication using the Security Assertion Markup Language (SAML) protocol.
## Overview
This integration allows your users to access Fiddler using their existing Okta credentials. Users are automatically provisioned in Fiddler on their first successful login, eliminating the need for manual user invitations.
## Prerequisites
Before starting, ensure you have:
* **Okta Administrator Access**: Permissions to create and configure applications in your Okta organization
* **Fiddler AuthN Administrator Access**: "Org Owner" role in Fiddler's AuthN management console
* **Deployment Information**: Your Fiddler deployment base URL
{% hint style="info" %}
The URL to the AuthN management console is your Fiddler instance base URL prepended with `authn-`. For example, if your base URL is `https://acme.cloud.fiddler.ai` then you can access the AuthN management console at `https://authn-acme.cloud.fiddler.ai`.
{% endhint %}
## Configuring Okta and Fiddler for Integration
{% stepper %}
{% step %}
**Fiddler AuthN Console Sign-in**
Sign in using the AuthN Console Org Owner user account credentials provided by your Fiddler representative:
{% endstep %}
{% step %}
**Select Your Organization**
Ensure your organization is selected in the dropdown. You may see the *fiddler* organization, but this is reserved for system use and should not be edited. Here we are using the *example1* organization:
{% endstep %}
{% step %}
**Navigate to Identity Providers in Settings**
Select *Settings* tab from the top menu and then select *Identity Providers* from the left navigation menu:
{% endstep %}
{% step %}
**Add and Configure New SAML Provider**
1. Select the SAML option in the *Add provider* section which brings up the Sign in with SAML form.
2. Choose a name for the Okta SAML integration. Note that this name will be displayed on the SSO login button on the Fiddler sign-in page so choose a name your users will recognize.
3. Paste the following placeholder value into the Metadata Xml text area. This is necessary for AuthN to create the URLs needed when you create the Okta app integration. It will be replaced in a later step.
{% code title="Placeholder Metadata Xml value" %}
```
PD94bWwgdmVyc2lvbj0iMS4wIj8+DQo8bWQ6RW50aXR5RGVzY3JpcHRvciB4bWxuczptZD0idXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6Mi4wOm1ldGFkYXRhIg0KICAgICAgICAgICAgICAgICAgICAgdmFsaWRVbnRpbD0iMjAyNS0wOC0zMFQxMzo0NToxM1oiDQogICAgICAgICAgICAgICAgICAgICBjYWNoZUR1cmF0aW9uPSJQVDYwNDgwMFMiDQogICAgICAgICAgICAgICAgICAgICBlbnRpdHlJRD0iaHR0cDovL2xvY2FsaG9zdDo4MDgwIj4NCiAgICA8bWQ6U1BTU09EZXNjcmlwdG9yIEF1dGhuUmVxdWVzdHNTaWduZWQ9ImZhbHNlIiBXYW50QXNzZXJ0aW9uc1NpZ25lZD0iZmFsc2UiIHByb3RvY29sU3VwcG9ydEVudW1lcmF0aW9uPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiPg0KICAgICAgICA8bWQ6TmFtZUlERm9ybWF0PnVybjpvYXNpczpuYW1lczp0YzpTQU1MOjEuMTpuYW1laWQtZm9ybWF0OnVuc3BlY2lmaWVkPC9tZDpOYW1lSURGb3JtYXQ+DQogICAgICAgIDxtZDpBc3NlcnRpb25Db25zdW1lclNlcnZpY2UgQmluZGluZz0idXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6Mi4wOmJpbmRpbmdzOkhUVFAtUE9TVCINCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBMb2NhdGlvbj0iaHR0cDovL2xvY2FsaG9zdDo4MDgwL2NvbnN1bWUvZGF0YSINCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBpbmRleD0iMSIgLz4NCiAgICAgICAgDQogICAgPC9tZDpTUFNTT0Rlc2NyaXB0b3I+DQo8L21kOkVudGl0eURlc2NyaXB0b3I+
```
{% endcode %}
{% endstep %}
{% step %}
**Create the IdP**
Select the Create button. Once the page refreshes, there are four URLs displayed. These three URLs will be required in the Okta App Integration steps. The fourth URL is unused.
* ZITADEL Metadata
* ZITADEL ACS Login Form URL
* ZITADEL ACS Intent API
{% endstep %}
{% step %}
**Create New App Integration in Okta**
1. Open your Okta Admin console and navigate to the Applications page and select the *Create App Integration* button:
2. In the sign-in method modal, select SAML 2.0 and select the *Next* button:
3. Name your Fiddler instance per your company guidelines and select the *Next* button:
{% endstep %}
{% step %}
**Configure the Okta App**
1. Enter the *ACS Login Form* URL from the AuthN console into the *Single sign-on URL* text box
1. Ensure the *Use this for Recipient URL and Destination URL* checkbox is selected
2. Enter the *Metadata* URL from the AuthN console into the Audience URI (SP Entity ID) text box
3. Expand the *Advanced Settings* section
4. In the *Other Requestable SSO URLs* section, select the *+ Add Another* button and enter the *ACS Intent API* URL copied from the AuthN console's [identity provider page](#create-the-idp), and enter 0 for the *Index*
5. In the *Attribute Statements* section, add the required attributes setting *Name format* as Basic for all entries:
1. Name=firstName, Value=user.firstName
2. Name=lastName, Value=user.lastName
3. Name=email, Value=user.email
6. Select the *Next* button. No changes are required on this page
7. Select the *Finish* button to complete the creation of the application
8. Copy the *Metadata URL* value on the Sign On page from the SAML 2.0 section
{% endstep %}
{% step %}
**Replace the Placeholder Metadata XML**
1. Please return to the Fiddler AuthN console where we left it in Step 5
2. Delete the placeholder Metadata XML value and leave it blank
3. Paste the Metadata URL copied from Okta in the previous step into the *Metadata URL* text box
{% endstep %}
{% step %}
**Configure Additional Parameters**
1. Expand the *optional* section
2. Ensure the *Automatic create* and *Automatic update* checkboxes are selected
3. Set the *Determines whether an identity will be prompted to be linked to an existing account* dropdown to *Check for existing Username*
{% endstep %}
{% step %}
**Save the Configuration Changes**
Select the *Save* button, and you will be returned to the Settings page for your Organization:
{% endstep %}
{% step %}
**Activate the Okta SAML IdP**
1. Select your IdP from the list for which the Metadata XML field is populated. The contents were dynamically inserted from the Metadata URL.
2. At the top of the page, select the *Activate* button to enable this IdP login.
3. Select *Login Behavior and Security* from the left nav menu and ensure the *External login allowed* checkbox is selected.
{% endstep %}
{% step %}
**Create a Custom Action**
Select the *Actions* tab from the top menu
1. Select the *New* button in the *Scripts* section to create a new action script
2. Copy the *Okta SAML Action Script* below and paste it into the script text area
3. Enter `setAttributesOnOktaSAMLAuth` in the Name text box
4. Select the *Add* button
{% code title="Okta SAML Action Script" %}
```javascript
function setAttributesOnOktaSAMLAuth(ctx, api) {
let firstName = ctx.v1.providerInfo.attributes["firstName"];
let lastName = ctx.v1.providerInfo.attributes["lastName"];
let email = ctx.v1.providerInfo.attributes["email"];
let groups = ctx.v1.providerInfo.attributes["groups"];
let nameParts = [firstName, lastName];
let filteredParts = nameParts.filter(part => part);
let displayName = filteredParts.join(' ');
if (firstName != undefined) {
api.setFirstName(firstName);
}
if (lastName != undefined) {
api.setLastName(lastName);
}
if (email != undefined) {
// Email is returned as an object in SAML response.
// We typecast it to string before normalizing it.
email = String(email).toLowerCase();
api.setEmail(email);
api.setEmailVerified(true);
api.setPreferredUsername(email);
}
if (displayName != undefined) {
api.setDisplayName(displayName);
}
api.v1.user.appendMetadata('fiddler_authentication_type', 'SSO:OKTA:SAML');
if (groups === null || groups === undefined){
groups = []
}
api.v1.user.appendMetadata('fiddler_groups', groups);
}
```
{% endcode %}
{% endstep %}
{% step %}
**Configure the Action Trigger**
Scroll down to the *Flows* section
1. Select the *+ Add trigger* button
2. Select the *Post Authentication* option for the *Trigger Type* dropdown
3. Select the *setAttributesOnOktaSAMLAuth* option for the *Actions* dropdown
4. Select the *Save* button
{% endstep %}
{% step %}
**Validate the Integration**
1. Enter your Fiddler URL. This is [https://example1.dev.fiddler.ai ](https://example1.dev.fiddler.ai/)in our example. Your Fiddler URL will vary according to your company name and the Fiddler deployment type.
2. Ensure you see the Fiddler Sign-on page and that the page displays the *SSO Login - Okta SAML* button:
3. Select the button and confirm that the Fiddler application loads:
{% hint style="info" %}
The first user to sign in to the Fiddler application is automatically assigned the Fiddler Org Admin role: subsequent members are Org Members by default
{% endhint %}
{% hint style="info" %}
Ensure your Okta user account is assigned to the new Okta application created
{% endhint %}
{% endstep %}
{% endstepper %}
### Getting Help
For additional assistance:
* Review the Okta system logs for authentication attempts
* Verify network connectivity between Fiddler and Okta
* Contact your Fiddler representative with specific error messages
## Reference Documentation
For detailed configuration guidance, refer to the official documentation:
* [Okta SAML Configuration Guide](https://zitadel.com/docs/guides/integrate/identity-providers/okta-oidc) - Comprehensive setup instructions
* [General SSO Authentication Guide](https://docs.fiddler.ai/reference/access-control/sso-authentication-guide) - Overview of SSO concepts and troubleshooting
* [Mapping AD Groups to Fiddler Teams](https://docs.fiddler.ai/reference/access-control/mapping-ad-groups-to-fiddler-teams) - Group synchronization details
## Important Notes
* **Automatic User Provisioning**: Users are automatically created on first successful login—no manual invitations required
* **Data Storage**: Fiddler stores only the user's first name, last name, email address, and SAML token from Okta
* **API Access**: For programmatic API access, users must create access tokens from the "Credentials" tab in Fiddler's Settings page
* **Single Authentication Method**: Users can only authenticate via either SSO or email authentication, not both
## Next Steps
After successful integration:
1. **Train Users**: Provide guidance on accessing Fiddler through Okta SSO
2. **Configure Teams**: Set up Fiddler teams to match your organizational structure
3. **Test Group Sync**: Verify automatic group synchronization is working as expected
4. **Monitor Usage**: Review authentication logs and user access patterns
.png?alt=media)
.png?alt=media)
.png?alt=media)
