# omniauth-twitter: an OmniAuth strategy for the X OAuth 1.0a flow > omniauth-twitter is a Ruby gem that plugs the browser based Sign in with X flow into OmniAuth, returning an OAuth 1.0a access token and secret for the authenticated user. It supports the query parameter options X exposes, such as force_login, screen_name, lang and use_authorize, and it is configured with a provider block in a Rails initializer. **arunagw/omniauth-twitter** — OmniAuth strategy for Twitter - Repository: https://github.com/arunagw/omniauth-twitter - Website: http://arunagw.github.io/omniauth-twitter/ - Stars: 577 · Forks: 163 - Language: Ruby - License: not declared - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/arunagw-omniauth-twitter ## What the strategy implements and what it does not omniauth-twitter is the OmniAuth strategy for X, previously Twitter. The gem contains the strategy itself, and the project homepage is at arunagw.github.io/omniauth-twitter. The important scope statement is in the documentation: X supports a few different methods of integration, and this strategy implements the browser variant of the Sign in with Twitter flow. It implements X's OAuth 1.0a flow and returns an OAuth access token and access token secret for the authenticated user. So this is an OAuth 1.0a client, not an OAuth 2.0 or OpenID Connect one. That distinction is the first thing to check, because X supports more than one integration path and the choice of strategy follows from which one you need. For a request to the API on behalf of the user, the OAuth 1.0a token and secret are what you get back, and they go into the credentials section of the OmniAuth auth hash. The strategy assumes OmniAuth is already installed in your app, and the documentation points you at the OmniAuth README if it is not. It also points at X's developer documentation for the protocol details. The users are Ruby and Rails applications that have already chosen OmniAuth as their authentication layer and need X as one provider among several. The project targets the classic middleware approach, with the provider registered in a Rails initializer. ## Registering the application and the callback URL that breaks if it mismatches The setup has one genuinely important step and several easy-to-miss details. You sign in to the X Developer Portal and create an application. You take note of your API Key and API Secret, and the documentation is explicit that these are not the Access Token and Access Token Secret, because those are what your web application uses to authenticate against the X API. Then you configure a callback URL in the X Developer Portal, or you may get authentication errors. The configured callback URL should match the callback URL used by your application. That is a two-sided constraint, and a mismatch between the two is the classic reason an OmniAuth Twitter integration appears to work and then fail at the redirect. For production applications, the documentation recommends storing the API credentials using Rails credentials, environment variables, or another secure secret management solution. That advice matters because the same key and secret authenticate every user of your application. The documentation also points out that X's own developer documentation contains detailed information about its OAuth implementation for anyone who wants the protocol details, which is the right place to go if the redirect behaviour surprises you rather than guessing at the request parameters. ## Adding the gem and registering the provider The gem goes into your Gemfile: ```ruby gem 'omniauth-twitter' ``` If you need the latest HEAD version, the documentation gives the git form: ```ruby gem 'omniauth-twitter', github: 'arunagw/omniauth-twitter' ``` Then you tell OmniAuth about the provider. In a Rails app, the config/initializers/omniauth.rb file holds the OmniAuth::Builder middleware block: ```ruby Rails.application.config.middleware.use OmniAuth::Builder do provider :twitter, "API_KEY", "API_SECRET" end ``` And the environment variable variant, which is the one most projects end up using: ```ruby Rails.application.config.middleware.use OmniAuth::Builder do provider :twitter, ENV.fetch("TWITTER_API_KEY"), ENV.fetch("TWITTER_API_SECRET") end ``` Note the provider symbol is :twitter rather than :x, even though the platform is now called X. That is a small thing that trips people up when they copy configuration from a newer guide, and the authentication hash carries the same provider value. The ENV.fetch form is also better than ENV access directly, because a missing key becomes an exception at boot rather than a nil that surfaces later as a confusing authentication failure. The documentation tells you to replace "API_KEY" and "API_SECRET" with the values you obtained earlier. The repository is a conventional gem layout, with a gemspec, a Gemfile, a Rakefile, a .rspec file, lib/ and spec/ directories, a CHANGELOG.md and a CONTRIBUTING.md. ## The X options that pass through as query parameters X exposes several authentication options, and the strategy handles them in a particular way. Normally you would specify these as query parameters on the X API authentication URL, which is https://api.x.com/oauth/authenticate by default. With OmniAuth you use http://yourapp.com/auth/twitter instead, and the strategy picks up the query parameters you pass to the /auth/twitter URL and re-uses them when making the call to the X API. That pass-through is the mechanism, and it means the options are per request rather than global configuration. The options are these. force_login sends the user to a sign-in screen to enter their X credentials even if they are already signed in, which is handy when your application supports multiple X accounts and you want to be sure the right one is used. screen_name implies force_login, except that the screen name field is pre-filled with a particular value. lang sets the language used in the X prompt, which is useful for i18n since it can be set per user. secure_image_url, set to true, uses https for the user image URL, and the default is false. image_size defines the size of the user image, with mini at 24x24, normal at 48x48, bigger at 73x73 and original at the uploaded size, and the default is normal. x_auth_access_type requests the level of access your app will have to the account, as described in the X API documentation. use_authorize switches to the second of the two URLs, https://api.x.com/oauth/authorize, instead of the default authenticate. With authenticate, a user who has already granted permission may be redirected straight back to your application, whereas authorize forces the authorization screen again, which is necessary for certain use cases. The combination is expressed through the authorize_params option, as in this example where the original profile picture is returned over https, the user is always prompted to sign in, and the prompt language is set: ```ruby Rails.application.config.middleware.use OmniAuth::Builder do provider :twitter, "API_KEY", "API_SECRET", { :secure_image_url => 'true', :image_size => 'original', :authorize_params => { :force_login => 'true', :lang => 'pt' } } end ``` ## What the authentication hash gives you, and what it might not The result lands in request.env['omniauth.auth'], and the documentation shows the structure as a representative example. The first part of it looks like this: ```ruby { :provider => "twitter", :uid => "123456", :info => { :nickname => "johnqpublic", # screen name :name => "John Q Public", :email => "john@example.com", # only present if your app has email permission and the user has granted it :location => "Anytown, USA", :image => "http://si0.twimg.com/sticky/default_profile_images/default_profile_2_normal.png", :description => "a very normal guy.", :urls => { :Website => nil, :Twitter => "https://twitter.com/johnqpublic" } }, ``` The credentials section carries the token and secret, with the token being the OAuth 1.0a access token, and the extra section holds an OAuth::AccessToken object plus the raw_info hash with the full profile payload. Two cautions are in the documentation. The email field is only present if your app has email permission and the user has granted it, so any code that reads info.email without a fallback will break for a user who has not granted that scope. And the documentation states that fields returned by X may vary depending on API permissions, user settings, and platform changes. That second point deserves emphasis. The hash is not a stable contract, it is a snapshot of what X chose to return to your application under your permissions at that moment. Treat it as such, and read the fields you need with a fallback rather than assuming the shape. ## Where omniauth-twitter is the wrong choice The first limit is the protocol generation. This strategy implements the OAuth 1.0a flow, and the documentation does not describe an OAuth 2.0 path. If you are building something new and your requirement is an OpenID Connect identity token, or you need the newer scoped access and refresh token model, this gem is the wrong shape and the effort belongs in a different strategy. The second is the option surface. Every X specific option is a query parameter you have to remember to pass, and because they are per request rather than global, a feature like forcing a sign in screen has to be threaded through your own application code. The default behaviour of the authenticate URL, where a user who has already granted permission is redirected straight back, is exactly the kind of surprise that shows up as a support ticket rather than as an exception. The third is that X's own platform changes affect the payload. The documentation says outright that fields returned by X may vary depending on API permissions, user settings and platform changes. A strategy that returns whatever the remote API returns cannot guarantee a fixed hash, and a consumer that assumes the example shape will break eventually. The fourth is operational. The gem is a thin adapter over a remote service whose developer portal, permissions model and callback rules are all outside your control, and the strategy's own maintenance is light. The repository is not archived and the last push was on 2026-07-06, so the code is not being worked on very actively, and the repository publishes no GitHub releases, so there is no tagged version to pin. Compare that with a general purpose OAuth 2.0 client library. The difference in approach is that a general library gives you the protocol mechanics and leaves the provider specifics to you, while this strategy encodes one provider's flow, its options and its request and response shapes so that you do not have to. That is exactly the value when you want X and exactly the problem when X's protocol changes underneath a newer flow you needed instead. ## Licence, packaging and the questions to settle before you wire it up The licence is the one piece of information the repository does not record, and the platform shows it as unknown. You should confirm the terms yourself rather than assume a standard MIT or BSD grant. The gem is packaged in the conventional way, with omniauth-twitter.gemspec at the root, the strategy code under lib/, and specs under spec/ with a.rspec file, which means the strategy has a test suite and the project is set up for RSpec. There is a CHANGELOG.md and a CONTRIBUTING.md, both of which are the places to look before you pin a version, and the.github/ directory holds the workflows. What to settle before you wire it up is short and specific. Register the application in the X Developer Portal and note the API Key and API Secret, not the access token pair. Configure the callback URL there to match the one your application uses, and treat a mismatch as the first thing to check when the redirect fails. Put the key and secret in Rails credentials or environment variables rather than in the initializer, and use the ENV.fetch form so a missing key fails at boot. Then decide what your application actually needs from the hash. If you need the email address, you need the app to have email permission and the user to have granted it, and you need a fallback for when it is absent. And if you need the user to always see the sign in screen, pass force_login, or you will get the redirect straight back behaviour described in the documentation. The last thing to check is the version. With no GitHub releases published, pin the gem version you deploy and read the CHANGELOG.md before upgrading. ## Conclusion omniauth-twitter fits a Ruby application that already uses OmniAuth and needs X sign in as one of several identity providers, especially if it needs the X specific options such as force_login or per user language on the prompt. It does not fit a new application that needs the newer OAuth 2.0 and OpenID Connect flow, because this strategy implements the OAuth 1.0a flow, and the project does not document an OAuth 2.0 path. Before you adopt it, register the application in the X Developer Portal and make the configured callback URL match the one your app uses, store the API key and secret through a secret manager rather than in the initializer, and confirm the fields you actually need are present in the authentication hash, since the documentation notes that what X returns depends on your API permissions and on the user. ## FAQ ### What does the omniauth-twitter strategy return after a successful sign in? It implements X's OAuth 1.0a flow and returns an OAuth access token and access token secret for the authenticated user. The result is available in request.env['omniauth.auth'], with the token and secret in the credentials section and the full profile payload under extra.raw_info. ### How do I add omniauth-twitter to a Rails application? Add gem 'omniauth-twitter' to your Gemfile, then register the provider in config/initializers/omniauth.rb with a provider :twitter block inside Rails.application.config.middleware.use OmniAuth::Builder. You can pass the key and secret literally or with ENV.fetch calls. ### Which authentication options does omniauth-twitter pass through to X? The strategy picks up query parameters passed to the /auth/twitter URL and re-uses them when calling the X API. The options are force_login, screen_name, lang, secure_image_url, image_size, x_auth_access_type and use_authorize, and they can be set per request or in the authorize_params block of the provider configuration. ### Why does my X sign in redirect straight back to my application? The default authentication URL is https://api.x.com/oauth/authenticate, and with it a user who has already granted permission may be redirected straight back. Passing use_authorize as true switches to https://api.x.com/oauth/authorize, which forces the authorization screen again. ### Is the email address always present in the omniauth-twitter auth hash? No. The documentation says the email field is only present if your app has email permission and the user has granted it, and that fields returned by X may vary depending on API permissions, user settings and platform changes. ### What licence does omniauth-twitter use? The repository does not record a licence on the platform, so check the terms before adopting it. The repository is not archived, the last push was on 2026-07-06, and it publishes no GitHub releases. ## Sources - [arunagw/omniauth-twitter on GitHub](https://github.com/arunagw/omniauth-twitter) - [Issues](https://github.com/arunagw/omniauth-twitter/issues) - [Project website](http://arunagw.github.io/omniauth-twitter/) - [README](https://github.com/arunagw/omniauth-twitter/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/arunagw-omniauth-twitter