To use the Auth ability we'll first need an instance of the AuthConfig type. This type establishes the contract between the auth provider and the application.

We'll use the defaultCloud helper function to construct an AuthConfig value with some Cloud-specific defaults and security benefits.

📓 Instructions

Edit the ex4_oauth.deploy function and copy the following stubs into the top of the function. We'll be filling in the following arguments one at a time:

  cloud-start/main> edit ex4_oauth.deploy

hmacKey : HMACKey
hmacKey = todo "HMACKey"
oauthClient : Oauth2Client IdToken
oauthClient = todo "oauthClient"
oauthScopes : Optional Text
oauthScopes = todo "additional scopes"
onSuccess : TokenResponse IdToken ->{Exception, Http, Log} ex4_oauth.UserId
onSuccess = todo "successCallback"
decodeSession : '{Decoder} ex4_oauth.UserId
decodeSession = todo "decodeSession"
encodeSession : : ex4_oauth.UserId -> Json
encodeSession = todo "encodeSession"

authConfig: AuthConfig {Http, Exception, Log} IdToken ex4_oauth.UserId
authConfig = defaultCloud
  hmacKey oauthClient oauthScopes onSuccess decodeSession encodeSession

Session cookie security with HMAC

When a user logs in, the Auth library creates a cookie that contains information about the user's session. This cookie is signed with an HMACKey to prevent tampering.

The defaultCloud function takes care of the signing and verification process when it writes the session cookie to the browser, so you just need to provide an HMACKey value and transform it into Bytes.

Some important security reminders when dealing with cookies:

The HMACKey should be of sufficient length.

We recommend you pick a key that is at least 32 characters (256 bits) long to help ensure that the HMAC value is secure. If a key is shorter than 256 bits, it is padded with zeros, making it a poor source of entropy.

Don't commit your secret keys to your codebase!

The HMACKey should not be committed to your codebase as a literal value or stored in regular Cloud databases. Instead, you should store secret values in an environment variable on the command line. You can also load it into the Cloud's secure Environment.Config storage.

It's important to sign cookies in the Cloud!

While the Auth library takes care of this step for you, if you are writing your own cookies to the Cloud, you should always remember to sign them.

If you do not, bad actors could write cookies to the browser in an attempt to impersonate a user. Signing and verifying the cookie ensures that authentication will fail if the cookie has been tampered with.

📚 Instructions

Create an environment variable for your HMACKey and use it to implement the hmacKey argument to the defaultCloud function.

It should look something like this:

hmacKey : HMACKey
hmacKey = HMACKey (Text.toUtf8 (IO.getEnv "HMAC_KEY"))

The IO.getEnv function reads an environment variable as a Text value, which we turn into Bytes.

Let's continue on to implement the oauthClient and oauthScopes fields. They need to match values that we'll obtain from a third-party auth provider.