{"_id":"59ca58721382cb00103a110c","project":"54eb50e5615ffc1900305a16","version":{"_id":"54eb63b859b1172100334fae","project":"54eb50e5615ffc1900305a16","forked_from":"54eb63a1867e1917009b711d","__v":28,"createdAt":"2015-02-23T17:30:32.501Z","releaseDate":"2015-02-23T17:30:32.501Z","categories":["54eb63b959b1172100334faf","54eb63b959b1172100334fb0","54eb63b959b1172100334fb1","54eb63b959b1172100334fb2","54ed8dd4ab373e2300f50eae","54ed99b2ab373e2300f50ede","55153a6de68daa2f00cff838","551546edbc466623002afe72","5515472ac28d6125001b8884","55154749c28d6125001b8885","555d9b4106dfec0d00d38ea7","5613e06e433e5735007c7708","5624bbb785a31117001c5403","56669e857cc81e0d00253f8e","568b8d837a42220d00498311","56a632277ef6620d00e2f18a","56d8147c3eb4dd0b00201aac","57a9ce2fac6db30e000d7efd","57a9cf4e944ea60e00dc3f74","58172386715dce0f00da4aa0","582dc59ee1b8692300c0dd03","589b19b4fec2730f0082e040","58b04a023529383900a759b5","58b92d1598157a0f004869bf","592e7685c58275000f20174f","59392839e376d4002f8a0474","59393064e376d4002f8a05a1","5947ae0d4005e2000f3a4fec","594a74df1d1de5001ab3517a","5954bc387a147f001b918915","59b8eeeb707542001076d3b6"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"category":{"_id":"5624bbb785a31117001c5403","pages":["5653264657978b1700df716a","5655bcf8dd82540d00278c26","5655bfd81a06b61900c66873","5655c7c0a66be71700968dd7","5660588e4320a80d00bec124","56618ad455e4450d00e62b89","56f1685a2a85600e00ea3dca"],"project":"54eb50e5615ffc1900305a16","version":"54eb63b859b1172100334fae","__v":7,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-10-19T09:45:27.364Z","from_sync":false,"order":11,"slug":"2-factor-authentication","title":"2-factor authentication"},"user":"54eb4fdedf7add210007b29b","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-26T13:38:58.523Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":15,"body":"**2-factor authentication** (2FA) is a cloud messaging security solution that confirms the identity of the user and protects the system from phishing or hacking attacks.\n\nA one-time PIN (PIN code) is generated and sent to the user's mobile phone. The user receives the PIN code and types it into the application to confirm the identity. If the PIN number that was sent out to the user matches the one that is received, the user is allowed to continue with the process.\n\nThis introduction will help you to get started:\n1. [Explaining the 2FA process and how it works](#2fa-process-overview)\n2. [Set up your first application and message template](#2fa-setup)\n3. [Send and verify PIN numbers](#send-and-verify-pins) \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2FA process overview\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b9470ef-2faFlow.jpg\",\n        \"2faFlow.jpg\",\n        1500,\n        1277,\n        \"#3c535b\"\n      ]\n    }\n  ]\n}\n[/block]\n1. User enters the Phone number into the client's application (mobile or web). The other option is that the client pulls the phone number from his user database.\n2. Application sends a request for the PIN code with the user’s phone number to Infobip\n3. Infobip generates the PIN and PIN ID, and sends the PIN ID back to the application\n4. Infobip sends Number lookup request to the MNO \n5. Infobip receives Number Lookup response from the MNO\n6. Infobip sends Number Lookup response to the Application\n7. If the Number Lookup result is valid, Infobip generates the PIN code and sends it via SMS\n8. MNO delivers the SMS with the PIN code\n9. Infobip receives the Delivery report for sent message\n10. User enters the received PIN code into the application\n11. Application sends the verification request with the PIN code and PIN  ID\n12. Infobip verifies the received PIN and sends the response to the application\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"**Steps 4** and **5** are important for clients that want to check whether the user entered a valid phone number before sending the verification SMS. We use Number Lookup to check the phone number validity. If the phone number is not valid (i.e. doesn’t exists) we don't generate the PIN code or send an SMS. In this way we prevent unnecessary costs for our clients. These steps are optional to fit the customer needs.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"2FA setup\"\n}\n[/block]\nSetup consists of two parts and requires only 2 API calls to complete the setup process - Application setup and Message template setup. Later, you will reuse message template(s) to send out PINs.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/cd1e1d5-2faSetup.PNG\",\n        \"2faSetup.PNG\",\n        716,\n        89,\n        \"#e3cfd0\"\n      ]\n    }\n  ]\n}\n[/block]\n###1. Application setup\n\n**Application** represents your service. It's a good practice to have separate applications for separate services. You may also have separate applications for the same service but different use cases. For example, 2FA for login may be represented as one application and 2FA for changing password as another. Separating use cases in different applications will allow you to choose different options and behavior for for each use case (like PIN attempts or PIN limits). \nStart building your 2FA service by [creating the application](/docs/2fa-application-setup).\n\n###2. Message template setup\n\n**Message template** is the message body with the PIN placeholder that will be sent to end users. You may create many message templates per single application and therefore use the same application for different use cases or different languages. When you create your message template, you will be provided with the message template ID, which you will be using later when sending PINs. By referencing a message template ID, our system will generate a PIN, place the PIN in the message template and finally send the message with the PIN to the end user.\nSee [message template documentation](/docs/2fa-message-template) for details.\n[block:api-header]\n{\n  \"title\": \"Send and verify PINs\"\n}\n[/block]\nOnce the Application and Message template are created, you are ready to send out PIN messages. The process also consists of two steps - Send PIN and Verify PIN.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/02a87e1-2faSendVerify.PNG\",\n        \"2faSendVerify.PNG\",\n        716,\n        92,\n        \"#ded0cd\"\n      ]\n    }\n  ]\n}\n[/block]\n###1. Send PIN\nPINs are generated by our system and sent out using message templates. You can have one or more message templates in each application and you can reuse each template to send out PINs as many times as you like. \n\n###2. Verify PIN\nSending out the PIN is just the fist step. Once the end user received the PIN to confirm his identity, you will need to verify if the PIN is correct and valid.\n\nSee [Send and Verify PIN documentation](/docs/send-and-verify-2fa-pin) for details.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Verify PIN Authorization\",\n  \"body\": \"Sending and Verifying a PIN requires the API key authorization method. [API key for 2FA documentation](/docs/api-key-create) describes how to create one.\"\n}\n[/block]","excerpt":"Learn more about 2-Factor Authentication (2FA) and how to set it up.","slug":"2fa-introduction-and-setup","type":"basic","title":"Introduction and setup"}

Introduction and setup

Learn more about 2-Factor Authentication (2FA) and how to set it up.

**2-factor authentication** (2FA) is a cloud messaging security solution that confirms the identity of the user and protects the system from phishing or hacking attacks. A one-time PIN (PIN code) is generated and sent to the user's mobile phone. The user receives the PIN code and types it into the application to confirm the identity. If the PIN number that was sent out to the user matches the one that is received, the user is allowed to continue with the process. This introduction will help you to get started: 1. [Explaining the 2FA process and how it works](#2fa-process-overview) 2. [Set up your first application and message template](#2fa-setup) 3. [Send and verify PIN numbers](#send-and-verify-pins) [block:api-header] { "type": "basic", "title": "2FA process overview" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/b9470ef-2faFlow.jpg", "2faFlow.jpg", 1500, 1277, "#3c535b" ] } ] } [/block] 1. User enters the Phone number into the client's application (mobile or web). The other option is that the client pulls the phone number from his user database. 2. Application sends a request for the PIN code with the user’s phone number to Infobip 3. Infobip generates the PIN and PIN ID, and sends the PIN ID back to the application 4. Infobip sends Number lookup request to the MNO 5. Infobip receives Number Lookup response from the MNO 6. Infobip sends Number Lookup response to the Application 7. If the Number Lookup result is valid, Infobip generates the PIN code and sends it via SMS 8. MNO delivers the SMS with the PIN code 9. Infobip receives the Delivery report for sent message 10. User enters the received PIN code into the application 11. Application sends the verification request with the PIN code and PIN ID 12. Infobip verifies the received PIN and sends the response to the application [block:callout] { "type": "info", "title": "Note:", "body": "**Steps 4** and **5** are important for clients that want to check whether the user entered a valid phone number before sending the verification SMS. We use Number Lookup to check the phone number validity. If the phone number is not valid (i.e. doesn’t exists) we don't generate the PIN code or send an SMS. In this way we prevent unnecessary costs for our clients. These steps are optional to fit the customer needs." } [/block] [block:api-header] { "title": "2FA setup" } [/block] Setup consists of two parts and requires only 2 API calls to complete the setup process - Application setup and Message template setup. Later, you will reuse message template(s) to send out PINs. [block:image] { "images": [ { "image": [ "https://files.readme.io/cd1e1d5-2faSetup.PNG", "2faSetup.PNG", 716, 89, "#e3cfd0" ] } ] } [/block] ###1. Application setup **Application** represents your service. It's a good practice to have separate applications for separate services. You may also have separate applications for the same service but different use cases. For example, 2FA for login may be represented as one application and 2FA for changing password as another. Separating use cases in different applications will allow you to choose different options and behavior for for each use case (like PIN attempts or PIN limits). Start building your 2FA service by [creating the application](/docs/2fa-application-setup). ###2. Message template setup **Message template** is the message body with the PIN placeholder that will be sent to end users. You may create many message templates per single application and therefore use the same application for different use cases or different languages. When you create your message template, you will be provided with the message template ID, which you will be using later when sending PINs. By referencing a message template ID, our system will generate a PIN, place the PIN in the message template and finally send the message with the PIN to the end user. See [message template documentation](/docs/2fa-message-template) for details. [block:api-header] { "title": "Send and verify PINs" } [/block] Once the Application and Message template are created, you are ready to send out PIN messages. The process also consists of two steps - Send PIN and Verify PIN. [block:image] { "images": [ { "image": [ "https://files.readme.io/02a87e1-2faSendVerify.PNG", "2faSendVerify.PNG", 716, 92, "#ded0cd" ] } ] } [/block] ###1. Send PIN PINs are generated by our system and sent out using message templates. You can have one or more message templates in each application and you can reuse each template to send out PINs as many times as you like. ###2. Verify PIN Sending out the PIN is just the fist step. Once the end user received the PIN to confirm his identity, you will need to verify if the PIN is correct and valid. See [Send and Verify PIN documentation](/docs/send-and-verify-2fa-pin) for details. [block:callout] { "type": "warning", "title": "Verify PIN Authorization", "body": "Sending and Verifying a PIN requires the API key authorization method. [API key for 2FA documentation](/docs/api-key-create) describes how to create one." } [/block]