{"id":13587211,"url":"https://github.com/cjww-development/gatekeeper","last_synced_at":"2026-01-22T10:40:59.049Z","repository":{"id":37821558,"uuid":"188290275","full_name":"cjww-development/gatekeeper","owner":"cjww-development","description":"Implementation of OIDC and OAuth2","archived":false,"fork":false,"pushed_at":"2022-06-16T09:50:44.000Z","size":1084,"stargazers_count":16,"open_issues_count":11,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-02-13T21:46:16.331Z","etag":null,"topics":["docker","gatekeeper","oauth2","oauth2-provider","oauth2-server","oidc","oidc-provider","oidc-server","scala"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cjww-development.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-23T18:57:18.000Z","updated_at":"2023-07-25T14:26:08.000Z","dependencies_parsed_at":"2022-08-19T11:21:34.947Z","dependency_job_id":null,"html_url":"https://github.com/cjww-development/gatekeeper","commit_stats":null,"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjww-development%2Fgatekeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjww-development%2Fgatekeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjww-development%2Fgatekeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjww-development%2Fgatekeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cjww-development","download_url":"https://codeload.github.com/cjww-development/gatekeeper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223290433,"owners_count":17120915,"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":["docker","gatekeeper","oauth2","oauth2-provider","oauth2-server","oidc","oidc-provider","oidc-server","scala"],"created_at":"2024-08-01T15:06:06.212Z","updated_at":"2026-01-22T10:40:59.043Z","avatar_url":"https://github.com/cjww-development.png","language":"Scala","funding_links":[],"categories":["Scala"],"sub_categories":[],"readme":"[![Apache-2.0 license](http://img.shields.io/badge/license-Apache-brightgreen.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)\n\ngatekeeper\n==========\n\nGatekeeper is an OIDC \u0026 OAuth2 server written in scala. This OAuth2 server is designed for the self-hosting community who are looking for an auth solution to get single sign-on on their self-hosted services.\n\nGatekeeper has been explicitly tested with the following services\n\n* Jenkins (via the [OpenId Connect Authentication Plugin](https://plugins.jenkins.io/oic-auth/))\n* Portainer\n* Gitea\n\nHowever, if a service offers integration with a third party OAuth2 provider, there is a good chance Gatekeeper will work with it. If it doesn't, please raise an issue.\n\n\n## Features\n- Client registration\n    - Update Redirects\n    - Limit scopes\n    - Limit available OAuth2 flows\n    - Modify token validity\n    - Regenerate client Id and secret\n    - Create clients from presets\n- User and developer registration\n    - Update email and password\n    - Email verification via\n\t    - AWS SES\n\t    - Mailgun\n\t    - More offerings to come\n    - TOTP MFA\n    - See list of apps accessing your account\n    - Revoke sessions for apps accessing your account\n    - Completely revoke access for apps accessing your account\n- Grant types\n\t- authorization_code\n\t- client_credentials\n\t- refresh_token\n\n\n\n## Prerequisites\n- Java 11\n- Scala 2.13.3\n- SBT 1.3.13\n- MongoDB 4.2\n- AWS credentials that have access to\n\t- SES (Simple email service)\n\t- SNS (Simple notification service)\n\nWe recommend managing Java, Scala and SBT via SDKMan. SDKMan installation notes can be found [here](https://sdkman.io/install).\n\nJava, Scala and SBT can be installed with\n\n```\nsdk install java 11.0.11.hs-adpt (or whichever java 11 release is available at the time)\nsdk install scala 2.13.6\nsdk install sbt 1.5.3\n```\n\nFor MongoDB, we recommend running MongoDB in docker. To boot a MongoDB image in docker, run\n\n```\ndocker-compose -f docker-compose-mongo.yml up -d\n```\n\nTo allow gatekeeper to send emails and sms messages you need an [AWS account](https://aws.amazon.com/) that has an IAM user or role available. AWS recommends creating IAM users and roles with the minimum set of privileges it needs to operate. \n\nCreate a policy with the following permissions and attach the policy to the IAM user or role.\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": \"GatekeeperMinPermissions\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"ses:SendEmail\",\n                \"sns:Publish\"\n            ],\n            \"Resource\": \"*\"\n        }\n    ]\n}\n```\n\nOn a new AWS Account, SES provides sandbox access. This means that you can only send emails to the Amazon SES mailbox simulator and verified email addresses or domains. You can request that AWS moves your account out of the SES sandbox, more details [here](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/request-production-access.html?icmpid=docs_ses_console). \n\n\n## How to run\n```\nsbt -Demail.from=test@email.com -Dplay.http.router=testing.Routes run\n```\n\ntest@email.com should be replaced with a email address or domain that's been verified in AWS SES\n\nThis will start the application on port *5678*\n\n## Running tests \n```\nsbt compile test it:test\n```\nTo the run the integration tests under `it:test` you will need MongoDB running. Refer to the prerequesites section to understand how to boot MongoDB in docker.\n\n## Booting in docker\nThe `docker-boot.sh` file packages gatekeeper into a tgz to be used by the Dockerfile. Docker image is then built from the file and subsequently booted along with MongoDB from the docker-compose file.\n  \nRun `./docker-boot.sh` to run this process.\n\n## Docker compose variables\nThe following table describes what each of the gatekeeper envs means in the docker compose file.\n\n| Env Var          | Default                          | Description                                                                                                                                         |\n|------------------|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|\n| VERSION          | dev                              | The version of Gatekeeper you're running. Appears at the bottom of pages                                                                            |\n| EMAIL_FROM       | test@email.com                   | The email address used to send emails from Gatekeeper                                                                                               |\n| MONGO_URI        | mongodb://mongo.local            | Where MongoDB lives. The database that backs Gatekeeper                                                                                             |\n| APP_SECRET       | 23817cc7d0e6460e9c1515aa4047b29b | The app secret scala play uses to sign session cookies and CSRF tokens. Should be changed to run in prod                                            |\n| ENC_KEY          | 23817cc7d0e6460e9c1515aa4047b29b | The key used to secure data. Should be changed to run in prod                                                                                       |\n| WKC_ISSUER       | http://localhost:5678            | Used in the tokens issued by Gatekeeper. Used in the token `iss` claim. Should be configured as the domain you connect to Gatekeeper with           |\n| MFA_ISSUER       | Gatekeeper (docker)              | The string used to describe the TOTP Code in apps like Google Authenticator                                                                         |\n| SMS_SENDER_ID    | SmsVerify                        | The string used to say where SMS messages have come from                                                                                            |\n| EMAIL_PROVIDER   | n/a                              | Used to determine what email provider to use. Valid options are ses or mail-gun                                                                     |\n| AWS_REGION       | n/a                              | Should only be set if EMAIL_PROVIDER is ses. Should match the AWS region you're running SES from                                                    |\n| AWS_IDENTITY_ARN | n/a                              | Should only be set if EMAIL_PROVIDER is ses. Should be the arn of the SES identity you're sending via if the SES identity lives in another AWS account |\n| MAILGUN_API_KEY  | n/a                              | Should only be set if EMAIL_PROVIDER is mail-gun. Obtained from the mailgun console after account creation                                          |\n| MAILGUN_URL      | n/a                              | Should only be set if EMAIL_PROVIDER is mail-gun. Obtained from the mailgun console after account creation                                          |\n      \n## Choosing an email provider\nGatekeeper currently sends emails via AWS SES or Mailgun. Both support sending emails from a proper address, or some address on a verified domain. On their respective free tiers you can only send to email addresses you've verified in SES or Mailgun.\nTo lift that limitation you need to be on a paid plan. However, AWS SES lets you send 62000 emails a month for free forever, but you need to be in their production zone on SES.\nMailgun, on their flex plan, allows 5000 emails a month for 3 months, and then you move to pay as you go ($0.80 / 1000 emails).\n\n## SES cross account authorisation\nAWS SES allows AWS accounts to send email via verified identities from other accounts. More information can be found [here](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-authorization.html).\nGatekeeper supports this if SES is your email provider. Ensure that the `AWS_IDENTITY_ARN` env var is set to the arn you're wanting to send via.\n\n### What if I don't want to use AWS SES or Mailgun?\nThat's a fair question. Neither may suit you. If you're technically minded, look at [the adding more email providers section](#Adding-further-email-providers) to find out more about adding your preferred provided (dev work required).\nIf you're not technically minded, no fear, get started with a [feature request](https://github.com/cjww-development/gatekeeper/issues/new?assignees=\u0026labels=\u0026template=feature_request.md\u0026title=) and we can try to make your request a reality.\n\nFind more information about each here\n- [Mailgun](https://www.mailgun.com/)\n- [AWS SES](https://aws.amazon.com/ses/)\n\n## Adding further client presets\nGatekeeper supports creating client presets for \n* Jenkins\n* Grafana\n* Portainer\n* OpenId connect playground\n\nOpenId connect playground has its domain configured as it's a managed service. Jenkins, grafana and portainer do not as they can be hosted anywhere.\n\n```hocon\nwell-known-services = [\n  {\n    name = \"jenkins\"\n    desc = \"Build great things at any scale\"\n    icon = \"jenkins.svg\"\n    redirect = \"/securityRealm/finishLogin\"\n  },\n  {\n    name = \"openid connect playground\"\n    desc = \"For testing OIDC configurations\"\n    icon = \"openid.png\"\n    domain = \"https://openidconnect.net\"\n    redirect = \"/callback\"\n  }\n]\n```\n\nIn `application.conf` the well known services block defines the presets. You can extend the preset services by creating PR's that add to this list. The domain should be specified if the service is hosted in one place.\n\nFor the time being, the service's icon needs to be hosted in Gatekeeper, find a suitable image for the service and place the image in `public/images/services`. In the config block enter the name of the file under icon.\n\nOnce a service has been added to this list, it will be available for creation in the frontend. \n\n## Adding further email providers\nRight now Gatekeeper can send emails via AWS SES or Mailgun, however these providers can be extended. Below details how you can go about adding new email providers.\n\n1. Clone the repository and branch off as `feature/email-provider/new-provider-name`\n\n\n2. Add the new email providers config into `conf/application.conf` \n```hocon\nemail-service {\n    selected-provider = ${?EMAIL_PROVIDER}\n    message-settings {\n      from = ${?EMAIL_FROM}\n      verification-subject = \"Verifying your account\"\n    }\n\n    ses {\n      region = ${?AWS_REGION}\n      cross-account-identity-arn = ${?AWS_IDENTITY_ARN}\n    }\n\n    mail-gun {\n      api-key = ${?MAILGUN_API_KEY}\n      url = ${?MAILGUN_URL}\n    }\n    \n    new-provider-name {\n        ...whatever config the new provider needs. API Key, endpoints etc\n    }\n}\n```\n\n3. Create a new default class and trait inside of `app/services/comms/email`. Traits in this package should all extend the `EmailService`. Ensure appropriate tests are included.\n\n```scala\nimport database.VerificationStore\nimport models.{EmailResponse, Verification}\nimport play.api.mvc.Request\nimport services.comms.email.EmailService\n\nimport scala.concurrent.{ExecutionContext, Future}\n\nclass DefaultNewProvider @Inject()(val config: Configuration,\n                                   val verificationStore: VerificationStore) extends NewProvider {\n  override val emailSenderAddress: String = config.get[String](\"email-service.message-settings.from\")\n  override val verificationSubjectLine: String = config.get[String](\"email-service.message-settings.verification-subject\")\n  override val valueFromConfigNeededForNewProvider: String = config.get[String](\"email-service.new-provider-name.whatever-required-config\")\n}\n\ntrait NewProvider extends EmailService {\n\n  val valueFromConfigNeededForNewProvider: String\n\n  override def sendEmailVerificationMessage(to: String, record: Verification)(implicit req: Request[_], ec: ExecutionContext): Future[EmailResponse] = {\n    //What ever logic is needed to send an email via the new provider\n    // Should return a Future EmailResponse\n    Future.successful(EmailResponse(\n      provider = \"new-provider-name\",\n      userId = record.userId,\n      messageId = \"some email message id returned from the new email provider\"\n    ))\n  }\n}\n```\n\n4. Add new class to Gatekeepers Service bindings in `app/global/ServiceBindings`\n```scala\nprivate def emailService(config: Configuration): Seq[Binding[_]] = {\n  config.get[String](\"email-service.selected-provider\") match {\n    case \"ses\"               =\u003e Seq(bind[EmailService].to[DefaultSesService].eagerly())\n    case \"mailgun\"           =\u003e Seq(bind[EmailService].to[DefaultMailgunService].eagerly())\n    case \"new-provider-name\" =\u003e Seq(bind[EmailService].to[DefaultNewProvider].eagerly())\n    case _                   =\u003e throw new RuntimeException(\"Invalid email provider\")\n  }\n}\n```\n\n5. Create a pull request\n\nLicense\n=======\nThis code is open sourced licensed under the Apache 2.0 License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjww-development%2Fgatekeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcjww-development%2Fgatekeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjww-development%2Fgatekeeper/lists"}