Project: sso (Provisioning / Key Management)
File: quickstart.md

This quickstart guide will walk you through the process of creating a set of Google OAuth credentials and using Docker Compose to run an example deployment of sso protecting two upstream services. To learn how to get started using SSO with Kubernetes, you can check out this and , added and written by , one of our community contributors! Before proceeding, ensure that the following software is installed: git clone https://github.com/buzzfeed/sso.git The rest of this guide will assume you are in the `quickstart` subdirectory of the repo: cd sso/quickstart Depending on which provider you would like to use SSO with (Google/Okta) follow the relevant section below: Follow steps 1 and 2 of the documentation. Note: Use `http://sso-auth.localtest.me/google/callback` as the Authorized redirect URI in step 2. At the end of step 2, you will have a client ID and client secret. Copy `env.google.example` to `env` (i.e. `cp env.google.example env`) and fill the placeholder values with your new client ID and client secret, like so: PROVIDERGOOGLEQUICKSTARTCLIENT_ID=<client id value>.apps.googleusercontent.com PROVIDERGOOGLEQUICKSTARTCLIENT_SECRET=<client secret value> PROVIDERGOOGLEQUICKSTARTTYPE=google PROVIDERGOOGLEQUICKSTARTSLUG=google Notes: `GOOGLEQUICKSTART` is a logical identifier that is used to group the configuration variables together for any one provider. This can be changed to an identifier that makes sense for your individual use case. `PROVIDER*TYPE` tells sso which provider type to use for a configuration identifier (`GOOGLEQUICKSTART` in this case) `PROVIDER*SLUG` controls the "slug" in the OAuth callback URL (i.e., the `/google/` in `http://sso-auth.localtest.me/google/callback`). This file will be used to configure `sso-auth` in the example deployment to allow you to log to sso. Once you've completed the (alternatively, you can skip to and complete Section 3 of the instead), follow through the below steps: Note: Use `http://sso-auth.localtest.me/okta/callback` as the Authorized redirect URI in step 3. At the end of step 3 you will be given a client ID and client secret, which can be found at the bottom of the settings page for the Application you've created. Copy `env.okta.example` to `env` (i.e. `cp

env`) and fill the placeholder values with your new client ID, client secret, and Okta URL, like so: PROVIDEROKTAQUICKSTARTCLIENT_ID=<client id value> PROVIDEROKTAQUICKSTARTCLIENT_SECRET=<client secret value> PROVIDEROKTAQUICKSTARTOKTA_URL=<organisation url> PROVIDEROKTAQUICKSTARTTYPE=okta PROVIDEROKTAQUICKSTARTSLUG=okta DEFAULTPROVIDERSLUG=okta Notes: `OKTAQUICKSTART` is a logical identifier that is used to group the configuration variables together for any one provider. This can be changed to an identifier that makes sense for your individual use case. `PROVIDER*TYPE` tells sso which provider type to use for a configuration identifier (`OKTAQUICKSTART` in this case) `PROVIDER*SLUG` controls the "slug" in the OAuth callback URL (i.e., the `/okta/` in `http://sso-auth.localtest.me/okta/callback`). `PROVIDER*OKTA_URL` configures the Okta provider with your Okta organization URL (e.g. `sso-test.okta.com`) `DEFAULTPROVIDERSLUG` tells sso to use the Okta provider by default If you are not using the default Okta authorization server you will also need to add `PROVIDEROKTAQUICKSTARTOKTA_SERVER=<okta auth server ID>` to the above file. This `env` file will be used to configure `sso-auth` in the example deployment to allow you to log in to sso. First, bring up all of the services: docker-compose up -d Next, confirm that they are running as expected: docker-compose ps You should see 5 services running, all in the "Up" state: Name Command State Ports -- quickstarthello-world1 /bin/sh -c php-fpm -d vari ... Up 80/tcp quickstarthttpbin1 /bin/go-httpbin Up 8080/tcp quickstartnginx-proxy1 /app/docker-entrypoint.sh ... Up 0.0.0.0:80->80/tcp quickstartsso-auth1 /bin/sso-auth Up 4180/tcp quickstartsso-proxy1 /bin/sso-proxy Up 4180/tcp Visit http://hello-world.sso.localtest.me in your web browser. Log in using any Google account. If you are using Okta as your SSO provider, log in using any Okta account that has been correctly assigned to the Application (this should have been done while setting up the Okta provider) Now visit http://httpbin.sso.localtest.me, and see that you are automagically logged in! (To verify that sso is actually working here, feel free to visit http://httpbin.sso.localtest.me in a private browsing window.) Make sure to take a look at http://httpbin.sso.localtest.me/headers to see the headers that sso provides to upstreams, like `X-Forwarded-User`, `X-Forwarded-Groups`, etc! Note: The `localtest.me` domain we use in this example deployment will always resolve to `127.0.0.1`, so it's a convenient way to avoid needing `/etc/hosts` hacks. See for more info. Take a look at to see how `sso-proxy` is configured to protect these two upstream services, or check out to see how the whole deployment is put together.