Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through creating a Web App in Workspace ONE Access (WSOA) and configuring Omni to authenticate against it via SAML.

​
Configure Workspace ONE Access

This section walks through creating and configuring the Web App inside WSOA.

​
Step 1: Create a new Web App

Log in to the WSOA user interface and navigate to Resources → Web Apps → New. Workspace ONE Access Web Apps page Enter the following values to identify the application, then click Next.
OptionValueDescription
NameOmniA descriptive name for the Web App
DescriptionSidero OmniA description for the Web App
IconImageAn icon to display on the dashboard
Web App definition settings

​
Step 2: Configure Single Sign-On

On the Single Sign-On page, configure the authentication type and endpoint URLs. The SSO URL and Recipient URL both point to Omni’s Assertion Consumer Service endpoint, and the Application ID points to its SAML metadata URL.
OptionValueDescription
Authentication TypeSAML 2.0The authentication protocol to use
ConfigurationManualManually specify all fields
Single Sign-On URLhttps://{omni-host}/saml/acsOmni’s Assertion Consumer Service URL
Recipient URLhttps://{omni-host}/saml/acsMust match the Single Sign-On URL
Application IDhttps://{omni-host}/saml/metadataOmni’s SAML metadata URL
Username formatUnspecifiedNo specific username format required
Username value${user.userName}The username to include in the SAML assertion
Relay State URLBlankLeave this empty
Single Sign-On authentication type settings

​
Step 3: Configure advanced signing properties

Still on the Single Sign-On page, scroll to the Advanced Properties section and set the following toggles. The key settings here are enabling assertion signing (required by Omni) while leaving response signing and assertion encryption off.
OptionValueDescription
Sign ResponseFalseDo not sign the full SAML response
Sign AssertionTrueSign the SAML assertion (required)
Encrypt AssertionFalseDo not encrypt the assertion
Include Assertion SignatureFalseDo not embed the signature separately
Device SSO ResponseFalseDisable Device SSO
Enable Force Authn RequestFalseDo not force re-authentication
Signature AlgorithmSHA-256 with RSAAlgorithm used to sign the assertion
Digest AlgorithmSHA-256Algorithm used to compute the digest
Assertion Lifetime200How long (in seconds) the assertion is valid
Advanced signing properties

​
Step 4: Map custom attributes

At the bottom of the Single Sign-On page, add the following entries in the Custom Attribute Mapping section. These attributes allow Omni to identify users and apply group-based role assignments.
NameFormatNamespaceValueDescription
emailUnspecified${user.email}The user’s email address
firstNameUnspecified${user.firstName}The user’s first name
lastNameUnspecified${user.lastName}The user’s last name
groupsUnspecified${groupNames}The user’s group memberships
Custom attribute mapping configuration

​
Step 5: Select an access policy

Click Next and select the access policy required by your organization. Access policy selection

​
Step 6: Assign users and groups

Click Save & Assign and configure who is permitted to log in to Omni.
  • Select the permitted group from your Active Directory or LDAP server.
  • Set Deployment Type to Automatic.
Save and assign screen Application assignment configuration

​
Step 7: Obtain the IdP metadata URL

Navigate to Settings and click Copy URL to copy the IdP metadata URL. Settings page showing Copy URL link
Copy this URL — you will pass it to Omni as the --auth-saml-url flag in the next step.
SAML metadata download settings

​
Configure Omni to use Workspace ONE Access

Pass the following flags to the Omni container at startup to enable SAML authentication. Alternatively, you can set these values in the Omni configuration file instead of passing them as CLI flags.
FlagDescription
--auth-saml-enabledEnables SAML authentication
--auth-saml-urlThe IdP metadata URL copied in Step 7
--auth-saml-label-rules='{"groups": "groups"}'Extracts the groups attribute from the SAML assertion and maps it to the label saml.omni.sidero.dev/groups/<value>
For example: 
--auth-saml-enabled=true
--auth-saml-url=https://{workspace-one-host}/SAAS/API/1.0/GET/metadata/idp.xml
--auth-saml-label-rules='{"groups": "groups"}'
Once Omni is running with these flags, refer to the Auto-assign roles to SAML users guide to automatically assign roles based on SAML group attributes. When using groups, the label prefix is saml.omni.sidero.dev/groups/ rather than a role name directly. For example: 
metadata:
  namespace: default
  type: SAMLLabelRules.omni.sidero.dev
  id: assign-admin-to-platform-admins-label
spec:
  assignroleonregistration: Operator
  matchlabels:
    - saml.omni.sidero.dev/groups/omni-platform-administrators