Skip to content

Update links in README #157

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arunagw merged 1 commit into from
Jul 3, 2026
Merged

Update links in README #157

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 34 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,20 @@
# OmniAuth Twitter

[![Gem Version](https://badge.fury.io/rb/omniauth-twitter.svg)](http://badge.fury.io/rb/omniauth-twitter)
[![Code Climate](https://codeclimate.com/github/arunagw/omniauth-twitter.png)](https://codeclimate.com/github/arunagw/omniauth-twitter)
This gem contains the X (formerly Twitter) strategy for OmniAuth.

This gem contains the Twitter strategy for OmniAuth.
X supports a few different methods of integration. This strategy implements the browser variant of the "Sign in with Twitter" flow.

Twitter offers a few different methods of integration. This strategy implements the browser variant of the "[Sign in with Twitter](https://dev.twitter.com/web/sign-in/implementing)" flow.
This strategy implements X's OAuth 1.0a flow and returns an OAuth access token and access token secret for the authenticated user.

Twitter uses OAuth 1.0a. Twitter's developer area contains ample documentation on how it implements this, so check that out if you are really interested in the details.
X's developer documentation contains detailed information about its OAuth implementation if you are interested in the protocol details.

## Before You Begin

You should have already installed OmniAuth into your app; if not, read the [OmniAuth README](https://github.com/omniauth/omniauth) to get started.
You should have already installed OmniAuth into your app; if not, read the OmniAuth README(https://github.com/omniauth/omniauth) to get started.

Now sign in into the [Twitter developer area](https://dev.twitter.com/apps) and create an application. Take note of your API Key and API Secret (not the Access Token and Access Token Secret) because that is what your web application will use to authenticate against the Twitter API. Make sure to set a callback URL or else you may get authentication errors. (It doesn't matter what it is, just that it is set.)
Now sign in to the X Developer Portal(https://developer.x.com/apps) and create an application. Take note of your API Key and API Secret (not the Access Token and Access Token Secret) because that is what your web application will use to authenticate against the X API. Make sure to configure a callback URL in the X Developer Portal or else you may get authentication errors. The configured callback URL should match the callback URL used by your application.

For production applications, it is recommended to store API credentials using Rails credentials, environment variables, or another secure secret management solution.

## Using This Strategy

Expand All @@ -26,7 +27,7 @@ gem 'omniauth-twitter'
If you need to use the latest HEAD version, you can do so with:

```ruby
gem 'omniauth-twitter', :github => 'arunagw/omniauth-twitter'
gem 'omniauth-twitter', github: 'arunagw/omniauth-twitter'
```

Next, tell OmniAuth about this provider. For a Rails app, your `config/initializers/omniauth.rb` file should look like this:
Expand All @@ -37,29 +38,39 @@ Rails.application.config.middleware.use OmniAuth::Builder do
end
```

Replace `"API_KEY"` and `"API_SECRET"` with the appropriate values you obtained [earlier](https://apps.twitter.com).
Alternatively, you may use environment variables:

```ruby
Rails.application.config.middleware.use OmniAuth::Builder do
provider :twitter,
ENV.fetch("TWITTER_API_KEY"),
ENV.fetch("TWITTER_API_SECRET")
end
```

Replace `"API_KEY"` and `"API_SECRET"` with the appropriate values you obtained earlier.

## Authentication Options

Twitter supports a [few options](https://developer.twitter.com/en/docs/basics/authentication/api-reference/authenticate) when authenticating. Usually you would specify these options as query parameters to the Twitter API authentication URL (`https://api.x.com/oauth/authenticate` by default). With OmniAuth, of course, you use `http://yourapp.com/auth/twitter` instead. Because of this, this OmniAuth provider will pick up the query parameters you pass to the `/auth/twitter` URL and re-use them when making the call to the Twitter API.
X supports a [few options](https://docs.x.com/fundamentals/authentication/api-reference) when authenticating. Usually you would specify these options as query parameters to the X API authentication URL (`https://api.x.com/oauth/authenticate` by default). With OmniAuth, of course, you use `http://yourapp.com/auth/twitter` instead. Because of this, this OmniAuth provider will pick up the query parameters you pass to the `/auth/twitter` URL and re-use them when making the call to the X API.

The options are:

* **force_login** - This option sends the user to a sign-in screen to enter their Twitter credentials, even if they are already signed in. This is handy when your application supports multiple Twitter accounts and you want to ensure the correct user is signed in. *Example:* `http://yoursite.com/auth/twitter?force_login=true`
- **force_login** - This option sends the user to a sign-in screen to enter their X credentials, even if they are already signed in. This is handy when your application supports multiple X accounts and you want to ensure the correct user is signed in. _Example:_ `http://yoursite.com/auth/twitter?force_login=true`

* **screen_name** - This option implies **force_login**, except the screen name field is pre-filled with a particular value. *Example:* `http://yoursite.com/auth/twitter?screen_name=jim`
- **screen_name** - This option implies **force_login**, except the screen name field is pre-filled with a particular value. _Example:_ `http://yoursite.com/auth/twitter?screen_name=jim`

* **lang** - The language used in the Twitter prompt. This is useful for adding i18n support since the language of the prompt can be dynamically set for each user. *Example:* `http://yoursite.com/auth/twitter?lang=pt`
- **lang** - The language used in the X prompt. This is useful for adding i18n support since the language of the prompt can be dynamically set for each user. _Example:_ `http://yoursite.com/auth/twitter?lang=pt`

* **secure_image_url** - Set to `true` to use https for the user's image URL. Default is `false`.
- **secure_image_url** - Set to `true` to use https for the user's image URL. Default is `false`.

* **image_size**: This option defines the size of the user's image. Valid options include `mini` (24x24), `normal` (48x48), `bigger` (73x73) and `original` (the size of the image originally uploaded). Default is `normal`.
- **image_size**: This option defines the size of the user's image. Valid options include `mini` (24x24), `normal` (48x48), `bigger` (73x73) and `original` (the size of the image originally uploaded). Default is `normal`.

* **x_auth_access_type** - This option (described [here](https://developer.twitter.com/en/docs/basics/authentication/api-reference/request_token)) lets you request the level of access that your app will have to the Twitter account in question. *Example:* `http://yoursite.com/auth/twitter?x_auth_access_type=read`
- **x_auth_access_type** - This option (described in the X API documentation) lets you request the level of access that your app will have to the X account in question. _Example:_ `http://yoursite.com/auth/twitter?x_auth_access_type=read`

* **use_authorize** - There are actually two URLs you can use against the Twitter API. As mentioned, the default is `https://api.x.com/oauth/authenticate`, but you also have `https://api.twitter.com/oauth/authorize`. Passing this option as `true` will use the second URL rather than the first. What's the difference? As described [here](https://developer.twitter.com/en/docs/basics/authentication/api-reference/authenticate), with `authenticate`, if your user has already granted permission to your application, Twitter will redirect straight back to your application, whereas `authorize` forces the user to go through the "grant permission" screen again. For certain use cases this may be necessary. *Example:* `http://yoursite.com/auth/twitter?use_authorize=true`. *Note:* You must have "Allow this application to be used to Sign in with Twitter" checked in [your application's settings](https://dev.twitter.com/apps) - without it your user will be asked to authorize your application each time they log in.
- **use_authorize** - There are actually two URLs you can use against the X API. As mentioned, the default is `https://api.x.com/oauth/authenticate`, but you also have `https://api.x.com/oauth/authorize`. Passing this option as `true` will use the second URL rather than the first. With authenticate, if your user has already granted permission to your application, X may redirect straight back to your application, whereas authorize forces the user to go through the authorization screen again. For certain use cases this may be necessary. _Example:_ `http://yoursite.com/auth/twitter?use_authorize=true`.

Here's an example of a possible configuration where the user's original profile picture is returned over https, the user is always prompted to sign-in and the default language of the Twitter prompt is changed:
Here's an example of a possible configuration where the user's original profile picture is returned over https, the user is always prompted to sign-in and the default language of the the X authentication prompt:

```ruby
Rails.application.config.middleware.use OmniAuth::Builder do
Expand All @@ -76,7 +87,8 @@ end
```

## Authentication Hash
An example auth hash available in `request.env['omniauth.auth']`:

The structure below is a representative example of the authentication hash available in `request.env['omniauth.auth']`. Fields returned by X may vary depending on API permissions, user settings, and platform changes.

```ruby
{
Expand All @@ -85,6 +97,7 @@ An example auth hash available in `request.env['omniauth.auth']`:
: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.",
Expand All @@ -94,7 +107,7 @@ An example auth hash available in `request.env['omniauth.auth']`:
}
},
:credentials => {
:token => "a1b2c3d4...", # The OAuth 2.0 access token
:token => "a1b2c3d4...", # The OAuth 1.0a access token
:secret => "abcdef1234"
},
:extra => {
Expand Down Expand Up @@ -155,9 +168,7 @@ Ryan Bates has put together an excellent RailsCast on OmniAuth:

## Supported Rubies

OmniAuth Twitter is tested under 2.1.x, 2.2.x and JRuby.

If you use its gem on ruby 1.9.x, 2.0.x, or Rubinius use version v1.2.1 .
OmniAuth Twitter is tested under Ruby 2.6 through 4.0 and JRuby.

## Contributing

Expand Down
Loading