Auth0 custom database client certificates sample

This sample shows how you can use client certificates authentication between your server/api and a Auth0 Custom Database Script. In the section Run in Auth0 as Custom Database Login script a step by step guide explains how you can integrate the script into the Auth0 platform.

Generate the certificates

For the purpose of this sample a Root Certificate Authority (CA) certificate needs to be created. This certificate is used as the root certificate for both client and server certificates.

Certificate Authority (SN=My Company Root CA)

First of all a key file needs to be generated by using the openssl command. The private key should be kept very very private.

openssl genrsa -out myCompanyRootCA.key 4096

Generate the Root Certificate Authority. In this step, multiple questions will be asked, but for the purpose of this example none of this information is of interest.

openssl req -x509 -new -nodes -key myCompanyRootCA.key -sha256 -days 3650 -out myCompanyRootCA.pem

Country Name (2 letter code) [AU]: BE
State or Province Name (full name) [Some-State]: East-Flanders
Locality Name (eg, city) []: Ghent
Organization Name (eg, company) [Internet Widgits Pty Ltd]: My Company
Organizational Unit Name (eg, section) []: IT
Common Name (e.g. server FQDN or YOUR name) []: My Company Root CA
Email Address []: [email protected]

Server Certificate (SN=api.mycompany.com)

Generate key file

openssl genrsa -out servercertificate.key 2048

Generate a Certificate Signing Request, the Common Name is the most important property here and it should match your API domain exactly (e.g. api.mycompany.com).

openssl req -new -key servercertificate.key -out servercertificate.crs

Country Name (2 letter code) [AU]:BE
State or Province Name (full name) [Some-State]:East-Flanders
Locality Name (eg, city) []:Ghent
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Company
Organizational Unit Name (eg, section) []:IT
Common Name (e.g. server FQDN or YOUR name) []:api.mycompany.com
Email Address []:[email protected]

Generate the certificate

openssl x509 -req -in servercertificate.crs -CA myCompanyRootCA.pem -CAkey myCompanyRootCA.key -CAcreateserial -out servercertificate.crt -days 3650 -sha256

Chain the root CA public key into the server certificate, so the certificate contains the full chain.

cat servercertificate.crt myCompanyRootCA.pem > servercertificate-chained.crt

Client Certificate (SN=Other Company Client)

Generate key file

openssl genrsa -out clientcertificate.key 2048

Generate a Certificate Signing Request. In this step, multiple questions will be asked, but for this sample only the Common name is of interest. The common name is used to validate the certificate server side.

openssl req -new -key clientcertificate.key -out clientcertificate.crs

Country Name (2 letter code) [AU]:BE
State or Province Name (full name) [Some-State]:East-Flanders
Locality Name (eg, city) []:Ghent
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Other  Company
Organizational Unit Name (eg, section) []:IT
Common Name (e.g. server FQDN or YOUR name) []:Other Company Client
Email Address []:[email protected]

Generate the certificate

openssl x509 -req -in clientcertificate.crs -CA myCompanyRootCA.pem -CAkey myCompanyRootCA.key -CAcreateserial -out clientcertificate.crt -days 3650 -sha256

How to run the sample

Run in Auth0 as Custom Database Login script

1. Go to Auth0 and click Sign Up.
2. Go to Connections > Database and click Create db connection, choose a name and save.
3. Open the tab Custom Database, and enable Use my own database, by default the Login database action script is opened.
4. Copy the content of the function from login.js into the Login function body via the action script editor.
5. In the Settings section below the code editor add the settings API_ENDPOINT, BASE64_CLIENT_KEY, BASE64_CLIENT_CERT, and BASE64_CA. The values are accessible through the global configuration object.

Server

Configuration

Rename the .env.sample to .env and fill in the configuration values, note that the BASE64_SERVER_KEY, BASE64_SERVER_CERT, and BASE64_CA values are Base64 encoded to avoid issues with format and encoding. The value of ALLOWED_CLIENT_SUBJECT_NAME should match the Common Name of the Client Certificate.

BASE64_SERVER_KEY=LS0tLS1CRUdJTiBSU0EgUFJJVk...VORCBSU0EgUFJJVkFURSBLRVktLS0tLQo=
BASE64_SERVER_CERT=LS0tLS1CRUdJTiBDRVJUSUZJQ...0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
BASE64_CA=LS0tLS1CRUdJTiBDRVJUSUZJQ0F...S0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo
ALLOWED_CLIENT_SUBJECT_NAME=Other Company Client

example, cat myCompanyRootCA.pem | base64

Add following entry to your hosts file /etc/hosts (OSX) if you are testing on your local machine.

127.0.0.1      api.mycompany.com # This should match the Common Name of the 'server certificate'

Run

cd server
npm install
npm start

Run the client local

Configuration

Rename the .env.sample to .env and fill in the configuration values, note that the BASE64_CLIENT_KEY, BASE64_CLIENT_CERT, and BASE64_CA values are Base64 encoded to avoid issues with format and encoding. The value API_ENDPOINT should be the URL of the server.

BASE64_CLIENT_KEY=LS0tLS1CRUdJTiBSU0EgUFJJVkS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg
BASE64_CLIENT_CERT=LS0tLS1CRUdJTiBDRVJUSUZJQ...tLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg
BASE64_CA=LS0tLS1CRUdJTiBDRVJUSUZJQ0F...S0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo

example, cat myCompanyRootCA.pem | base64

Run

cd client
npm install
npm run login

In the file /client/login.js you can change the email/password to trigger the unauthorized code path.

What is Auth0?

Auth0 helps you to:

• Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others, or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider.
• Add authentication through more traditional username/password databases.
• Add support for linking different user accounts with the same user.
• Support for generating signed Json Web Tokens to call your APIs and flow the user identity securely.
• Analytics of how, when and where users are logging in.
• Pull data from other sources and add it to the user profile, through JavaScript rules.

Create a free Auth0 Account

1. Go to Auth0 and click Sign Up.
2. Use Google, GitHub or Microsoft Account to login.

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

Author

Auth0

License

This project is licensed under the MIT license. See the LICENSE file for more info.