{"_id":"571509e8ff0cce190056edf5","parentDoc":null,"__v":14,"version":{"_id":"56a83b989ec7660d002e07c1","project":"56a83b979ec7660d002e07be","__v":9,"createdAt":"2016-01-27T03:38:00.333Z","releaseDate":"2016-01-27T03:38:00.333Z","categories":["56a83b989ec7660d002e07c2","56a83c282036420d002d21e1","56a96de8f834950d0037b35a","56a9706013a69a0d00a778c3","56a970ec2d8fd90d0036eec7","56a971a62bb3910d000ee934","56a973372d8fd90d0036eece","56a978dc2bb3910d000ee93f","571d5ae118b3c10e003e55cd"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Beta","version_clean":"1.0.0","version":"1.0"},"project":"56a83b979ec7660d002e07be","user":"56b673a022bf021700123a6b","category":{"_id":"56a83b989ec7660d002e07c2","pages":["56a83b999ec7660d002e07c4","56a83c1011d0390d00a3d107","56a83c6ded52570d0001a1e8","56a83cba70a9440d00ef5ef9","56a83f1470a9440d00ef5efb","56a83f5b70a9440d00ef5efd","56a97284f834950d0037b35e","56a973312bb3910d000ee937"],"project":"56a83b979ec7660d002e07be","version":"56a83b989ec7660d002e07c1","__v":8,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-27T03:38:00.961Z","from_sync":false,"order":1,"slug":"documentation","title":"General"},"githubsync":"","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-18T16:23:04.775Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"<div class=\"corner-ribbon top-left sticky blue\"><a style=\"color: white;\" href=\"https://pathfinder.readme.io/blog/pathfinder-now-in-public-beta\">Public Beta!</a></div>\n\nThere are several ways to provide authentication with your pathfinder application depending on the developer's needs. Pathfinder supports ready to use authentication but allows developers to use their own custom authentication.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication Flow\"\n}\n[/block]\nWhich ever authentication scheme you use for your application, the general flow is relatively the same. \n\n1. When the client attempts to connect to the Pathfinder service, Pathfinder responds with a randomly generated, unique connection id.\n\n2. This connection id, along with data identifying the user, is then sent to a server responsible for authenticating users.\n\n3. Once the authentication server is ready, the client sends an authenticate message back to the Pathfinder service.\n\n4. The Pathfinder service then sends a request to the authentication server to determine of it is okay to allow the user to open the connection.\n\n5. If that is successful, an authenticated message is sent back to the client and then the client can start using the developer's Pathfinder data.\n[block:image]\n{\n  \"images\": [\n    {}\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Pathfinder Authentication\"\n}\n[/block]\nPathfinder provides ready to go authentication. All the developer has to do is configure the application's authentication settings through the application dashboard. By default, Pathfinder uses google openid connect tokens to identify users. The client must get the user's openid connect token and then provide it to the SDK. The process of obtaining an open id connect token is shown [here](https://developers.google.com/identity/protocols/OpenIDConnect). How to use the id tokens is shown below.\n\n\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/vZ1xkKgGR8KcGWTQXmoL_auth.png\",\n        \"auth.png\",\n        \"1010\",\n        \"269\",\n        \"#4b5d76\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Permissions\"\n}\n[/block]\n\nThe application dashboard allows the developer to set up a white list of email addresses of users who have access to the application data stored by pathfinder. This includes all of the clusters, transports, and commodities in the application.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Custom Authentication\"\n}\n[/block]\nThe Pathfinder API also allows the developer to roll their own authentication. They just need to implement their own authentication endpoint and configure their application to use it. Note that the permissions set on the dashboard only apply to Pathfinder authentication. If you decide to use custom authentication, then the endpoint you've set up to handle authentication needs to be able to handle permissions.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Custom Authentication Flow\"\n}\n[/block]\nCustom authentication is more involved since it requires setting up your own authentication server and requires a few extra steps to use the SDKs.\n\nThe SDKs allow you to specify what happens when a user attempts to use Pathfinder. For custom authentication, your app should send user information along with the received connection id to your authentication server. From this, the authentication server should prepare to response to a connection request from the api server. Through the response, the authentication server indicates whether the user trying to use Pathfinder is authorized to. The url of your authentication server is specified using the authentication configurations on the Pathfinder dashboard.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/MqsxJVIToCeYu2YJbMFD_customauth.png\",\n        \"customauth.png\",\n        \"1016\",\n        \"272\",\n        \"#51688b\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nOnce it is configured, the api server sends a get request to the specified url whenever a Pathfinder client requests authentication.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET www.my_auth_server.com/connection?connection_id=cfc85366-a8f3-42a8-ad7d-95537a8cd18e&application_id=9869bd06-12ec-451f-8207-2c5f217eb4d0 HTTPS/1.1\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nIt has two query parameters, connection_id and application_id. Once your server receives this request, it needs to respond with a Pathfinder JWT signed with your private key.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"header = {\\n  \\\"alg\\\": \\\"HS256\\\",\\n  \\\"typ\\\": \\\"JWT\\\"\\n}\\npayload = {\\n\\t\\\"aud\\\":\\\"https://api.thepathfinder.xyz\\\",\\n  \\\"iss\\\":your_app_id,\\n  \\\"exp\\\":1461549610,\\n  \\\"sub\\\":connection_id,\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nPathfinder then should be ready to use","excerpt":"","slug":"authentication","type":"basic","title":"Authentication"}
<div class="corner-ribbon top-left sticky blue"><a style="color: white;" href="https://pathfinder.readme.io/blog/pathfinder-now-in-public-beta">Public Beta!</a></div> There are several ways to provide authentication with your pathfinder application depending on the developer's needs. Pathfinder supports ready to use authentication but allows developers to use their own custom authentication. [block:api-header] { "type": "basic", "title": "Authentication Flow" } [/block] Which ever authentication scheme you use for your application, the general flow is relatively the same. 1. When the client attempts to connect to the Pathfinder service, Pathfinder responds with a randomly generated, unique connection id. 2. This connection id, along with data identifying the user, is then sent to a server responsible for authenticating users. 3. Once the authentication server is ready, the client sends an authenticate message back to the Pathfinder service. 4. The Pathfinder service then sends a request to the authentication server to determine of it is okay to allow the user to open the connection. 5. If that is successful, an authenticated message is sent back to the client and then the client can start using the developer's Pathfinder data. [block:image] { "images": [ {} ] } [/block] [block:api-header] { "type": "basic", "title": "Using Pathfinder Authentication" } [/block] Pathfinder provides ready to go authentication. All the developer has to do is configure the application's authentication settings through the application dashboard. By default, Pathfinder uses google openid connect tokens to identify users. The client must get the user's openid connect token and then provide it to the SDK. The process of obtaining an open id connect token is shown [here](https://developers.google.com/identity/protocols/OpenIDConnect). How to use the id tokens is shown below. [block:image] { "images": [ { "image": [ "https://files.readme.io/vZ1xkKgGR8KcGWTQXmoL_auth.png", "auth.png", "1010", "269", "#4b5d76", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Permissions" } [/block] The application dashboard allows the developer to set up a white list of email addresses of users who have access to the application data stored by pathfinder. This includes all of the clusters, transports, and commodities in the application. [block:api-header] { "type": "basic", "title": "Custom Authentication" } [/block] The Pathfinder API also allows the developer to roll their own authentication. They just need to implement their own authentication endpoint and configure their application to use it. Note that the permissions set on the dashboard only apply to Pathfinder authentication. If you decide to use custom authentication, then the endpoint you've set up to handle authentication needs to be able to handle permissions. [block:api-header] { "type": "basic", "title": "Custom Authentication Flow" } [/block] Custom authentication is more involved since it requires setting up your own authentication server and requires a few extra steps to use the SDKs. The SDKs allow you to specify what happens when a user attempts to use Pathfinder. For custom authentication, your app should send user information along with the received connection id to your authentication server. From this, the authentication server should prepare to response to a connection request from the api server. Through the response, the authentication server indicates whether the user trying to use Pathfinder is authorized to. The url of your authentication server is specified using the authentication configurations on the Pathfinder dashboard. [block:image] { "images": [ { "image": [ "https://files.readme.io/MqsxJVIToCeYu2YJbMFD_customauth.png", "customauth.png", "1016", "272", "#51688b", "" ] } ] } [/block] Once it is configured, the api server sends a get request to the specified url whenever a Pathfinder client requests authentication. [block:code] { "codes": [ { "code": "GET www.my_auth_server.com/connection?connection_id=cfc85366-a8f3-42a8-ad7d-95537a8cd18e&application_id=9869bd06-12ec-451f-8207-2c5f217eb4d0 HTTPS/1.1\n", "language": "javascript" } ] } [/block] It has two query parameters, connection_id and application_id. Once your server receives this request, it needs to respond with a Pathfinder JWT signed with your private key. [block:code] { "codes": [ { "code": "header = {\n \"alg\": \"HS256\",\n \"typ\": \"JWT\"\n}\npayload = {\n\t\"aud\":\"https://api.thepathfinder.xyz\",\n \"iss\":your_app_id,\n \"exp\":1461549610,\n \"sub\":connection_id,\n}", "language": "javascript" } ] } [/block] Pathfinder then should be ready to use