XIVAuth OmniAuth Strategy

Plug XIVAuth into your Omniauth protected application simply and efficiently. This strategy supports both user-based and character-based flows.

Please be sure to refer to the XIVAuth documentation for information on how it provides OAuth2 services and how to use scopes.

Installation

Add the following line to your application's Gemfile:

gem 'omniauth-xivauth'

Usage

This gem is standard for OmniAuth strategies. An example provider:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :xivauth, ENV['XIVAUTH_CLIENT_ID'], ENV['XIVAUTH_CLIENT_SECRET'],
           scope: 'user user:email character:all'
end

By default, this strategy will request the user scope. Additional scopes may be requested through the scope option. Generally speaking, applications will likely want one of character, user, or user character:all.

Consumers must also take care to expect data in odd formats. Users may approve/reject certain scopes, or share many/one/no characters depending on their preferences. Applications should be prepared to handle these cases gracefully.

Auth Hash Information

The format of the auth hash will differ based on the scope(s) requested, namely whether user or character is chosen. In nearly all cases, the following structure will be returned. Note that user information will not be returned unless the user scope is requested and granted.

{
  provider: "xivauth",
  uid: "53f5faa3-3a9a-4d1e-91e5-80626b1a7da1",  # user id
  info: {  # information about the user
    name: "StandardUserTest",
    email: "someuser@invalid.test",  # nil unless `user:email` was granted and the address is verified
    image: "https://cdn.xivauth.test/dummydata/standard-user-avatar.png"
  },
  extra: {
    raw_info: { 
      # Alias of `extra.user` hash. 
    },
    user: {
      # API response from XIVAuth's /api/v1/user endpoint. 
    },
    characters: nil # populated only if a character scope was granted
  }
}

However, if an application is using just the character scope, the auth hash will instead present the chosen character's identity as the authoritative object. This allows for applications that only care about character information to treat inbound characters as their own first-class identities.

{
  provider: "xivauth",
  uid: "7bBfWdAGQYQ3mtHzalpgQOyFdTk",  # character persistent key
  info: {
    name: "Mikoto Jinba",
    image: "https://cdn.xivauth.test/dummydata/mikoto-portrait.png",
    location: "Behemoth",  # Home world of the character
    urls: {
      lodestone: "https://na.finalfantasyxiv.com/lodestone/character/32080755/"
    },
    lodestone_id: "32080755"
  },
  extra: {
    raw_info: { 
      # Alias of `extra.characters` array's first (and only) element.
    },
    user: nil,  # will always be null; this is a character-only auth hash
    characters: [
      { "persistent_key" => "7bBfWdAGQYQ3mtHzalpgQOyFdTk", "name" => "Mikoto Jinba" }
    ]
  }
}

Contributing

Contributions are welcome! Feel free to submit Issues and PRs to improve this gem if you spot something that can be made better. Note, however, that this gem is ultimately a transparent wrapper around the XIVAuth API. Upstream changes should likely be filed against that project instead.

Please make sure tests pass (bundle exec rspec) and that Rubocop is happy (bundle exec rubocop) before submitting a PR.

License

Licensed under the MIT license.