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.
Similar to email auth, social login authentication is ideal for users who prefer not to manage API keys or passkeys directly. This makes it particularly well-suited for onboarding users who are comfortable with traditional web2-style accounts but may be unfamiliar with cryptographic keys and credentials. An example implementing social login authentication for an organization can be found in our SDK repo here.
Turnkey: runs verifiable infrastructure to create credentials and verify OIDC tokens
Parent: that’s you! For the rest of this guide we’ll assume you, the reader, are a Turnkey customer. We assume that you have:
End-User: the end-user is a user of your web app. They have an account with Google.
OIDC Provider: a provider able to authenticate your End-Users and provide OIDC tokens as proof. We’ll use Google as an example.
CREATE_SUB_ORGANIZATION
activity to register Google as the Oauth provider under the root user.The user is now registered: a sub-organization under the parent organization has been created with a a root user, authenticated via an OAuth Provider. Concretely:
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
activity, signed by the Parent’s backend.The user is now authenticated and able to perform Turnkey activities.
All OIDC tokens are verified inside of Turnkey’s secure enclaves.
We’ve designed a new secure enclave to fetch TLS content securely and bring non-repudiation on top of TLS content: our TLS fetcher returns a URL and the fetched content, signed by the TLS fetcher’s quorum key. By trusting the TLS fetcher quorum key, other Turnkey enclaves can bring TLS-fetched data into their computation safely. Verifying OIDC token is the first computation which requires this!
To verify an OIDC token, other Turnkey enclaves receive the OIDC token as well as:
/.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!With all of that, an enclave can independently verify an OIDC token without making outbound requests. Once the token is parsed and considered authentic, our enclaves match the 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).
Our OAUTH
activity requires 2 parameters minimum:
oidcToken
: the base64 OIDC tokentargetPublicKey
: the client-side public key generated by the userIn order to prevent OIDC tokens from being used against multiple public keys, our enclaves parse the OIDC token and, as part of the validation logic, enforce that the nonce
claim is set to sha256(targetPublicKey)
.
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 targetPublicKey
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(targetPublicKey)
; not both.
OAuth2.0 is a separate protocol from OIDC, with distinct goals:
We chose to name this feature “OAuth” because of the term familiarity: most Turnkey customers will have to setup an “OAuth” app with Google, and the user experience is often referred to as “OAuth” flows regardless of the protocol underneath.
Below, some details and pointers about specific providers we’ve worked with before. If yours isn’t listed below it does not mean it can’t be supported: any OIDC provider should work with Turnkey’s OAuth.
This provider is extensively tested and supported. We’ve integrated it in our demo wallet (hosted at https://wallet.tx.xyz), along with Apple and Facebook:
The code is open-source, feel free to check it out for reference. The exact line where the OAuth component is loaded is here: ui/src/screens/LandingScreen.tsx.
The main documentation for Google OIDC is available here.
Apple integration is also extensively tested and supported, and is integrated into our demo wallet (hosted at https://wallet.tx.xyz). The code provides an example component as well as an example redirect handler.
Documentation for Apple OIDC can be found here.
Facebook OIDC requires a manual flow with PFKE (Proof for Key Exchange). This flow requires a few extra steps compared with Apple or Google. Specifically:
In our example demo wallet, we opt to avoid using a database in the authentication process and instead generate our verification code serverside using the hash of a nonce and a secret salt value. The nonce is then passed to and returned from the Facebook API as a state parameter (see the API spec for details). Finally, the server reconstructs the verification code by re-hashing the nonce and the the salt. The full flow is displayed below:
Code for the redirect component, OAuth callback, and code exchange are all available in the example wallet repo.
If you prefer to use a database such as Redis instead of reassembling the verification code, you can store the verification code and retrieve it in the exchange stage using a lookup key either passed as state or stored in local browser storage.
This provider was tested successfully and offers a wide range of authentication factors and integration. For example, Auth0 can wrap Twitter’s auth or any other “Social Connection”.
In the testing process we discovered that Auth0 admins can manage users freely. Be careful about who can and can’t access your Auth0 account: Auth0’s management APIs allow for account merging. Specifically, anyone with a 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.
The main thing to call out is the inability to pass custom nonce
claims easily. To pass the hash of the end-user’s iframe public key, use a custom tknonce
claim instead.
Social linking is the concept of automatically linking an email address to a Turnkey user by authenticating with a social provider. This allows an end-user to authenticate with the social provider, or a matching email address. Currently, we only allow automatic linking for Google social logins.
The cases are as follows:
For more information on how to implement social linking, see the social linking code example.
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.
Similar to email auth, social login authentication is ideal for users who prefer not to manage API keys or passkeys directly. This makes it particularly well-suited for onboarding users who are comfortable with traditional web2-style accounts but may be unfamiliar with cryptographic keys and credentials. An example implementing social login authentication for an organization can be found in our SDK repo here.
Turnkey: runs verifiable infrastructure to create credentials and verify OIDC tokens
Parent: that’s you! For the rest of this guide we’ll assume you, the reader, are a Turnkey customer. We assume that you have:
End-User: the end-user is a user of your web app. They have an account with Google.
OIDC Provider: a provider able to authenticate your End-Users and provide OIDC tokens as proof. We’ll use Google as an example.
CREATE_SUB_ORGANIZATION
activity to register Google as the Oauth provider under the root user.The user is now registered: a sub-organization under the parent organization has been created with a a root user, authenticated via an OAuth Provider. Concretely:
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
activity, signed by the Parent’s backend.The user is now authenticated and able to perform Turnkey activities.
All OIDC tokens are verified inside of Turnkey’s secure enclaves.
We’ve designed a new secure enclave to fetch TLS content securely and bring non-repudiation on top of TLS content: our TLS fetcher returns a URL and the fetched content, signed by the TLS fetcher’s quorum key. By trusting the TLS fetcher quorum key, other Turnkey enclaves can bring TLS-fetched data into their computation safely. Verifying OIDC token is the first computation which requires this!
To verify an OIDC token, other Turnkey enclaves receive the OIDC token as well as:
/.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!With all of that, an enclave can independently verify an OIDC token without making outbound requests. Once the token is parsed and considered authentic, our enclaves match the 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).
Our OAUTH
activity requires 2 parameters minimum:
oidcToken
: the base64 OIDC tokentargetPublicKey
: the client-side public key generated by the userIn order to prevent OIDC tokens from being used against multiple public keys, our enclaves parse the OIDC token and, as part of the validation logic, enforce that the nonce
claim is set to sha256(targetPublicKey)
.
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 targetPublicKey
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(targetPublicKey)
; not both.
OAuth2.0 is a separate protocol from OIDC, with distinct goals:
We chose to name this feature “OAuth” because of the term familiarity: most Turnkey customers will have to setup an “OAuth” app with Google, and the user experience is often referred to as “OAuth” flows regardless of the protocol underneath.
Below, some details and pointers about specific providers we’ve worked with before. If yours isn’t listed below it does not mean it can’t be supported: any OIDC provider should work with Turnkey’s OAuth.
This provider is extensively tested and supported. We’ve integrated it in our demo wallet (hosted at https://wallet.tx.xyz), along with Apple and Facebook:
The code is open-source, feel free to check it out for reference. The exact line where the OAuth component is loaded is here: ui/src/screens/LandingScreen.tsx.
The main documentation for Google OIDC is available here.
Apple integration is also extensively tested and supported, and is integrated into our demo wallet (hosted at https://wallet.tx.xyz). The code provides an example component as well as an example redirect handler.
Documentation for Apple OIDC can be found here.
Facebook OIDC requires a manual flow with PFKE (Proof for Key Exchange). This flow requires a few extra steps compared with Apple or Google. Specifically:
In our example demo wallet, we opt to avoid using a database in the authentication process and instead generate our verification code serverside using the hash of a nonce and a secret salt value. The nonce is then passed to and returned from the Facebook API as a state parameter (see the API spec for details). Finally, the server reconstructs the verification code by re-hashing the nonce and the the salt. The full flow is displayed below:
Code for the redirect component, OAuth callback, and code exchange are all available in the example wallet repo.
If you prefer to use a database such as Redis instead of reassembling the verification code, you can store the verification code and retrieve it in the exchange stage using a lookup key either passed as state or stored in local browser storage.
This provider was tested successfully and offers a wide range of authentication factors and integration. For example, Auth0 can wrap Twitter’s auth or any other “Social Connection”.
In the testing process we discovered that Auth0 admins can manage users freely. Be careful about who can and can’t access your Auth0 account: Auth0’s management APIs allow for account merging. Specifically, anyone with a 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.
The main thing to call out is the inability to pass custom nonce
claims easily. To pass the hash of the end-user’s iframe public key, use a custom tknonce
claim instead.
Social linking is the concept of automatically linking an email address to a Turnkey user by authenticating with a social provider. This allows an end-user to authenticate with the social provider, or a matching email address. Currently, we only allow automatic linking for Google social logins.
The cases are as follows:
For more information on how to implement social linking, see the social linking code example.