Recently, Vizend introduced and refactored the ThirdParty login feature. The ThirdParty login allows user verification through external authentication methods such as Google, Apple, Facebook, and Keycloak, connecting the result to Vizend's internal user system. On the user-facing screen, it appears as a commonly seen 'Log in with external account' button, but from the server perspective, the key is how to connect the external authentication result with internal accounts, subscription policies, account linkage policies, and session policies.
The important point in this work was to separate external authentication from internal login. External providers can verify that the user is the owner of a specific account. However, they cannot determine whether that user is active within Vizend, which organization they belong to, what permissions they should have, or whether they meet the conditions for service access. This judgment must be made within Vizend's user model and authentication policies.
Therefore, ThirdParty login is not a feature that directly treats the success of external authentication as the success of internal login. It is closer to an authentication auxiliary flow that standardizes external authentication results, verifies the connection with internal users, and leads to new sign-ups or linking existing accounts if necessary. In this article, I will share the design direction, application process, and key considerations organized while introducing and refactoring ThirdParty login at Vizend.
Application Background
Vizend's Gate is a common authentication foundation used across multiple services. While each service could implement Google login, Apple login, and Keycloak login directly, doing so would disperse the authentication policies across the services. Initially, this may seem faster, but as more providers and services are added, the operational costs increase, making it difficult to understand the impact scope when policy changes occur.
For example, some companies may need to allow Google login, while others may only permit internal Keycloak. Some services might only allow automatic sign-up for users whose emails are verified, while other services might allow external login but prevent automatic sign-up. Distributing these policies across each service's code would lead to repeating implementations of the same criteria, and when issues arise, the causes also become dispersed.
Another background is the relationship between external accounts and internal accounts. Just because a user successfully authenticated with Google does not mean they can be immediately regarded as an internal user of Vizend. They may already have an internal account or may not have signed up yet. They could also be a user who was activated externally but is inactive internally. Therefore, a separate step to link the external authentication result to the internal account is necessary.
The criteria for introducing and refactoring ThirdParty login can be summarized as follows.
-
Absorb differences in authentication methods by provider into a common flow within the Gate.
-
Allow different settings for providers and sign-up policies by organization.
-
Manage external account information as connection information without mixing it directly with internal users.
-
Clearly distinguish between new sign-ups and existing account linkages.
-
Maintain internal user status, permissions, and session policies even after external authentication.
Design Direction
The key to the design is to separate the differences by provider from the internal authentication policies. While the name OAuth is the same, the actual behavior differs by provider. Some providers retrieve user information using an access token, while others need to exchange an authentication code for a token. In the case of Apple, user identification information may be verified directly from the id token itself.
If the difference is directly recognized by the sign-up logic or the account linking logic, the branching in the existing flow increases every time a provider is added. Therefore, the authentication results for each provider are converted into common user information that Gate can understand, and the subsequent flow is configured to be handled based on the same criteria regardless of the type of provider.
Common user information includes external user ID, email, name, email verification status, provider identifier, etc. Internal user matching, determining the possibility of new sign-ups, and assessing connection to existing accounts are conducted based on this common information and Vizend's policies. This way, the implementation for each provider is isolated at the front end, and domain policies are maintained stably.
We chose to manage policies as company-specific settings instead of hard-coding them. External login settings can change even during operation. The redirect URI may change, Keycloak realms may be separated, and certain providers may need to be temporarily deactivated. If these values are embedded in the code, even minor operational changes would require deployment. By separating them as policies, we can respond more flexibly at the corporate level.
External account connection information is also managed separately. Directly placing provider IDs within internal user information is simple but lacks scalability. A single user can connect multiple external accounts, and it may be necessary to deactivate only certain external account connections. Therefore, a structure that keeps the connection between the external provider's user ID and the internal user ID as separate information is more appropriate.
Overall flow
The overall flow of ThirdParty login can be organized in the order of external authentication, Gate verification, internal user matching, and sign-up or linking. First, the user performs authentication with providers like Google, Apple, and Keycloak from the client. When the provider authentication is complete, the client passes the credentials received as a result to the Gate.
The Gate first checks whether that provider can be used in the respective company. If the provider is disabled or there is no policy, external authentication will not be allowed by the Gate even if successful. This step is the first line of defense to maintain operational policies.
If the use of the provider is allowed, the Gate verifies the credentials and retrieves external user information. At this point, differences arise per provider. Google, Facebook, Apple, and Keycloak have different ways of verifying user information and response formats. However, within the Gate, this is converted into common user information and passed to the next step.
Next, the Gate checks whether the external account is already linked to an internal user. If a connected user exists, it returns the internal user information, and subsequent access to services follows Gate's standard login and token policies. If no connected user exists, it does not sign up immediately, but issues a short-term registration token to proceed to the next step.
The registration token is a mechanism for safely carrying over the results of external authentication. After external authentication, the user may not complete the sign-up immediately. They might need to set a username, input additional information, or decide whether to link to an existing account. If the client carries important values like provider user ID or email directly during this period, there is a risk of manipulation. By having the server temporarily store the results of external authentication and only passing a short-lived token to the client, this risk can be reduced.
If the user chooses to sign up, the Gate verifies the registration token and applies sign-up policies. It checks whether sign-ups are allowed in that company, whether provider-based sign-up is activated, whether an email is required, and whether a verified email is necessary. If the conditions are met, it creates an internal user and also retains the external account connection information.
If the user chooses to connect an existing account, they will be asked to re-enter the username and password of the internal account. It is risky to link to an existing internal account solely based on the success of external authentication. In situations with shared devices or account switching, an incorrect external account could be linked to the internal account. Reconfirming the internal account password allows for another verification that the user is indeed the owner of that internal account.
Handling Provider-Specific Differences
The first area to organize in ThirdParty login is the differences in provider responses. Even with common standards like OAuth or OIDC, the actual integration varies in the information and verification methods provided by each provider.
Google provides a relatively clear comparison of the email and email verification status. This value can be an important basis for automatic sign-up or automatic linking policies. In contrast, even if Facebook can receive the email value, it is difficult to trust the verification status in the same way. In such cases, it is safer to handle them conservatively.
Apple has a flow centered around id tokens. The user identifier can be seen based on the token's subject, and emails can also be transmitted as a token claim. However, name information is not always reliably provided, and characteristics such as private relay emails must also be considered. Therefore, the Apple integration should not be designed under the assumption that complete user profile information can always be obtained.
Keycloak is close to the standard OIDC flow, but it heavily depends on configuration. The method of token exchange and userinfo retrieval can vary depending on the realm, client, redirect URI, and client authentication method. Especially when integrating with client companies or in-house IdPs, the endpoint and client authentication method may differ by environment, making policy-based configuration important.
Although there are differences by provider, within the Gate internal flow, the information is processed after being converted into common user information. This structure reduces the scope of impact when adding or changing providers. Even if a new provider is added, there is no need to recreate enrollment policies, account linking policies, or internal user lookup flows.
Separation of new signups and existing account linking
When external authentication is successful but there is no internal link information, it is unclear whether the user is new or if they have an existing account. If the server arbitrarily proceeds with enrollment in this state, duplicate accounts may be created. Conversely, if the existing account is linked solely because the email is the same, incorrect account linking may occur.
To mitigate this issue, the results of external authentication checks and actual enrollment or linking are separated. The Gate first verifies external users, and if there are no connected internal users, it issues a registration token. Then, if the user chooses to sign up, the flow proceeds to the enrollment process; if they choose to link an existing account, the flow proceeds to the account linking process.
This separation also helps with the screen flow. The client can look at the response from the Gate and continue the login flow if the user is already linked, while providing a signup or account linking screen for unlinked users. This reduces the need to create different screen logic for each provider.
During signup, the company’s policies are checked. It is determined whether external provider-based signups are allowed, whether an email is required, whether email verification is necessary, whether administrator approval is needed, etc. Internal users are created and external account link information is retained only after passing this policy.
When linking an existing account, the verification of the internal account owner is performed. The existing account is not connected solely based on the external provider’s authentication results, but the authentication information of the internal account is re-verified. This step is an important safeguard against incorrect linking.
Email-based automatic linking
Email-based automatic linking in ThirdParty login is a convenient but cautious feature. From the user experience perspective, it seems natural to auto-link when the email received from the provider matches the internal account email. However, simply having the same email string does not validate account ownership.
Therefore, it is necessary to distinguish between simple email-based linking and verified email-based linking. When a provider clearly indicates that it has verified email ownership, the trustworthiness of automatic linking increases. Conversely, with a provider where verification cannot be assured, it is safer to limit automatic linking.
Additionally, if there are multiple active users with the same email, one should not be automatically selected. Ambiguous automatic determinations in the authentication system can lead to security incidents. In this case, it is better to address it as a policy violation and guide the user to sort or link accounts through a clear process.
Email-based linking requires a balance between convenience and security. In Vizend’s ThirdParty login, the flow has been divided to consider both the email verification status by provider and the duplication status among internal users.
The role of the Registration Token
The registration token is a short-term token that bridges external authentication and internal registration or linking. The external provider authentication result includes information such as provider user ID, email, email verified, and name. These values are needed for registration and linking but should not be modified arbitrarily by the client.
Using the registration token allows the server to store the external authentication result and only pass an opaque token to the client. When a registration or linking request arrives later, the server verifies the token to restore the original external authentication result. This method reduces the potential for manipulation of external authentication results and safely handles the time difference between external authentication and internal processing.
Tokens must be valid for a short time and should not be reusable once used. If a user lingers on the registration screen for too long, the token may expire, and there may be cases where a previously used token is sent again due to browser back navigation or duplicate submissions. In such cases, guiding the user back to the external authentication step is a natural approach.
In a production environment, the method of storing tokens is also important. In a single instance, memory-based storage can work simply, but in an environment scaled to multiple instances, shared storage is necessary. This is because the instance that issues the token and the instance that consumes it may be different. Therefore, considering scalability, it is appropriate to develop based on shared storage such as Redis.
Application results
After introducing and refactoring ThirdParty login, the flow has been separated by provider-specific implementations and domain policies. Although Google, Facebook, Apple, and Keycloak have different authentication methods, they can be handled in the same flow within Gate. Differences between providers are organized upfront, and thereafter, internal user matching, registration policies, and account linking policies are applied uniformly.
There are also operational advantages. Providers can be activated or deactivated on a company-by-company basis, and client settings or redirect URIs specific to each provider can be managed as policies. If an issue arises with a specific provider, only that provider's policy can be adjusted without changing the overall authentication structure.
From a security perspective, the separation of external authentication and internal login judgment is the most important. Even if external provider authentication is successful, access to the service can only occur after passing through the internal user state and policies. If a user has an external account but is inactive within Vizend, access may not be allowed.
From a maintenance perspective, the cost of adding providers is reduced. When a new provider is added, it only requires checking the credentials of that provider and updating the common user information conversion. Registration policies, linking policies, and internal user lookup flows can still be used as they are. This separation is vital for services where the possibility of increasing authentication methods is present in the long term.
Summary
ThirdParty login is not just a simple OAuth API call, but an authentication flow that connects external authentication results to the internal user model. While it appears as a single button on the user's screen, internally on the server, external authentication, internal user status, registration policies, account linking, and session policies all connect. If this flow is not clearly delineated, implementation may seem quick, but operational and scalability challenges will arise.
In the introduction and refactoring of Vizend's ThirdParty login, we chose to organize the differences between external providers upfront, manage company-specific policies through settings, and maintain actual service access judgments based on internal user and authentication policies. This structure allows for consistency in the authentication model even as the number of providers increases.
In the authentication domain, preventing incorrect connections is more important than convenience. Decisions like not automatically linking accounts simply because the emails are the same, not trusting unverified emails, and preventing the reuse of tokens that have been used once are all in the same direction. Even if it requires an additional confirmation step from users, it is safer to prevent incorrect account linking.
In the future, the registration token storage will be transitioned to a shared storage basis according to operational scalability, and policies like manual connection approval or administrator approval can be more closely tied to the operational interface. Monitoring the causes of failures and processing times by provider will also speed up incident responses. ThirdParty login can be viewed as a foundational function that goes beyond merely increasing external login methods to consistently connect various authentication methods with the internal user model.
David