passbyme2fa-client 1.0.1 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +195 -0
- data/lib/passbyme2fa-client.rb +1 -1
- metadata +2 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 19f21252f315321d33532ea67aeb2cd9ee226063
|
|
4
|
+
data.tar.gz: d92b837f750ff82ea10b0378035c870750355d04
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 2bb65ea4be8e71f7874d2577979b1dc21dd3af0dc6e4e3378999f37b42e51f167f8de5d2f9c080f5eb81e2e02f76eb3cec0a7ec24326cff0d30789bc17bb4b95
|
|
7
|
+
data.tar.gz: a1c6eb457a93424dd3f17e772b7ff18f3e562bea4f43e68e7cc5b9bd6e0c3b8caad1d1d7bfb5bc928f3f4de689e84863c3328616e5c8b94044a1bfdabecdfdc0
|
data/README.md
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
PassBy[ME] Mobile ID client
|
|
2
|
+
===========================================
|
|
3
|
+
|
|
4
|
+
This library provides you with functionality to handle PassBy[ME] messages.
|
|
5
|
+
|
|
6
|
+
For further information on PassBy[ME] please visit:
|
|
7
|
+
[www.passbyme.com](https://www.passbyme.com) and sign up for a free account.
|
|
8
|
+
You can download our API documentation after login.
|
|
9
|
+
|
|
10
|
+
# Table of contents
|
|
11
|
+
* [Installation](#installation)
|
|
12
|
+
* [Usage](#usage)
|
|
13
|
+
* [PassByME2FAClient](#passbyme2faclient)
|
|
14
|
+
* [Handling messages](#handling-messages)
|
|
15
|
+
* [Sending messages](#sending-messages)
|
|
16
|
+
* [Tracking messages](#tracking-messages)
|
|
17
|
+
* [Cancelling messages](#cancelling-messages)
|
|
18
|
+
* [SessionInfo](#sessioninfo)
|
|
19
|
+
* [Errors](#errors)
|
|
20
|
+
* [HTTPError](#httperror)
|
|
21
|
+
* [PassByMEError](#passbymeerror)
|
|
22
|
+
* [Build](#build)
|
|
23
|
+
* [Release History](#release-history)
|
|
24
|
+
|
|
25
|
+
# Installation
|
|
26
|
+
```
|
|
27
|
+
gem install passbyme2fa-client
|
|
28
|
+
```
|
|
29
|
+
# Usage
|
|
30
|
+
To use the PassBy[ME] Mobile ID SDK first you have to acquire the following:
|
|
31
|
+
|
|
32
|
+
- Account authentication PEM file and its password
|
|
33
|
+
|
|
34
|
+
You can get these after registering at
|
|
35
|
+
[www.passbyme.com](https://www.passbyme.com), by hitting the "Sign up for
|
|
36
|
+
free" button. To complete the registration you will need an Android or iOS
|
|
37
|
+
device with the PassBy[ME] application installed.
|
|
38
|
+
|
|
39
|
+
If you login after registration you can download the PEM from the Application
|
|
40
|
+
menu. You can add new applications to your registration by hitting the "New
|
|
41
|
+
application". The application (along with its Application Id) will appear in
|
|
42
|
+
the table below.
|
|
43
|
+
|
|
44
|
+
*We suggest you to read the available User Guides and API documentation before
|
|
45
|
+
you continue with the integration. You can download these from the
|
|
46
|
+
Documentation section of the administration website after login.*
|
|
47
|
+
|
|
48
|
+
## PassByME2FAClient
|
|
49
|
+
```ruby
|
|
50
|
+
require 'passbyme2fa-client'
|
|
51
|
+
|
|
52
|
+
pem_file = File.read("auth.pem")
|
|
53
|
+
pbm = PassByME2FAClient.new({
|
|
54
|
+
:cert => OpenSSL::X509::Certificate.new(pem_file),
|
|
55
|
+
:key => OpenSSL::PKey::RSA.new(pem_file, "<auth.pem password>")
|
|
56
|
+
})
|
|
57
|
+
```
|
|
58
|
+
The **PassByME2FAClient** constructor accepts the following parameters in a
|
|
59
|
+
Hash object:
|
|
60
|
+
|
|
61
|
+
- **cert**: the authentication certificate. (See:
|
|
62
|
+
[Net::HTTP attributes](https://ruby-doc.org/stdlib-2.4.0/libdoc/net/http/rdoc/Net/HTTP.html)
|
|
63
|
+
for details)
|
|
64
|
+
- **key**: the authentication key. (See:
|
|
65
|
+
[Net::HTTP attributes](https://ruby-doc.org/stdlib-2.4.0/libdoc/net/http/rdoc/Net/HTTP.html)
|
|
66
|
+
for details)
|
|
67
|
+
- **address**: The address of the PassBy[ME] service to use. This parameter is
|
|
68
|
+
optional. by default the SDK will connect to our test service. The PassBy[ME]
|
|
69
|
+
service url-s are the following:
|
|
70
|
+
- *Test service*: auth-sp.passbyme.com
|
|
71
|
+
- *Production service*: api.passbyme.com
|
|
72
|
+
- You can supply any attribute accepted by Net::HTTP
|
|
73
|
+
(see: https://ruby-doc.org/stdlib-2.4.0/libdoc/net/http/rdoc/Net/HTTP.html)
|
|
74
|
+
to influence the connection.
|
|
75
|
+
|
|
76
|
+
Throws an [ArgumentError](https://ruby-doc.org/core-2.4.0/ArgumentError.html)
|
|
77
|
+
when a required parameter is missing.
|
|
78
|
+
|
|
79
|
+
## Handling Messages
|
|
80
|
+
|
|
81
|
+
### Sending messages
|
|
82
|
+
```ruby
|
|
83
|
+
session_info = pbm.send_message(
|
|
84
|
+
recipients: ["test@pers.on"],
|
|
85
|
+
availability: 300,
|
|
86
|
+
type: PassByME2FAClient::MessageType::AUTHORIZATION,
|
|
87
|
+
subject: "Test subject", body: "Test message"
|
|
88
|
+
)
|
|
89
|
+
```
|
|
90
|
+
The **send_message** method accepts the following parameters in a Hash object
|
|
91
|
+
(or as named parameters, as in the example above):
|
|
92
|
+
- **recipients**: An array containing the PassBy[ME] ID-s of the recipients
|
|
93
|
+
- **subject**: The subject of the message
|
|
94
|
+
- **body**: The body of the message
|
|
95
|
+
- **availability**: The availability of the message in seconds
|
|
96
|
+
- **type**: One of the following types:
|
|
97
|
+
- **PassByME2FAClient::MessageType::AUTHORIZATION** - for authorization requests
|
|
98
|
+
- **PassByME2FAClient::MessageType::MESSAGE** - to send a general message with
|
|
99
|
+
arbitrary body
|
|
100
|
+
- **PassByME2FAClient::MessageType::ESIGN** - if the message body contains an
|
|
101
|
+
esign url
|
|
102
|
+
|
|
103
|
+
When successful, returns a [SessionInfo](#sessioninfo) object.
|
|
104
|
+
|
|
105
|
+
Throws an [ArgumentError](https://ruby-doc.org/core-2.4.0/ArgumentError.html)
|
|
106
|
+
when a required parameter is missing.
|
|
107
|
+
Throws an [HTTPError](#httperror) if an error in HTTP communication occurs.
|
|
108
|
+
**HTTPError.response** contains the HTTP response.
|
|
109
|
+
Throws a [PassByMEError](#passbymeerror) if a PassBy[ME] specific error occurs.
|
|
110
|
+
**PassByMEError.response** contains the JSON response received from the PassBy[ME]
|
|
111
|
+
server as a Hash object.
|
|
112
|
+
|
|
113
|
+
### Tracking messages
|
|
114
|
+
```ruby
|
|
115
|
+
session_info.refresh
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
To track messages, the most efficient way is to call **SessionInfo.refresh**.
|
|
119
|
+
After a successful call, the [SessionInfo](#sessionInfo) object will contain
|
|
120
|
+
up-to-date information about the message.
|
|
121
|
+
|
|
122
|
+
Throws an [HTTPError](#httperror) if an error in HTTP communication occurs.
|
|
123
|
+
Throws a [PassByMEError](#passbymeerror) if a PassBy[ME] specific error occurs.
|
|
124
|
+
|
|
125
|
+
### Cancelling messages
|
|
126
|
+
```ruby
|
|
127
|
+
session_info.cancel
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
To cancel the message, the most efficient way is to call **SessionInfo.cancel**.
|
|
131
|
+
After a successful call, the message will be cancelled and the
|
|
132
|
+
[SessionInfo](#sessionInfo) object will contain up-to-date information about the
|
|
133
|
+
message.
|
|
134
|
+
|
|
135
|
+
Throws an [HTTPError](#httperror) if an error in HTTP communication occurs.
|
|
136
|
+
Throws a [PassByMEError](#passbymeerror) if a PassBy[ME] specific error occurs.
|
|
137
|
+
|
|
138
|
+
### SessionInfo
|
|
139
|
+
The **SessionInfo** object describes the state of a message session. It consists
|
|
140
|
+
of the following readable attributes:
|
|
141
|
+
- **message_id**: The id of the message that can be used to reference the message
|
|
142
|
+
- **expiration_date**: The date and time until the message can be downloaded with
|
|
143
|
+
the PassBy[ME] applications
|
|
144
|
+
- **recipient_statuses**: An array of **RecipientStatus** objects. Each object
|
|
145
|
+
consist of the following fields
|
|
146
|
+
- **user_id**: The PassBy[ME] ID of the user represented by this recipient object
|
|
147
|
+
- **status**: The delivery status of this message for this user
|
|
148
|
+
|
|
149
|
+
Available statuses are (all constants available as **PassByME2FAClient::MessageStatus::***):
|
|
150
|
+
- **PENDING**: Initial status of the message.
|
|
151
|
+
- **NOTIFIED**: The recipient has been notified about a new message.
|
|
152
|
+
- **DOWNLOADED**: The recipient has downloaded the message, but has not uploaded
|
|
153
|
+
the evidence yet.
|
|
154
|
+
- **SEEN**: The recipient has seen the message and uploaded the evidence.
|
|
155
|
+
- **NOT_SEEN**: The recipient has not seen the message.
|
|
156
|
+
- **NOT_NOTIFIED**: The recipient has not received the notification.
|
|
157
|
+
- **NOT_DOWNLOADED**: The recipient received the notification about the message
|
|
158
|
+
but has not downloaded the message
|
|
159
|
+
- **NO_DEVICE**: The message could not be sent because the recipient had no PassBy[ME]
|
|
160
|
+
ready device that supports messaging.
|
|
161
|
+
- **FAILED**: The message could not be sent because of an error.
|
|
162
|
+
- **DISABLED**: The message could not be sent because the recipient is disabled.
|
|
163
|
+
- **CANCELLED**: The message was cancelled by the sender.
|
|
164
|
+
- **APPROVED**: Authentication has finished successfully.
|
|
165
|
+
- **DENIED**: The user has cancelled the authentication.
|
|
166
|
+
|
|
167
|
+
## Errors
|
|
168
|
+
|
|
169
|
+
### HTTPError
|
|
170
|
+
|
|
171
|
+
Denotes that the server responded with a HTTP error code. Its readable **response**
|
|
172
|
+
attribute contains the [Net::HTTPResponse](https://ruby-doc.org/stdlib-2.4.0/libdoc/net/http/rdoc/Net/HTTPResponse.html)
|
|
173
|
+
received from the server.
|
|
174
|
+
|
|
175
|
+
### PassByMEError
|
|
176
|
+
|
|
177
|
+
Denotes a PassBy[ME] specific error. See the API documentation for the possible
|
|
178
|
+
error codes. Its readable **response** attribute contains the JSON message
|
|
179
|
+
received from the server as a Hash object.
|
|
180
|
+
|
|
181
|
+
# Build
|
|
182
|
+
|
|
183
|
+
To build the gem, first we have to run our tests, which can be done typing
|
|
184
|
+
```
|
|
185
|
+
rake
|
|
186
|
+
```
|
|
187
|
+
If the tests all pass, we can create the gem using the command
|
|
188
|
+
```
|
|
189
|
+
gem build passbyme2fa-client.gemspec
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
# Release History
|
|
193
|
+
|
|
194
|
+
- 1.0.0
|
|
195
|
+
- Initial release
|
data/lib/passbyme2fa-client.rb
CHANGED
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: passbyme2fa-client
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 1.0.
|
|
4
|
+
version: 1.0.2
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Microsec ltd.
|
|
@@ -73,6 +73,7 @@ executables: []
|
|
|
73
73
|
extensions: []
|
|
74
74
|
extra_rdoc_files: []
|
|
75
75
|
files:
|
|
76
|
+
- README.md
|
|
76
77
|
- lib/passbyme2fa-client.rb
|
|
77
78
|
- lib/passbyme2fa-client/http_error.rb
|
|
78
79
|
- lib/passbyme2fa-client/json_helper.rb
|