Skip to main content

Generic Social Login configuration guide

This guide describes a typical OpenID Connect integration with the Generic Social Login Step. Use the pattern reference for the complete list of pattern properties.

Provider registration​

Before configuring nevisAdmin, register a confidential authorization-code client at the provider and confirm:

  • the client ID and client secret;
  • the exact redirect URI;
  • whether the provider requires PKCE;
  • whether the client uses client_secret_basic or client_secret_post;
  • the scopes and claims available to the client.

If the provider publishes an OpenID Connect discovery document, use it to obtain the provider endpoint configuration. Discovery metadata does not necessarily describe the policy of an individual client registration, so confirm the client settings with the provider administrator.

Basic pattern configuration​

  1. Select OpenID Connect as the Provider Type.
  2. Configure the discovery URL as the Provider Endpoint.
  3. Enter the registered Client ID and Client Secret.
  4. Set the Return Path to the callback path registered at the provider.
  5. Select the scopes required by the provider. The openid scope is added automatically for OpenID Connect.
  6. Select the client authentication method required by the provider: Basic Authentication uses client_secret_basic; POST uses client_secret_post.
  7. Enable PKCE only when required or supported by the provider. When enabled, use S256.
  8. Assign the Virtual Host that serves the callback endpoint.

For example, if the public frontend address is https://portal.example.com and the configured return path is exact:/oidc/example/callback, register this redirect URI at the provider:

https://portal.example.com/oidc/example/callback

The redirect URI must match exactly, including the scheme, host, path, and trailing slash.

The current RelyingParty AuthState requires a client secret and supports only client_secret_basic and client_secret_post for the token exchange. PKCE can be combined with either method, but public PKCE-only clients are not supported. private_key_jwt and other token-endpoint authentication methods are not supported by this pattern/AuthState combination.

Account resolution and linking​

Leave nevisIDM unset when the provider identity alone is sufficient for the application. Configure it when the social identity should be linked to or used to create a nevisIDM user.

The account-resolution branches have distinct meanings:

  • On Success: the provider identity is already linked, or no nevisIDM lookup is configured.
  • On User Found: no provider identity link exists, but the fallback lookup (normally e-mail) found an existing nevisIDM user. This is a linkable-user branch; it does not mean that linking has already happened.
  • On User Not Found: neither the provider identity nor the fallback lookup found an existing nevisIDM user.

For a linkable user, place any required checks, such as an e-mail TAN, before Social Login Link User. For an unknown user, use Social Login Create User when account creation is intended. The normal generated completion restores the original URL after the configured continuation chain finishes, so an extra Social Login Done step is not required for the normal case. Keep Social Login Done when an explicit AUTH_DONE or AUTH_ERROR terminal state is needed.

Social Login Create User uses the provider's mapped email value for both the nevisIDM email attribute and, by default, the loginId. If the provider does not expose a suitable email claim, configure Email Source with an expression that provides the value to store as email. Configure Login ID Source separately when the nevisIDM loginId must differ from the email, for example:

Email Source: ${sess:Generic_Social_Login.idTokenClaim.mail}
Login ID Source: ${sess:Generic_Social_Login.idTokenClaim.sub}

Both settings are session expressions. The referenced values must be available when the create-user step runs; otherwise nevisIDM user creation fails.

When account management is enabled, configure stable claim mappings and select the scopes that provide the required values, commonly email and profile. Configure Account Linking - User Property explicitly if the pattern may be renamed later.

PKCE and client authentication​

The client authentication method is used at the token endpoint:

  • Basic Authentication sends client_secret_basic;
  • POST sends client_secret_post.

A mismatch between the provider registration and this setting commonly results in an invalid_client error during the authorization-code exchange.

PKCE currently requires client authentication with one of the two methods above; it cannot replace the client secret. S256 is the recommended code challenge method. For OpenID Connect, the RelyingParty AuthState generates and stores the verifier itself; the PKCE Secret property is not used.

Claims request​

Claims Request must be a JSON object and must not end with spaces or tabs. Static malformed JSON is rejected during pattern validation. Values containing runtime expressions cannot be fully validated until generation or runtime evaluation.