Single sign-on (SAML)

SSO is included in the Scale plan. Only organization owners can set it up; admins can see its status.

How it works

1. Verify your e-mail domains. You prove that your organization controls a domain (for example example.com) by adding a DNS TXT record. Only addresses at verified domains can use SSO for your organization.
2. Connect your identity provider. You create a SAML application in your IdP with the values below and give NanoFlags its metadata (a URL or an XML file).
3. Request activation. NanoFlags connects your identity provider, usually within one business day, and e-mails you. Until then the SSO page shows Waiting for NanoFlags to activate and everyone signs in as before.
4. Optionally require SSO. Once SSO is active you can require it for every member at a verified domain.

Everything is in Settings → Security → SSO.

Step 1: verify a domain

1. In Settings → Security → SSO, enter your domain and select Add domain. Public mailbox domains such as gmail.com or outlook.com cannot be used.
2. Add the TXT record shown on the page at your DNS provider:

   Type	Name	Value
   TXT	_nanoflags-verification.example.com	nanoflags-domain-verification=<token shown on the page>

3. Select Verify. NanoFlags looks the record up through Cloudflare's DNS-over-HTTPS resolver. DNS changes can take a few minutes to appear; select Verify again if the record is not found yet.

You can remove the TXT record after the domain is verified. A domain can be verified by one NanoFlags organization only. Repeat for every domain your people sign in with (up to 20).

Step 2: connect your identity provider

Create a SAML 2.0 application in your identity provider with these values (they are also shown on the SSO page):

Attributes. NanoFlags needs the user's e-mail address. Send it as an attribute named email, and optionally name (or first_name and last_name). NanoFlags also recognises the common names mail, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress and urn:oid:0.9.2342.19200300.100.1.3.

Then, on the SSO page, paste your IdP's metadata URL, or paste or upload its metadata XML, and select Save metadata.

Okta

1. Admin Console → Applications → Applications → Create App Integration → SAML 2.0 → Next.
2. App name: NanoFlags. Next.
3. SAML Settings:
   • Single sign-on URL: the ACS URL above. Keep Use this for Recipient URL and Destination URL checked.
   • Audience URI (SP Entity ID): the Entity ID above.
   • Name ID format: EmailAddress. Application username: Email.
   • Attribute Statements: email → user.email; name → user.displayName (or first_name → user.firstName, last_name → user.lastName).
4. Finish, then Assignments → assign the people or groups who use NanoFlags.
5. Sign On tab → copy the Metadata URL and paste it on the NanoFlags SSO page.
6. Optional: to show a NanoFlags tile that starts the sign-in, add a Bookmark App with the Start URL above (Okta's IdP-initiated SAML sign-in is not supported; the bookmark starts a normal sign-in).

Microsoft Entra ID (Azure AD)

1. Entra admin center → Identity → Applications → Enterprise applications → New application → Create your own application → name NanoFlags, Integrate any other application you don't find in the gallery (Non-gallery) → Create.
2. Single sign-on → SAML.
3. Basic SAML Configuration → Edit:
   • Identifier (Entity ID): the Entity ID above (remove the default placeholder).
   • Reply URL (Assertion Consumer Service URL): the ACS URL above.
   • Sign on URL (optional): the Start URL above.
4. Attributes & Claims → Edit:
   • Unique User Identifier (Name ID): user.mail (or user.userprincipalname if it is the e-mail address), format Email address.
   • Add a claim email → user.mail (leave the namespace empty).
   • Add a claim name → user.displayname (optional).
5. SAML Certificates → copy the App Federation Metadata Url and paste it on the NanoFlags SSO page.
6. Users and groups → assign the people or groups who use NanoFlags.

Google Workspace

1. Admin console → Apps → Web and mobile apps → Add app → Add custom SAML app.
2. App name: NanoFlags → Continue.
3. Google Identity Provider details → Download Metadata (an XML file). Google does not offer a metadata URL; upload this file on the NanoFlags SSO page. Continue.
4. Service provider details:
   • ACS URL: the ACS URL above.
   • Entity ID: the Entity ID above.
   • Start URL (optional): the Start URL above.
   • Name ID format: EMAIL; Name ID: Basic Information > Primary email.
5. Attribute mapping: Primary email → email; First name → first_name; Last name → last_name. Finish.
6. User access → turn the app ON for everyone (or for the organizational units that use NanoFlags). It can take a few minutes to apply.

Step 3: request activation

When at least one domain is verified and the metadata is saved, select Request activation. NanoFlags connects your identity provider and e-mails you when it is done. If you later change the metadata or the domains, the page asks you to Request update so the change is applied to the connection.

Signing in with SSO

On the sign-in page, choose Sign in with SSO and enter your work e-mail. NanoFlags sends you to your identity provider and back. If SSO is not set up for your domain, the page says so and you can sign in with your password.

• New accounts. The first SSO sign-in creates a NanoFlags account for your SSO identity and adds it to your organization: with the same role as an existing member with the same e-mail address (an owner becomes an admin), or as a viewer. An owner can change roles in Settings → Members. Existing password accounts are not merged with the SSO account.
• Sessions follow your identity provider's sign-in; signing out of NanoFlags does not sign you out of your IdP.

Requiring SSO

With Require single sign-on turned on, members whose e-mail address is at a verified domain must sign in with SSO:

• password sign-in is refused for them, with a message that points to Sign in with SSO;
• their existing password sessions end the next time they open a dashboard page;
• owners keep password sign-in as break-glass access in case your identity provider is unavailable. To turn enforcement on, the owner must have two-step verification set up for their own account.

What enforcement does not cover: API tokens and SDK keys keep working (they are not interactive sign-ins). When someone leaves your company, remove them in your identity provider and revoke any API tokens they created in NanoFlags. Members whose address is not at a verified domain (for example contractors) keep signing in with their password.

If your plan changes to one without SSO, enforcement stops and members sign in with passwords again; your configuration is kept.

Troubleshooting