Identity API · Replicated

{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"Identity API","type":"basic","slug":"identity-api","excerpt":"","body":"Replicated currently supports integration with LDAP. Identity API provides authentication and syncing with LDAP sever.\n[block:callout]\n{\n \"type\": \"info\",\n \"body\": \"The Identity API is part of the [Integration API](doc:integration-api-reference). To discover the Integration API base endpoint, query the `REPLICATED_INTEGRATIONAPI` environment variable from inside your container.\",\n \"title\": \"Identity API Endpoint\"\n}\n[/block]\n# LDAP Authentication\n[block:api-header]\n{\n \"type\": \"post\",\n \"title\": \"/identity/v1/login\"\n}\n[/block]\nAuthenticates the user and returns the corresponding entry properties.\n\n### Request payload\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Name\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\",\n \"0-0\": \"username\",\n \"0-1\": \"String\",\n \"0-2\": \"As defined by the `ldap_username_field` setting\",\n \"1-0\": \"password\",\n \"1-1\": \"String\",\n \"1-2\": \"Cleartext passowrd\"\n },\n \"cols\": 3,\n \"rows\": 2\n}\n[/block]\n### Response Status code\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Status\",\n \"0-0\": \"200\",\n \"h-1\": \"Description\",\n \"0-1\": \"User authenticated successfully\",\n \"1-0\": \"401\",\n \"1-1\": \"Invalid username or password\",\n \"2-0\": \"\",\n \"2-1\": \"\"\n },\n \"cols\": 2,\n \"rows\": 2\n}\n[/block]\nIn case `200` is returned, the body of the response will contain LDAP properties for the authenticated user entry. The `password` attribute will be omitted from the result.\n\n### Response body\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"DN\",\n \"0-1\": \"String\",\n \"h-0\": \"Name\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\",\n \"0-2\": \"LDAP DN for the user's entry\",\n \"1-0\": \"Username\",\n \"1-1\": \"String\",\n \"1-2\": \"Username\",\n \"2-0\": \"Attributes\",\n \"2-1\": \"Array\",\n \"2-2\": \"An array of available LDAP attributes for the user's entry, including any custom attributes for the user.\",\n \"3-0\": \"Groups\",\n \"3-1\": \"Array\",\n \"3-2\": \"Array of groups that the user belongs to. Each group contains group's DN and a list of its LDAP attributes.\"\n },\n \"cols\": 3,\n \"rows\": 4\n}\n[/block]\n### Example\n\nNote that the response JSON has been prettified for easier reading.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n\\t\\\"DN\\\": \\\"cn=Test User,ou=users,dc=replicated,dc=com\\\",\\n\\t\\\"Username\\\": \\\"testuser\\\",\\n\\t\\\"Groups\\\": [{\\n\\t\\t\\\"DN\\\": \\\"cn=replicated,ou=groups,dc=replicated,dc=com\\\",\\n\\t\\t\\\"ID\\\": \\\"501\\\",\\n\\t\\t\\\"Name\\\": \\\"replicated\\\",\\n\\t\\t\\\"Attributes\\\": {\\n\\t\\t\\t\\\"cn\\\": [\\\"replicated\\\"],\\n\\t\\t\\t\\\"gidnumber\\\": [\\\"501\\\"],\\n\\t\\t\\t\\\"memberuid\\\": [\\\"testuser\\\", \\\"testuser2\\\", \\\"testuser3\\\", \\\"testuser4\\\"],\\n\\t\\t\\t\\\"objectclass\\\": [\\\"posixGroup\\\", \\\"top\\\"]\\n\\t\\t}\\n\\t}],\\n\\t\\\"Attributes\\\": {\\n\\t\\t\\\"cn\\\": [\\\"Test User\\\"],\\n\\t\\t\\\"gidnumber\\\": [\\\"500\\\"],\\n\\t\\t\\\"givenname\\\": [\\\"Test\\\"],\\n\\t\\t\\\"homedirectory\\\": [\\\"/home/users/testuser\\\"],\\n\\t\\t\\\"objectclass\\\": [\\\"inetOrgPerson\\\", \\\"posixAccount\\\", \\\"top\\\"],\\n\\t\\t\\\"sn\\\": [\\\"User\\\"],\\n\\t\\t\\\"uid\\\": [\\\"testuser\\\"],\\n\\t\\t\\\"uidnumber\\\": [\\\"1005\\\"]\\n\\t}\\n}\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"get\",\n \"title\": \"/identity/v1/user/:username\"\n}\n[/block]\nReturns properties for the specified user.\n\n### Response Status code\n[block:parameters]\n{\n \"data\": {\n \"0-1\": \"User authenticated successfully\",\n \"0-0\": \"200\",\n \"1-0\": \"401\",\n \"1-1\": \"Invalid username or password (for LDAP search user)\",\n \"2-0\": \"404\",\n \"2-1\": \"Requested user is not found\"\n },\n \"cols\": 2,\n \"rows\": 3\n}\n[/block]\nIn case `200` is returned, the body of the response is the same as that of the `/identity/v1/login` call.\n[block:api-header]\n{\n \"type\": \"get\",\n \"title\": \"/identity/v1/user/:username/exists\"\n}\n[/block]\nChecks if the supplied `username` exists on the server and returns `true` or `false`.\n\nIn case `200` is returned, the body of the response will be `true` if the user exists or `false` otherwise.\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Status\",\n \"h-1\": \"Description\",\n \"0-0\": \"200\",\n \"0-1\": \"Check completed successfully\",\n \"1-0\": \"401\",\n \"1-1\": \"Invalid username or password\",\n \"2-0\": \"\",\n \"2-1\": \"\"\n },\n \"cols\": 2,\n \"rows\": 2\n}\n[/block]\n### Examples\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"$ curl -k -i $REPLICATED_INTEGRATIONAPI/identity/v1/user/jdoe/exists\\nHTTP/1.1 200 OK\\nContent-Type: text/plain; charset=utf-8\\nDate: Wed, 14 Oct 2015 19:00:30 GMT\\nContent-Length: 4\\n\\ntrue\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"$ curl -k -i $REPLICATED_INTEGRATIONAPI/identity/v1/user/badusername/exists\\nHTTP/1.1 200 OK\\nContent-Type: text/plain; charset=utf-8\\nDate: Wed, 14 Oct 2015 19:00:30 GMT\\nContent-Length: 5\\n\\nfalse\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]","updates":[],"order":6,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5702deb796fc8d2b001a663f","createdAt":"2015-10-14T18:57:52.620Z","githubsync":"","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Integration API","slug":"integration-api","order":7,"from_sync":false,"reference":false,"_id":"5702deb696fc8d2b001a661d","project":"550f1e4021de720d005b8cbb","version":"5702deb696fc8d2b001a6615","createdAt":"2015-03-22T20:15:45.359Z","__v":0},"parentDoc":null,"user":"553faffb23c53c0d00ccce03","version":{"version":"2.0","version_clean":"2.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5702deb696fc8d2b001a6616","5702deb696fc8d2b001a6617","5702deb696fc8d2b001a6618","5702deb696fc8d2b001a6619","5702deb696fc8d2b001a661a","5702deb696fc8d2b001a661b","5702deb696fc8d2b001a661c","5702deb696fc8d2b001a661d","5702deb696fc8d2b001a661e"],"_id":"5702deb696fc8d2b001a6615","createdAt":"2016-04-04T21:37:58.778Z","hasReference":true,"releaseDate":"2016-04-04T21:37:58.778Z","__v":1,"project":"550f1e4021de720d005b8cbb","hasDoc":true},"__v":0,"project":"550f1e4021de720d005b8cbb"}

Replicated currently supports integration with LDAP. Identity API provides authentication and syncing with LDAP sever. [block:callout] { "type": "info", "body": "The Identity API is part of the [Integration API](doc:integration-api-reference). To discover the Integration API base endpoint, query the `REPLICATED_INTEGRATIONAPI` environment variable from inside your container.", "title": "Identity API Endpoint" } [/block] # LDAP Authentication [block:api-header] { "type": "post", "title": "/identity/v1/login" } [/block] Authenticates the user and returns the corresponding entry properties. ### Request payload [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "username", "0-1": "String", "0-2": "As defined by the `ldap_username_field` setting", "1-0": "password", "1-1": "String", "1-2": "Cleartext passowrd" }, "cols": 3, "rows": 2 } [/block] ### Response Status code [block:parameters] { "data": { "h-0": "Status", "0-0": "200", "h-1": "Description", "0-1": "User authenticated successfully", "1-0": "401", "1-1": "Invalid username or password", "2-0": "", "2-1": "" }, "cols": 2, "rows": 2 } [/block] In case `200` is returned, the body of the response will contain LDAP properties for the authenticated user entry. The `password` attribute will be omitted from the result. ### Response body [block:parameters] { "data": { "0-0": "DN", "0-1": "String", "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-2": "LDAP DN for the user's entry", "1-0": "Username", "1-1": "String", "1-2": "Username", "2-0": "Attributes", "2-1": "Array", "2-2": "An array of available LDAP attributes for the user's entry, including any custom attributes for the user.", "3-0": "Groups", "3-1": "Array", "3-2": "Array of groups that the user belongs to. Each group contains group's DN and a list of its LDAP attributes." }, "cols": 3, "rows": 4 } [/block] ### Example Note that the response JSON has been prettified for easier reading. [block:code] { "codes": [ { "code": "{\n\t\"DN\": \"cn=Test User,ou=users,dc=replicated,dc=com\",\n\t\"Username\": \"testuser\",\n\t\"Groups\": [{\n\t\t\"DN\": \"cn=replicated,ou=groups,dc=replicated,dc=com\",\n\t\t\"ID\": \"501\",\n\t\t\"Name\": \"replicated\",\n\t\t\"Attributes\": {\n\t\t\t\"cn\": [\"replicated\"],\n\t\t\t\"gidnumber\": [\"501\"],\n\t\t\t\"memberuid\": [\"testuser\", \"testuser2\", \"testuser3\", \"testuser4\"],\n\t\t\t\"objectclass\": [\"posixGroup\", \"top\"]\n\t\t}\n\t}],\n\t\"Attributes\": {\n\t\t\"cn\": [\"Test User\"],\n\t\t\"gidnumber\": [\"500\"],\n\t\t\"givenname\": [\"Test\"],\n\t\t\"homedirectory\": [\"/home/users/testuser\"],\n\t\t\"objectclass\": [\"inetOrgPerson\", \"posixAccount\", \"top\"],\n\t\t\"sn\": [\"User\"],\n\t\t\"uid\": [\"testuser\"],\n\t\t\"uidnumber\": [\"1005\"]\n\t}\n}", "language": "curl" } ] } [/block] [block:api-header] { "type": "get", "title": "/identity/v1/user/:username" } [/block] Returns properties for the specified user. ### Response Status code [block:parameters] { "data": { "0-1": "User authenticated successfully", "0-0": "200", "1-0": "401", "1-1": "Invalid username or password (for LDAP search user)", "2-0": "404", "2-1": "Requested user is not found" }, "cols": 2, "rows": 3 } [/block] In case `200` is returned, the body of the response is the same as that of the `/identity/v1/login` call. [block:api-header] { "type": "get", "title": "/identity/v1/user/:username/exists" } [/block] Checks if the supplied `username` exists on the server and returns `true` or `false`. In case `200` is returned, the body of the response will be `true` if the user exists or `false` otherwise. [block:parameters] { "data": { "h-0": "Status", "h-1": "Description", "0-0": "200", "0-1": "Check completed successfully", "1-0": "401", "1-1": "Invalid username or password", "2-0": "", "2-1": "" }, "cols": 2, "rows": 2 } [/block] ### Examples [block:code] { "codes": [ { "code": "$ curl -k -i $REPLICATED_INTEGRATIONAPI/identity/v1/user/jdoe/exists\nHTTP/1.1 200 OK\nContent-Type: text/plain; charset=utf-8\nDate: Wed, 14 Oct 2015 19:00:30 GMT\nContent-Length: 4\n\ntrue", "language": "curl" } ] } [/block] [block:code] { "codes": [ { "code": "$ curl -k -i $REPLICATED_INTEGRATIONAPI/identity/v1/user/badusername/exists\nHTTP/1.1 200 OK\nContent-Type: text/plain; charset=utf-8\nDate: Wed, 14 Oct 2015 19:00:30 GMT\nContent-Length: 5\n\nfalse", "language": "curl" } ] } [/block]