Social and custom providers
A provider is another service that vouches for the user: SeekAuth sends the browser there, the provider sends it back to SeekAuth’s callback, and SeekAuth logs the user in to its own account for them. Your app only ever sees SeekAuth’s tokens. Providers always go through a redirect, from the embedded login too.
Built-in providers
Section titled “Built-in providers”| Id | Protocol | Trusted for email | Notes |
|---|---|---|---|
google |
OpenID Connect | Yes | The account chooser is shown at every login. |
apple |
OpenID Connect | Yes | Needs your team id, key id and the .p8 key Apple gives out. Apple returns by form post. |
github |
OAuth 2 | No | The primary address is read from GitHub’s list of the user’s emails. The account chooser is shown at every login. |
discord |
OAuth 2 | No | |
x |
OAuth 2 | No | X gives no email address. |
microsoft |
OAuth 2 | No | The account chooser is shown at every login. |
The account chooser is asked for so that someone who logged out to come back as somebody else is not signed straight back in to the account they left.
Credentials
Section titled “Credentials”- Development environments can use the platform’s shared credentials for the six built-in providers: switch the provider on and try it at once.
- Production environments need your own. Register an app at the provider, then enter its client id and secret on the Login methods page, or with the management API (admin role):
PUT /v1/environments/{environment_id}/providers/googleContent-Type: application/json
{ "client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..." }For Apple, client_secret is the text of the .p8 key, with team_id and key_id beside it; SeekAuth signs Apple’s client secret itself for each request. The secret is never shown again; to change other fields, send them without it.
The callback URL
Section titled “The callback URL”Register this address as the redirect URI at the provider. It is the environment’s issuer followed by /callback/ and the provider’s id:
https://your-app.auth.dev.seek.services/callback/googleThe answer of PUT …/providers/:provider, and GET /v1/environments/:id/providers, give it as callback_url. If the environment moves to a custom domain, the callback URL changes with it: register the new one at the provider.
Then turn the provider on in Login methods (or add its id to the environment’s login methods).
Accounts and email addresses
Section titled “Accounts and email addresses”When a provider sends someone back, SeekAuth decides whose account it is:
- Someone already logged in with this provider account. That user is logged in.
- The provider vouches for an address somebody has. When the provider says the address is verified and the provider is trusted for email (Google and Apple, or a custom provider an admin marked as trusted), the provider’s account is linked to that user and logs them in.
- The provider gives an address it does not vouch for, or is not trusted to, and the environment has email codes on. The login goes on with that address, at the step a person who typed it would be at: SeekAuth mails a code to it (or takes the account’s password, where passwords are on). The code logs in to the account that has the address, or makes one if sign-up is open, and the provider is linked to that account: the next time, it logs in with no code. As with a provider linked from account settings, the account’s address is told by email, and an account that already has a login with that provider gets no second one (the login completes without the link).
- Anything else (the provider gives no address, or the environment does not have email codes on). A new account is made, if sign-up is open. It takes the provider’s address only when the address is verified and the provider is trusted; otherwise the account has no address. An app that needs one asks for it before the login completes (see Sign-ups and access).
An address from a provider that is not trusted for email, or one the provider does not call verified, is never compared with the accounts there are before its code is answered: it is whatever was typed at the provider, and an answer that depended on it would tell anybody whether that address has an account. The step it goes on to, and every answer there, is the same whoever has the address. Somebody who already has an account with that address and comes in through such a provider answers the code and is in their own account, with the provider linked to it.
The environment’s address rules apply to a provider’s address too: with tags or throwaway domains refused, such an address cannot make an account.
A login through any provider has amr ["social"]. No captcha can be shown after a redirect, so sign-ups through a provider are never asked for one.
Custom providers
Section titled “Custom providers”On the Pro and Scale plans, an environment can add up to 10 providers of its own: an identity provider your company runs, a partner’s login, any service that speaks OpenID Connect or OAuth 2. Each one is a login method of its own, with a button labelled as you say.
PUT /v1/environments/{environment_id}/providers/custom-acmeContent-Type: application/json
{ "label": "Acme SSO", "kind": "oidc", "issuer": "https://login.acme.example", "client_id": "acme-client", "client_secret": "...", "scopes": ["email", "profile"]}| Field | Meaning |
|---|---|
| id (in the path) | custom- and then 2 to 32 lowercase letters, digits or hyphens, not starting or ending with a hyphen. Not one that reads as one of SeekAuth’s own products (custom-seek, custom-linkpay-login): 400 name_not_allowed. |
label |
The button’s text (“Continue with …”), 1 to 40 characters, read as names are: Seek, LinkPay or a look-alike of them is 400 name_not_allowed. |
kind |
oidc (endpoints from the issuer’s discovery document) or oauth2 (endpoints given here). It cannot change later: remove the provider and add it again. |
issuer |
For oidc. |
authorization_endpoint, token_endpoint, userinfo_endpoint |
For oauth2. |
client_id, client_secret |
Your app at the provider. The secret may be left out of an update, unless the issuer or token endpoint changes. |
scopes |
Up to 20 scopes to ask for. |
claims |
For oauth2: which userinfo fields hold sub, email, email_verified, name and picture. |
token_auth |
How SeekAuth authenticates at the token endpoint: basic (the default) or post. |
email_trusted |
Whether the provider’s verified addresses link to existing accounts and are given to new ones. Default false. |
- Every endpoint must be an
httpsaddress with a public host name, on port 443 or 8443, and SeekAuth connects only to public addresses. email_trustedis set by each save: an update that leaves it out turns it off. Send it every time for a provider you trust.- A new custom provider is off until you turn it on in Login methods.
- On the Free plan, adding one answers
402 plan_limit; an 11th answers409. - When a login asks for the person again (
prompt=login,max_age=0, or a step-up of a session that is not fresh enough), SeekAuth sends the providerprompt=loginandmax_age=0. A provider that follows them asks the person to sign in there again. SeekAuth does not check that it did: a provider that answers from its own session without asking (an OAuth 2 provider, which has no such parameters, or an OpenID provider that ignores them) still counts as a fresh login, for the account settings that need one too.
See Environments for the full reference, including DELETE …/providers/:provider.
Linking a provider from account settings
Section titled “Linking a provider from account settings”A signed-in user can add a provider login to their own account, so that it logs in to the account they already have. auth-react’s <LinkedAccounts /> does the whole round trip: it sends the user to the provider, shows SeekAuth’s confirmation page on the way back (“Add this GitHub login?”), and finishes the link when your page comes back with #link_code=…. It needs a login from the last ten minutes, and the page it returns to must be an allowed origin of the client. See Account settings and linking a provider in the account API.