Single sign-on with Okta

Connect Okta to Cargo Marshal over SAML, verify your email domain, and let your team sign in with their Okta accounts.

Single sign-on (SSO) lets people with an email on your company domain sign in to Cargo Marshal through Okta. Their first sign-in adds them to your organization as members, as long as a seat is free.

Connect Okta

Copy the Cargo Marshal values

In Cargo Marshal, open Settings → Single sign-on and keep SAML selected. Copy the ACS URL and the Entity ID.

Create the app in Okta

In the Okta Admin Console, go to Applications → Applications → Create App Integration, choose SAML 2.0, and name the app “Cargo Marshal”. On Configure SAML:

Single sign-on URL: the ACS URL from Cargo Marshal.
Audience URI (SP Entity ID): the Entity ID from Cargo Marshal.
Name ID format: EmailAddress.
Application username: Email.

Okta signs the assertion by default; keep it that way. Cargo Marshal rejects unsigned assertions.

Copy the Okta values

Open the app’s Sign On tab and view the SAML setup instructions. Copy the Identity Provider Single Sign-On URL, the Identity Provider Issuer, and the X.509 Certificate.

Back in Settings → Single sign-on, enter your email domain (for example acme.com), paste the three Okta values into IdP single sign-on URL, IdP entity ID (issuer), and IdP signing certificate, and click Connect.

Verify your domain

Cargo Marshal shows a TXT record. Add it at your DNS provider, then click Verify domain. DNS changes can take a while to appear. Sign-in through SSO starts working once the domain is verified.

In Okta, assign the app to the people or groups who use Cargo Marshal. They sign in at the Cargo Marshal login page with Sign in with SSO and their work email.

Okta also supports OpenID Connect. To use it instead, select OpenID Connect in Cargo Marshal, create an OIDC web app in Okta with the Redirect URI as its sign-in redirect URI, and enter your Okta URL as the issuer with the app’s client ID and client secret.

Require SSO

Once the domain is verified and you have signed in through SSO yourself, you can turn on Require SSO. Everyone on the domain is signed out, except you, and can then only sign in through Okta. If Okta is ever unavailable, see SSO break-glass access.

Provision users with SCIM

With SCIM, Okta adds people to your Cargo Marshal organization when you assign them the app, and takes their access away when you unassign or deactivate them. You need a verified domain first.

Generate a token in Cargo Marshal

In Settings → Single sign-on, find SCIM provisioning. Copy the SCIM base URL and click Generate token. Copy the token right away. Cargo Marshal shows it only once.

Turn on provisioning in Okta

In the Cargo Marshal app in Okta, open the General tab, click Edit under App Settings, select SCIM as the provisioning method, and save. On the new Provisioning tab, under Integration, enter:

SCIM connector base URL: the SCIM base URL from Cargo Marshal.
Unique identifier field for users: userName.
Supported provisioning actions: Push New Users and Push Profile Updates.
Authentication Mode: HTTP Header, with the token as the bearer token.

Click Test Connector Configuration, then save.

Choose what Okta does

Under Provisioning → To App, enable Create Users, Update User Attributes, and Deactivate Users. Okta’s username must be the person’s email on your verified domain.

What each Okta action does in Cargo Marshal:

Assign the app: Okta creates the person as a member of your organization. This needs a free seat. Someone who already joined through SSO is linked, not duplicated.
Unassign the app or deactivate the person: Cargo Marshal deactivates them. They are signed out everywhere, cannot sign in, and their seat is free again. They stay in the member list.
Assign again or reactivate: they can sign in again, if a seat is free.
The organization’s owner: Cargo Marshal refuses to deactivate or remove them, and the IdP reports an error. Transfer ownership in Cargo Marshal first.

While SCIM is on, only people Okta provisioned, and people you invite, join through SSO. To stop provisioning, click Turn off SCIM. Members keep their access. To replace a lost token, click Rotate token and paste the new one into Okta. The old token stops working immediately.

Troubleshooting

“Single sign-on isn’t set up for this email domain”: the domain is not verified yet, or the email is on a different domain.
“Your organization has no free seat”: the plan’s member limit is reached. Free a seat or invite the person, then sign in again. An invited person can always join.
“…an email outside your organization’s verified domain”: Okta sent a different email than the one on your domain. Check Application username and the Name ID format.
“…you haven’t been added yet”: SCIM is on and Okta has not provisioned this person. Assign them the app in Okta.
Okta reports an error when it pushes a user: the plan’s member limit is reached, or the username is not an email on your verified domain.