{"id":21496527,"url":"https://github.com/mlibrary/keycard","last_synced_at":"2025-07-15T19:32:40.478Z","repository":{"id":29461743,"uuid":"121754014","full_name":"mlibrary/keycard","owner":"mlibrary","description":"Keycard provides authentication support and user/request information, especially in Rails applications","archived":false,"fork":false,"pushed_at":"2023-04-10T22:01:31.000Z","size":155,"stargazers_count":1,"open_issues_count":2,"forks_count":2,"subscribers_count":21,"default_branch":"main","last_synced_at":"2024-08-10T10:36:50.044Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlibrary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-16T13:31:09.000Z","updated_at":"2022-03-07T13:53:11.000Z","dependencies_parsed_at":"2023-01-14T14:58:55.459Z","dependency_job_id":null,"html_url":"https://github.com/mlibrary/keycard","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fkeycard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fkeycard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fkeycard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fkeycard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlibrary","download_url":"https://codeload.github.com/mlibrary/keycard/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226064471,"owners_count":17568036,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-23T16:16:55.113Z","updated_at":"2024-11-23T16:16:55.826Z","avatar_url":"https://github.com/mlibrary.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Tests](https://github.com/mlibrary/keycard/actions/workflows/test.yml/badge.svg)](https://github.com/mlibrary/keycard/actions/workflows/test.yml)\n[![Coverage Status](https://coveralls.io/repos/github/mlibrary/keycard/badge.svg?branch=main)](https://coveralls.io/github/mlibrary/keycard?branch=main)\n[![User Docs](https://img.shields.io/badge/user_docs-readthedocs-blue.svg)](https://keycard.readthedocs.io/en/latest)\n[![API Docs](https://img.shields.io/badge/API_docs-rubydoc.info-blue.svg)](https://www.rubydoc.info/gems/keycard)\n\n# Keycard\n\nKeycard provides authentication support and user/request information, especially\nin Rails applications.\n\nKeycard is designed to give you sound guidelines and integration between\nauthentication and authorization without constraining your application. It\ntakes inspiration from [Sorcery](https://github.com/Sorcery/sorcery), but has\nfour important distinctions:\n\n1. It does not use mixins to configure a \"model that can log in\".\n2. It provides a way to retrieve user and session attributes like directory\n   information or IP address-based region, rather than being strictly about\n   logging in and out.\n3. It only provides one built-in strategy for logins, focused on single sign-on\n   scenarios.\n4. It offers an optional group implementation for whatever objects your\n   application manages as accounts or users.\n\nThe ultimate goal is to provide useful tools that integrate easily and simplify\nbuilding applications that have clean, well-factored designs. Keycard should\nhelp you focus on solving your application problems, while remaining invisible\n-- not magical -- to most of your application.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'keycard'\n```\n\nAnd then execute:\n\n    $ bundle\n\n## Configuration\n\nThere are two aspects of Keycard that are configurable: the database for IP\nranges as they map to institutions (IP blocks map to networks, and networks are\nassociated with institutions), and the access mode (whether your application is\nserved directly or behind a reverse proxy). These will be unified eventually,\nbut for now, they are configured separately.\n\n### For the Database\n\nFor the database, there is a Railtie that, when running in a Rails app,\nattempts to use the same connection information as ActiveRecord. If you are\nrunning in this configuration, you will need to run a `rake db:migrate` to\ncreate the Keycard tables and add them to your `db/schema.rb`. From there forward,\nrunning `db:setup` or `db:schema:load` will create these tables for you. There is\na `keycard:migrate` Rake task if you want to run it separately, but it hooks into\nthe Rails `db:migrate` by default for convenience.\n\nIf you need to customize the database configuration, which will be typical for\nat least the production environment, the easiest way is to define an\ninitializer. In a multi-application environment, the database may be read-only,\nwhich will require the `Keycard::DB.config` to have its `readonly` property set\nto `true`. You can also set either the `Keycard::DB.config.opts` to the options\nto pass to the Sequel connection or set `Keycard::DB.config.url` to use a\nconnction string. The latter is equivalent to setting the `KEYCARD_DATABASE_URL`\nenvironment variable.\n\n### For the Access Mode\n\nTo extract the username and client IP from each request, Keycard must be\nconfigured for an \"access mode\". This can be set in an initializer, under the\n`Keycard.config.access` property, and should be either `:direct` if clients\nwill make HTTP requests directly to the Ruby webserver, or `:proxy` if a\nreverse proxy will be used.\n\nUnder the hood, these modes amount to using either `REMOTE_USER` and\n`REMOTE_ADDR` in the environment set by the Ruby webserver for direct mode or\nthe `X-Forwarded-User` and `X-Forwarded-For` headers set by a reverse proxy.\n\n## Compatibility\n\nKeycard is intended to be compatible with all community-supported Ruby branches (i.e., minor versions), currently:\n\n - 2.6\n - 2.7\n - 3.0\n - 3.1\n\nWe prefer the newest syntax and linting rules that preserve compatibility with the oldest branch in normal maintenance.\nWhen the security maintenance for a branch expires, Keycard's compatibility should be considered unsupported.\n\nSee also, [Ruby's branch maintenance policy](https://www.ruby-lang.org/en/downloads/branches/).\n\n## License\n\nKeycard is licensed under the BSD-3-Clause license. See [LICENSE.md](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlibrary%2Fkeycard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlibrary%2Fkeycard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlibrary%2Fkeycard/lists"}