Skip to content
Avaloi

Single sign-on with SAML

Connect your identity provider, prove your domains, test the connection, and make single sign-on mandatory. Includes provisioning, role mapping, and certificate rotation.

Single sign-on lets your people sign in to Avaloi with your company account. It is for Enterprise accounts only. Only the Owner sets it up, under Company settings, then Single sign-on.

What you need

  • An Enterprise account. See Account types.
  • Your identity provider's metadata URL, or its metadata file, or its entity ID, sign-in URL, and signing certificate.
  • Access to DNS for your email domains, to add one TXT record.

Set it up

  1. Open Single sign-on. Under Details for your identity provider, copy the Entity ID, the ACS URL, and the metadata address, or download the metadata file. Create an Avaloi application in your identity provider with them. The provider must sign the assertion. Use the email address as the NameID, or send it as the email attribute.
  2. Choose Enable. Paste the metadata URL, paste the metadata XML, or enter the entity ID, sign-in URL, and certificate by hand. List the email domains your company owns, separated by commas.
  3. Add the DNS TXT record shown under Domain proof at _avaloi-sso.<your domain>, then choose Verify domain. People on your domains cannot sign in through SSO until this passes, so no company can claim a domain it does not own.
  4. Choose Test connection. It checks the identity provider settings, the certificate dates, the metadata URL (when you gave one), and the domain proof.
  5. Sign in once through Sign in with your company to confirm the whole path.

Sign in

On the sign-in page, a person types their work email. Avaloi finds the company by the email domain and sends them to the identity provider. They can also choose Sign in with your company first. The first sign-in creates their Avaloi account.

Mandatory single sign-on

Turn on Mandatory single sign-on after a passing test and a verified domain. Then people on your domains can sign in only through your identity provider: passwords, Google, and GitHub are closed for them. Two kinds of people keep a password:

  • The Owner. The owner is the break-glass account, so a broken identity provider cannot lock the company out.
  • Exceptions. Addresses on the Exceptions list can still use a password. Add contractors here.

Changing the domain list turns mandatory single sign-on off until the new list is verified.

Just-in-time provisioning

With Create people at sign-in on, anyone your identity provider signs in on one of your domains joins the company with the Default role. Turn it off to keep creation by invitation, and people already in the company can still sign in.

To give roles by group, set the Group attribute your provider sends, such as groups, and fill the Group to role map with lines such as Avaloi Admins = admin. A mapped group sets the role at each sign-in. A person with no mapped group keeps the role they have. The owner role is never given or changed by SSO. Roles you can map are admin, developer, billing, viewer, site_admin, and site_developer.

Sign-in started on the identity provider's page

This is off by default, because a response nobody asked for is easier to abuse. Turn on Sign in from the identity provider only if your provider needs it. With it off, a response that does not answer an Avaloi sign-in request is refused.

Rotate the signing certificate

  1. Under Signing certificates, choose Add certificate and paste the new certificate before your provider switches to it. Avaloi then accepts a response signed by either one.
  2. After the provider switches, choose Remove on the old certificate. A connection always keeps one current certificate.

Test connection warns when a certificate expires within 30 days, and notices when your metadata URL lists a certificate Avaloi does not have yet.

What Avaloi checks on every sign-in

  • The response is signed by a certificate you added. An unsigned response, a changed response, and a response signed by another key are refused.
  • The response is for Avaloi (audience and recipient), answers a request Avaloi made, and is inside its time window with two minutes of clock difference allowed.
  • A response works once. Sending the same one again is refused.
  • Deprecated signature algorithms such as SHA-1 are refused.
  • The email must be on a domain you verified, so your provider cannot create or take over accounts on other domains.

Fix a problem

  • "Invalid SAML response" or a signature error. The certificate in Avaloi does not match the one your provider signs with. Add the current certificate.
  • Audience mismatch. The Entity ID in your provider is not the one on this page.
  • Domain mismatch. The signed-in email is not on a verified domain.
  • Unsolicited response. The sign-in started on your provider's page. Start from Avaloi, or turn on the setting above.
  • A response that expired. Check the clocks on your identity provider's servers.

Quick answers

Is OpenID Connect available? Not yet. Avaloi supports SAML 2.0.

Is SCIM available? No. Avaloi creates people at their first sign-in.

Can Support paste my metadata? No. You paste it in the dashboard.

API

  • GET /v1/companies/me/sso
  • PUT /v1/companies/me/sso
  • PATCH /v1/companies/me/sso
  • DELETE /v1/companies/me/sso
  • GET /v1/companies/me/sso/sp-metadata
  • POST /v1/companies/me/sso/verify-domain
  • POST /v1/companies/me/sso/test
  • POST /v1/companies/me/sso/certificates
  • DELETE /v1/companies/me/sso/certificates/{fingerprint}
  • POST /v1/auth/sso/discover
  • POST /v1/auth/sso/start

Still stuck?

Email [email protected] with your site name and what you tried, or send us a message.