{"id":15755445,"url":"https://github.com/grantbirki/ldap-api","last_synced_at":"2026-03-11T16:04:30.338Z","repository":{"id":213165616,"uuid":"733199680","full_name":"GrantBirki/ldap-api","owner":"GrantBirki","description":"A RESTful API and caching layer for LDAP written in Ruby","archived":false,"fork":false,"pushed_at":"2026-01-19T06:20:39.000Z","size":80882,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-19T14:46:14.803Z","etag":null,"topics":["cache","json","ldap","rest","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GrantBirki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-18T19:36:44.000Z","updated_at":"2026-01-19T06:20:41.000Z","dependencies_parsed_at":"2023-12-19T02:43:21.980Z","dependency_job_id":"16e0c15c-4f50-40a6-95c6-0b21e722d496","html_url":"https://github.com/GrantBirki/ldap-api","commit_stats":{"total_commits":119,"total_committers":3,"mean_commits":"39.666666666666664","dds":"0.32773109243697474","last_synced_commit":"57ee62a8dc796bd5c173c7a5b41fd0e42d55cee0"},"previous_names":["grantbirki/ldap-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GrantBirki/ldap-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrantBirki%2Fldap-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrantBirki%2Fldap-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrantBirki%2Fldap-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrantBirki%2Fldap-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GrantBirki","download_url":"https://codeload.github.com/GrantBirki/ldap-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrantBirki%2Fldap-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30387014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T14:10:17.325Z","status":"ssl_error","status_checked_at":"2026-03-11T14:09:37.934Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","json","ldap","rest","ruby"],"created_at":"2024-10-04T08:21:52.445Z","updated_at":"2026-03-11T16:04:30.321Z","avatar_url":"https://github.com/GrantBirki.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ldap-api\n\n[![acceptance](https://github.com/GrantBirki/ldap-api/actions/workflows/acceptance.yml/badge.svg)](https://github.com/GrantBirki/ldap-api/actions/workflows/acceptance.yml) [![lint](https://github.com/GrantBirki/ldap-api/actions/workflows/lint.yml/badge.svg)](https://github.com/GrantBirki/ldap-api/actions/workflows/lint.yml) [![CodeQL](https://github.com/GrantBirki/ldap-api/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/GrantBirki/ldap-api/actions/workflows/codeql-analysis.yml)\n\nldap-api is a small read-only Ruby Rack application intended to be a REST service providing access to users and groups stored in a LDAP backend with optional caching configuration.\n\n## REST API Description\n\nFor conveninence we named current version as number 1 to be prepared if a meaningfull change in future releases will not affect your installed applications using v1 service.\n\nThis fact means that every request to services provided will need to be prefixed with:\n\n```text\n/v1\n```\n\nThis API will return all results in JSON format\n\n## Get Users List\n\n```text\n/:version/users\n```\n\nReturns a list of users from LDAP. List might be truncated if LDAP server limits response size\n\nExample Response:\n\n```json\n[\n    {\n        \"uid\": \"NEBELUNg\",\n        \"manager\": {\n            \"rdns\": [\n                {\n                    \"uid\": \"oJosazuLEs\"\n                },\n                {\n                    \"ou\": \"People\"\n                },\n                {\n                    \"dc\": \"kittens\"\n                },\n                {\n                    \"dc\": \"net\"\n                }\n            ]\n        },\n        \"mail\": \"NEBELUNg@kittens.net\",\n        \"employeenumber\": \"000001\",\n        \"uidnumber\": 20244\n    },\n    {\n        \"uid\": \"pixiebob\",\n        \"manager\": {\n            \"rdns\": [\n                {\n                    \"uid\": \"balinese\"\n                },\n                {\n                    \"ou\": \"People\"\n                },\n                {\n                    \"dc\": \"kittens\"\n                },\n                {\n                    \"dc\": \"net\"\n                }\n            ]\n        },\n        \"mail\": \"pixiebob@kittens.net\",\n        \"employeenumber\": \"000002\",\n        \"uidnumber\": 20245\n    }\n]\n```\n\n### Users List Parameters\n\nThis service only receives one parameter named *filter* which will be used to filter users by specified attributes in config file, using special character * (asterisk) as wildcard character\n\nAn example list of users whose name begins with chrod is issued by the following URL:\n\n```text\nhttp://SERVER_NAME/API_BASE/v1/users?filter=chrod*\n```\n\nSee documentation section to configure filtering attributes for users\n\n## Get a Single User\n\n```text\n/:version/users/:username\n```\n\nReturn a single user maching specified username\n\n## Get Group Membership of Single User\n\n```text\n/:version/users/:username/groups\n```\n\nReturns a list of groups specified username is member of\n\n## Get Groups List\n\n```text\n/:version/groups\n```\n\nReturns a list of groups from LDAP. List might be truncated if LDAP server limits response size\n\n### Groups Parameters\n\nThis service only receives one parameter named *filter* which will be used to filter gorups by specified attributes in config file, using special character * (asterisk) as wildcard character\n\nAn example list of groups whose name begins with vpn is issued by the following URL:\n\n```text\nhttp://SERVER_NAME/API_BASE/v1/groups?filter=vpn*\n```\n\nSee documentation section to configure filtering attributes for users\n\n## Get list of group members\n\n```text\n/:version/groups/:name/members\n```\n\nReturns a list of users that are members of specified group\n\n## Configuring ldap-api\n\nThis simple RACK application is configured using a yml file. This file should be named `config/config.yml`.\n\nThis application requires two environment variables to be set:\n\n- `export LDAP_PASSWORD=\u003cpassword\u003e` - The password to use for API -\u003e LDAP authentication\n- `export CONFIG_PATH=config/config.example.yml` - The path to the configuration file\n\nNow all configuration is done in the `config/config.yml` file from here on out.\n\n## Sample configuration file config/config.yml\n\nHere is an example configuration file that the API uses:\n\n```yml\nldap:\n  cache:\n    ttl: 3600 # cache ttl in seconds\n  limit_results: -1 # -1 for no limit - the number of results to return from LDAP\n  connection:\n    host: \"localhost\" # LDAP server host\n    port: 389 # LDAP server port (389 is default, 636 is for LDAPS)\n    base: dc=kittens,dc=net # LDAP base DN\n    bind_dn: uid=emmy,ou=Service_Accounts,dc=kittens,dc=net # LDAP bind DN when making a connection\n    # password: kittens !deprecated! # Please use the environment variable LDAP_PASSWORD\n    # method: :plain # :ssl, :tls, :plain allowed # Please let ActiveLdap decide for you\n  user:\n    dn_attribute: uid\n    prefix: ou=People\n    classes:\n      - organizationalPerson\n    filter: (|(uid=%s)) # attributes you can query string filter on ex: /users?filter=chrod*\n    attributes:\n      uid: uid\n      # sn: sn\n      # givenname: givenname\n      # cn: cn\n      uidnumber: uidnumber\n  group:\n    dn_attribute: cn\n    member_attribute: uniquemember\n    user_membership_attribute: dn\n    classes:\n      - groupOfUniqueNames\n    attributes:\n      cn: name\n```\n\nA sample configuration file is provided in the [`config`](config/) directory.\n\n## Configuration file sections\n\n### Cache\n\n- `ttl`: is a time in seconds to cache results in memory by server, without quering LDAP for same result just queried\n\nOnce you have configured caching, you will see the `Cache-Ttl` header in responses from the API. This header indicates how much longer in seconds the response will be cached for.\n\n### Limit result sets\n\n- `limit_results`: numbers of entries to return when searching users or groups. If removed, limit is not set and all entries are returned or limited by server\n\n### Connection\n\n- `host`: LDAP host server\n- `port`: LDAP port. Default is `389` for LDAP and `636` for LDAPS\n- `base`: LDAP base dn\n- `bind_dn`: LDAP user to bind into LDAP as\n- `allow_anonymous`: if specified anonymous access to LDAP will be used\n\n### User\n\n- `dn_attribute`: attribute used as dn: for example uid or cn\n- `prefix`: prefix where users reside. If omited, ldap.base will be used\n- `classess`: array of objectclass retrieved users must meet. Array elements must\nbe listed in separate lines prefixed with minus sign\n- `filter`: filter to be used when filtering user listing\n- `attributes`: attribute mapping array. You must define a dictionary (hash) of attribute mappings from LDAP attribute name on the left, to a service name attribute on the right. In the given example above, you can see that cn ldap attribute will be retrieved as display_name by rest service\n\n### Group\n\n- `dn_attribute`: attribute used as dn: for example cn\n- `prefix`: prefix where groups reside. If omited, ldap.base will be used\n- `classess`: array of objectclass retrieved groups must meet. Array elements must be listed in separate lines prefixed with minus sign\n- `member_attribute`: attribute used by ldap groups to specify members. For example: member\n- `user_membership_attribute`: attribute used by group membership to reference a user. For example: dn means users are specified as full dn\n- `filter`: filter to be used when filtering group listing\n- `attributes`: attribute mapping array. You must define a dictionary (hash) of attribute mappings from LDAP attribute name on the left, to a service name attribute on the right. In the given example above, you can see that cn ldap attribute will be retrieved as name by rest service\n\n---\n\n## Running ldap-api\n\nTo run this application, do the following:\n\n1. Ensure that you have a `config/config.yml` file with all the correct settings\n2. Run `script/bootstrap` to install all dependencies\n3. Run `script/server` to start the server\n\nYour application will now be running at `localhost:8080` and you can begin making requests to it.\n\n### Testing Locally\n\nTo test locally, this project comes with a pre-configured `docker-compose.yml` file with a mock LDAP server. To test locally with this mock server, do the following:\n\n1. Run `script/bootstrap` to install all dependencies\n2. Use the `config/config.example.yml` file included in this project with all of its defaults (no need to change anything at all here). Now set the following environment variables to use this file:\n     - `export LDAP_PASSWORD=kittens`\n     - `export CONFIG_PATH=config/config.example.yml`\n3. Run `make run` to spin up the docker-compose stack\n4. Run `script/server` to start the API server\n5. Make requests to `localhost:8080` and get back mock data - [get users example](http://localhost:8080/v1/users)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrantbirki%2Fldap-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrantbirki%2Fldap-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrantbirki%2Fldap-api/lists"}