Cookie-based Authorization
Setting up the local development enviroment for websites that use cookie-based authorization.
Running a local Authgear server is not trivial. This guide provides a simple way to bootstrap your local application that communicates with the production Authgear server.
This guide is only for cookie-based authentication in local development setup. A typical scenario is developing websites. If you are developing mobile applications which use token-based authentication, you can just skip this guide and continue with it as usual.
Problems using localhost as a local website domain
Authgear sets a cookie in the browser inside the project domain. When running your application on localhost
, the browser will not see the cookies because the website is not in the subdomain of the domain in which the cookies are set. Therefore, the browser will not be able to authenticate itself.
You can learn more here.
Setup a new Authgear project
For local development, it is highly recommended to create a new application on Authgear before continuing to the rest of the guide.
Log in and create a new project on https://portal.authgearapps.com
Go to the Application tab in your dashboard
Add your local application domain
{SUBDOMAIN}.{PROJECT_NAME}.authgearapps.com
under the Allowed Origins listAdd an application, name it whatever you want. DO NOT check the Issue JWT as access token box because we are using cookie-based authorization.
Put your redirect URI for login and logout under the Redirect URIs list and Post Logout Redirect URIs list respectively.
Map domain in hosts
hosts
To make the cookies visible to the browser, the local website domain has to be inside the domain where the cookies are set.
By adding the following line to the /etc/hosts
file on the local machine, we can point the application domain name to localhost.
The browser will be able to see the auth cookies if visiting the website via this domain.
Use HTTPS
Although you can see the cookies now, the cookies have the Secure attribute set. To include them in an HTTP request, the request has to be transmitted over a secure channel (HTTPS in most browsers). Therefore, we also need to establish HTTPS connections for our browser with the server.
Generate certificates
One quick simple way to do this is to use mkcert, you may follow the installation steps here. After installing mkcert, generate a certificate with the following command:
A key file and a cert file will be generated. They will be used in the next part of the guide.
Using nginx
We will need an nginx server to serve the certificate and enable SSL.
Add the following config file to your nginx/conf.d
directory, or mount it to a volume together with the cert and key if you are using nginx in docker.
The examples below show the nginx config files for nginx in host and nginx in docker.
In the above examples, nginx will also authenticate requests by creating sub-requests to the Authgear internal endpoint. You can learn more here.
Finish
Now visit the website through https://{SUBDOMAIN}.{PROJECT_NAME}.authgearapps.com
, the browser will be able to send requests with the authorization cookies.
For implementing login and logout logic in your website, please refer to Web SDK.
Last updated
Was this helpful?