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_basicorclient_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
- Select
OpenID Connectas theProvider Type. - Configure the discovery URL as the
Provider Endpoint. - Enter the registered
Client IDandClient Secret. - Set the
Return Pathto the callback path registered at the provider. - Select the scopes required by the provider. The
openidscope is added automatically for OpenID Connect. - Select the client authentication method required by the provider:
Basic Authenticationusesclient_secret_basic;POSTusesclient_secret_post. - Enable PKCE only when required or supported by the provider. When enabled,
use
S256. - Assign the
Virtual Hostthat 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 Authenticationsendsclient_secret_basic;POSTsendsclient_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.