Auth0 Guide
There are a few things you'll need to get started
- An Auth0 Account. You can sign up for a free Auth0 account here.
- A Cymatic account. You can sign up for a free Cymatic account here.
- A Cymatic javascript snippet to add to your Auth0 site. You will generate this code snippet automatically during Cymatic signup or during the creation of each additional app you add within Cymatic.
If you'd rather watch a video on this, please go here.
- Signup for a free Cymatic account at: https://cymatic.io/go/sign-up/
- Choose either to sign up with your email address or via Google social login.
- Follow the steps to activate your account.
- Name your Organization. An Organization is your top level entity in Cymatic. For example, Meta or Alphabet. We will also create your first company automatically to streamline your experience, but don't worry you can rename this later on.
- Once your Organization is created, you will see the organization screen. Click on your newly created organization to create your first site.
- Now let's create your first site.
- Enter a name for your site (the application you are protecting with Auth0).
- Enter your site's URL. We already added the protocol (HTTP/S), so please only enter www.your_domain.com or your_domain.com.
- Click 'Create Site'
- Add the selectors specific to your Auth0 login form. Unless you renamed the default selectors in your Auth0 forms, you can just add the following:
- Login form selector: form
- Username field selector: form input[type=email]
- Password field selector: form input[type=password]
- Submit button selector: form button[type=submit]
- Click 'Continue'
- Copy the snippet on the next screen to your clipboard. You will need this in Step 3.
- Before moving further in the setup wizard, please go to Step 2 below.
If you'd rather watch a video on this, please go here.
In this example, http://localhost:3000 is our application's FQDN and https://dev-xza5b0nd.us.auth0.com is Auth0's FQDN (where user's login, register, change passwords, etc.). Let's make sure Cymatic trusts and allows Auth0's domain by adding it as an "Additional Url"
- Following on from Step 1, click on 'Settings' found in the left-hand menu bar.
- Under 'General -> Site', expand the 'Site Restrictions' section and add your Auth0 FQDN in the 'Additional URL' field. You will not need to add a Key/Value pair. Leave these blank.
- Click 'Save Changes'. You will now be exited out of the site creation wizard and ready to connect Cymatic with your Auth0 environment.
If you'd rather watch a video on this, please go here.
- Log into the Auth0 UI and go to: 'Branding > Universal Login'
- Under 'Login' in the menu bar, click on 'HTML' if it is not highlighted.
- During your site creation in Step 1, you should have copied Cymatic's javascript snippet to your clipboard. If you did not copy the snippet during site setup, you will need to go back through the setup process discussed in Step 1.
Add the first 2 lines of your Cymatic javascript snippet in the <head> section.
The Cymatic javascript snippet will look like the following (DO NOT COPY THIS ONE. YOUR SNIPPET WILL BE UNIQUE TO YOUR APPLICATION).
<!-- Snippet for http://localhost:3000 -->
<script src="https://sdk.cymatic.io/company_id/site_id/sdk" ></script>Here is an example with the script tag embedded within the Auth0 template:
We will initialize as soon as Auth0 shows the sign-in form through the Auth0 Lock mechanism
At the bottom of the HTML template after the line: lock.show(); add the following code:
var lock = new Auth0Lock( ... );In this case for lock variable we will listen for event signin ready and initialize the script as follow (if you did not customize the selectors, you can just copy and paste the code below):
lock.on('signin ready', function(){
CymaticXid.v2.init({
login : {
selector :'form',
username :'form input[type=email]',
password :'form input[type=password]',
submit :'form button[type=submit]'
}
});
});As soon as someone logins to your application, Cymatic will see this attempt and activate additional features in the platform. At this point, you can go back to the Cymatic UI and see this data.
Auth0 provides a new experience to customize the universal login, you can read more here or follow this example.
Add this line of your Cymatic javascript snippet in the <head> section.
The Cymatic javascript snippet will look like the following (DO NOT COPY THIS ONE. YOUR SNIPPET WILL BE UNIQUE TO YOUR APPLICATION).
<script src="https://sdk.cymatic.io/company_id/site_id/sdk" ></script>We will initialize as soon as Auth0 shows the sign-in form through the Auth0 liquid template
- Read more about Cymatic script
- Read more about selectors
- Read more about liquid and their available variables
Here is an example with the script tag embedded within the Auth0 template:
<!DOCTYPE html>
<html>
<head>
<script src='https://sdk.cymatic.io/company_id/site_id/sdk'></script>
{%- auth0:head -%}
</head>
<body>
{%- auth0:widget -%}
<script>
CymaticXid.v2.init({
login : {
selector :'form',
username :'form input#username',
password :'form input#password',
submit :'form button[type=submit]'
}
});
</script>
</body>
</html>Make sure to set up your Custom Domain, once is verified is time to set it up on your app.
NodeJS regular web app
{
"baseURL" : "https://YOUR_DOMAIN",
"issuerBaseURL" : "https://YOUR_CUSTOM_DOMAIN",
"clientID" : "YOUR_CLIENT_ID",
"secret" : "LONG_RANDOM_STRING",
"clientSecret" : "YOUR_CLIENT_SECRET",
"authorizationParams" : {
"response_type" : "code id_token"
}
}Turn off customize switches
Auth0 > Branding > Universal Login > Login
Customize Login Page is `off`
Auth0 > Branding > Universal Login > Password Reset
Customize Password Reset Page is `off`
Auth0 > Branding > Universal Login > Multi-factor Authentication
Customize MFA Page is `off`
Application URIs
Auth0 > Applications > App > Settings
Allowed Callback URLs
https://YOUR_DOMAIN/callback
Allowed Logout URLs
https://YOUR_DOMAIN
Allowed Web Origins
https://YOUR_DOMAIN
When you try it out make sure it goes through your custom domain not through auth0's app domain
If you'd rather watch a video on this, please go here.
By configuring this optional step, Cymatic will be able to provide deeper level insights into your users' risks and activity. In order to provide this capability, Cymatic needs to know about your users. Instead of having to map your users to Cymatic, Cymatic offers an easy way to do this mapping for you through the use of a Cymatic session cookie. In order for Cymatic to identify your users, please create a session cookie by following the steps below:
Set a cookie when session is created
res.cookie("cymatic", "some value");Clear cookie when session is closed
res.clearCookie("cymatic"); Finally, you will need to load and initialize Cymatic's script on your application. Please note that this step is in addition to Step 3.3 above as we are now initializing Cymatic within your application, not Auth0's login flow. The src URL will be the same, however.
<head>
<script src="https://sdk.cymatic.io/company_id/site_id/sdk"></script>
<script>CymaticXid.init()</script>
</head>