API et documentation
-
1. Qu’est ce que PhoneKey?
Phonekey est un service d’identification et d’authentification forte par SMS. L’identité d’un utilisateur est associé à son numéro de téléphone et la vérification de cette identité se fait grâce au SMS qu’il envoi à PhoneKey depuis ce même téléphone.
Une mise en œuvre Phonekey est disponible en PHP (> = 5.3). Ce mode de réalisation fourni des méthodes simples pour interagir avec le service de Phonekey.
2. Qui peut utiliser PhoneKey?
Actuellement, seuls les développeurs PHP peuvent utiliser PhoneKey. Les implémentations via d’autres langages sont en cours de conception.
3. Pour commencer
1. Créer un compte
Allez sur http://webservice.phonekey.eu/signin pour créer votre compte
2. Générer une clé SSH au format PEM
Vous devez générer un couple de clés privées / publiques afin d’être en mesure d’utiliser le webservice. Tout d’abord ouvrir votre terminal préféré et générer votre clé privée, par défaut, vous devrez définir un mot de passe
$> openssl genrsa -des3 -out private 2048Puis extraire la clé publique de la clé privée générée:
$> openssl rsa -in private -outform PEM -pubout -out public.pemEnfin, exporter votre clé privée non cryptée:
$> openssl rsa -in private -out private.pem -outform PEMEnsuite, vous pouvez supprimer le fichier «privé» mais gardez « public.pem » et « private.pem »
Note: openssl est fourni par le paquet openssl sur Debian / Ubuntu.3. Votre fichier de configuration
Allez sur votre compte: http://webservice.phonekey.eu/user/profile
Copier / coller la clé publique précédemment générée (le contenu de ‘public.pem’) dans la section "Paramètres du profil".Télécharger l’archive de l’API, qui est sur http://webservice.phonekey.eu/ et décompressez-la. Cette archive contient une implémentation PHP avec les outils pour configurer et utiliser l’API de PhoneKey.
Lire et éditer la section Ce que vous avez à mettre en place dans le « conf_help.php ».
L’information nécessaire pour remplir cette section êtes ici: http://webservice.phonekey.eu/user/profile.
Exécuter « conf_help.php » avec PHP. Il va créer un fichier de configuration nécessaire pour utiliser le webservice.
N’oubliez pas de mettre le nom que vous avez donné au fichier de config dans la « PhoneKeyAPI.class.php ».
Comme le fichier de configuration contient toutes les informations nécessaires pour vous authentifier au webservice PhoneKey, n’oubliez pas de le protéger contre tout accès. En d’autres termes ne mettez pas ce fichier sur un chemin accessible depuis votre serveur web.4. Qu’est ce que vous devez savoir au sujet de l’API
PhoneKey vous permet d’identifier et d’authentifier vos utilisateurs grâce à des jetons dits "token".
Le premier s’appelle “token distant”, et le second "token local"Qu’est ce que l’authentification avec un token distant?
An authentication with a remote token will ask PhoneKey to handle the communication with your client directly, during all the states of the procedure. You must provide 3 URLs that will be used to redirect the client in the 3 possible cases of an authentication process:
Une authentification avec un token distant demandera à PhoneKey de gérer la communication avec votre client directement, au cours de tous les états de la procédure. Vous devez alors fournir 3 URLs qui seront utilisées pour rediriger le client dans les trois cas possibles d’un processus d’authentification:
- Succes URL : si le client s’authentifie avec succes
- Abort URL : si le client décide d’annuler l’authentification
- Time out URL : si le client dépasse le temps apparti de connexion
En retour, PhoneKey vous donnera un jeton contenant une URL unique pour rediriger votre client vers sa session.
Vous avez deux façons de créer un jeton à distance:
La première façon s’utilise quand vous connaissez le numéro de téléphone de votre client. Dans ce cas vous devez utiliser la fonction requestRemoteAuthenticationWithPhoneNumber () .
La deuxième façon est lorsque vous ne connaissez pas votre numéro de téléphone du client et que vous souhaitez laisser PhoneKey pour le lui demander Dans ce cas, vous devez utiliser la fonction requestRemoteAuthentication () .
Vous pouvez regarder l’état du jeton ( après que le client ai été redirigé vers votre site) avec la fonction getStatus () .
Qu’est-ce que l’authentification avec un token local ?
Pour créer un token local, vous devez connaître le numéro de téléphone de votre utilisateur et le soumettre à la fonction
requestLocalAuthentication() .Dans ce cas, c’est à vous de regarder l’état du jeton en appelant la fonction getStatus () périodiquement. En effet, PhoneKey ne vous informera pas pour vous donner l’état du jeton.
5. Faire le premier test
L’archive que vous décompresserez contient 2 fichiers dont vous avez besoin pour communiquer avec le PhoneKey :
"PhoneKeyAPI.class.php" et "PhoneKeyServiceException.class.php"Le troisième fichier "usage_example.php"est un exemple fonctionnel d’utilisation montrant les exemples précédemment cités. Le code est commenté.
Pour nous contacter
-
1. What’s Phonekey?
Phonekey is a web service which aims to provide a strong user authentication by using SMS service: you give us a phone number, we give you a 5 digits code, a phone number on which to send the code and a token code. With this token code, you can ask us if the 5 digits code has been received from the phone number you provided.
A Phonekey implementation is available in PhP (>=5.3). This implementation provides some simple methods to interact with the Phonekey service.2. Who can use it?
Currently, only a PHP implementation of the service is available, so PHP developers can use it now. Some implementations in several other languages will come later.
3. Getting started
1. Create your account
Go to http://webservice.phonekey.eu/signin to create your account.
2. Generating SSH keys in a PEM format
You have to generate a couple of private/public keys in order to be able to use the webservice.
First of all open your preferred terminal and generate your private key, by default you will have to set a password on it:$> openssl genrsa -des3 -out private 2048Then extract the public key from the private key generated:
$> openssl rsa -in private -outform PEM -pubout -out public.pemFinally, export your private key unencrypted:
$> openssl rsa -in private -out private.pem -outform PEMThen you can delete the file ‘private’ but keep ‘public.pem’ and ‘private.pem’ Note: openssl is provided by the openssl package on Debian/Ubuntu.
3. Setting up your config file
Go on your account: http://webservice.phonekey.eu/user/profile
Copy/past the public key your just generated (the content of ‘public.pem’) in the “Profile settings” section.
Download the API archive, which is on http://webservice.phonekey.eu/ and unzip it. This archive contains a PhP implementation with some tools to configure and use the PhoneKey API.
Read and edit the section “What you have to set up” in the “conf_help.php”. The information needed
to fill this section are here: http://webservice.phonekey.eu/user/profile.Execute “conf_help.php” with PhP. It will create a config file needed to use the webservice. Don’t forget to put the name you gave to the config file in the “PhoneKeyAPI.class.php”. As the config file contains all the information needed to authenticate you to the PhoneKey webservice, don’t forget to protect it against any access other that your scripts using it. In others words don’t put this file on an accessible path through your webserver.
4. What you have to know to use the API
PhoneKey provides you to way of authenticating your clients.
One with what we call a « Remote Token », and the second with what we call a « Local Token ».What’s an authentication with a Remote Token?
An authentication with a remote token will ask PhoneKey to handle the communication with your client directly, during all the states of the procedure. You must provide 3 URLs that will be used to redirect the client in the 3 possible cases of an authentication process:
- Succes URL : if the client authentication succeeds
- Abort URL : if the client decides to abort his authentication
- Time out URL : if the time given to authenticate is elapsed
In return, PhoneKey will give you a token containing a unique URL for redirecting your client to an authentication session.
You have two ways to create a remote token. The first way is when you know the phone number of your client, so you can call the requestRemoteAuthenticationWithPhoneNumber() function. The second way is when you don’t know your client phone number and you want to let PhoneKey ask him for you, then you can use the requestRemoteAuthentication() function.
You can watch the status of the token (i.e. after the client has been redirected to your site) with the getStatus() function.
What’s an authentication with a Local token?
It’s almost the same thing than a Remote Token authentication.
To create such a Token, you have to know the phone number of your client and provide it to the
requestLocalAuthentication() function.The difference in this case is that it’s up to you to watch the state of the Token by calling the getStatus()
function periodically. Indeed, PhoneKey will not call you back to tell you the state of the token.5. Making a first test
The archive you uncompressed contains 2 files needed to communicate with the webservice: “PhoneKeyAPI.class.php” and “PhoneKeyServiceException.class.php”.
A third file “usage_example.php” contains a functional example of the use of the PhoneKeyAPI showed in the previous item. All the mechanic is explained by comments inside this fil. You will need a web browser to run it through an HTTP server + PhP >=5.3.Do you want to contact us ?
contact@phonekey.eu
We accept mail in English and French and answer in these languages.
en cours de traduction