Manage Single Sign-On (SSO)

Use Single Sign-On (SSO) to integrate MAS with your identity provider (IdP). This allows users to authenticate using their existing corporate credentials.

Required attribute

Your IdP must send the user's email address as NameID. This must match the email configured in MAS for that user.

Configure SSO

1. Provide Identity Provider (IdP) metadata to Vitesse

Provide your IdP metadata to Vitesse as a metadata URL (preferred) or an exported XML file.

This metadata must include:

Field	Description
Entity ID	Unique identifier for your IdP
SSO URL	Authentication endpoint
X.509 signing certificate	Used to validate SAML assertions

❗
Only a single signing key is supported. We currently do not support signing key rotation or auto key renewal. Contact Vitesse before certificate expiry to update keys to avoid service interruption.

2. Obtain service provider metadata from Vitesse

After configuring your SSO connection, Vitesse provides the service provider metadata for MAS.

This includes:

Field	Description
Entity ID	Unique identifier for the Vitesse service provider
Assertion Consumer Service (ACS) URL	URL your IdP sends the SAML response to after successful authentication
X.509 signing certificate	Certificate your IdP can use to validate signed requests from Vitesse, where applicable, in PEM format (contact Support if you require a different format)

📘
If your IdP requires the Vitesse Entity ID as the audience value, use the Entity ID provided in the SP metadata.

3. Configure your IdP

Create a new SAML 2.0 application in your IdP and use the SP metadata provided by Vitesse to configure:

Entity ID
📘
Some IdPs require the Vitesse Entity ID to be set as the audience.
Redirect (ACS) URL
X.509 signing certificate
NameId mapping to the user's email address

Recommended settings:

NameID format: urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress
Assertion validity: 5 minutes
Enable signed assertions
Enforce 2FA
Enforce device or corporate access policies

❗
Users must login using the Vitesse login page. Do not launch MAS from an application tile in your IdP.

4. Test the connection

Nominate a test user and share their details with Vitesse.
Ensure the user exists in MAS and has status Active.
Ask the user to start from the Vitesse login page.
Confirm the user is redirected to your IdP.
Confirm the user can sign in successfully and return to MAS.

📘
Use a private or incognito browser session when testing to avoid interference from existing IdP sessions.

5. Enable SSO for users

After testing is complete, ask Vitesse to enable SSO for the required users or account.

Troubleshooting

Check the following if sign-in fails:

The user exists in both MAS and your IdP
The email address in MAS matches the NameID value in the SAML assertion
The Entity ID and ACS URL are configured correctly
The correct X.509 certificate is in use
The SAML assertion includes the required attribute mapping

If the issue persists, contact Support.