Consumer and social providers

iya-sts can sign people in through consumer and social identity providers: Google, Apple, Microsoft personal accounts, GitHub, Discord and the others listed below (#565). This page covers:

• what is supported, and how far each provider has been tested;
• how to turn the feature on and add a provider;
• what to register at each provider;
• who a person becomes when they sign in;
• how people connect a provider to an account they already have;
• how risk scoring and the issuance policy treat these sign-ins;
• the security properties, the limits, and what to check when something fails.

At a glance

• Applications need nothing new. An application keeps using its iya-sts integration: OpenID Connect, OAuth 2.0, SAML or WS-Federation. It is issued iya-sts’s own tokens and assertions whichever provider the person used. No provider library or provider credential goes into an application.
• Each provider is a federation relationship of its own category, consumer. It is created from a built-in profile for that provider and lives beside the enterprise partners in the same realm. It works wherever an enterprise partner does: the sign-in screen, an application’s own list of partners (appFederationRelationship), and a broker relationship.
• The category is off by default. A realm turns it on with federation.consumerProviders.
• A newcomer gets an account of their own. An email address is never used to match an existing person. People with an account already connect a provider to it themselves, from the portal.
• Provider tokens are not kept. iya-sts reads the person’s profile at sign-in, then discards the provider’s access token. It asks for no refresh token.

Supported providers

16 provider profiles, plus 2 generic profiles for a provider outside the catalogue. None has yet been run against its live provider. Doing so needs an application registered at each provider, with its credentials.

The Tested column says how each profile is exercised by tests/federation_consumer_providers.js and tests/protocol/sts_federation_consumer.js:

• Sign-in means a full sign-in through a server that behaves the way the provider documents: the authorization request, the token request with the provider’s client authentication, the profile calls, and the entry created.
• Profile only means the profile exists and is checked when a relationship is created, with no sign-in driven through it.

Not supported:

• Netflix publishes no interface for signing a person in to a third party.
• Sentry’s OAuth exists to authorize an integration’s API calls. Whether it can sign a person in has not been established.

The feasibility record at the end of this page has what each provider’s own documentation says.

How it works

1. The person chooses Continue with <provider> on the sign-in screen, or an application’s own list of partners sends them straight there.
2. iya-sts sends the browser to the provider’s authorization endpoint, with state, a nonce for OpenID Connect, and PKCE. PKCE is always sent.
3. The provider sends the browser back to the relationship’s assertion consumer service, /federation/acs/<id>. iya-sts redeems the code at the provider’s token endpoint, using the provider’s own client authentication.
4. iya-sts establishes who the person is:
   • OpenID Connect providers: the ID Token is verified against the provider’s keys. That covers the signature, the issuer, the audience, the expiry and the nonce. The person is the token’s sub.
   • OAuth 2.0 providers: iya-sts calls the profile endpoint the profile names, and a second endpoint where the provider keeps the address elsewhere (GitHub’s /user/emails). The person is the identifier the profile names.
5. The provider’s answer is read through its profile. The profile says where the identifier, the address, its verification and the person’s other details come from. The result goes through the relationship’s attribute mapping into the person’s directory entry.
6. The sign-in is assessed by risk scoring and decided by the issuance policy. A session starts. The application is answered with iya-sts’s own tokens or assertion, and the session’s amr begins federated.

Turning it on

The realm setting federation.consumerProviders is off by default. While it is off:

• a consumer provider cannot be added to the realm or enabled;
• a sign-in through one is refused at every door, including a relationship written directly into the directory (STS-FED-0171, STS-FED-0175).

Enterprise relationships are not affected in either position. Set it on the realm’s federation settings page, or through the management API:

POST /admin-api/config/set   { "key": "federation.consumerProviders", "value": "true" }

In a trust realm, use the realm’s own prefix: /realm/<realm>/admin-api/config/set.

Adding a provider

1. Register an application at the provider (see What to register at each provider). Its redirect URI is the relationship’s assertion consumer service:
   • https://<host>/federation/acs/<id> in the default realm;
   • https://<host>/realm/<realm>/federation/acs/<id> in a trust realm.

   <id> is the id you will give the relationship. Its page shows the exact address once it exists.

2. Add it in the console. Go to Protocols → Federation → Consumer and social providers, find the provider, and enter an id, the client ID and the client secret. Then select Add.
3. Fill in anything the provider needs beyond that. The relationship’s page lists what is still missing. Apple needs its team id, key id and signing key. A generic provider needs its endpoints.
4. Enable the relationship. It is created disabled, like every relationship.

The same, through the management API:

POST /admin-api/federation/create
{ "id": "google", "role": "service-provider", "protocol": "oidc",
  "provider": "google", "clientId": "<client id>", "clientSecret": "<secret>" }

POST /admin-api/federation/enable   { "id": "google" }

The response never repeats the client secret. GET /admin-api/federation?category=consumer lists the consumer providers, and ?category=enterprise lists the rest.

What the profile writes, and what it reads. When a relationship is added, its profile writes the provider’s endpoints, issuer, scope and token-endpoint authentication onto it. These are ordinary fields on the relationship’s page, and you can change them there. Every address iya-sts calls is one of these fields.

Where the person’s identifier, address and verification come from is different. That is the provider’s profile, and it is read at every sign-in. So a corrected profile in a later release reaches every relationship of that provider.

What to register at each provider

Provider consoles change their names and layouts, so take these as directions rather than click paths. In every case:

• register a web application, also called a confidential client;
• add the redirect URI above;
• copy the client ID and the client secret into iya-sts.

Sign in with Apple

Apple needs three things beyond the client ID, which is the Services ID. Enter them on the relationship’s page:

• fedTeamId: your Apple Developer team id.
• fedKeyId: the id of your Sign in with Apple key.
• fedClientSigningKey: that key’s .p8 file, pasted whole. It is sealed wherever keys persist and is never shown again.

iya-sts signs a fresh, five-minute client secret for every token request. The code comes back by form_post. The person’s name arrives once, on their first authorization only, and unsigned. It is used as a display value only.

Register https://<host>/federation/notifications/<id> as the relationship’s server-to-server notification endpoint at Apple:

• consent-revoked and account-delete remove the person’s connection through Apple, and end the sessions it started. The person’s account here stays.
• email-disabled and email-enabled are recorded.

A notification is verified against Apple’s keys and accepted only once. Without an exp, it is accepted only while its iat is recent. In a service deployed as cells it reaches every cell. If a cell cannot be reached, it is answered 503, so Apple’s retry is accepted.

Connecting Apple from the portal needs HTTPS. Apple’s form_post is a cross-site POST, so the browser binding has to be a SameSite=None; Secure cookie.

Microsoft for allowed organisations

microsoft-any uses the common authority, whose tokens each name their own tenant. List the tenant ids whose people may sign in, in fedAllowedTenants. The personal-account tenant is listed by default. A token from any other tenant is refused. A single organisation is usually better added as an enterprise OpenID Connect relationship.

A provider outside the catalogue

Use generic-oidc or generic-oauth2, and fill in the endpoints by hand, as for an enterprise partner. For an OAuth 2.0 provider whose profile answer names the person somewhere other than sub, id or user_id, set fedSubjectClaim to the field’s path, for example data.id. If the provider needs extra authorization request parameters, add them as fedAuthorizeParams, one name=value per entry. The parameters iya-sts sets itself, such as state, nonce and redirect_uri, are refused.

Who a person becomes

• A newcomer gets an entry of their own. It is named after the relationship and the provider’s stable identifier for them, for example discord~80351110224678912. Relationships of this category default to fedSubjectPolicy jit-namespaced, with fedAutocreateUsers on in both modes.
• A relationship creates at most fedProvisionCap people, and on these relationships it is never unlimited by default. A new relationship is given federation.consumerProvisionCap (10000 unless the realm says otherwise), and an empty fedProvisionCap means that setting. Set 0 on the relationship for no limit. At the cap a newcomer is refused (STS-FED-0090); people already connected still sign in.
• A newcomer is asked for what the provider did not send. In product mode the realm’s attribute policy (Directory > Policies > Attribute policy, givenName, sn and mail by default) must be met by every new person. When the provider sends no surname, or no address, the person is shown a short form asking for exactly the missing values before the account is created (/federation/profile/{handle}). The policy is not relaxed. This covers Sign in with Apple, which sends the name on the first authorization only. An address typed there is recorded as unverified. The form is good for one sign-in, in the browser it started in, and for five tries.
• An email address is never used to find an existing person, whether or not it is verified. A local person with the same name and the same address is left exactly as they were. any-existing is refused on these relationships in every mode (STS-FED-0172).
• An address is unverified unless the provider says it is verified. It is still written to the entry. An unverified address opens no flow that needs a verified one, such as emailed codes.
• The provider’s details go through the same mapping as any partner’s. fedAttributeMap and the default table decide what reaches the entry. A provider’s own field, such as GitHub’s company, is listed under Sent and not written until it is mapped. What is on the entry reaches the tokens iya-sts issues through the usual release rules.
• A provider’s own MFA claim does not count as MFA here. The session records the sign-in as federated. Nothing a provider says about how the person authenticated satisfies a step-up.

Connecting a provider to an existing account

People who already have an account connect a provider to it on the portal’s Connected accounts page (/portal/connected-accounts). They are signed in as themselves, select Connect, and sign in at the provider. From then on, a sign-in through that provider is them. Disconnect removes the connection and ends the sessions it started. Only a consumer provider’s connection can be removed there. An enterprise partner’s link is an administrator’s. Disconnect is refused when the connection is the account’s only way in (STS-PORTAL-0614): no password, no passkey that signs in, and no other connected account. The page tells the person to add another way to sign in first.

A connect needs:

• a sign-in whose risk is LOW or unscored;
• an authentication within federation.connectRecentAuthMinutes (ten minutes by default). Otherwise the person is asked to sign in again first. Any sign-in counts, including through a provider: an account a provider created has no password here.

A connect is refused:

• in another browser. It is finished only in the browser it was started in.
• for a provider account already connected to somebody else here (STS-FED-0182).
• for a console administrator’s account, unless the relationship sets fedMayAssertAdministrators (STS-FED-0183).

The person is mailed a security notice when a connect succeeds.

Risk scoring and the issuance policy

Consumer sign-ins are scored like any other (Risk scoring), with three signals of their own:

• A newcomer is assessed too. Their first sign-in is not scored, but it is decided on the evidence, such as a network that has created many accounts in the hour.
• Creating an account is its own policy question (create-account). A policy can refuse creation while existing people still sign in (STS-FED-0179). Nobody is created when it refuses.
• A step-up is answered here. When the policy asks an existing person’s federated sign-in for a step-up, the person answers with an authenticator app or security key they hold here. That is never a password and never an enrolment. Someone who holds neither is refused (STS-RISK-0018). The session then records federated plus the factor, with acr mfa. If the sign-in is then refused anyway, the session the second factor started is ended (STS-FED-0192): no session outlives a refused sign-in.
• The policy is told the category. The issuance request carries:
  • urn:sts:xacml:authn-category: consumer or enterprise;
  • urn:sts:xacml:authn-provider: the provider;
  • urn:sts:xacml:email-verified: true or false.

A provider’s security events

A provider that sends Shared Signals about its users is configured exactly as an enterprise partner’s are: in the relationship’s Shared Signals from this partner section (Shared Signals). Its events end the sessions it started, and can block its own sign-ins of a person, and do nothing beyond that relationship. Google’s Cross-Account Protection uses RISC this way. Whether its stream configuration works with this receiver has not been verified. Apple’s notifications are their own endpoint, described above.

Security properties

• Every answer is verified against the relationship’s own configuration. An ID Token is checked against the provider’s keys, issuer and audience, and never against a key the token brings with it. Google’s bare-host issuer spelling is accepted only while the relationship’s issuer is still Google’s.
• PKCE and state are always sent. A response this service did not start is refused.
• The client secret is sealed under the key-encryption key wherever keys persist. Apple’s signing key is sealed the same way. Neither is ever shown or returned by the management API, nor written to the audit log.
• The provider’s tokens are not kept, and no refresh token is asked for.
• Every address iya-sts calls is a field an administrator set, or one the profile wrote when the relationship was added. It is never an address taken from a request.
• The provider’s libraries are not used. The libraries the providers publish were evaluated (Google’s google-auth-library, GitHub’s Octokit, Apple’s browser SDK; Discord publishes none). Each would have called the provider outside iya-sts’s outbound controls, or verified tokens outside its one crypto module, so iya-sts’s own flow is used for all of them.

Limits and what is not verified

• No profile has been run against its live provider. Each one is built from the provider’s published documentation. Six are exercised against servers that behave as the documentation describes. Providers change their endpoints, scopes and review rules, so the first live sign-in through each is the real test.
• The over-HTTP job has run in development mode only.
• Sign-in buttons are text only. Provider logos are under each provider’s brand rules, and are not included.
• Applications cannot use the provider’s tokens to call the provider’s APIs. iya-sts keeps none.
• Whether Apple retries a notification answered 503 is Apple’s behaviour, and has not been verified.
• Google’s RISC stream with this receiver has not been verified.

Troubleshooting

Every refusal has an error code on the audit row and in the log, and never in the response (Error codes).

Feasibility of the platforms requested

Ticket #565 names seventeen platforms. This table records what each provider’s published developer documentation says about signing a person in, as read when the catalogue was started (October 2026). Each row is checked again when its profile is used live, because providers change their terms, endpoints and review requirements.

Related

• Federation: relationships, links, provisioning and the subject policies these relationships use.
• Risk scoring: the signals and the levels.
• Shared Signals: a partner’s or provider’s security events.
• Configuration: federation.consumerProviders, federation.connectRecentAuthMinutes and risk.networkSignupThreshold.