Class: GdsApi::AccountApi

Inherits:
Base
  • Object
show all
Defined in:
lib/gds_api/account_api.rb

Overview

Adapter for the Account API

Constant Summary collapse

AUTH_HEADER_NAME =
"GOVUK-Account-Session".freeze

Instance Attribute Summary

Attributes inherited from Base

#options

Instance Method Summary collapse

Methods inherited from Base

#client, #create_client, #get_list, #initialize, #url_for_slug

Constructor Details

This class inherits a constructor from GdsApi::Base

Instance Method Details

#delete_email_subscription(name:, govuk_account_session:) ⇒ Object

Unsubscribe and delete an account-linked email subscription.

Parameters:

  • name (String)

    Name of the subscription

  • govuk_account_session (String)

    Value of the session header


135
136
137
# File 'lib/gds_api/account_api.rb', line 135

def delete_email_subscription(name:, govuk_account_session:)
  delete_json("#{endpoint}/api/email-subscriptions/#{CGI.escape(name)}", {}, auth_headers())
end

#delete_user_by_subject_identifier(subject_identifier:) ⇒ Object

Delete a users account

Parameters:

  • subject_identifier (String)

    The identifier of the user, shared between the auth service and GOV.UK.


69
70
71
# File 'lib/gds_api/account_api.rb', line 69

def delete_user_by_subject_identifier(subject_identifier:)
  delete_json("#{endpoint}/api/oidc-users/#{subject_identifier}")
end

#get_attributes(attributes:, govuk_account_session:) ⇒ Hash

Look up the values of a user's attributes

Parameters:

  • attributes (String)

    Names of the attributes to check

  • govuk_account_session (String)

    Value of the session header

Returns:

  • (Hash)

    The attribute values (if present), and a new session header


95
96
97
98
# File 'lib/gds_api/account_api.rb', line 95

def get_attributes(attributes:, govuk_account_session:)
  querystring = nested_query_string({ attributes: attributes }.compact)
  get_json("#{endpoint}/api/attributes?#{querystring}", auth_headers())
end

#get_email_subscription(name:, govuk_account_session:) ⇒ Hash

Get the details of an account-linked email subscription.

Parameters:

  • name (String)

    Name of the subscription

  • govuk_account_session (String)

    Value of the session header

Returns:

  • (Hash)

    Details of the subscription, if it exists.


116
117
118
# File 'lib/gds_api/account_api.rb', line 116

def get_email_subscription(name:, govuk_account_session:)
  get_json("#{endpoint}/api/email-subscriptions/#{CGI.escape(name)}", auth_headers())
end

#get_end_session_url(govuk_account_session: nil) ⇒ Hash

Get an OIDC end-session URL to redirect the user to

Parameters:

  • govuk_account_session (String, nil) (defaults to: nil)

    Value of the session header

Returns:

  • (Hash)

    An end-session URL


42
43
44
# File 'lib/gds_api/account_api.rb', line 42

def get_end_session_url(govuk_account_session: nil)
  get_json("#{endpoint}/api/oauth2/end-session", auth_headers())
end

#get_sign_in_url(redirect_path: nil, mfa: false) ⇒ Hash

Get an OAuth sign-in URL to redirect the user to

Parameters:

  • redirect_path (String, nil) (defaults to: nil)

    path on GOV.UK to send the user to after authentication

  • mfa (Boolean, nil) (defaults to: false)

    whether to authenticate the user with MFA or not

Returns:

  • (Hash)

    An authentication URL and the OAuth state parameter (for CSRF protection)


17
18
19
20
21
22
23
24
25
# File 'lib/gds_api/account_api.rb', line 17

def (redirect_path: nil, mfa: false)
  querystring = nested_query_string(
    {
      redirect_path: redirect_path,
      mfa: mfa,
    }.compact,
  )
  get_json("#{endpoint}/api/oauth2/sign-in?#{querystring}")
end

#get_user(govuk_account_session:) ⇒ Hash

Get all the information about a user needed to render the account home page

Parameters:

  • govuk_account_session (String)

    Value of the session header

Returns:

  • (Hash)

    Information about the user and the services they've used, and a new session header


51
52
53
# File 'lib/gds_api/account_api.rb', line 51

def get_user(govuk_account_session:)
  get_json("#{endpoint}/api/user", auth_headers())
end

#match_user_by_email(email:, govuk_account_session: nil) ⇒ Hash

Find a user by email address, returning whether they match the given session (if any)

Parameters:

  • email (String)

    The email address to search for

  • govuk_account_session (String, nil) (defaults to: nil)

    Value of the session header, if not given just checks if the given email address exists.

Returns:

  • (Hash)

    One field, “match”, indicating whether the session matches the given email address


61
62
63
64
# File 'lib/gds_api/account_api.rb', line 61

def match_user_by_email(email:, govuk_account_session: nil)
  querystring = nested_query_string({ email: email })
  get_json("#{endpoint}/api/user/match-by-email?#{querystring}", auth_headers())
end

#put_email_subscription(name:, topic_slug:, govuk_account_session:) ⇒ Hash

Create or update an account-linked email subscription.

Parameters:

  • name (String)

    Name of the subscription

  • topic_slug (String)

    The email-alert-api topic slug to subscribe to

  • govuk_account_session (String)

    Value of the session header

Returns:

  • (Hash)

    Details of the newly created subscription.


127
128
129
# File 'lib/gds_api/account_api.rb', line 127

def put_email_subscription(name:, topic_slug:, govuk_account_session:)
  put_json("#{endpoint}/api/email-subscriptions/#{CGI.escape(name)}", { topic_slug: topic_slug }, auth_headers())
end

#set_attributes(attributes:, govuk_account_session:) ⇒ Hash

Create or update attributes for a user

Parameters:

  • attributes (String)

    Hash of new attribute values

  • govuk_account_session (String)

    Value of the session header

Returns:

  • (Hash)

    A new session header


106
107
108
# File 'lib/gds_api/account_api.rb', line 106

def set_attributes(attributes:, govuk_account_session:)
  patch_json("#{endpoint}/api/attributes", { attributes: attributes }, auth_headers())
end

#update_user_by_subject_identifier(subject_identifier:, email: nil, email_verified: nil) ⇒ Hash

Update the user record with privileged information from the auth service. Only the auth service will call this.

Parameters:

  • subject_identifier (String)

    The identifier of the user, shared between the auth service and GOV.UK.

  • email (String, nil) (defaults to: nil)

    The user's current email address

  • email_verified (Boolean, nil) (defaults to: nil)

    Whether the user's current email address is verified

Returns:

  • (Hash)

    The user's subject identifier and email attributes


80
81
82
83
84
85
86
87
# File 'lib/gds_api/account_api.rb', line 80

def update_user_by_subject_identifier(subject_identifier:, email: nil, email_verified: nil)
  params = {
    email: email,
    email_verified: email_verified,
  }.compact

  patch_json("#{endpoint}/api/oidc-users/#{subject_identifier}", params)
end

#validate_auth_response(code:, state:) ⇒ Hash

Validate an OAuth authentication response

Parameters:

  • code (String)

    The OAuth code parameter, from the auth server.

  • state (String)

    The OAuth state parameter, from the auth server.

Returns:

  • (Hash)

    The value for the govuk_account_session header, the path to redirect the user to, and the GA client ID (if there is one)


33
34
35
# File 'lib/gds_api/account_api.rb', line 33

def validate_auth_response(code:, state:)
  post_json("#{endpoint}/api/oauth2/callback", code: code, state: state)
end