Table of Contents
Security Assertion Markup Language (SAML) is an open standard for exchanging authorization data. SAML enables convenient Single Sign-On access to multiple applications through one authentication. Fleetio offers SAML-based Single Sign-On for several providers. This article demonstrates the setup steps using Okta.
Once enabled, users may log in via either SSO or the standard Fleetio credentials (username or email address and password). BOTH methods will be available.
PERMISSIONS: Only Account Owners and Administrators with the Manage SAML Connectors permission can manage Single Sign-On. See User Management Overview for more information.
Prepare for Setup
If you're on the Fleetio Professional or Premium plans, SAML is automatically enabled for your account.
- Navigate to your Account Menu > Settings > SAML Connectors to get started.
If you're on the Essential plan, SAML is available as an add-on feature.
- Contact sales@fleetio.com for details.
Okta Setup
- Log in to your Okta Administrator Account and click the Admin button (Do NOT click Add Apps).
- Click the Applications tab (a), then Add Application (b):
- Click the Create New App button:
- Set the Platform to Web (a), and Sign on method to SAML 2.0 (b), then click Create.
- For the App name, enter Fleetio, then click Next.
- On the SAML Settings screen, UN-check the box "Use this for Recipient URL and Destination URL" and enter the following values:
| Field Name | Value |
|---|---|
| Single sign on URL |
https://secure.fleetio.com/users/sign_in NOTE: this is a placeholder which you will update later in the process |
| Recipient URL | https://secure.fleetio.com/users/saml/auth |
| Destination URL | https://secure.fleetio.com/users/saml/auth |
| Audience URI (SP Entity ID) | https://secure.fleetio.com/users/saml/metadata |
| Default RelayState | BLANK |
| Name ID format | EmailAddress |
| Application Username | Okta username |
| Update application username on | Create and update |
NOTE: Name ID format must be EmailAddress; an email address is required here, it cannot be a username.
- OPTIONAL: Attribute Statements are used to create new Fleetio users dynamically, via the Okta sign-on, if an existing user is not found. Add 3 Attribute Statements as follows:
| Name | Name Format | Value |
|---|---|---|
| Unspecified | user.email | |
| first_name | Unspecified | user.firstName |
| last_name | Unspecified | user.lastName |
Additional Accepted Attributes:
| Attribute Name | Usage | Description |
|---|---|---|
| first_name | Create/Update | Contact first name |
| last_name | Create/Update | Contact last name |
| group | Create | Contact's group. If a hierarchy, use a pipe (|) to separate the groups. For example: Parent|Child |
| employee_number | Create/Update | Contact employee number |
| username | Create/Update | Custom username |
| classifications | Create/Update | Contact classifications, comma separated. Possible values include; employee,technician,vehicle_operator |
- Click Next.
- Select the option "I'm an Okta customer adding an internal app" and click Finish.
- Fleetio supports dynamic configuration, so you will simply click Identity Provider Metadata to view an XML file containing your metadata. Download and save this file for the Fleetio Setup process in the next section.
- Click the Assignments tab (a), then the Assign drop-down button (b), and select Assign to People (c).
- Click Assign (a) for each (edit to apply the Fleetio User Name (b) if necessary), then click Done (c).
Fleetio Setup
- Open a new browser tab, log into Fleetio, go to your Account Menu, and select Settings.
- In the Settings sidebar, click SAML Connectors in the Integrations section.
- Click the + Add SAML Connector button.
- On the SAML Configuration page, click the Pick File button and browse to the XML metadata file you created in Okta Setup Step 10 above.
- If you wish to create new Fleetio users dynamically, select Create New Users and select the type of user (Regular or Administrator) then, select the Role from the drop-down. Completing the Users and Roles section will apply the Attributes you configured in Step 7 above.
IMPORTANT: The SAML Connector allows one User Type/Role to be designated for user creation; it is not currently possible to assign different Fleetio User Type/Role based on Okta group. Users may be created via SAML and can be deprovisioned through SCIM, however, you must contact Fleetio to have deprovisioning through SCIM enabled.
- Click the Save SAML Connector button and confirm success on the bottom right of the screen.
Finalize Connector Setup
The last step in the process is to apply the SSO URL from Fleetio to your Okta account. This value contains an ID which does not exist until you complete the Fleetio portion of the setup procedure.
- After completing the Fleetio setup above, return to Account Settings > SAML Connectors, and click the Copy to Clipboard button.
- Navigate back to your open browser tab for your Okta account, click the General tab (a), scroll down to the SAML Settings section, and click the corresponding Edit button (b):
- Click the Next button to advance to Configure SAML > SAML Settings, then paste your copied value in the Single Sign On URL field.
- Scroll down to click Next, and then Finish.
- Navigate to My Applications in Okta, and click Fleetio.
NOTE: A domain is required for SAML/SSO configuration. To request that a domain be added to your SAML connector, contact help@fleetio.com. Requests must come from the Fleetio Account Owner or Administrator.
Single Sign-On Enforcement
Once setup is complete, you can now enable Single Sign-On Enforcement which requires all users to sign in using SSO.
IMPORTANT: Ensure the SAML Single Sign-On process is working correctly prior to enabling this option.
To enable SSO Enforcement:
- Go to your Account Menu and select Settings.
- In the Settings sidebar, click Security in the User Access section.
- Check the box to Enforce SAML Single Sign-On (SSO). Do not check this box if you want users to have the option to sign in with either their Fleetio credentials or SSO.
- (Optional) To exclude specific Email addresses or Domains from SSO enforcement, enter them in the Email addresses excluded from SSO enforcement or Domains excluded from SSO enforcement fields.
NOTE: Enforce SAML Single Sign-On applies to all users EXCEPT for the Account Owner and any Email addresses or Domains listed in their respective fields.
- Scroll to the bottom of the page and click the Save Security Settings button to save your changes.
NOTE: Once this option is enabled, the change will take effect on the user's next login.
