Configuring SSO

Introduction

A default installation of Screenshotbot comes with a simple email/password based authentication and registration system. Screenshotbot does not intend to be full-fledged identity management platform, so this system is intentionally minimalist.

For more complex set ups, we suggest using an external Identity Provider using OpenID Connect (OIDC). For instance, you could Google Workplace or Okta. Most well known identity providers will support OIDC. In this document we'll refer to the Identity Provider as IdP (your IT team would know this terminology if you need their help).

Using a generic IdP

Let's assume you're running screenshotbot at https://screenshotbot.example.com.

First you need to create your Client in your IdP. In your IdP, create an OpenID Connect application. Name it "Screenshotbot", and give it a scope of email name profile. Your IdP should then provide you a Client ID and Client Secret, we'll use this in the next step.

Once you save this, a new Credentials tab will show up on the top. Let's click it, and copy your secret. So now you have a Client ID and a Client Secret. We can move on to the next step. You will most likely also be provided an Issuer URL.

Updating the config

We need to update config.lisp, to set up our new authentication provider.

(setf (installation)
      (make-instance 
         'installation
         :default-oidc-provider (make-instance 'oidc-provider
                                   :scope "openid email profile"
                                   :client-id "<client-id>"
                                   :client-secret "<client-secret>"                  
                                   :issuer "<issuer-url>")))

At this point you can restart your server. If you open up https://screenshotbot.example.com in your browser, it will now take you to your IdP to complete the login.

Configuring Profile pictures for GitHub as SSO

We rely on the the userinfo endpoint of the IdP providing a picture argument for profile picture. If you're using Keycloak with GitHub as an IdP, then you should map "avatar_url" to "profile" as an attribute.