Skip to content

Commit

Permalink
Update oauth.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@pconrad
pconrad authored Oct 13, 2024
1 parent 59075c4 commit 3716e9e
Showing 1 changed file with 117 additions and 56 deletions.
173 changes: 117 additions & 56 deletions docs/oauth.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,26 @@ Setting this up on localhost requires the first two steps below; getting this to
1. Obtaining a Google *client id* and *client secret*, which is
done at the [Google Developer Console](https://console.cloud.google.com/).
2. Configuring the `.env` file with these values.
3. Copying the `.env` values to the Heroku app's configuration values.
3. Copying the `.env` values to the dokku app's configuration values.

Each of these three steps is explained in more detail below.

# OAuth Setup

If this is your first time setting up a Google OAuth application in this course, you may need to do three steps.
Later in the course, you'll only need to do the last of these, three, since the first two are typically "one-time" only steps.

1. One time only: Set up a project in the Google Developer Console:
- <https://ucsb-cs156.github.io/topics/oauth/google_create_developer_project.html>
2. One time only: Set up an OAuth Consent Screen for your project:
- <https://ucsb-cs156.github.io/topics/oauth/google_oauth_consent_screen.html>
3. Once for each application: Create a set of OAuth credentials (`GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` values):
- <https://ucsb-cs156.github.io/topics/oauth/oauth_google_setup.html>

Once you have created the OAuth Credentials, you'll need to
configure your application with these values.

* For `localhost`, those values go in the `.env` file (as explained below)
* For Dokku, those values are set using `dokku config:set ...` (as explained below)

# About the `.env` and `.env.SAMPLE` files.

Expand All @@ -25,43 +42,9 @@ Each of these three steps is explained in more detail below.
* There is more information about `.env` vs. `.env.SAMPLE` on this page if you are interested: [docs/environment-variables](environment-variables.md).


## Step 1: Obtain a Google client id and client secret

1. Login to the Google Developer Console at <https://console.cloud.google.com/>.

2. Create a new project on the top left (or select the project you would like to create your OAuth app in).

If you need help with creating a project, visit: <https://ucsb-cs156.github.io/topics/oauth/google_create_developer_project.html>]

2. On the upper left, there is a hamburger menu icon that provides a left navigation menu.

* Look for `APIs and Services` then `Credentials`.
* On that page, near the top, click the button for `+ CREATE CREDENTIALS`
* This makes a pull-down menu where you can select `OAuth Client ID`
* For Application Type, select `Web Application`
* For name, choose something you will remember; I suggest using the name of your repo, or the name of the Dokku application
* Scroll down to the part of the page that says: `Authorized redirect URIs`
## Step 1: Set up `.env` values for `localhost`

3. Under `Authorized redirect URIs`, you'll need to click the `+ ADD URI` button twice to enter two addresses:

* For localhost, enter: `http://localhost:8080/login/oauth2/code/google`
- Note that this *must* be `http` not `https`
* For Dokku, enter: `https://myappname.dokku-xx.cs.ucsb.edu/login/oauth2/code/google`
- Note that you should substitute in *your* app name in place of `my-app-name`
- Also note that you need the specific dokku server number, not `xx`.
- Note that this *must* be `https` not `http`

![image](https://user-images.githubusercontent.com/1119017/149854295-8e1c4c63-929c-4706-972d-1962c644a40a.png)

Then click the blue `CREATE` button.

You will now see the client id and client secret values.

Keep this window open, since you'll need these values in the next step.

## Step 2: Copy `.env.SAMPLE` to `.env` and enter values

In the frontend directory, use this command to copy `.env.SAMPLE` to `.env`. Recall that you
In the top level directory, use this command to copy `.env.SAMPLE` to `.env`. Recall that you
may need to use `ls -a` to get the files to show up, since they are hidden files on Unix-like systems.

```
Expand All @@ -84,47 +67,125 @@ ADMIN_EMAILS=phtcon@ucsb.edu

Replace `see-instructions` with the appropriate values.

For ADMIN_EMAILS, add your own email and any teammates you are collaborating with after phtcon.ucsb.edu; you can separate multiple emails with commas, e.g.
# Setting up `ADMIN_EMAILS`

The `ADMIN_EMAILS` value is used to determine which users have access to administrative features in the app. One of those
is the ability to list the users that have logged in.

For `ADMIN_EMAILS`, add your own email and any teammates you are collaborating with after phtcon.ucsb.edu; you can separate multiple emails with commas, e.g.

```
ADMIN_EMAILS=phtcon@ucsb.edu,cgaucho@ucsb.edu,ldelplaya@ucsb.edu
`ADMIN_EMAILS=phtcon@ucsb.edu,cgaucho@ucsb.edu,ldelplaya@ucsb.edu`
```

*Do not separate emails with spaces*; only commas:
* ❌ WRONG: `ADMIN_EMAILS=phtcon@ucsb.edu, cgaucho@ucsb.edu, ldelplaya@ucsb.edu`
* ✅ Correct: `ADMIN_EMAILS=phtcon@ucsb.edu,cgaucho@ucsb.edu,ldelplaya@ucsb.edu`

* Add your own UCSB email address
* Add `phtcon@ucsb.edu` (your instructor)
* Add the mentor for your team (look up the mentor's name on the course team listing, then ask them in your channel)
* Add everyone else on your team

I suggest that, as a team, you collaborate in your team slack channel on getting a standard list of these, and then
that you pin that post in your team slack channel for easy reference.

With this done, you should be all set to run on localhost.

For Heroku, there is one more step.

## Step 3: Copying `.env` values to Dokku
## Step 2: Copying `.env` values to Dokku

See: <https://ucsb-cs156.github.io/topics/dokku/environment_variables.html>
There are two ways to set up your `.env` values on Dokku.

* One variable at a time (recommended if this is your first time doing this)
* All at once with a file

## Step 2a: Copying `.env` values to Dokku one at a time

To copy the values to Dokku one at a time, do this
for each line in the `.env` file:

On the dokku server command line, type:<br />

<tt>dokku config:set --no-restart <b></i>app-name VARIABLE=VALUE</i></b></tt>, where

* <b></i>app-name</i></b> is your app name such as `jpa03-cgaucho`. It needs to match what you see when you type `dokku apps:list`
* <b></i>VARIABLE=VALUE</i></b> is one of the lines in your .env. file

Note that on Dokku, you also typically need to set this
value (this typically does *not* go in your .env)

<tt>dokku config:set --no-restart <b></i>app-name</i></b> PRODUCTION=true</tt>

## Troubleshooting

If you see this:
## Step 2b: Copying `.env` values to Dokku all at once

<img src="https://user-images.githubusercontent.com/1119017/149856156-575fb638-7db8-460a-a344-9069145aa242.png" alt="Redirect URI Mismatch" width="600" />
The idea of this step is to copy/paste the values
from from your `.env` file into a file in your Dokku account
and then load the values all at once.

You could use file transfer, but because of various firewall settings, it may be easier to just copy/paste like this:

Try clicking the little arrow to open up the additional message:

<img src="https://user-images.githubusercontent.com/1119017/149856193-512acb25-2bfc-4e53-991b-f61de37f1ed6.png" alt="Request Details" width="600" />
1. On the system where you are doing development,
use `cat .env` to list out the contents, e.g.

```
pconrad@Phillips-MacBook-Air STARTER-jpa03 % cat .env
GOOGLE_CLIENT_ID=26622685272-ofq4729s9nt8loednuuv5c0opja1vaeb.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-fakeCredentials99_fakefake-_fake
ADMIN_EMAILS=phtcon@ucsb.edu
Now, you'll see the Redirect URI that the app is expecting.
JDBC_DATABASE_URL=jdbc:postgresql://example.org:5432/starter_jpa03_db
JDBC_DATABASE_USERNAME=postgres
JDBC_DATABASE_PASSWORD=password
pconrad@Phillips-MacBook-Air STARTER-jpa03 %
```

If you go back to the [Google Developer Console](https://console.cloud.google.com/) you can see what you really entered.
2. At the shell prompt on your dokku server (e.g. dokku-07.cs.ucsb.edu), type this, where `jpa03-cgaucho` is the name of your
app:

For example, when I was getting this error message, it's because I put in this for my Redirect URI:
```
cat > jpa03-gaucho.env
```

![image](https://user-images.githubusercontent.com/1119017/149856340-98acd5e4-8712-4723-a899-e3bf2f06d3fa.png)
Then, copy paste the contents of the `.env` file into the window, followed by hitting enter, and then Control-D.

Rookie mistake! I literally had `my-heroku-app` instead of `demo-spring-react-example`.
If you then do an `ls` you should see that you have
a file called `jpa03-gaucho.env` containing the values
you want to set.

Change it to the correct URI, click save. Then go back to the URL for the home page of your app and refresh the page (you don't need to restart the Heroku backend; just refresh your browser page.) Click login again, and you should get something like this:
3. Now type the following (assuming that `jpa03-cgaucho` is
your Dokku app name).

```
dokku config:set --no-restart jpa03-cgaucho `cat jpa03-gaucho.env`
```

In this command, the part in backticks (<tt>\`cat jpa03-gaucho.env\`</tt>) specfies that the output of that command should be placed on the command line.

Accordingly, this sets all of the environment variables at once.

Note that on Dokku, you also typically need to set this
value (this typically does *not* go in your .env)

<tt>dokku config:set --no-restart <b></i>app-name</i></b> PRODUCTION=true</tt>

Your next step is likely to configure the application
for using the Postgres database; instructions for that
can be found here:

* <https://ucsb-cs156.github.io/topics/dokku/postgres_database.html>

If you want to restart the application you can either
* Leave off the `--no-restart` part, or
* Type `dokku ps:restart jpa03-cgaucho` as the next command

## Troubleshooting

For general troubleshooting with OAuth, see:

<img src="https://user-images.githubusercontent.com/1119017/149856532-b1cda813-bd3f-4fd1-a79e-630e5929d7be.png" alt="Choose an Account" width="600" />
* <https://ucsb-cs156.github.io/topics/oauth/oauth_troubleshooting.html>


Success!

0 comments on commit 3716e9e

Please sign in to comment.