Identity

An Identity decides who may call a Solution's Flex Gateway, and how they prove it. It might be your company's single sign-on, a customer-facing identity provider, a SAML provider federated through a user pool, or a machine credential such as an API key. It answers "who is this end user?" for the apps and APIs you build, which is separate from how your builders sign in to Studio.

Why it matters#

• Your users sign in the way they already do. Microsoft Entra ID, Okta, Auth0, Amazon Cognito, Google, a SAML provider and many more, with no provider-specific code in the app.
• Machines are first-class callers. API keys, signed requests, Basic credentials and client certificates for partner systems and scripts.
• Access follows your directory. Claims from the sign-in (groups, email domain) can decide who gets in and which documents they see.
• Secrets stay on the server. The browser never holds a client secret: where a provider needs one, the gateway completes the sign-in.

Key concepts#

How it works#

1. Browser. The app reads the gateway's published sign-in settings, or shows its own sign-in page. Except for a Microsoft sign-in, it asks the gateway where the provider's sign-in page is, so a provider that blocks lookups from a browser still works.
2. Provider sign-in. The person signs in on the provider's own page. Microsoft presets use MSAL; every other redirect provider uses the Authorization Code flow with PKCE (a one-time proof that protects the code).
3. Code back. The provider returns a one-time code to the app.
4. Gateway redeems it. The code is exchanged on the server, with a client secret sealed at rest. The token address comes only from the Identity's own settings (its issuer, the provider's fixed address, or one pinned on the Identity), so a crafted request cannot send the exchange anywhere else. GitHub returns no ID token; the gateway asks GitHub who signed in and hands the app that profile.
5. Signed in. The app sees the person, and the gateway adds them to the Identity's Members list, applies any email invitation waiting for them and runs the Identity's On sign-in Flow if it has one. A Microsoft sign-in, which finishes in the browser, is reported to the gateway so the same happens. Their claims drive the rules, their audiences and any Fact Base row policies.

Nine mechanisms#

SAML without SAML code#

SAML works by browser redirects and signed assertions, so there is no token an API can check directly. Flexday AI accepts a customer's SAML provider by federating it through a user pool that does issue tokens: an Amazon Cognito user pool, a Microsoft Entra External ID tenant or another OpenID Connect issuer. You register the SAML provider on the pool, create a SAML (federated) Identity that names the pool, and the app's sign-in is an ordinary redirect to the pool, which sends the person to their SAML provider and back. See the Service Desk Copilot's authentication for a worked example with Cognito.

Provider presets#

Access tags#

A person's access tags decide which documents and files they may see. There are three ways to give them:

• By hand. On the Members tab, an admin grants a tag to anyone who has signed in. Invite by email (or Bulk import) grants a tag to someone who has not signed in yet. It applies at their first sign-in, and only when the provider vouches for that email address.
• On sign-in. The Identity's On sign-in setting names a Flow with a Set access tags step. It runs as the person signs in, before the app's first call, and receives what the sign-in verified: their subject, email, name, groups and other claims. It runs once per person: if that run fails, it runs again at their next sign-in. It never blocks the sign-in.
• For existing members. The For existing members setting names the Flow an admin runs for one person from the Members tab ("Re-evaluate tags for name now"). It receives the same details, from that person's latest sign-in.

Either setting can pick a Flow that is published and switched on, has a Set access tags step for this Identity, has no step that waits for a person and has no webhook trigger. A Flow that can't be picked yet is listed under Not listed? with its reason, and Enable switches one on in place when that is all it needs. A Flow that sets access tags can't be put on a Flex Gateway endpoint, because whoever called it would choose whose access changes.

The Set access tags step takes its tags as a list, a comma- or line-separated text, a JSON array, or the rows of a query that returns one column. Each value is tidied into a tag (Grade 5 becomes grade-5). A value that can't become a tag is skipped and reported in the step's output. A value that resolves to nothing, a query with several columns, or more than 100 tags fail the step instead, so a mistake never wipes anyone's access; [] means "no tags". Its Write mode either replaces the tags this Flow gave the person (an admin's grants stay) or only adds tags. It always targets a signed-in person, never an email address.

Testing an Identity#

The Check a credential card validates a token or key you paste and shows the mapped subject, email and groups with a pass or fail for every rule. Where an Identity opts in, admins can also test as a member, and turning that option off ends every test session on its next request.

Where you work with it#

Identities are listed under Credentials → Identities. An Identity's Configuration tab groups its settings into cards: Provider, Credential (write-only secrets), Token, Browser sign-in, Claim mapping, Authorization rules and Advanced. Its Members tab lists everyone who has signed in with the access tags they hold, and email invitations for people who have not signed in yet; it refreshes itself while you watch. Above the tabs, On sign-in and For existing members each name the Flow that sets access tags.

Works with#

• Flex Gateway: a gateway uses one Identity, or picks one per caller in dynamic mode.
• Flow: a Flow can set a person's access tags, list an Identity's members, verify a domain and add a new sign-in option for it.
• Doc Base and File Store: audiences from claims and tags decide what a person may see.
• Fact Base: the signed-in subject reaches row policies.

Governance and limits#

Related#

• Identity and access
• APIs and integrations
• Glossary: Identity, Issuer, Claim, Claim map, SAML