{"id":13507431,"url":"https://github.com/parroty/oauth2ex","last_synced_at":"2026-02-22T11:04:34.881Z","repository":{"id":19931044,"uuid":"23197569","full_name":"parroty/oauth2ex","owner":"parroty","description":"An OAuth 2.0 client library for elixir.","archived":false,"fork":false,"pushed_at":"2017-11-02T05:36:16.000Z","size":77,"stargazers_count":56,"open_issues_count":2,"forks_count":15,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-21T16:10:39.712Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parroty.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-08-21T18:06:43.000Z","updated_at":"2024-12-10T10:06:57.000Z","dependencies_parsed_at":"2022-08-17T15:45:46.670Z","dependency_job_id":null,"html_url":"https://github.com/parroty/oauth2ex","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/parroty/oauth2ex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parroty%2Foauth2ex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parroty%2Foauth2ex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parroty%2Foauth2ex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parroty%2Foauth2ex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parroty","download_url":"https://codeload.github.com/parroty/oauth2ex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parroty%2Foauth2ex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29688221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T15:51:39.154Z","status":"ssl_error","status_checked_at":"2026-02-21T15:49:03.425Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T02:00:33.429Z","updated_at":"2026-02-22T11:04:34.606Z","avatar_url":"https://github.com/parroty.png","language":"Elixir","funding_links":[],"categories":["Authentication"],"sub_categories":[],"readme":"# OAuth2Ex [![Build Status](https://secure.travis-ci.org/parroty/oauth2ex.png?branch=master \"Build Status\")](https://travis-ci.org/parroty/oauth2ex)\n\n__Note: This repository is not actively maintained. Please check the other libraries like [oauth2](https://hex.pm/packages/oauth2) instead.__\n\nAn OAuth 2.0 client library for elixir. It provides the following functionalities.\n- OAuth token retrieval by communicating with OAuth 2.0 server.\n- Caching the acquired token locally, and refreshing the token when the it's expired.\n- HTTP client access by specifying OAuth2 access token. It uses httpoison (https://github.com/edgurgel/httpoison) as http client library.\n\nThe `OAuth2Ex.Sample` modules contain several examples for OAuth2 providers like Google, GitHub and Dropbox.\n\nIt's pretty much work in progress yet, and APIs will likely to change.\n\n### Setup\nSpecify `:oauth2ex` in the `appliations` and `deps` section in the mix.exs.\n\n```Elixir\ndef application do\n  [ applications: [:logger, :oauth2ex] ]\nend\n\ndefp deps do\n  [\n    {:oauth2ex, github: \"parroty/oauth2ex\"}\n  ]\nend\n```\n\n### Usage\nThe following is an example to call Google's BigQuery API.\n\n#### Manual token retrieval using browser\nAn example to use OAuth2Ex helper methods to retrieve OAuth token.\n\n```Elixir\n# Setup config parameters (retrive required parameters from OAuth 2.0 providers).\nconfig = OAuth2Ex.config(\n  id:            System.get_env(\"GOOGLE_API_CLIENT_ID\"),\n  secret:        System.get_env(\"GOOGLE_API_CLIENT_SECRET\"),\n  authorize_url: \"https://accounts.google.com/o/oauth2/auth\",\n  token_url:     \"https://accounts.google.com/o/oauth2/token\",\n  scope:         \"https://www.googleapis.com/auth/bigquery\",\n  callback_url:  \"urn:ietf:wg:oauth:2.0:oob\",\n  token_store:   %OAuth2Ex.FileStorage{\n                   file_path: System.user_home \u003c\u003e \"/oauth2ex.google.token\"}\n)\n# -\u003e %OAuth2Ex.Config{authorize_url: \"https://accounts.google.com/o/oauth2/auth\"...\n\n# Get authentication parameters.\nIO.puts OAuth2Ex.get_authorize_url(config)\n# -\u003e https://accounts.google.com/o/oauth2/auth?client_id=1...\n#    Open this url using browser and acquire code string.\n\n# Acquire code from browser and a get access token using the code.\ncode = \"xxx...\"\ntoken = OAuth2Ex.get_token(config, code)\n# -\u003e %OAuth2Ex.Token{access_token: \"xxx.......\",\n#    expires_at: 1408467022, expires_in: 3600,\n#    refresh_token: \"yyy....\",\n#    token_type: \"Bearer\"}\n\n# Access API server using token.\nresponse = OAuth2Ex.HTTP.get(token, \"https://www.googleapis.com/bigquery/v2/projects\")\n# -\u003e %HTTPoison.Response{body: \"{\\n \\\"kind\\\": \\\"bigquery#projectList...\n\n# Save token to a file for later use.\nOAuth2Ex.Token.save(token)\n\n# Load previously saved token from the file.\ntoken = OAuth2Ex.Token.load(\n          %OAuth2Ex.FileStorage{file_path: System.user_home \u003c\u003e \"/oauth2ex.google.token\"})\n\n# Refresh access_token from refresh_token.\ntoken = OAuth2Ex.refresh_token(config, token)\n```\n\n#### Automatic token retrieval using local callback server\nAn example to uses local server for automating the token retrieval using OAuth2Ex.Client module.\n\n```Elixir\n# Setup config parameters (retrive required parameters from OAuth 2.0 providers).\nconfig = OAuth2Ex.config(\n  id:            System.get_env(\"GOOGLE_API_CLIENT_ID\"),\n  secret:        System.get_env(\"GOOGLE_API_CLIENT_SECRET\"),\n  authorize_url: \"https://accounts.google.com/o/oauth2/auth\",\n  token_url:     \"https://accounts.google.com/o/oauth2/token\",\n  scope:         \"https://www.googleapis.com/auth/bigquery\",\n  callback_url:  \"http://localhost:4000\",\n  token_store:   %OAuth2Ex.FileStorage{\n                   file_path: System.user_home \u003c\u003e \"/oauth2ex.google.token\"}\n)\n# -\u003e %OAuth2Ex.Config{authorize_url: \"https://accounts.google.com/o/oauth2/auth\"...\n\n# Retrieve token from server. It opens authorize_url using browser,\n# and then waits for the callback on the local server on port 4000.\ntoken = OAuth2Ex.Token.browse_and_retrieve!(config, receiver_port: 4000)\n# -\u003e %OAuth2Ex.Token{access_token: \"...\"\n\n# Access API server using token.\nresponse = OAuth2Ex.HTTP.get(token, \"https://www.googleapis.com/bigquery/v2/projects\")\n# -\u003e %HTTPoison.Response{body: \"{\\n \\\"kind\\\": \\\"bigquery#projectList...\n```\n\n**Note:** There's a case that retrieving token fails with `(OAuth2Ex.Error) Error is returned from the server while getting tokens`, depending on the browser and its version. Please try with other browser if the problem still occurs.\n\n#### Encrypted token storage\n`OAuth2Ex.EncryptedStorage` module can be used as `:token_store` to save `access_token` and `refresh_token` in encrypted format.\n\n```Elixir\ntoken = %OAuth2Ex.Token{access_token: \"aaa\", refresh_token: \"bbb\"}\nstorage = %OAuth2Ex.EncryptedStorage{\n            encryption_key: \"encryption_key\", file_path: \"test/tmp/token_file\"}\nOAuth2Ex.EncryptedStorage.save(original_token, storage)\n```\n\nThe token is saved to the file specified by the `:file_path` using the `encryption_key`, as the following.\n\n```javascript\n{\n  \"access_token\": [\n    \"iN/U\",\n    \"nb1HhOXWlPusXj1yRRgF3g==\"\n  ],\n  \"auth_header\": \"Bearer\",\n  \"config\": null,\n  \"expires_at\": null,\n  \"expires_in\": null,\n  \"refresh_token\": [\n    \"07OM\",\n    \"Ykh2a9vE38XY7yQTwyXQ1g==\"\n  ],\n  \"token_type\": null\n}\n```\n\nThe token file can be loaded as follows.\n\n```Elixir\nstorage = %OAuth2Ex.EncryptedStorage{\n            encryption_key: \"encryption_key\", file_path: \"test/tmp/token_file\"}\ntoken = OAuth2Ex.EncryptedStorage.load(storage)\n```\n\n#### Ensure to refresh token\nSome providers sets expiration date for the access token (ex. Google has 1 hour expiration). For this kind of providers, `OAuth2Ex.ensure_token` can be used. This method checks the expiration date and refresh the token if it's expired, and does nothing if it's not expired.\n\n```Elixir\n\ntoken = OAuth2Ex.ensure_token(config, token)\nresponse = OAuth2Ex.HTTP.get(token, \"https://www.googleapis.com/bigquery/v2/projects\")\n```\n\n#### Helper functions\n`OAuthEx.Client` module provides some helper functions for token retrieval and http accessing.\n- The `retrieve_token` method retrieves the OAuth token and store it locally.\n    - This method-call starts up local web server with specified `:receiver_port` to listen callback from OAuth 2.0 server.\n- The `project` method calls Google's BigQuery API using the pre-acquired OAuth token.\n\n```Elixir\ndefmodule OAuth2Ex.Sample.Google do\n  @moduledoc \"\"\"\n  Sample setting for Google OAuth 2.0 API.\n\n  API: https://developers.google.com/identity/protocols/OAuth2\n  \"\"\"\n\n  use OAuth2Ex.Client\n\n  @doc \"\"\"\n  Client configuration for specifying required parameters\n  for accessing OAuth 2.0 server.\n  \"\"\"\n  def config do\n    OAuth2Ex.config(\n      id:            System.get_env(\"GOOGLE_API_CLIENT_ID\"),\n      secret:        System.get_env(\"GOOGLE_API_CLIENT_SECRET\"),\n      authorize_url: \"https://accounts.google.com/o/oauth2/auth\",\n      token_url:     \"https://accounts.google.com/o/oauth2/token\",\n      scope:         \"https://www.googleapis.com/auth/bigquery\",\n      callback_url:  \"http://localhost:3000\",\n      token_store:   %OAuth2Ex.FileStorage{\n                       file_path: System.user_home \u003c\u003e \"/oauth2ex.google.token\"},\n      client_options: [receiver_port: 3000, timeout: 60_000]\n    )\n  end\n\n  @doc \"\"\"\n  List the projects by calling Google BigQuery API.\n  API: https://cloud.google.com/bigquery/docs/reference/v2/#Projects\n  \"\"\"\n  def projects do\n    response = OAuth2Ex.HTTP.get(token, \"https://www.googleapis.com/bigquery/v2/projects\")\n    response.body |\u003e JSX.decode!\n  end\nend\n```\n\n### Config parameters\n`OAuth2Ex.config` method requires the following parameters.\n\nParameter        | Description\n---------------- | -------------\nid(*)            | Client ID to identify the user to access.\nsecret(*)        | Client secret to authorize the token retrieval.\nauthorize_url(*) | Authorization url to retrieve a code to start authentication.\ntoken_url(*)     | Token url to retrieve token.\nscope            | Scope to identify the allowed scope within the provider's API. Some providers does not have one.\ncallback_url     | Callback url for receiving code, which is redirected from authorize_url.\ntoken_store      | Specify a module to handle saving and loading.\nauth_header      | HTTP Access header for specifying OAuth token. It defaults to \"Bearer\", which sends `Authorization: Bearer xxxx` header.\nresponse_type    | Response type when accessing authorization url. It defaults to \"code\".\nclient_options   | Additional options for clients.\n\n(*) indicates mandatory parameter.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparroty%2Foauth2ex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparroty%2Foauth2ex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparroty%2Foauth2ex/lists"}