{"__v":6,"_id":"551c450c0360770d00f5ce3a","category":{"__v":5,"_id":"53fe7d8daddab8973c1af2b1","pages":["53fe732eaddab8973c1af27f","53fe7df4addab8973c1af2b7","53fe7e08addab8973c1af2b9","544945633acc37080099e719","551c450c0360770d00f5ce3a"],"project":"53fe6dc5addab8973c1af267","version":"53fe6dc5addab8973c1af26a","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-08-28T00:53:33.662Z","from_sync":false,"order":5,"slug":"login-reference","title":"Login Reference"},"parentDoc":null,"project":"53fe6dc5addab8973c1af267","user":"53fe6d8baddab8973c1af266","version":{"__v":19,"_id":"53fe6dc5addab8973c1af26a","project":"53fe6dc5addab8973c1af267","createdAt":"2014-08-27T23:46:13.941Z","releaseDate":"2014-08-27T23:46:13.941Z","categories":["53fe6dc5addab8973c1af26b","53fe71a2addab8973c1af276","53fe7d89addab8973c1af2b0","53fe7d8daddab8973c1af2b1","53fe836faddab8973c1af2ce","53ff9a4823a37e1d5cebafe1","53ff9e3723a37e1d5cebaff7","53ffaca523a37e1d5cebb039","53ffad2e23a37e1d5cebb03c","5400c7d2ec93b29b61d4f7be","5400f0e1ec93b29b61d4f7dd","54d5636323010a0d001aca81","54d565c1276f8e0d00feab54","54ff40532882a10d00546927","556606d25561af0d008208b7","558c91900b236c2500d37c9a","56180a14f8c9632100ac7599","564fb3a59b4fab1700187518","5702e2d2f2d6f336005e901f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-04-01T19:20:44.899Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Verifying the `state` parameter\"\n}\n[/block]\nTo protect against CSRF attacks, you should *always* pass in a `state` parameter to either the Clef button (with `data-state`) or the Clef login URL (by specifying `&state=` in the URL). In the handshake, this `state` parameter will be passed back and you'll need to verify that it is the same as the one you passed in.\n\n**This check is especially important if you are connecting Clef to an already existing account. If it's not implemented correctly, it can lead to [\"The Most Common OAuth2 Vulnerability\"](http://homakov.blogspot.com/2012/07/saferweb-most-common-oauth2.html).**\n\n# Implementation\n\nIn your web app, you likely already have some method of generating and verifying CSRF tokens. You should use this functionality to generate and verify the `state` parameter. \n\nOn generation side, this might look something like:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script data-state=\\\"{{ generate_csrf_token }}\\\" data-app-id=\\\"YOUR_APP_ID\\\" data-redirect-url=\\\"YOUR_REDIRECT_URL\\\" class=\\\"clef-button\\\" src=\\\"https://clef.io/v3/clef.js\\\"></script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nOn the verification side, this might look something like:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"state = request.args.get('state')\\nif not verify_csrf_token(state):\\n    raise BadStateException\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"verifying-state-parameter","type":"basic","title":"Verifying the state parameter"}

Verifying the state parameter


[block:api-header] { "type": "basic", "title": "Verifying the `state` parameter" } [/block] To protect against CSRF attacks, you should *always* pass in a `state` parameter to either the Clef button (with `data-state`) or the Clef login URL (by specifying `&state=` in the URL). In the handshake, this `state` parameter will be passed back and you'll need to verify that it is the same as the one you passed in. **This check is especially important if you are connecting Clef to an already existing account. If it's not implemented correctly, it can lead to ["The Most Common OAuth2 Vulnerability"](http://homakov.blogspot.com/2012/07/saferweb-most-common-oauth2.html).** # Implementation In your web app, you likely already have some method of generating and verifying CSRF tokens. You should use this functionality to generate and verify the `state` parameter. On generation side, this might look something like: [block:code] { "codes": [ { "code": "<script data-state=\"{{ generate_csrf_token }}\" data-app-id=\"YOUR_APP_ID\" data-redirect-url=\"YOUR_REDIRECT_URL\" class=\"clef-button\" src=\"https://clef.io/v3/clef.js\"></script>", "language": "html" } ] } [/block] On the verification side, this might look something like: [block:code] { "codes": [ { "code": "state = request.args.get('state')\nif not verify_csrf_token(state):\n raise BadStateException", "language": "python" } ] } [/block]