def authenticate(self,
end_user_ip,
personal_number=None,
requirement=None,
**kwargs):
"""Request an authentication order. The :py:meth:`collect` method
is used to query the status of the order.
Note that personal number is not needed when authentication is to
be done on the same device, provided that the returned
``autoStartToken`` is used to open the BankID Client.
Example data returned:
.. code-block:: json
{
"orderRef":"131daac9-16c6-4618-beb0-365768f37288",
"autoStartToken":"7c40b5c9-fa74-49cf-b98c-bfe651f9a7c6"
}
:param end_user_ip: IP address of the user requesting
the authentication.
:type end_user_ip: str
:param personal_number: The Swedish personal number in
format YYYYMMDDXXXX.
:type personal_number: str
:param requirement: An optional dictionary stating how the signature
must be created and verified. See BankID Relying Party Guidelines,
section 13.5 for more details.
:type requirement: dict
:return: The order response.
:rtype: dict
:raises BankIDError: raises a subclass of this error
when error has been returned from server.
"""
data = {"endUserIp": end_user_ip}
if personal_number:
data["personalNumber"] = personal_number
if requirement and isinstance(requirement, dict):
data["requirement"] = requirement
# Handling potentially changed optional in-parameters.
data.update(kwargs)
response = self._post(self._auth_endpoint, json=data)
if response.status_code == 200:
return response.json()
else:
raise get_json_error_class(response)
def cancel(self, order_ref):
"""Cancels an ongoing sign or auth order.
This is typically used if the user cancels the order
in your service or app.
:param order_ref: The UUID string specifying which order to cancel.
:type order_ref: str
:return: Boolean regarding success of cancellation.
:rtype: bool
:raises BankIDError: raises a subclass of this error
when error has been returned from server.
"""
response = self._post(self._cancel_endpoint, json={"orderRef": order_ref})
if response.status_code == 200:
return response.json() == {}
else:
raise get_json_error_class(response)
def collect(self, order_ref):
"""Collects the result of a sign or auth order using the
``orderRef`` as reference.
RP should keep on calling collect every two seconds as long as status
indicates pending. RP must abort if status indicates failed. The user
identity is returned when complete.
Example collect results returned while authentication or signing is
still pending:
.. code-block:: json
{
"orderRef":"131daac9-16c6-4618-beb0-365768f37288",
"status":"pending",
"hintCode":"userSign"
}
Example collect result when authentication or signing has failed:
.. code-block:: json
{
"orderRef":"131daac9-16c6-4618-beb0-365768f37288",
"status":"failed",
"hintCode":"userCancel"
}
Example collect result when authentication or signing is successful
and completed:
.. code-block:: json
{
"orderRef":"131daac9-16c6-4618-beb0-365768f37288",
"status":"complete",
"completionData": {
"user": {
"personalNumber":"190000000000",
"name":"Karl Karlsson",
"givenName":"Karl",
"surname":"Karlsson"
},
"device": {
"ipAddress":"192.168.0.1"
},
"cert": {
"notBefore":"1502983274000",
"notAfter":"1563549674000"
},
"signature":"<base64-encoded data>",
"ocspResponse":"<base64-encoded data>"
}
}
See `BankID Relying Party Guidelines Version: 3.5 <https://www.bankid.com/assets/bankid/rp/bankid-relying-party-guidelines-v3.5.pdf>`_
for more details about how to inform end user of the current status,
whether it is pending, failed or completed.
:param order_ref: The ``orderRef`` UUID returned from auth or sign.
:type order_ref: str
:return: The CollectResponse parsed to a dictionary.
:rtype: dict
:raises BankIDError: raises a subclass of this error
when error has been returned from server.
"""
response = self._post(self._collect_endpoint,
json={"orderRef": order_ref})
if response.status_code == 200:
return response.json()
else:
raise get_json_error_class(response)