Why? 🤷

We needed a much simpler and extensively documented way to add "Sign-in with Google" capability to our Elixir App(s). <br />

What? 💭

An Elixir package that seamlessly handles Google OAuth2 Authentication/Authorization in as few steps as possible. <br /> Following best practices for security & privacy and avoiding complexity by having sensible defaults for all settings.

We built a lightweight solution that only does one thing and is easy for complete beginners to understand/use. <br /> There were already several available options for adding Google Auth to apps on hex.pm/packages?search=google <br /> that all added far too implementation steps (complexity) and had incomplete documentation (@doc false) and testing. <br /> e.g: github.com/googleapis/elixir-google-api which is a "generated" client and is considered "experimental". <br /> We have drawn inspiration from several sources including code from other programming languages to build this package. This result is much simpler than anything else and has both step-by-step instructions and an complete working example App including how to encrypt tokens for secure storage to help you ship your app fast.

Who? 👥

This module is for people building apps using Elixir/Phoenix who want to ship the "Sign-in with Google" feature faster and more maintainably.

It's targetted at complete beginners with no prior experience/knowledge of auth "schemes" or "strategies". <br /> Just follow the detailed instructions and you'll be up-and running in 5 minutes.

How? ✅

You can add Google Authentication to your Elixir App using elixir_auth_google <br /> in under 5 minutes by following these 5 easy steps:

1. Add the hex package to deps 📦

Open your project's mix.exs file and locate the deps (dependencies) section. <br /> Add a line for :elixir_auth_google in the deps list:

def deps do
  [
    {:elixir_auth_google, "~> 1.0.0"}
  ]
end

Once you have added the line to your mix.exs, remember to run the mix deps.get command in your terminal to download the dependencies.

2. Create Google APIs Application OAuth2 Credentials 🆕

Create a Google Application if you don't already have one, generate the OAuth2 Credentials for the application and save the credentials as environment variables accessible by your app.

Note: There are a few steps to creating a set of Google APIs credentials, so if you don't already have a Google App, we created the following step-by-step guide to make it quick and relatively painless: create-google-app-guide.md <br /> Don't be intimidated by all the buzz-words; it's quite straightforward. And if you get stuck, ask for help!

By the end of this step you should have these two environment variables set:

GOOGLE_CLIENT_ID=631770888008-6n0oruvsm16kbkqg6u76p5cv5kfkcekt.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=MHxv6-RGF5nheXnxh1b0LNDq

⚠️ Don't worry, these keys aren't valid. They are just here for illustration purposes.

3. Create a GoogleAuthController in your Project 📝

🔜 Simplified instructions coming soon!

Create a new endpoint matching the google_redirect_uri. On this endpoint you can exchange the google code for the user's token and then get the user profile:

  def index(conn, %{"code" => code}) do
    token = ElixirAuthGoogle.get_token(code)
    profile = ElixirAuthGoogle.get_user_profile(token["access_token"])
    render(conn, "index.html", profile: profile)
  en

Set up :elixir_auth_google configuration values google_client_id, google_scope ("profile" by default) and google_redirect_uri (the same as the one defined in the google application)

for example in config.exs:

config :elixir_auth_google,
  google_client_id: <YOUR-CLIENT-ID-HERE>,
  google_scope: "profile",
  google_redirect_uri: <REDIRECT_URI>,

Example code:

4. Create the /auth/google/callback Endpoint 📍

Open your router.ex file and add the /auth/google/callback endpoint.

5. Add the "Login with Google" Button to your Template ✨

Example code:

Done!

Implementation Details 💡

If you want to dive a bit deeper into understanding how this package works, You can read and grok the code in under 10 minutes: /lib/elixir_auth_google.ex

If you are using the the elixir_auth_google package in a Phoenix application (the most popular use case), these implementation details might be helpful.

Generating Phoenix Session Key (SECRET_KEY_BASE) and Encryption Keys

To generate a cryptographically secure session key, open your terminal, run the command mix phx.gen.secret and paste the resulting string

Notes 📝

• Official Docs for Google Identity Platform: https://developers.google.com/identity/choose-auth
  • Web specific sample code (JS): https://developers.google.com/identity/sign-in/web
• Google Sign-In for server-side apps: https://developers.google.com/identity/sign-in/web/server-side-flow
• Using OAuth 2.0 for Web Server Applications: https://developers.google.com/identity/protocols/OAuth2WebServer
• Google Auth Branding Guidelines: https://developers.google.com/identity/branding-guidelines <br /> Only two colors are permitted for the button: white#FFFFFF and blue#4285F4

Fun Facts 📈📊

Unlike other "social media" companies, Google/Alphabet does not report it's Monthly Active Users (MAUs) or Daily Active Users (DAUs) however they do release stats in drips in their Google IO or YouTube events. The following is a quick list of facts that make adding Google Auth to your App a compelling business case:

• As of May 2019, there are over 2.5 Billionactive Android devices; 87% global market share. All these people have Google Accounts in order to use Google services.
• YouTube has 2 billion monthly active YouTube users (signed in with a Google Account).
• Gmail has 1.5 Billion monthly active users a 27% share of the global email client market.
• 65% of Small and Medium sized businesses use Google Apps for business.
• 90%+ of startups use Gmail. This is a good proxy for "early adopters".
• 68% of schools in the US use Google Classroom and related G-suite products. <br /> So the next generation of internet/app users have Google accounts.
• Google has 90.46% of the search engine market share worldwide. 95.4% on Mobile.

Of the 4.5 billion internet users (58% of the world population), around 3.2 billion (72%) have a Google account. 90%+ of tech "early adopters" use Google Apps which means that adding Google OAuth Sign-in is the logical choice for most Apps.

Privacy Concerns? 🔐

A common misconception is that adding Google Auth Sign-in sends a user's application data to Google. This is false and App developers have 100% control over what data is sent to (stored by) Google. An App can use Google Auth to authenticate a person (identify them and get read-only access to their personal details like first name and email address) without sending any data to Google. Yes, it will mean that Google "knows" that the person is using your App, but it will not give Google any insight into how they are using it or what types of data they are storing in the App. Privacy is maintained. So if you use the @dwyl app to plan your wedding or next holiday, Google will not have any of that data and will not serve any annoying ads based on your project/plans.