Class: Soteria::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/soteria/client.rb

Instance Method Summary collapse

Constructor Details

#initialize(cert_file, cert_key_file, password, should_log) ⇒ Client

To use Soteria, SSL certificates for Symantec VIP Services are required. To obtain a certificate go to manager.vip.symantec.com/ and log in. From the dashboard go to Account -> Manage VIP Certificates -> Request a Certificate. From there follow the directions to create a new certificate. On the download screen select the PKCS#12 format and enter the password you would like to use to secure the certificate. Once the certificate is downoaded run these two commands to split the PKCS#12 certificate into a public and private key.

Parameters:

  • cert_file (String) —

    The relative path to the SSL cert on the server.

  • cert_key_file (String) —

    The relative path to the SSL cert key on the server.

  • password (String) —

    The password for the cert key file.

  • should_log (Boolean) —

    if the client should log everything. This is good for development.



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/soteria/client.rb', line 23

def initialize(cert_file, cert_key_file, password, should_log)
  # @cert_file = cert_file
  # @cert_key_file = cert_key_file
  # @cert_key_password = password

  #[:get_server_time, :get_user_info, :get_credential_info, :get_temporary_password_attributes, :poll_push_status]
  @query_client = Utilities.create_client('http://webdev.cse.msu.edu/~yehanlin/vip/vipuserservices-query-1.7.wsdl', should_log, cert_file, cert_key_file, password)

  #[:authenticate_user, :authenticate_user_with_push, :authenticate_credentials, :evaluate_risk, :confirm_risk, :deny_risk, :check_otp]
  @auth_client = Utilities.create_client('http://webdev.cse.msu.edu/~yehanlin/vip/vipuserservices-auth-1.7.wsdl', should_log, cert_file, cert_key_file, password)

  #[:create_user, :update_user, :delete_user, :clear_user_pin, :add_credential, :update_credential, :remove_credential, :set_temporary_password, :clear_temporary_password, :set_temporary_password_attributes, :send_otp, :register]
  @management_client = Utilities.create_client('http://webdev.cse.msu.edu/~yehanlin/vip/vipuserservices-mgmt-1.7.wsdl', should_log, cert_file, cert_key_file, password)

  @auth = Auth.new(cert_file, cert_key_file, password, should_log)

  @push = Push.new
  @sms = SMS.new
  @credential = Credential.new
  @user = User.new
end

Instance Method Details

#activate_token(token_id) ⇒ Hash

Call when a newly registered SMS OTP credential requires activation

Parameters:

  • token_id (Int) —

    Specifies the phone number that identifies the credential to the VIP Web Services. Do not use spaces or dashes.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



360
361
362
 
# File 'lib/soteria/client.rb', line 360

def activate_token(token_id)
  @auth.activate_token(token_id)
end

#add_credential(user_id, credential_id, credential_type, options) ⇒ Hash

Add a credential to an existing user in the Symantec VIP database.

Parameters:

  • user_id (String) —

    Id of the user to add a credential to.

  • credential_id (String)
  • credential_type (String) —

    must be one of the keys to the credential types from the Utilities class.

  • options (Hash) —

    A hash that can contain the following. :name adds a friendly name to the credential added to vip, :otp sends a otp from the credential with the request to verify that the user actually has possession of the credential

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes

See Also:



268
269
270
 
# File 'lib/soteria/client.rb', line 268

def add_credential(user_id, credential_id, credential_type, options)
  @user.add_credential(@management_client, user_id, credential_id, credential_type, options)
end

#authenticate_credentials(otp, credentials) ⇒ Hash

Check if a otp is valid for a given credential.

Parameters:

  • otp (Integer) —

    The One Time Password to check if valid.

  • credentials (Array) —

    An array of hashes, with between 1 and 5 credentials. Each hash should contain 2 values :id - the id of the credential and :type - the type of the credential.

Returns:

  • (Hash) —

    A hash with all information about if the otp was successful

See Also:



131
132
133
 
# File 'lib/soteria/client.rb', line 131

def authenticate_credentials(otp, credentials)
  @credential.authenticate_credentials(@auth_client, otp, credentials)
end

#authenticate_user_cridential(user_id, credential_code) ⇒ Hash

Authenticate a user with a credential. A credential includes a physical token, the desktop VIP credential app or the mobile VIP credential app. Users must link their credential id to their user id for this authentication to work.

Parameters:

  • user_id (String) —

    Id of the user to authenticate. This is the user id that is stored in the Symantec database.

  • credential_code (String) —

    The code from the users credential that was entered into the website.

Returns:

  • (Hash) —

    A hash with information on if the authentication was successful.



120
121
122
 
# File 'lib/soteria/client.rb', line 120

def authenticate_user_cridential(user_id, credential_code)
  @credential.authenticate_user_credential(@auth_client, user_id, credential_code)
end

#authenticate_with_push(user_id, interval, time_out, options) ⇒ Hash

authenticate_with_push handles the process of sending the push to a user as well as polling for the response. It calls send_push, then takes the transaction id from that call and starts polling for the result. It has the same result as making the calls independently but requires only one call instead of two as well as handles any errors.

Parameters:

  • user_id (String) —

    Id of the user to authenticate. This is the user id that is stored in the Symantec database.

  • interval (Int) —

    An integer value in seconds that is the interval between polling VIP Services for a push response.

  • time_out (Int) —

    An integer value in seconds that is the timeout for polling. This should match the timeout that was set for the push message.

  • options (Hash)

Returns:

  • (Hash) —

    A hash with information on if the authentication was successful.



101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/soteria/client.rb', line 101

def authenticate_with_push(user_id, interval, time_out, options)
  push_response = @push.send_push(@auth_client, user_id, options)

  unless push_response[:success]
    return push_response
  end

  transaction_id = push_response[:transaction_id]

  @push.poll_for_response(@query_client, transaction_id, interval, time_out)
end

#check_otp(user_id, otp) ⇒ Hash

Check if the otp that a user entered is valid or not.

Parameters:

  • user_id (String) —

    Id of the user to authenticate. This is the user id that is stored in the Symantec database.

  • otp (Object) —

    The otp that was sent to the user via sms or voice

Returns:

  • (Hash) —

    A hash with all information about if the otp was successful



151
152
153
 
# File 'lib/soteria/client.rb', line 151

def check_otp(user_id, otp)
  @sms.check_otp(@auth_client, user_id, otp)
end

#clear_temp_pass(user_id) ⇒ Hash

Use clearTemporaryPassword to add users to VIP User Services.to remove a temporary security code from a user. If the user attempts to use a temporary security that has been cleared, VIP User Services returns an error stating the security code is not set. If the user validates a security code using a valid credential, any temporary security code that is set for that user is automatically cleared.

Parameters:

  • user_id (String) —

    The unique ID for the user.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



235
236
237
 
# File 'lib/soteria/client.rb', line 235

def clear_temp_pass(user_id)
  @user.clear_temp_pass(@management_client, user_id)
end

#clear_user_pin(user_id) ⇒ Hash

Use clearUserPin to remove an assigned PIN from a user.

Parameters:

  • user_id (String) —

    The unique ID for the user.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



189
190
191
 
# File 'lib/soteria/client.rb', line 189

def clear_user_pin(user_id)
  @user.clear_user_pin(@management_client, user_id)
end

#create_user(user_id, pin) ⇒ Hash

Add a new user to the list of users in Symantec VIP database.

Parameters:

  • user_id (String) —

    Id of the user to create.

  • pin (String) —

    an optional value that is a pin for the user. The PIN may be 4 to 128 international characters in length, depending on restrictions of the PIN policy.

Returns:

  • (Hash) —

    A hash that contains: :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



161
162
163
 
# File 'lib/soteria/client.rb', line 161

def create_user(user_id, pin)
  @user.create(@management_client, user_id, pin)
end

#deactivate_token(token_id) ⇒ Hash

Use the DeactivateToken for SMS OTP API to deactivate an SMS OTP credential. If the deactivation is successful, the credential is deactivated.

Parameters:

  • token_id (Int) —

    Specifies the phone number that identifies the credential to the VIP Web Services. Do not use spaces or dashes.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



369
370
371
 
# File 'lib/soteria/client.rb', line 369

def deactivate_token(token_id)
  @auth.deactivate_token(token_id)
end

#delete_user(user_id) ⇒ Hash

Delete a user from the database of Symantec VIP users.

Parameters:

  • user_id (String) —

    Id of the user to delete.

Returns:

  • (Hash) —

    A hash that contains: :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



170
171
172
 
# File 'lib/soteria/client.rb', line 170

def delete_user(user_id)
  @user.delete(@management_client, user_id)
end

#disable_sms_credentail(reason, token_id) ⇒ Hash

Use the DisableToken for SMS OTP API to disable an SMS OTP credential.

Parameters:

  • reason (String) —

    The reason for disabling the token.

  • token_id (Int) —

    Specifies the phone number that identifies the credential to the VIP Web Services. Do not use spaces or dashes.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



351
352
353
 
# File 'lib/soteria/client.rb', line 351

def disable_sms_credentail(reason, token_id)
  @auth.disable_sms_credentail(reason, token_id)
end

#enable_sms_credentail(token_id) ⇒ Hash

Use the EnableToken for SMS OTP API to enable a previously disabled SMS OTP credential.

Parameters:

  • token_id (Int) —

    Specifies the phone number that identifies the credential to the VIP Web Services. Do not use spaces or dashes.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



341
342
343
 
# File 'lib/soteria/client.rb', line 341

def enable_sms_credentail(token_id)
  @auth.enable_sms_credentail(token_id)
end

#get_auth_client ⇒ Soteria.Client

Getter for the auth client

Returns:



57
58
59
 
# File 'lib/soteria/client.rb', line 57

def get_auth_client
  @auth_client
end

#get_credential_info(credential_id, credential_type, include_push) ⇒ Hash

Use getCredentialInfo to get the credential that was last bound to the user, When the credential was last authenticated and the friendly name for the credential.

Parameters:

  • credential_id (String) —

    The unique ID for the credential.

  • credential_type (String) —

    The type of the credential.

  • include_push (Boolean) —

    If this flag is present and set to be true, the response contains all the push attributes in the field pushAttributes.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes. Also contains :credential which is a hash with info about the credential.



247
248
249
 
# File 'lib/soteria/client.rb', line 247

def get_credential_info(credential_id, credential_type, include_push)
  @credential.get_credential_info(@query_client, credential_id, credential_type, include_push)
end

#get_management_client ⇒ Soteria.Client

Getter for the management client

Returns:



65
66
67
 
# File 'lib/soteria/client.rb', line 65

def get_management_client
  @management_client
end

#get_query_client ⇒ Soteria.Client

Getter for the query client

Returns:



49
50
51
 
# File 'lib/soteria/client.rb', line 49

def get_query_client
  @query_client
end

#get_server_time ⇒ Hash

Use getServerTime to obtain the current server time.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes. Also contains :time which is current server time.



255
256
257
 
# File 'lib/soteria/client.rb', line 255

def get_server_time()
  @credential.get_server_time(@query_client)
end

#get_temp_pass_attr(user_id) ⇒ Hash

Use getTemporaryPasswordAttributes to poll VIP User Services every three to five seconds to check the status of a push notification. The push notification is validated against the notification’s unique transaction ID.

Parameters:

  • user_id (String) —

    The unique ID for the user.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



209
210
211
 
# File 'lib/soteria/client.rb', line 209

def get_temp_pass_attr(user_id)
  @user.get_temp_pass_attr(@query_client, user_id)
end

#get_user_info(user_id, include_push) ⇒ Object

Get all the credentials that have been last bound to a user or the last authentication, as well as the friendly name for the user’s credential.

Returns an array with a hash for every credential that can be used as a second factor authentication option a user has. Each hash contains:

  • :type - The type of the credential.

  • :enabled - If the credential is enabled.

  • :friendly_name - The name the user gave the credential.

  • :push - A boolean if push is enabled for the credential.

  • :credential_id - The id of the credential. This is useful for SMS auth.

Parameters:

  • user_id (String) —

    Id of the user to get information about.

  • include_push (Boolean) —

    If the users push details should be returned.



285
286
287
 
# File 'lib/soteria/client.rb', line 285

def (user_id, include_push)
  @user.(@query_client, user_id, include_push)
end

#poll_for_response(transaction_id, interval, time_out) ⇒ Hash

Polls for the status of the push notification. This is necessary because VIP does not have push support. This will poll until the response is no longer push in progress, then it will return a hash with the results.

Parameters:

  • transaction_id (String) —

    The id of the push transaction. id is in the hash returned from the send_push call

  • interval (Int) —

    An integer value in seconds that is the interval between polling VIP Services for a push response.

  • time_out (Int) —

    An integer value in seconds that is the timeout for polling. This should match the timeout that was set for the push message.

Returns:

  • (Hash) —

    A hash with information on if the authentication was successful.



87
88
89
 
# File 'lib/soteria/client.rb', line 87

def poll_for_response(transaction_id, interval, time_out)
  @push.poll_for_response(@query_client, transaction_id, interval, time_out)
end

#register(token_id) ⇒ Hash

Register a new SMS OTP credential.

Parameters:

  • token_id (Int) —

    Specifies the phone number that identifies the credential to the VIP Web Services. Do not use spaces or dashes.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



378
379
380
 
# File 'lib/soteria/client.rb', line 378

def register(token_id)
  @auth.register(token_id)
end

#register_sms(phone_number) ⇒ Hash

Call to register a SMS credential to the VIP account. Before a user can add a SMS credential to their account it must first exist in the organizations list of credentials.

Parameters:

  • phone_number (Integer) —

    The phone number credential to register.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



295
296
297
 
# File 'lib/soteria/client.rb', line 295

def register_sms(phone_number)
  @credential.register_sms(@management_client, phone_number)
end

#remove_credential(user_id, credential_id, credential_type) ⇒ Hash

Remove a credential from a given user. If the Device deletion policy for Remembered Devices is set to Admin Only, credentials can only be removed through VIP Manager. The removeCredential API will return the error 6010: This account is not authorized to perform the requested operation

Parameters:

  • user_id (String) —

    Id of the user to remove a credential from.

  • credential_id (String) —

    Unique identifier of the credential.

  • credential_type (String) —

    must be one of the keys to the credential types from the Utilities class.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes

See Also:



309
310
311
 
# File 'lib/soteria/client.rb', line 309

def remove_credential(user_id, credential_id, credential_type)
  puts @user.remove_credential(@management_client, user_id, credential_id, credential_type)
end

#send_push(user_id, options) ⇒ Hash

Send a push notification to the specified user for authentication.

Parameters:

  • user_id (String) —

    Id of the user to authenticate. This is the user id that is stored in the Symantec database.

  • options (Hash)

Returns:

  • (Hash) 


75
76
77
 
# File 'lib/soteria/client.rb', line 75

def send_push(user_id, options)
  @push.send_push(@auth_client, user_id, options)
end

#send_sms(user_id, phone_number) ⇒ Hash

Send a sms One Time Password to a user.

Parameters:

  • user_id (String) —

    Id of the user to authenticate. This is the user id that is stored in the Symantec database.

  • phone_number (Int) —

    The phone number that the sms code should be sent to.

Returns:

  • (Hash) —

    A hash with all the appropriate information about the status of the SMS.



141
142
143
 
# File 'lib/soteria/client.rb', line 141

def send_sms(user_id, phone_number)
  @sms.send_sms(@management_client, user_id, phone_number)
end

#set_temp_pass(token_id, pass) ⇒ Hash

Send a temporary password to the token.

Parameters:

  • token_id (Int) —

    Specifies the phone number that identifies the credential to the VIP Web Services. Do not use spaces or dashes.

  • pass (Int)

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



332
333
334
 
# File 'lib/soteria/client.rb', line 332

def set_temp_pass(token_id, pass)
  @auth.set_temp_pass(token_id, pass)
end

#set_temp_pass_attr(user_id, options) ⇒ Hash

Use setTemporaryPasswordAttributes to change the expiration date for a temporary security code you previously set.

Parameters:

  • user_id (String) —

    The unique ID for the user.

  • options (Object)

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



199
200
201
 
# File 'lib/soteria/client.rb', line 199

def set_temp_pass_attr(user_id, options)
  @user.set_temp_pass_attr(@management_client, user_id, options)
end

#set_temp_password(user_id, phone, options) ⇒ Hash

Use setTemporaryPassword to set a temporary security code for a user. You can optionally set an expiration date for the security code, or set it for one-time use only. The request requires the user ID and optionally, the temporary security code string. If you do not provide a security code, VIP User Services generates one for you.

Parameters:

  • user_id (String) —

    The unique ID for the user.

  • phone (Int) —

    The phone or mobile device number to which the VIP User Service should deliver the security code.

  • options (Hash)

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



223
224
225
 
# File 'lib/soteria/client.rb', line 223

def set_temp_password(user_id, phone, options)
  @user.set_temp_password(@management_client, user_id, phone, options)
end

#update_credential(user_id, credential_id, credential_type, name) ⇒ Hash

Updates the friendly name of a users credential.

Parameters:

  • user_id (String) —

    Id of the user to remove a credential from.

  • credential_id (String) —

    Unique identifier of the credential.

  • credential_type (String) —

    must be one of the keys to the credential types from the Utilities class.

  • name (Object) —

    A user-defined name to identify the credential.

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes

See Also:



322
323
324
 
# File 'lib/soteria/client.rb', line 322

def update_credential(user_id, credential_id, credential_type, name)
  puts @user.update_credential(@management_client, user_id, credential_id, credential_type, name)
end

#update_user(user_id, options) ⇒ Hash

Use updateUser to update information about a user in VIP User Services.

Parameters:

  • user_id (String) —

    The unique ID for the user.

  • options (Object)

Returns:

  • (Hash) —

    A hash that contains; :success a boolean if the call succeeded, :message a string with any error message, :id the id of the call for debugging purposes



180
181
182
 
# File 'lib/soteria/client.rb', line 180

def update_user(user_id, options)
  @user.update_user(@management_client, user_id, options)
end