Single sign-on (SAML) setup guide

Let your team sign in to Formaya through the identity provider your organisation already uses. Setup is an exchange of a few values between Formaya and your provider, then one DNS record to prove you own the email domain.

How it works

Single sign-on is available on the Business plan and is configured by a workspace owner or admin under Settings → Members → Single sign-on (SAML). The card has three parts, and the setup follows them in order:

1. Your service provider details. Three values Formaya gives you: an entity ID, an ACS URL and a metadata URL. These go into your identity provider when you add Formaya as an application. They are specific to your workspace, so a staging workspace and a production workspace need two separate applications on the provider side.
2. Identity provider. Three values your provider gives you: its entity ID (also called issuer), its sign-in URL and its signing certificate. If the provider shows a metadata URL, paste that into Import from metadata URL and press Import: the three fields fill themselves. Otherwise paste the three by hand. Only the workspace owner can change these; changing them switches sign-in off until the domain below is verified again, so a new provider is always approved by whoever controls the domain.
3. Email domain. The domain of your work addresses, for example acme.com. Formaya shows a TXT record; add it to the domain's DNS and press Verify domain. Only addresses on this domain can sign in through the provider, and a domain can be verified by one workspace at a time.

Then turn the Single sign-on is on switch on, save, and use Test sign-in. Members sign in from the Formaya login page by typing their work email and pressing Continue with SSO. Nobody needs an invitation: an address on the verified domain that the provider vouches for is created as a member on first sign-in, or matched to its existing account.

Field map

Every provider asks for the same two things and hands back the same three, under its own names. Use these two tables to copy in the right direction.

From Formaya into your provider

From your provider into Formaya

The certificate field accepts the PEM text with its BEGIN and END lines, or just the base64 body between them.

Okta

1. In the Admin Console open Applications → Applications and press Create App Integration. Choose SAML 2.0, Next. If your org shows a Create your app wizard with integration cards instead, pick Classic experience; the card wizard is for publishing to Okta's catalog.
2. General Settings: name it, for example Formaya. Next.
3. Configure SAML, section A:
   • Single sign-on URL ← Formaya's ACS URL. Leave Use this for Recipient URL and Destination URL ticked.
   • Audience URI (SP Entity ID) ← Formaya's Entity ID.
   • Default RelayState: empty.
   • Name ID format: EmailAddress. Application username: Email.
   • Leave Show Advanced Settings as it is: response and assertion signed, RSA-SHA256, unencrypted, Signed Requests off.
4. Next, then on the Feedback step choose I'm an Okta customer adding an internal app and press Finish.
5. On the app's Sign On tab, under Metadata details, press More details. Copy Issuer → Formaya IdP entity ID, Sign on URL → Formaya Sign-in URL, and download the Signing Certificate → Formaya certificate field. View SAML setup instructions shows the same three.
6. Still on the Sign On tab, under Attribute statements, press Add expression three times: name email with expression user.profile.email, givenName with user.profile.firstName, sn with user.profile.lastName. Older consoles show these as Attribute Statements inside the wizard with user.email style values.
7. Assignments tab: assign the app to the people or groups who may sign in. Okta refuses anyone not assigned.

Microsoft Entra ID

1. In the Microsoft Entra admin center go to Entra ID → Enterprise apps → New application, press Create your own application, name it, choose Integrate any other application you don't find in the gallery (Non-gallery) and press Create. You need the Cloud Application Administrator or Application Administrator role.
2. In the app, open Single sign-on and select SAML.
3. Basic SAML Configuration, Edit:
   • Identifier (Entity ID) ← Formaya's Entity ID.
   • Reply URL (Assertion Consumer Service URL) ← Formaya's ACS URL.
   • Sign on URL, Relay State, Logout Url: leave empty. Save.
4. Attributes & Claims, Edit. Open Unique User Identifier (Name ID), set the source attribute to user.mail and Choose name identifier format to Email address. The default additional claims already include emailaddress, givenname and surname, which is all Formaya reads.
5. SAML Certificates: next to Certificate (Base64) press Download → Formaya certificate field.
6. In the Set up <your app> section copy Login URL → Formaya Sign-in URL and Microsoft Entra Identifier → Formaya IdP entity ID.
7. Users and groups: add the users or groups who may sign in. With Assignment required set to Yes, which is the default for enterprise apps, nobody else can.

Google Workspace

1. In the Admin console, as a super administrator, go to Apps → Web and mobile apps, press Add app → Add custom SAML app, name it, Continue.
2. On Google Identity Provider details: copy SSO URL → Formaya Sign-in URL, Entity ID → Formaya IdP entity ID, and download the Certificate → Formaya certificate field. Continue.
3. On Service provider details:
   • ACS URL ← Formaya's ACS URL.
   • Entity ID ← Formaya's Entity ID.
   • Start URL: empty. Signed response: leave unticked; Google signs the assertion either way.
   • Name ID format: EMAIL. Name ID: Basic Information → Primary email. Continue.
4. Attribute mapping (optional, gives new accounts their real name): add First name → givenName and Last name → sn. Finish.
5. Open the app, press User access, choose ON for everyone or turn it on per organisational unit, Save. Google says changes can take up to 24 hours, in practice usually minutes.

JumpCloud

1. In the Admin Portal go to SSO Applications, press + Add New Application, choose Custom Application, Next, select Manage Single Sign-On (SSO) with Configure SSO with SAML, Next, and give it a display label.
2. On the SSO tab, either press Upload Metadata and give it the file from Formaya's Metadata URL, or fill in by hand:
   • SP Entity ID ← Formaya's Entity ID.
   • ACS URL ← Formaya's ACS URL.
   • SAMLSubject NameID: email. SAMLSubject NameID Format: emailAddress.
   • Signature Algorithm: RSA-SHA256. Sign Assertion: ticked. Login URL: https://formaya.app/login.
   • IdP Entity ID: any identifier you choose, for example formaya-jumpcloud. Copy the same value → Formaya IdP entity ID.
   • Under Advanced Settings, IDP URL defaults to https://sso.jumpcloud.com/saml2/<name> and cannot be changed after activation. Copy it → Formaya Sign-in URL.
3. Under Attributes, add a user attribute mapping email → email, and optionally givenName → firstname and sn → lastname.
4. Activate the application. Download the IDP Certificate (or press Export Metadata and take the certificate from it) → Formaya certificate field.
5. On the User Groups tab, bind the groups who may sign in.

OneLogin

1. In the admin portal go to Applications → Applications → Add App, search for SAML Custom Connector (Advanced), give it a display name, Save.
2. Configuration tab:
   • Audience (EntityID) ← Formaya's Entity ID.
   • Recipient and ACS (Consumer) URL ← Formaya's ACS URL.
   • ACS (Consumer) URL Validator: the ACS URL as a regular expression, for example ^https:\/\/formaya\.app\/api\/sso\/saml\/.*\/acs$.
   • SAML nameID format: Email. SAML initiator: Service Provider. SAML signature element: Assertion, or Both. Save.
3. Parameters tab: set NameID value to Email. Add parameters email → Email, givenName → First Name, sn → Last Name, each with Include in SAML assertion ticked. Save.
4. SSO tab: copy Issuer URL → Formaya IdP entity ID, SAML 2.0 Endpoint (HTTP) → Formaya Sign-in URL, and under X.509 Certificate press View Details and download the certificate → Formaya certificate field.
5. Give access through Users or Roles.

Other SAML 2.0 providers

Keycloak, Authentik, Auth0, PingOne, Duo, Rippling, Cisco Duo and the rest all work; the vocabulary is what differs. Look for these on the provider side:

• The service provider, relying party or client is Formaya. Its entity ID, audience, client ID or issuer of the request is Formaya's Entity ID. Its ACS, reply, callback, redirect or assertion consumer URL is Formaya's ACS URL. Many providers can import all of this from Formaya's Metadata URL.
• The provider's own entity ID or issuer goes into Formaya's IdP entity ID; its SSO, login or single sign-on service URL for the HTTP-Redirect binding goes into the Sign-in URL; its signing (not encryption) certificate goes into the certificate field.
• Set the Name ID format to email address, or send an email attribute. Sign the assertion. Leave assertion encryption off; Formaya has no decryption key.
• Formaya starts every sign-in itself (SP-initiated) and signs its requests. A sign-in started from the provider's own portal is refused, so if your provider offers a "sign request" verification option you can switch it on using the certificate in Formaya's metadata.

Attributes Formaya reads

Without a name attribute a new account is named after the part of the address before the @. An existing account keeps the name and language it already has.

Domain verification

Save the email domain on the card and it shows a TXT record of the form formaya-sso=…. Add it in your DNS provider either on the domain itself (name @) or on the subdomain _formaya, then press Verify domain. Propagation is usually under a minute; Formaya checks the record again whenever the identity provider details change.

A domain can be verified by one workspace at a time. Subdomains are separate domains: acme.com does not cover mail.acme.com.

Troubleshooting

Still stuck? Write to us through the contact page with the name of your provider and the exact message shown.