Bankid
Bankid authentication for Ruby!
Installation
Add this line to your application's Gemfile:
gem 'bankid'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install bankid
Usage
Bankid authentication is done in the following steps:
- Generate an "authentication order" by hitting the
auth
endpoint - You get an authentication object containing, among other things, an
orderRef
and astartSecret
back - Use the data contained in the authentication object to show the user a QR code
- Poll the
collect
endpoint every now and then using theorderRef
you got back in the second step - When user has scanned the QR code and logged in, the poll will return their data.
This is step 1:
client = Bankid::Auth.new
auth = client.generate_authentication(ip: request.remote_ip) # user's ip address
Keep the values from that auth
object around, you'll need them in later steps, as you'll see. Note that you should never reveal the qr_start_secret
to users!
Onward to step 3, showing a QR code:
@qr_code = client.generate_qr(
start_token: auth.qr_start_token,
start_secret: auth.qr_start_secret,
seconds: seconds_elapsed_since_auth_response_received
)
Bankid uses animated QR, which means the code is a SHA256 hex digest that includes elapsed seconds. You'll need some way to keep track of those as you refresh the QR code and poll for a response.
Final step:
response = client.poll(order_ref: auth.order_ref)
raise "logged in!" if response.status == "complete"
Keep polling until your response status changes to "complete", and the response object will be a struct containing the completion_data
property you're ultimately looking for.
Certificates
Your BankID provider will have given you a certificate. It might be in .p12
format. If that's the case, you'll need to convert it to an OpenSSL X509 certificate - version 0.1.x of the BankID gem relied on PKCS12 which saw big changes in OpenSSL v3, so the implementation has been switched to X509 instead. The gem looks for a certificate and a key in these default locations:
./config/certs/#{environment}_client_certificate.pem
./config/certs/#{environment}_client_certificate.key
If you're upgrading from 0.1.x and want to convert an existing p12 key, it's pretty straightforward:
# Export certificate
openssl pkcs12 -legacy -in my_certificate.p12 -clcerts -nokeys -out my_certificate.pem
# Export key
openssl pkcs12 -legacy -in my_certificate.p12 -clcerts -nocerts -out my_certificate.key
That should hopefully get things running again.
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and the created tag, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/bankid.
License
The gem is available as open source under the terms of the MIT License.