Social and enterprise sign-in

Authio acts as a broker. To your app, a sign-in through Google or a company directory is an ordinary Authio sign-in: the same authorization request, the same code, tokens issued by the realm for a local account. Behind the scenes Authio sends the person to the provider, validates what comes back and decides which account of the realm it belongs to.

You register a provider once per realm, then choose which clients show it on their sign-in screen and in what order. Your app needs no change to gain a new way in.

Supported providers

Google, Microsoft Entra ID, GitHub and Apple are presets: their endpoints, scopes and claim names are already known. The generic OpenID Connect type reads its endpoints from the authority, the base address where the provider publishes its discovery document, so it fits Okta, Auth0, Keycloak, another Authio realm or any compliant directory.

Add a provider

1. 1

   Register the provider in Authio

   Open Identity Providers and choose Create. Pick the realm and the type, then give it the button label people will see. The alias is derived from the name and becomes part of the callback address; neither the alias nor the type can change after the provider is registered.

2. 2

   Register Authio at the provider

   In the provider’s own console, create an OAuth or OIDC application and register the callback address. The provider’s view in Authio shows it, ready to copy:

   Callback addressPlain text

   https://authio.api.hyperio.tech/realms/acme/broker/google/callback

3. 3

   Fill in the credentials and the linking mode

   Paste the client ID and secret the provider issued (for Apple, the Team ID, Key ID and private key). For Microsoft Entra ID and generic OpenID Connect, enter the authority. Then choose how accounts are linked.

   The secret is written once and never shown again. Authorities and endpoints that point to a private network — a non-public IP, localhost, .local or .internal names — are refused when you save.

4. 4

   Offer it on a client

   Registering a provider makes it available to the realm; offering it makes it visible. In Clients, open the client, choose Edit and go to Sign-in options: offer the providers you want and put them in order. The list is saved as a whole.

5. 5

   Try it

   Start a sign-in from your app. Under the sign-in button, the hosted login now shows Continue with Google, or whatever label you chose.

When an authorization request names an organization, the sign-in shows that organization’s providers, in its order, instead of the client’s.

Account linking and new accounts

The first time someone arrives through a provider, Authio has to decide whose account they land in. An identity already linked to an account is always honoured first — even if the e-mail changed at the provider. For an identity it has never seen, the provider’s Account linking mode decides:

Accounts created on first sign-in

• The account is created without a password and linked to the client the person came through. The user_created webhook is published.
• It counts toward the user quota of the plan that owns the realm. With no room left, the sign-in is refused with a message the person understands.
• The username is the provider’s username, or else the e-mail, or else the provider alias and the subject joined by an underscore.
• The e-mail is marked confirmed only when the provider is trusted and stated the address was verified.

After the provider

Coming back from the provider is not the end of the sign-in. Authio treats it like any other first factor:

• It counts as one factor, whatever the provider did, and is recorded as fed in amr; the provider’s alias goes in the idp claim. The client’s second-factor steps still apply: Google plus a push approval gives acr 2.
• The same refusals as a password sign-in apply: suspended or inactive account, no access to the client, sign-in address not approved.
• If the client offers passkeys and the account has none, the registration step is offered.
• The provider’s own errors become a fixed message on the hosted login, in the client’s branding and language; a person who declines at the provider is treated as a choice, not a failure.

What your app asked for travels on to the provider as far as each one understands it:

Roles from provider claims

A provider can grant roles. On the provider’s Access tab, add rules that turn a claim the provider sends — groups containing finance, a department, a tenant — into a role of the realm. The rules run on every federated sign-in.

A claim that arrives and does not match always withdraws the role. Rules only touch roles granted by the same provider’s rules: roles given by hand or through a group are never removed. Before saving, the preview shows what a rule would grant or withdraw, replaying a person’s last real sign-in or claims you type in.

How the broker protects the sign-in

• PKCE with S256 on every provider, confidential ones included, an opaque state used once and valid for 15 minutes, and a nonce checked in the ID token.
• The provider’s ID token is validated in full: signature against the published keys, issuer, audience and lifetime.
• Only providers offered on the client can be used from its sign-in, and only while active.
• Calls to the provider, including its discovery document and keys, go only to public addresses and never follow redirects.
• Your app never receives the provider’s tokens, only an ordinary Authio code.

Hiding and removing a provider

Hiding a provider from Identity Providers sets it inactive: its button disappears from every sign-in screen and the broker refuses sign-ins through it. Showing it again is immediate.

Removing a provider keeps the accounts that came through it, but they lose this way in. People without a password need another way to sign in, such as a password reset or a passkey.

Next steps