Social logins provide a familiar and convenient way for users to access applications using their existing accounts from popular platforms like Google, Apple, or Facebook. Under the hood, this functionality is powered by OAuth - a robust authentication protocol that enables secure user verification through OpenID Connect (OIDC) tokens. This feature is available exclusively for sub-organization users.
CREATE_SUB_ORGANIZATION
activity to register Google as the Oauth provider under the root user.issuer
is set to https://accounts.google.com
audience
is set to <google-oauth-app-id>
(your Oauth app ID)subject
is set <google-end-user-id>
(the user ID of End-User
on Google’s side)Parent backend
receives the OIDC token authenticating End-User.OAUTH_LOGIN
activity, signed by the Parent’s backend./.well-known/openid-configuration
for each domain. For Google for example, the issuer configuration is at accounts.google.com/.well-known/openid-configuration
. This JSON document contains, among other thing, a jwksUri
key. The value for this key is a URL hosting the list of currently-valid OIDC token signers.jwksUri
(e.g., for Google, the jwksUri
is googleapis.com/oauth2/v3/cert
). This is a list of public keys against which the secure enclave can verify tokens. Note: these public keys rotate periodically (every ~6hrs), hence it’s not possible to hardcode these public keys in our secure enclave code directly. We have to fetch them dynamically!iss
, aud
and sub
attributes against the registered OAuth providers on the Turnkey sub-organization. We also check exp
to make sure the OIDC token is not expired, and the nonce
attribute (see next section).
OAUTH_LOGIN
activity requires 2 parameters minimum:
oidcToken
: the base64 OIDC tokenpublicKey
: the client-side public key generated by the usernonce
claim is set to sha256(publicKey)
.
For example, if the iframe public key is 04bb76f9a8aaafbb0722fa184f66642ae425e2a032bde8ffa0479ff5a93157b204c7848701cf246d81fd58f6c4c47a437d9f81e6a183042f2f1aa2f6aa28e4ab65
, our enclaves expect the OIDC token nonce to be 1f9570d976946c0cb72f0e853eea0fb648b5e9e9a2266d25f971817e187c9b18
.
This restriction only applies during authentication (OAUTH
activity). Registration via CREATE_OAUTH_PROVIDER
and CREATE_SUB_ORGANIZATION
activities is not affected since these activities do not accept a publicKey
and do not return encrypted credentials as a result.
If your OAuth provider does not allow you to customize nonce
claims, Turnkey also accepts and validates tknonce
claims. This is an alternative claim that will be considered. Only one of (nonce
, tknonce
) needs to be set to sha256(publicKey)
; not both.
users:update
scope token can call this endpoint to arbitrarily link an identity.
For example, if a Google-authenticated user (OIDC token sub
claim: google-oauth2|118121659617646047510
) gets merged into a Twitter-authenticated user (OIDC token sub
claim: twitter|47169608
), the OIDC token obtained by logging in through Google post-merge will be twitter|47169608
. This can be surprising and lead to account takeover if an Auth0 admin is malicious. This is documented in Auth0’s own docs, here.
nonce
claims easily. To pass the hash of the end-user’s iframe public key, use a custom tknonce
claim instead.