Gatekeeper is an OIDC & 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.

Gatekeeper has been explicitly tested with the following services

• Jenkins (via the OpenId Connect Authentication Plugin)
• Portainer
• Gitea

However, 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.

• Client registration
  • Update Redirects
  • Limit scopes
  • Limit available OAuth2 flows
  • Modify token validity
  • Regenerate client Id and secret
  • Create clients from presets
• User and developer registration
  • Update email and password
  • Email verification via
    • AWS SES
    • Mailgun
    • More offerings to come
  • TOTP MFA
  • See list of apps accessing your account
  • Revoke sessions for apps accessing your account
  • Completely revoke access for apps accessing your account
• Grant types
  • authorization_code
  • client_credentials
  • refresh_token

• Java 11
• Scala 2.13.3
• SBT 1.3.13
• MongoDB 4.2
• AWS credentials that have access to
  • SES (Simple email service)
  • SNS (Simple notification service)

We recommend managing Java, Scala and SBT via SDKMan. SDKMan installation notes can be found here.

Java, Scala and SBT can be installed with

sdk install java 11.0.11.hs-adpt (or whichever java 11 release is available at the time)
sdk install scala 2.13.6
sdk install sbt 1.5.3

For MongoDB, we recommend running MongoDB in docker. To boot a MongoDB image in docker, run

docker-compose -f docker-compose-mongo.yml up -d

To allow gatekeeper to send emails and sms messages you need an AWS account 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.

Create a policy with the following permissions and attach the policy to the IAM user or role.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "GatekeeperMinPermissions",
            "Effect": "Allow",
            "Action": [
                "ses:SendEmail",
                "sns:Publish"
            ],
            "Resource": "*"
        }
    ]
}

On 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.

sbt [email protected] -Dplay.http.router=testing.Routes run

[email protected] should be replaced with a email address or domain that's been verified in AWS SES

This will start the application on port 5678

sbt compile test it:test

To 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.

The 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.

Run ./docker-boot.sh to run this process.

The following table describes what each of the gatekeeper envs means in the docker compose file.

Gatekeeper 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. To 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. Mailgun, 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).

AWS SES allows AWS accounts to send email via verified identities from other accounts. More information can be found here. Gatekeeper 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.

That's a fair question. Neither may suit you. If you're technically minded, look at the adding more email providers section to find out more about adding your preferred provided (dev work required). If you're not technically minded, no fear, get started with a feature request and we can try to make your request a reality.

Find more information about each here

• Mailgun
• AWS SES

Gatekeeper supports creating client presets for

• Jenkins
• Grafana
• Portainer
• OpenId connect playground

OpenId connect playground has its domain configured as it's a managed service. Jenkins, grafana and portainer do not as they can be hosted anywhere.

well-known-services = [
  {
    name = "jenkins"
    desc = "Build great things at any scale"
    icon = "jenkins.svg"
    redirect = "/securityRealm/finishLogin"
  },
  {
    name = "openid connect playground"
    desc = "For testing OIDC configurations"
    icon = "openid.png"
    domain = "https://openidconnect.net"
    redirect = "/callback"
  }
]

In 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.

For 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.

Once a service has been added to this list, it will be available for creation in the frontend.

Right 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.

1. Clone the repository and branch off as feature/email-provider/new-provider-name

2. Add the new email providers config into conf/application.conf

email-service {
    selected-provider = ${?EMAIL_PROVIDER}
    message-settings {
      from = ${?EMAIL_FROM}
      verification-subject = "Verifying your account"
    }

    ses {
      region = ${?AWS_REGION}
      cross-account-identity-arn = ${?AWS_IDENTITY_ARN}
    }

    mail-gun {
      api-key = ${?MAILGUN_API_KEY}
      url = ${?MAILGUN_URL}
    }
    
    new-provider-name {
        ...whatever config the new provider needs. API Key, endpoints etc
    }
}

3. 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.

import database.VerificationStore
import models.{EmailResponse, Verification}
import play.api.mvc.Request
import services.comms.email.EmailService

import scala.concurrent.{ExecutionContext, Future}

class DefaultNewProvider @Inject()(val config: Configuration,
                                   val verificationStore: VerificationStore) extends NewProvider {
  override val emailSenderAddress: String = config.get[String]("email-service.message-settings.from")
  override val verificationSubjectLine: String = config.get[String]("email-service.message-settings.verification-subject")
  override val valueFromConfigNeededForNewProvider: String = config.get[String]("email-service.new-provider-name.whatever-required-config")
}

trait NewProvider extends EmailService {

  val valueFromConfigNeededForNewProvider: String

  override def sendEmailVerificationMessage(to: String, record: Verification)(implicit req: Request[_], ec: ExecutionContext): Future[EmailResponse] = {
    //What ever logic is needed to send an email via the new provider
    // Should return a Future EmailResponse
    Future.successful(EmailResponse(
      provider = "new-provider-name",
      userId = record.userId,
      messageId = "some email message id returned from the new email provider"
    ))
  }
}

4. Add new class to Gatekeepers Service bindings in app/global/ServiceBindings

private def emailService(config: Configuration): Seq[Binding[_]] = {
  config.get[String]("email-service.selected-provider") match {
    case "ses"               => Seq(bind[EmailService].to[DefaultSesService].eagerly())
    case "mailgun"           => Seq(bind[EmailService].to[DefaultMailgunService].eagerly())
    case "new-provider-name" => Seq(bind[EmailService].to[DefaultNewProvider].eagerly())
    case _                   => throw new RuntimeException("Invalid email provider")
  }
}

5. Create a pull request

This code is open sourced licensed under the Apache 2.0 License