View source for Documentation:External login services in MDriven Turnkey

You can enable Google, Microsoft, and Facebook sign-in for a [[Documentation:Starting with MDriven Turnkey|MDriven Turnkey]] site by registering your site with the provider and sending the provider credentials to Turnkey; this page is for Turnkey administrators.

External login lets a user authenticate with an account at a third-party identity provider instead of a password created in your site. Turnkey creates and maintains the local user connection through the [[Documentation:SysUserAuthentication|SysUserAuthentication]] pattern, including a <code>SysExternalLogin</code> object for the external provider.

For a video walkthrough of Google, Facebook, and Microsoft setup, see [https://www.youtube.com/watch?v=n2C9geLx4D0 MDriven Turnkey Part 6: Social Login].
== Before you begin ==

# Confirm that your model includes the [[Documentation:SysUserAuthentication|SysUserAuthentication]] pattern. The pattern provides Turnkey registration, sign-in, and external-login handling.
# Identify the public base URL of the Turnkey site. For example: <code>https://mdriventestone.azurewebsites.net</code>.
# Decide which providers you will offer. Configure each provider separately.
# Sign in to [https://portal.mdriven.net portal.mdriven.net] with the account that owns the Turnkey site.
# Open the site in the MDriven Portal: select ''Views'' and then ''Show my Turnkey sites''.

Each provider requires a redirect URI. A ''redirect URI'' is the URL to which the provider returns the browser after the user has authenticated. The URI registered with the provider must match your Turnkey site and the provider-specific ending exactly.

{| class="wikitable"
! Provider
! Required redirect URI
! Example for <code>https://mdriventestone.azurewebsites.net</code>
|-
| Google
| <code>&lt;site-url&gt;/signin-google</code>
| <code>https://mdriventestone.azurewebsites.net/signin-google</code>
|-
| Microsoft
| <code>&lt;site-url&gt;/signin-microsoft</code>
| <code>https://mdriventestone.azurewebsites.net/signin-microsoft</code>
|-
| Facebook
| <code>&lt;site-url&gt;/signin-facebook</code>
| <code>https://mdriventestone.azurewebsites.net/signin-facebook</code>
|}
== Configure Google sign-in ==
# Go to [https://console.developers.google.com Google Developers Console] and sign in with the Google account that will own the integration.
# Open ''Credentials'', select ''Create Credential'', and choose ''OAuth Client ID''.
# Choose ''Web application''.
# Enter the application name and the site URL requested by Google.
# Add the authorized redirect URI <code>&lt;site-url&gt;/signin-google</code>. For example, enter <code>https://mdriventestone.azurewebsites.net/signin-google</code>.
# Turn on the Google+ API.
# Create the credential, then copy its ''Client ID'' and ''Client Secret''.
# Return to the selected Turnkey site in the MDriven Portal. Paste the values into ''Google Client ID'' and ''Google Client Secret''.
# Save the portal changes, then select ''Send Settings and Restart''.

After the restart, open the site's login page. Google should be available as an external sign-in option.

After registering in Google Developers Console, configure your Turnkey site settings.
Go to [https://portal.mdriven.net/ portal.mdriven.net] and sign in under your existing account. Head to your application (Views -> Show my Turnkey sites) in which you want to add the external login services.
[[File:Block with settings for the external login services.jpg|none|thumb|428x428px|Block with settings for the external login services]]

At the end of the redirect URL, add the "'''sign-in-google'''" - for example, if your home page URL is — ''<nowiki>https://mdriventestone.azurewebsites.net/</nowiki>'', your redirect URL will be  — https://mdriventestone.azurewebsites.net/signin-google
[[File:Google authentication settings.jpg|alt=Setting up Google Authentication|none|thumb|415x415px|Setting up Google Authentication]]
== Configure Microsoft sign-in ==
# Go to [https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps App registrations] in the Azure portal and sign in with the Microsoft account that will own the integration.
# Select ''New Registration''.
# Enter an application name. Microsoft shows this name to users during sign-in.
# Select the account types that may use the application login.
# Choose ''Web'' and add the redirect URI <code>&lt;site-url&gt;/signin-microsoft</code>. For example, enter <code>https://mdriventestone.azurewebsites.net/signin-microsoft</code>.
# Select ''Register''.
# In the left menu, select ''Certificates and secrets''.
# Under ''Client secrets'', select ''+ New client secret''.
# Enter a description and expiration time, then select ''Add''.
# Copy the secret ''Value'' now. Microsoft displays this value only once.
# Copy the application's ''Application ID''.
# Return to the selected Turnkey site in the MDriven Portal. Paste the Application ID into ''Microsoft Client ID'' and the secret value into ''Microsoft Client Secret''.
# Save the portal changes, then select ''Send Settings and Restart''.

You can also use ''Branding and properties'' in the Azure portal to provide a logo and application information, including the site's home-page URL. To review an account's granted application rights, use [https://microsoft.com/consent Microsoft consent].

To set up authentication through a Microsoft Account in your Turnkey app, go to https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps (App registrations). Sign in under your Microsoft Account and '''click on "New Registration"'''.
# Name your application (''Note'': This name will be visible for users when they use Microsoft Authentication) and press '''"Create"'''. 
# Select which account types can use your application login. 
# Choose "Web" and enter '''Redirect URLs'''.
'''!Important!''' You have to enter a full link to your app (e.g. <nowiki>https://mdriventestone.azurewebsites.net/</nowiki>) and add "'''signin-microsoft'''" at the end of the link.
[[File:Registration information of app.jpg|none|thumb|427x427px|Registration Information of the App]]
* Click "Register"
* On the next screen, in the menu to the left, select "Certificates and secrets".
* Select "Client secrets" and then "+ New client secret".
* On the pane to the right, enter a description and expiration time, then click "Add".
Your '''Client Secret''' will be shown as "Value" in the list of secrets and you need to copy it now (to portal.mdriven.net or somewhere else, because it will be displayed '''''only once''''').[[File:Microsoft Client Secret.jpg|none|thumb|817x817px|Microsoft Client Secret]]Save the '''Microsoft Portal''' and copy your Application ID and Client Secret to portal.mdriven.net (App ID to '''Microsoft Client ID''' and Client Secret to '''Microsoft Client Secret''').
[[File:MS client id.png|none|thumb|850x850px]]
In the '''MDriven Portal''', save the change and press "'''Send settings and restart'''" to add Microsoft Authentication to your Turnkey App.
== Configure Facebook sign-in ==
# Go to [https://developers.facebook.com Facebook for Developers] and sign in or create a developer account.
# Open ''My apps'' and select ''Add a new App''.
# Name the app. On the next screen, select ''Set up'' on the Facebook Login card.
# Select the ''Web'' platform and enter the site URL, then save and continue. You can skip the remaining setup steps at this point.
# Open ''Settings'' → ''Basic''. Enter the application URL as the App domain and save the changes.
# Open the Client OAuth settings and add <code>&lt;site-url&gt;/signin-facebook</code> as a valid OAuth Redirect URI. For example, enter <code>https://mdriventestone.azurewebsites.net/signin-facebook</code>.
# Copy the Facebook ''App ID'' and ''App Secret''.
# Return to the selected Turnkey site in the MDriven Portal. Paste the values into ''Facebook Client ID'' and ''Facebook Client Secret''.
# Save the portal changes, then select ''Send Settings and Restart''.

To set up authentication through your Facebook Account in your Turnkey App, go to [https://developers.facebook.com/ https://developers.facebook.com]. Sign in under your Facebook account or register a new one.
# Head to "My apps" and choose "'''Add a new App'''". Name your app and on the next screen, press "'''Set up'''" on the '''Facebook login''' card.
# Next, select '''Web platform''' and enter the '''Site URL''' (URL of your application), press save, and continue but skip other steps. 
# Head to Settings -> Basic, enter the App domain (URL of your application), and save the changes.
# Also at Client OAuth Settings, add <SITE URL>/signin-facebook as a valid OAuth Redirect URI. 
Now copy the App ID and App Secret to portal.mdriven.net. 
[[File:Facebook authentication settings.jpg|alt=Facebook authentication settings|none|thumb|598x598px|Facebook authentication settings]]
Paste your App ID and App Secret to '''Facebook Client ID''' and '''Facebook Client Secret''', save the changes, and press "'''Send settings and Restart'''" to add Facebook Authentication to your Turnkey App.
== Test the sign-in flow ==

# Wait for the Turnkey restart to complete, then open the site in a new browser session.
# Go to the login page and select the button for the provider you configured.
# Authenticate with a provider account and approve the requested access.
# Complete the first-sign-in registration in Turnkey when prompted.

Turnkey uses a local user identity as part of the external-login flow. In the walkthrough, the email used for the local account must be unique in the application. If you test several providers, use an email identity that does not conflict with an existing local user.

If the provider button does not appear, verify that you entered both the client ID and client secret in the correct portal fields and that you selected ''Send Settings and Restart'' after saving. If a restart reports an error because the application is busy, retry the restart.
== Control the login interface ==

Turnkey can display external-login buttons in the default navigation and login UI. If you use a custom login page, you can hide the default navigation buttons with [[HowTos:Hide External Login Buttons|Hide External Login Buttons]].

For a site that must use external sign-in rather than local passwords, configure [[Documentation:Hide Password login|Hide Password login]]. Related Turnkey settings also control whether a user can edit the email proposed during first external sign-in and whether Turnkey shows the external-account confirmation screen.
== Troubleshoot a user stuck on Register ==

A user who authenticates successfully with a provider but remains stuck on the Register page can have stale or incorrect <code>SysUser</code> or <code>SysExternalLogin</code> data. Follow [[Documentation:External login screen problem|External login screen problem]] to remove the old objects, clear the running server state as instructed, and—when applicable—remove the application's approval from the user's provider account before testing again.
== Windows Authentication for intranet sites ==

Windows Authentication is different from Google, Microsoft, and Facebook external sign-in. Use it when an intranet Turnkey site should use existing Kerberos Windows authentication. Configure IIS to perform authentication before the application, following the MDrivenServer IIS authentication guidance, and make the required Turnkey <code>web.config</code> changes for <code>SingleSignOn</code>.
==== Turn on the Google+ API ====

Turn on the Google+ API. 
[[File:Google+ API .png|none|thumb|452x452px]]

=== Microsoft Authentication ===

Additionally, in the left menu, you can select "Branding and properties" to enter a logo and other information, like the '''Home page URL''' of your application.[[File:Platforms settings.jpg|none|thumb|677x677px|Enter the Home Page URL of Your App]]''Extra info:'' You can view an MS account's given App rights at https://microsoft.com/consent

== See also ==

* [[Documentation:TurnkeyUserLogin|Turnkey user login]]
* [[Documentation:SysUserAuthentication|SysUserAuthentication]]
* [[Documentation:Integration|Integration]]
* [[Documentation:External login screen problem|External login screen problem]]
* [[Documentation:Hide Password login|Hide Password login]]
* [[Documentation:MDriven Turnkey Series|MDriven Turnkey Series]]

[[Category:Intermediate-Friendly]]
[[Category:MDriven Turnkey]]
[[Category:Priority 60]]
[[Category:Turnkey How-To Guides]]
[[Category:Using Social Login in Turnkey (Google/Facebook)]]