Version 1.1 - Updated on 8/11/2016
The standard OAuth 2.0 authorization helper. Use this if you’re writing a web app.
Classes:
#initialize(consumer_key, consumer_secret, redirect_uri, session, csrf_token_session_key, locale = nil) ⇒ SdkOAuth2Flow
consumer_key
: Your application’s Keyconsumer_secret
: Your application’s Secretredirect_uri
: The URI to which the server will redirect the user after the user has authorized your app. This URI must be HTTPs-based and pre-registered with the servers, though localhost URIs are allowed without pre-registration and can be either HTTP or HTTPS.session
: A hash that represents the current web app session. It is used to save the CSRF token.locale
: The locale of the user currently using your app, such as en
or en_US
.
def initialize(consumer_key, consumer_secret, redirect_uri, session, csrf_token_session_key, locale=nil)
super(consumer_key, consumer_secret, locale)
if not redirect_uri.is_a?(String)
raise ArgumentError, "redirect_uri must be a String, got #{consumer_secret.inspect}"
end
@redirect_uri = redirect_uri
@session = session
@csrf_token_session_key = csrf_token_session_key
end
finish
#finish(query_params) ⇒ Object
Call this method after the user has visited the authorize URL, granted your app access to his or her content and then has been redirected to your redirect URI.
query_params
: The query params on the GET request to your redirect URI.Returns a tuple of access_token
, user_id
and url_state
:
access_token
which can be used to construct an SdkClient
.user_id
is the user ID of the user that jst approved your app.url_state
is the value you originally passed in to start()
.Can throw the following:
BadRequestError
BadStateError
CsrfError
NotApprovedError
ProviderError
SdkError
def finish(query_params)
csrf_token_from_session = @session[@csrf_token_session_key]
# Check well-formedness of request.
state = query_params['state']
if state.nil?
raise BadRequestError.new("Missing query parameter 'state'.")
end
error = query_params['error']
error_description = query_params['error_description']
code = query_params['code']
if not error.nil? and not code.nil?
raise BadRequestError.new("Query parameters 'code' and 'error' are both set;" +
" only one must be set.")
end
if error.nil? and code.nil?
raise BadRequestError.new("Neither query parameter 'code' or 'error' is set.")
end
# Check CSRF token
if csrf_token_from_session.nil?
raise BadStateError.new("Missing CSRF token in session.");
end
unless csrf_token_from_session.length > 20
raise RuntimeError.new("CSRF token unexpectedly short: #{csrf_token_from_session.inspect}")
end
split_pos = state.index('|')
if split_pos.nil?
given_csrf_token = state
url_state = nil
else
given_csrf_token, url_state = state.split('|', 2)
end
if not Sdk::safe_string_equals(csrf_token_from_session, given_csrf_token)
raise CsrfError.new("Expected #{csrf_token_from_session.inspect}, " +
"got #{given_csrf_token.inspect}.")
end
@session.delete(@csrf_token_session_key)
# Check for error identifier
if not error.nil?
if error == 'access_denied'
# The user clicked "Deny"
if error_description.nil?
raise NotApprovedError.new("No additional description from server.")
else
raise NotApprovedError.new("Additional description from server: #{error_description}")
end
else
# All other errors.
full_message = error
if not error_description.nil?
full_message += ": " + error_description
end
raise ProviderError.new(full_message)
end
end
# If everything went ok, make the network call to get an access token.
access_token, user_id = _finish(code, @redirect_uri)
return access_token, user_id, url_state
end
start
#start(url_state = nil) ⇒ Object
Starts the OAuth 2.0 authorizaton process, which involves redirecting the user to the returned “authorization URL”. When the user then either approves or denies your app access, the user will be redirected to the redirect_uri
you provided to the constructor. Call finish()
to complete the process.
This function saves a CSRF token to the session and csrf_token_session_key
you provided to the constructor. This CSRF token is checked on finish()
to prevent request forgery.
url_state
: Any data you would like to keep in the URL through the authorization process. This exact value is returned to you when you call finish()
.Returns the URL to redirect the user to.
def start(url_state=nil)
unless url_state.nil? or url_state.is_a?(String)
raise ArgumentError, "url_state must be a String"
end
csrf_token = SecureRandom.base64(16)
state = csrf_token
unless url_state.nil?
state += "|" + url_state
end
@session[@csrf_token_session_key] = csrf_token
return _get_authorize_url(@redirect_uri, state)
end
Copyright © 2015-2017, Verizon and/or its Licensors. All rights reserved.