Package: hanko-sdk
Hanko Authentication SDK for PythonThis package is maintained byHanko.ContentsIntroductionDocumentationInstallationUsagePrerequisitesCreate a new Hanko API ClientRegister a WebAuthn credentialAuthenticate with a registered WebAuthn credentialMaking TransactionsCredential ManagementSerializing and deserializing Hanko payloads and responseException handlingEnable debug loggingSupportIntroductionThis SDK provides an API client that lets you communicate with theHanko Authentication APIto easily integrateFIDO®-based authentication into your web application written in
Python.DocumentationHanko DocumentationwebsiteHanko AuthenticationAPI referenceInstallationPippipinstallhanko_sdkBuilding a wheelpy-mbuild
pipinstalldist/hanko_sdk-X.X.X-py3-none-any.whlUsagePrerequisitesIn order to utilize the client provided by the SDK you need an API URL as well as API credentials in the form of an
API key ID and an API secret. View ourgetting startedguide in the official
documentation on how to obtain these.The minimum supported Python version is 3.7.Create a new Hanko API ClientOnce you have set up your account, create aHankoHttpClientConfigwith the API URL, the API Key Id and the API secret and
use it to construct aHankoHttpClient.hanko_config=HankoHttpClientConfig("<YOUR_BASEURL>","<YOUR_API_SECRET>","<YOUR_API_KEY>")hanko_client=HankoHttpClient(hanko_config)Register a WebAuthn credentialRegistration of a WebAuthn credential involves retrieving credential creation options from the Hanko API
(initialization), passing these options to the browser's Web Authentication API and lastly sending the WebAuthn response
back to the Hanko API for validation (finalization).For a more complete example of the authentication process, see theimplementation guidein the Hanko documentation.Registration initialization:Using defaults# To create the user object you'll need a userId, a username, and optionally, a# displayName. The username usually comes either from a form a user provides when# registering for the first time, or from your existing session# store or database, as well as a related userId, which may needs to be generated# if it is a new user.user_id="<YOUR_USER_ID>"username="<YOUR_USERNAME>"display_name="<YOUR_DISPLAY_NAME>"request=RegistrationInitializationRequest(User(user_id,username,display_name))response=hanko_client.initialize_registration(request)Modifying registration optionsYou can modify the default credential creation options for registration as follows:user_id="<YOUR_USER_ID>"username="<YOUR_USERNAME>"display_name="<YOUR_DISPLAY_NAME>"request=RegistrationInitializationRequest(User(user_id,username,display_name),RegistrationInitializationRequestOptions(AuthenticatorSelection(AuthenticatorAttachment.from_json_serializable(authenticator),True,UserVerificationRequirement.REQUIRED),ConveyancePreference.NONE))response=hanko_client.initialize_registration(request)Pass Hanko API response to the browser's Web Authentication APIInitialization with the Hanko API returns a response that representPublicKeyCredentialCreationOptionsthat must be provided to the browser's WebAuthn Authentication API to create a credential. The WebAuthn Authentication API
requires data that looks like JSON but contains binary data, represented as ArrayBuffers, that needs to be encoded.
So we can't pass the Hanko APIregistrationInitializationResponsedirectly asPublicKeyCredentialCreationOptions, but you can
use theHanko JavaScript WebAuthn Librarythat wraps the WebAuthn Authentication API
and encodes / decodes the data and allows you to easily pass Hanko API responses to the WebAuthn Authentication API
and vice versa.You can provide theregistrationInitializationResponseobtained from thehanko_client.initialize_registration(request)directly to thecreatefunction of theHanko JavaScript WebAuthn Libraryfor creating a credential.For a more complete
example of the registration process, see theimplementation guidein the Hanko documentation.Registration finalizationAfter you have executed thecreate()function mentioned before and the user has completed the process, you will receive back a response  from the browser's WebAuthn API.Deserialize and pass the Web Authentication API response as returned from the Hanko WebAuthn Library'screatefunction to
thefinalize_registrationclient method.webauthn_response="{\"id\":\"ATIihVy...\", ...}";fromhanko_sdkimportjson_serializerrequest=json_serializer.deserialize_string(webauthn_response,RegistrationFinalizationRequest)response=hanko_client.finalize_registration(request)Authenticate with a registered WebAuthn credentialFor a more complete example of the authentication process, see theimplementation guidein the Hanko documentation.Authentication initializationUsing defaultsuser_id="e3be22a7-13cf-4235-a09c-380dfd44ac04"request=AuthenticationInitializationRequest(User(user_id))response=hanko_client.initialize_authentication(request)Modifying authentication optionsYou can modify the default credential request options for authentication as follows:user_id="e3be22a7-13cf-4235-a09c-380dfd44ac04"request=AuthenticationInitializationRequest(User(user_id),AuthenticationInitializationRequestOptions(UserVerificationRequirement.REQUIRED,AuthenticatorAttachment.PLATFORM))response=hanko_client.initialize_authentication(request)Pass Hanko API response to Web Authentication APIYou can provide theresponseto theget()function of theHanko WebAuthn Libraryfor authenticating with a credential. For a more
complete example of the authentication process, see theimplementation guidein the Hanko documentation.Authentication finalizationDeserialize and pass the Web Authentication API response as returned from the Hanko WebAutn Library'sget()function to thefinalize_authenticationclient method.webauthn_response="{\"id\":\"DaNOpBx...\", ...}";fromhanko_sdkimportjson_serializerrequest=json_serializer.deserialize_string(webauthn_response,AuthenticationFinalizationRequest)response=hankoClient.finalize_authentication(request)Making transactionsA transaction is technically the equivalent of an authentication, with the difference being that when initializing
a transaction, atransaction_textcan be included, which becomes part of the authentication challenge.Transaction initializationUsing defaultsuser_id="e3be22a7-13cf-4235-a09c-380dfd44ac04"request=TransactionInitializationRequest(User(user_id),"Pay $5 to Bob?")response=hanko_client.initialize_transaction(request)Pass Hanko API response to Web Authentication APIYou can provide theresponseto theget()function of theHanko WebAuthn Libraryfor authenticating with a credential. For a more
complete example of the authentication process, see theimplementation guidein the Hanko documentation.Transaction finalizationDeserialize and pass the Web Authentication API response as returned from the Hanko WebAutn Library'sget()function to thefinalize_transactionclient method.webauthn_response="{\"id\":\"fSmpQnC...\", ...}";fromhanko_sdkimportjson_serializerrequest=json_serializer.deserialize_string(webauthn_response,TransactionFinalizationRequest)response=hanko_client.finalize_transaction(request)Credential managementcredential_id="AQohBypyLBrx8R_UO0cWQuu7hhRGv7bPRRGtbQLrjl..."# Get all details of the specified credential.credential=hanko_client.get_credential(credential_id)# Update the name of a credential.update_request=CredentialUpdateRequest("MySecurityKey")updated_credential=hanko_client.update_credential(credential_id,update_request)# Delete the specified credential.hanko_client.delete_credential(credential_id)# Search for credentials filtering by userId and paginating results.query=CredentialQuery("65a3eba6-22cb-4c35-9881-b21fac6acfd0",# userId15,# page size1# page)credentials=hanko_client.list_credentials(query)Serializing and deserializing Hanko payloads and responseAs theHankoHttpClientworks with objects, you may need to serialize or deserialize Hanko payloads and responses. For that you can use thejson_serializermodule as follows:# Import the serializer modulefromhanko_sdkimportjson_serializer# Serialize a TransactionInitializationResponsetransaction_initialization_response=TransactionInitializationResponse()# ... code for generating the transaction initialization responsetransaction_initialization_response_json=hanko_serializer.serialize(transaction_initialization_response)# ... process the transaction initialization response# Deserialize a TransactionFinalizationRequestwebauthn_response="{\"id\":\"fSmpQnC...\", ...}";transaction_finalization_request=json_serializer.deserialize_string(webauthn_response,TransactionFinalizationRequest)finalization_response=hanko_client.finalize_transaction(transaction_finalization_request)Exception handlingtry:user_id="<YOUR_USER_ID>"username="<YOUR_USERNAME>"display_name="<YOUR_DISPLAY_NAME>"request=RegistrationInitializationRequest(User(user_id,username,display_name))responsehanko_client.initialize_registration(request)exceptHankoApiExceptionashanko_api_exception:print(hanko_api_exception)Enable debug loggingTheHankoHttpClientaccepts alogging.Loggerinstance as an optional constructor parameter, which if not none, will be used for debug logging.