Fork of signalnerve/workers-auth0-example for targeting Azure AD instead of Auth0.
authorization/authentication at the edge, using cloudflare workers and Azure AD
- a cloudflare workers unlimited account
- an Azure AD account and a configured application
- if deploying in front of a domain, a configured cloudflare zone (see the "origin" section of "deploys" below)
wrangler
cli tool installed and configured (see the quick start in the docs)
using wrangler
, you can generate a new project using this repo:
wrangler generate my-auth-example https://github.com/bradyjoslin/workers-azuread-example
this project makes heavy use of wrangler
, the workers command-line tool, for managing environment variables and deploying this codebase. before trying to deploy this project, i recommend closely following this section of the readme to get all the relevant tokens, ids, and values that you'll need to successfully deploy this project.
the wrangler.toml
config file in this repository needs to be configured for deploying your own version of this application. using wrangler generate
will automatically add a name
field - you'll also need to configure an account id, and, depending on if you're deploying your application to a zone (see "deploying" later in this readme), a zone id and route.
for more information on configuring this correctly, i strongly recommend you check out the quick start in the workers docs!
by default, this project uses the binding AUTH_STORE
to refer to a kv namespace where credentials are read/written from the workers script. to create your own kv namespace, use wrangler
, and copy the resulting id into the kv-namespaces
portion of wrangler.toml
:
wrangler kv:namespace create AUTH_STORE
below is a table of secrets that the workers script will look for when it processes a client request. each should be set with wrangler secret
:
wrangler secret key | value |
---|---|
AAD_DOMAIN | your Azure AD domain with your tenant id (e.g. https://login.microsoftonline.com/{tenant_id} ) |
AAD_CLIENT_ID | your Azure AD client id |
AAD_CLIENT_SECRET | your Azure AD client secret |
AAD_CALLBACK_URL | the callback url for your application (see below) |
PASSWORD | A secret string used to encrypt stored tokens using encrypt-workers-kv |
in order to correctly set the callback url for your application, you will need to determine where your application will be deployed. regardless of whether you're setting up a originless or origin-based deploy, the callback handler for this project is defined at /auth
. this means that if you're testing or deploying a staging version of this project, your callback url will likely be something like https://my-auth-example.signalnerve.workers.dev/auth
, or for production, you should set it to something like https://my-production-app.com/auth
.
this application features a growing number of configuration options available via the config
object in index.js
. these can be customized to toggle different features in the script, and are outlined below (with callouts to more detailed explanations, further in the readme):
enable authorization state hydration, to pass user info such as name and email to your application. see "edge state hydration" later in the readme.
serve responses directly from the edge, without the need for an origin server. see "deploying" later in the readme.
by default, any information stored in Azure AD, such as your user's name, email, or other custom values can be inlined into your website's response by defining script#edge_state
tag in the head
section of your static site. workers' htmlrewriter
will inline the provided state into that tag as a JSON string. you can opt into this feature by pasting something similar to the below snippet:
<script id="edge_state" type="application/json">
{}
</script>
note that if you'd like to disable this feature, you can toggle the config option hydrateState
to false
.
wrangler publish
by default, this codebase is deployed without an origin - we call this "originless" - and can be used to serve responses "from the edge". this means that your application can be authenticated/authorized at a cloudflare edge server close to your users, which can make a huge impact on latency.
this project uses workers sites
to serve static websites from the edge. by default, any assets in the public
folder will be uploaded to workers kv, and used to serve your static site to users. if you'd like to change this from public
, modify the site.bucket
field in wrangler.toml
to point to your application. if you're using gatsby
or similar static site frameworks, this should represent the final, compiled version of your site.
if you'd like to authorize/authenticate users at the edge, but still return a response from an origin server, set config.originless
to false
. this requires that your workers script is deployed to a zone (see "configure" and "publish to your domain" in the cloudflare workers quick start). this hasn't been tested and may be broken. sorry, coming soon!
please file issues for bugs and feature requests on this project! note that this repo isn't a good place to get help with wrangler, cloudflare workers, or other specific platform issues: check out the workers forums.
mit