SynqDocs
Guides

Your own sign-in providers

Add any OpenID Connect issuer or OAuth 2.0 server as a way to sign in at a brand, through your own app there.

Beside Google, Apple, Discord and Synq's other providers, a brand can sign people in through a provider of its own: any OpenID Connect issuer, discovered from its issuer, or any OAuth 2.0 server at endpoints you name. Your company's login, a community's account system, a partner's: each shows on the sign-in page as "Continue with …", links to people's accounts, and is listed for your app's own screens, as Synq's providers are.

Say Acme Guild runs its own identity server at https://id.acme-guild.example and wants its members to sign in to the Acme Guild app with it. It registers an app there, adds the provider to its brand, and puts it on the brand's sign-in page.

Adding one

Your own providers are on Scale and Enterprise (auth.custom_providers): adding one, or replacing its app, on another plan is refused with plan_feature_unavailable, which names the plan that has them. Both need org.connections.edit. Changing a provider's settings, turning it on or off and deleting it never need the plan, so the ones a brand has keep working after a move down. Accounts your app verifies are on every plan.

{
  "id": "custom-acme-guild",
  "type": "oidc",
  "name": "Acme Guild",
  "issuer": "https://id.acme-guild.example",
  "client_id": "acme-guild-synq",
  "client_secret": "…",
  "scopes": ["email", "profile"]
}

For OAuth 2.0, type is oauth2, and endpoints names its three:

{
  "id": "custom-guild-api",
  "type": "oauth2",
  "name": "Guild API",
  "endpoints": {
    "authorization": "https://oauth.acme-guild.example/oauth/authorize",
    "token": "https://oauth.acme-guild.example/oauth/token",
    "userinfo": "https://api.acme-guild.example/v1/me"
  },
  "client_id": "acme-guild-synq",
  "client_secret": "…",
  "claims": { "subject": "data.id", "handle": "data.username", "email": "data.email" }
}
  • Its id is custom- and a slug you pick, and never changes: it is the provider's name in its sign-in URL, in synq_method, and on people's linked accounts. Its kind and issuer never change either: to move to another issuer, add another provider.
  • Its app is yours, at the provider: register the redirect_uri the answer names, the brand's own callback. The client secret is kept sealed and never returned; replace the app with PUT …/custom-sign-in-providers/{provider}/app. token_endpoint_auth_method is client_secret_basic (HTTP Basic, the default) or client_secret_post.
  • Asked first: Synq reads an OpenID Connect issuer's discovery document (provider_discovery_failed where it can't) and tries your app's id and secret at the token endpoint (connection_rejected where the provider refuses them), so nothing the provider refuses is kept.
  • Off until you put it on the sign-in page: shown first or under More ways, with PATCH …/sign-in-page or the brand's Sign-in page in the dashboard. Deleting the brand's last way that's on is refused with no_way_to_sign_in.

Adding a provider, or replacing its app, wants a sign-in from the last 5 minutes for a person (fresh_sign_in_required); an API key never does. Each change is recorded as brand.updated, with the provider's id and each setting under custom_sign_in_provider., never the secret.

Who someone is

claims says where in the provider's answer each thing about the person is: an ID token or user endpoint claim by name, or a dotted path into an object such as data.id.

ClaimOpenID Connect defaultOAuth 2.0 default
subjectsubid
namenamename
handlepreferred_usernamenone
picturepicturenone
emailemailemail
email_verifiedemail_verifiednone

The subject says who someone is, for life: one person at one provider is one identity at the brand, so it must never change or be reused for someone else. An OpenID Connect provider is read from its ID token, with its user endpoint beside it where its discovery names one; an OAuth 2.0 provider from its user endpoint.

Email addresses

Unless you mark the provider's email authoritative, every address it gives is unverified. It never signs anyone in to an account that has that address, never joins one, and a newcomer verifies it before it counts. A provider you don't control could otherwise claim anyone's address.

Turn email_authoritative on only for a provider whose addresses you trust as much as your own: an address it says it proved (email_verified) is then verified, and signs the person in to the brand's user who verified it, as Google's word does for Gmail.

Safety

Synq reaches your provider only from its own server, never from a browser, and only:

  • over https, at addresses on the public internet: never a private, loopback or link-local address, a local name (localhost, .local, .internal), or a name that resolves to one, checked as each connection is made. An address Synq never reaches is refused with provider_url_unsafe, whether you sent it or the provider's discovery document names it;
  • following no redirects, reading a bounded answer, with a timeout.

Every sign-in uses state, PKCE (S256) and, for OpenID Connect, a nonce, and checks the ID token's signature, issuer, audience and expiry, as for Synq's own providers. A fresh sign-in an app asks for (prompt=login, max_age) is asked of an OpenID Connect provider too and checked against its auth_time; an OAuth 2.0 provider can't show one, so it isn't offered for one.

Linking, tokens and claims

Your own providers work as Synq's do:

  • Linking: GET /me/v1/link-methods lists each by its id and name, and POST /me/v1/link-requests adds one as { "method": "custom", "provider": "custom-acme-guild" }. The SDK's accounts.link('custom-acme-guild') sends that for you. A linked account another user has is a conflict the brand's link_conflicts settles, as for any provider.
  • use: link_only makes it a provider people only add to their account (keep provider tokens).
  • Tokens and claims: keep_tokens and kept_claims, as for Synq's providers (keep provider tokens).
  • Icon: upload a square image for provider_icon (brand images) and set the file's url as icon, or use the dashboard's upload.
  • One app's ways: an app that takes every way, the default, takes your own providers too. An app that takes only some (sign_in_methods) names each by its id beside Synq's, such as ["email", "custom-acme-guild"], or in the dashboard ticks it under The brand's own providers on the app's Ways to sign in.

Deleting one

DELETE …/custom-sign-in-providers/{provider} deletes the provider, its app's secret and every account linked there. People keep their accounts and their other ways in; someone whose only way in it was can't sign in until you give them another. It comes off every app's list of ways that names it, each recorded as that app's app.updated. While an app takes no other way, the delete is refused with sign_in_method_in_use, naming the apps in apps, and nothing changes: give each another way, or let it take every way the brand offers, then delete the provider. Its id is free again, and a provider made with it starts with nobody and is on no app's list.

With your agent

Synq's MCP server reads your own providers (get_configuration's custom_sign_in_providers), and changes or deletes one, or puts it on or off the sign-in page (set_sign_in_page), through request_configuration_change: at once, unless you or your org asked to approve every AI agent change (Approving every change). Adding one, or replacing its app, takes its client secret, which an agent never holds: you paste it in the dashboard.

On this page