CGIParty

CGIParty is a gem made for integrating against the CGI Group GRP2 API. As of now you can only perform BankID authorization.

• You will need an agreement with CGI group in order to user their API. We do not provide this.

NOTE: If you're still using the old GRP API, you'll need to install the old version (1.0.0) of this gem.

Installation

Add this line to your application's Gemfile:

gem 'cgi_party'

And then execute:

$ bundle

Or install it yourself as:

$ gem install cgi_party

Configuration

To use the gem you must configure some settings. Here is the settings available:

CGIParty.configure do |config|
  # (Optional) The number of seconds a poll operation will be active before timeout. Recommended is 180 seconds.
  config.collect_polling_timeout = 180

  # (Optional) The number of seconds a poll operation will wait between each call. Recommended is 3 seconds.
  config.collect_polling_delay = 3

  # (Optional) The path where the WSDL is located. Change to CGIParty::WSDL_TEST_PATH in development and testing
  config.wsdl_path = CGIParty::WSDL_PATH

  # (Required) The name that will be displayed in the BankID app. "Jag legitimerar mig mot #{display_name}"
  config.display_name = "display_name"

  # (Required) An identifier for your service provided by the CGI Group
  config.service_id = "service_id"
end

Usage

Before doing any consecutive requests you must first initiate a client and call the authenticate method. The authenticate response will contain information about the authentication order.

client = CGIParty::Client.new
authenticate_response = client.authenticate(ip_address)

Autostart on the same device

You can acquire an url for prompting the BankID application on the device.

authenticate_response.autostart_url(return_url)
#=> "bankid:///?autostarttoken=[token]&redirect=[return_url]"

QR code for BankID on another device

Generate an animated QR code. You'll need some way to keep track of elapsed seconds as you refresh the QR code.

client.generate_qr(start_token: authenticate_response.qr_start_token,
                   start_secret: authenticate_response.qr_start_secret,
                   seconds: seconds_elapsed)

Collect

To poll the collect action you can use the poll collect method. The block will be yielded every time the API responds. You can take appropriate action in your application by using the provided progress statuses.

You can read more about them in the CGI Group GRP API documentation: https://www.cgi.se/sites/default/files/files_se/pdf/grp_api.pdf

client.poll_collect(authenticate_response.order_ref,
                    authenticate_response.transaction_id) do |collect_response|
  case collect_response.progress_status
  when "OUTSTANDING_TRANSACTION"    # Awaiting BankID application to start. (Might need manual boot)
  when "EXPIRED_TRANSACTION"        # No activity from the user after 180s.
  when "ALREADY_IN_PROGRESS"        # An order for the user is already in progress.
  when "INVALID_PARAMETERS"         # Invalid parameters provided.
  when "ACCESS_DENIED_RP"           # Internal access problem. Contact CGI.
  when "CERTIFICATE_ERR"            # The users BankID are revoked or invalid.
  when "INTERNAL_ERROR"             # An internal BankID error occured.
  when "START_FAILED"               # BankID client did't start after 30s
  when "USER_CANCEL"                # The order was canceled by the user.
  when "CLIENT_ERR"                 # An internal BankID error occurred.
  when "CANCELLED"                  # The order was cancelled.
  when "NO_CLIENT"                  # Users BankID was not available
  when "COMPLETE"                   # The authentication is completed
  when "RETRY"                      # A temporary error has occurred. Prompt the user to try again.
  end
end

A successful collect response will contain attributes about the authenticated person.

collect_response.attributes
#=>
[
  { name: "cn", value: "Bob Basil" },
  { name: "serialnumber", value: "680916-1794" },
  # ...
]

Development and testing

When testing the functionality against the API it is preferable to not use the real endpoints. By changing the wsdl_path config variable in testing you can change all requests to enpoints made for testing.

CGIParty.configure do |config|
  config.wsdl_path = CGIParty::WSDL_TEST_PATH
  # ...
end

License

The gem is available as open source under the terms of the MIT License.