SAML SSO

Marathon Cloud supports SAML 2.0 single sign-on with any identity provider (IdP) that issues SAML assertions: Okta, Microsoft Entra ID, Google Workspace, OneLogin, and others. SSO is configured per verified email domain. Users whose email is on that domain sign in through your IdP and are provisioned into your team automatically.

Prerequisites

• The Owner role in your Marathon Cloud team. The Domains & SAML page is only shown to owners.
• Admin access to your IdP.
• Access to DNS for the email domain.

Verify your domain

1. Open the user menu in the top-right corner of the console and choose Domains & SAML (/domains).

2. Click Add domain, enter the domain (for example example.com), and click Add domain.

3. The verification page shows the DNS record to create at your registrar:

   Field	Value
   Type	TXT
   Alias or host name	@
   Destination or points to address	MARATHON=<verification code shown on the page>
   TTL	3600

4. After the record propagates, click Verify. If the page reports TXT record not found, wait for propagation and try again. Marathon Cloud also re-checks unverified domains hourly.

Configure SAML

1. From the verified domain, click Open SAML configuration, or use SAML configuration on the domains list.

2. Create the application in your IdP

   The page shows the ACS URL to use in your IdP:

   https://cloud.marathonlabs.io/api/v2/saml/acs?domain=<your domain>

   Use the same URL as the Entity ID / Audience in your IdP. Both SP-initiated and IdP-initiated sign-in are supported.

3. Map attributes

   Configure the assertion to include these attribute names exactly:

   Attribute	Required	Description
   email	Yes	The user’s email. Must be on the verified domain.
   first_name	No	Set on the user’s first sign-in.
   last_name	No	Set on the user’s first sign-in.
   role	No	Team role, applied on every sign-in: owner, editor, or reader. The prefixed forms marathon_owner, marathon_editor, marathon_reader are also accepted. Any other value, or no value, leaves an existing user’s role unchanged and creates new users as reader.

   Microsoft Entra ID’s default claim URIs (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email, .../first_name, .../last_name, .../role) are accepted as fallbacks.

4. Enter IdP details

   Either Upload IdP Metadata (the XML your IdP exports), or fill in the fields manually:

   • SAML SSO URL: your IdP’s sign-in endpoint (HTTP-Redirect binding).
   • Entity ID: your IdP’s issuer.
   • Public certificate: the IdP’s X.509 signing certificate, PEM text.

5. Test and save

   Click Test configuration. A Saml configuration test successful message means the values parse and a service-provider configuration can be built; it does not perform a sign-in. Click Save.

6. Sign in

   On the sign-in page choose Use single sign-on, enter an email on the verified domain, and click Log in. You are redirected to your IdP and back with a Marathon Cloud session.

How users are provisioned

Accounts are created just-in-time on first SSO sign-in with the email, name, and role from the assertion, and added to the team that owns the verified domain. On later sign-ins only role is re-applied; name changes in your IdP are not synced.

Users with a matching domain can still use the SSO page even if they were originally invited with a password.

Removing access

Disable or unassign the user in your IdP. They cannot start a new session afterwards; an existing session lasts until it expires. To revoke immediately, also remove them from the team on the Users page.

Caution

Keep at least one owner who can sign in with email and password, so an IdP outage or misconfiguration cannot lock the team out.

Troubleshooting

SAML_DOMAIN_NOT_CONFIGURED on sign-in

The domain is not verified, or one of SSO URL, Entity ID, or certificate is empty. All four must be present for SSO to activate.

EMAIL_NOT_PROVIDED

The assertion has no email attribute (or Microsoft .../claims/email). Check the attribute mapping in your IdP.

Names or roles are blank

Attribute names are case-sensitive and use underscores: first_name, last_name, role. firstName / givenName style names are not read.

Sign-in loops or signature errors

The certificate saved in Marathon Cloud does not match the one your IdP signs with. Re-paste the current signing certificate; rotate it before the old one expires.