Auth0 Authentication
What you'll learn
Why authenticate programmatically?
Typically, logging in a user within your app by authenticating via a third-party provider requires visiting login pages hosted on a different domain. Since each Cypress test is limited to visiting domains of the same origin, we can subvert visiting and testing third-party login pages by programmatically interacting with the third-party authentication API to login a user.
This guide is setup for testing against an Auth0 Single Page Application using the Classic Universal Login Experience. This configuration is recommended for a "Test Tenant" and/or "Test API" setup for automated end-to-end testing.
Auth0 Application Setup
To get started with Auth0, an application needs to be setup within the Auth0 Dashboard via the following steps:
- Visit the Auth0 Dashboard and click the "Create Application" button.
- Enter the desired name for your application.
- Select "Single Page Application"
Once your application is created, visit the
Application Settings
tab under your application, and add your local development URL and port (e.g
http://localhost:3000
) under the following sections:
- Allowed Callback URLs
- Allowed Logout URLs
- Allowed Web Origins
- Allowed Origins (CORS)
In the bottom of Application Settings, click Show Advanced Settings, select "Grant Types" tab and check "Password" (unchecked by default).
Next, click your Tenant icon (upper right avatar menu) to go to your Tenant Settings. On the General tab go to the API Authorization Settings
- Set "Default Audience" to the Audience URL for the Application you are testing
(e.g.
https://your-api-id.auth0.com/api/v2/
) - Set "Default Directory" to "Username-Password-Authentication"
Refer to the Auth0 Tenant Settings documentation for additional details.
Finally, create a user in the Auth0 User Store for testing with Cypress. This testing-dedicated target user will be login to your application within your test specs. If required for your testing purposes, you can make as many users needed to test your specific application.
Setting Auth0 app credentials in Cypress
To have access to test user credentials within our tests we need to configure
Cypress to use the Auth0 environment variables set in the
.env
file.
const { defineConfig } = require('cypress')
// Populate process.env with values from .env file
require('dotenv').config()
module.exports = defineConfig({
env: {
auth0_username: process.env.AUTH0_USERNAME,
auth0_password: process.env.AUTH0_PASSWORD,
auth0_domain: process.env.REACT_APP_AUTH0_DOMAIN,
auth0_audience: process.env.REACT_APP_AUTH0_AUDIENCE,
auth0_scope: process.env.REACT_APP_AUTH0_SCOPE,
auth0_client_id: process.env.REACT_APP_AUTH0_CLIENTID,
auth0_client_secret: process.env.AUTH0_CLIENT_SECRET
}
})
import { defineConfig } from 'cypress'
// Populate process.env with values from .env file
require('dotenv').config()
export default defineConfig({
env: {
auth0_username: process.env.AUTH0_USERNAME,
auth0_password: process.env.AUTH0_PASSWORD,
auth0_domain: process.env.REACT_APP_AUTH0_DOMAIN,
auth0_audience: process.env.REACT_APP_AUTH0_AUDIENCE,
auth0_scope: process.env.REACT_APP_AUTH0_SCOPE,
auth0_client_id: process.env.REACT_APP_AUTH0_CLIENTID,
auth0_client_secret: process.env.AUTH0_CLIENT_SECRET
}
})
Deprecated
The plugins file is deprecated as of Cypress CFG_VERSION. We recommend that you update your configuration. Please see the plugins guide and the migration guide for more information.
// cypress/plugins/index.js
// Populate process.env with values from .env file
require('dotenv').config()
module.exports = (on, config) => {
config.env.auth0_username = process.env.AUTH0_USERNAME
config.env.auth0_password = process.env.AUTH0_PASSWORD
config.env.auth0_domain = process.env.REACT_APP_AUTH0_DOMAIN
config.env.auth0_audience = process.env.REACT_APP_AUTH0_AUDIENCE
config.env.auth0_scope = process.env.REACT_APP_AUTH0_SCOPE
config.env.auth0_client_id = process.env.REACT_APP_AUTH0_CLIENTID
config.env.auth0_client_secret = process.env.AUTH0_CLIENT_SECRET
return config
}
Custom Command for Auth0 Authentication
Below is a command to programmatically login into Auth0, using the /oauth/token endpoint and set an item in localStorage with the authenticated users details, which we will use in our application code to verify we are authenticated under test.
The loginByAuth0Api
command will execute the following steps:
- Use the /oauth/token endpoint to perform the programmatic login.
- Finally the
auth0Cypress
localStorage item is set with theaccess token
,id_token
and user profile.
// cypress/support/commands.js
Cypress.Commands.add(
'loginByAuth0Api',
(username: string, password: string) => {
cy.log(`Logging in as ${username}`)
const client_id = Cypress.env('auth0_client_id')
const client_secret = Cypress.env('auth0_client_secret')
const audience = Cypress.env('auth0_audience')
const scope = Cypress.env('auth0_scope')
cy.request({
method: 'POST',
url: `https://${Cypress.env('auth0_domain')}/oauth/token`,
body: {
grant_type: 'password',
username,
password,
audience,
scope,
client_id,
client_secret,
},
}).then(({ body }) => {
const claims = jwt.decode(body.id_token)
const {
nickname,
name,
picture,
updated_at,
email,
email_verified,
sub,
exp,
} = claims
const item = {
body: {
...body,
decodedToken: {
claims,
user: {
nickname,
name,
picture,
updated_at,
email,
email_verified,
sub,
},
audience,
client_id,
},
},
expiresAt: exp,
}
window.localStorage.setItem('auth0Cypress', JSON.stringify(item))
cy.visit('/')
})
}
)
With our Auth0 app setup properly in the Auth0 Developer console, necessary
environment variables in place, and our loginByAuth0Api
command implemented,
we will be able to authenticate with Auth0 while our app is under test. Below is
a test to login as a user via Auth0, complete the
onboarding process and logout.
describe('Auth0', function () {
beforeEach(function () {
cy.task('db:seed')
cy.loginByAuth0Api(
Cypress.env('auth_username'),
Cypress.env('auth_password')
)
})
it('shows onboarding', function () {
cy.contains('Get Started').should('be.visible')
})
})
Try it out
The runnable version of this test is in the Cypress Real World App.
Adapting an Auth0 App for Testing
Note
The previous sections focused on the recommended Auth0 authentication practice within Cypress tests. To use this practice it is assumed you are testing an app appropriately built or adapted to use Auth0.
The following sections provides guidance on building or adapting an app to use Auth0 authentication.
The Cypress Real World App is used and provides configuration and runnable code for both the React SPA and the Express back end.
The front end uses the auth0-react SDK for React Single Page Applications (SPA), which uses the auth0-spa-js SDK underneath. The back end uses express-jwt to validate JWT's against Auth0.
Note
Use the yarn dev:auth0
command when starting the
Cypress Real World App.
Adapting the back end
In order to validate API requests from the frontend, we install express-jwt and jwks-rsa and configure validation for JWT's from Auth0.
// backend/helpers.ts
import jwt from 'express-jwt'
import jwksRsa from 'jwks-rsa'
dotenv.config()
const auth0JwtConfig = {
secret: jwksRsa.expressJwtSecret({
cache: true,
rateLimit: true,
jwksRequestsPerMinute: 5,
jwksUri: `https://${process.env.REACT_APP_AUTH0_DOMAIN}/.well-known/jwks.json`,
}),
// Validate the audience and the issuer.
audience: process.env.REACT_APP_AUTH0_AUDIENCE,
issuer: `https://${process.env.REACT_APP_AUTH0_DOMAIN}/`,
algorithms: ['RS256'],
}
Next, we'll define an Express middleware function to be use in our routes to
verify the Auth0 JWT sent by the front end API requests as
the Bearer
token.
// backend/helpers.ts
// ...
export const checkJwt = jwt(auth0JwtConfig).unless({ path: ['/testData/*'] })
Once this helper is defined, we can use globally to apply to all routes:
// backend/app.ts
// initial imports ...
import { checkJwt } from './helpers'
// ...
if (process.env.REACT_APP_AUTH0) {
app.use(checkJwt)
}
// routes ...
Adapting the front end
We need to update our front end React app to allow for authentication with Auth0. As mentioned above, the auth0-react SDK for React Single Page Applications (SPA) is used.
First, we create a AppAuth0.tsx
container to render our application as it is
authenticated with Auth0. The component is identical to the
App.tsx
component, but uses the useAuth0
React Hook, removes the need for
the Sign Up and Sign In routes and wraps the component with the
withAuthenticationRequired
higher order function (HOC).
A useEffect
hook is added to get the access token for the authenticated user
and send an AUTH0
event with the user
and token
objects to work with the
existing authentication layer (authMachine.ts
).
// src/containers/AppAuth0.tsx
// initial imports ...
import { withAuthenticationRequired, useAuth0 } from '@auth0/auth0-react'
// ...
const AppAuth0 = () => {
const { isAuthenticated, user, getAccessTokenSilently } = useAuth0()
// ...
useEffect(() => {
;(async function waitForToken() {
const token = await getAccessTokenSilently()
authService.send('AUTH0', { user, token })
})()
}, [user, getAccessTokenSilently])
// ...
const isLoggedIn =
isAuthenticated &&
(authState.matches('authorized') ||
authState.matches('refreshing') ||
authState.matches('updating'))
return <div className={classes.root}>// ...</div>
}
export default withAuthenticationRequired(AppAuth0)
Note: The full AppAuth0.tsx component is in the Cypress Real World App.
Next, we update our entry point (index.tsx
) to wrap our application with the
<Auth0Provider>
from the
auth0-react SDK SDK providing a custom
onRedirectCallback
. We pass props for the Auth0 environment variables set in
.env
above, and render our <AppAuth0>
component as the application.
// src/index.tsx
// initial imports ...
import AppAuth0 from "./containers/AppAuth0";
// ..
const onRedirectCallback = (appState: any) => {
history.replace((appState && appState.returnTo) || window.location.pathname);
};
if (process.env.REACT_APP_AUTH0) {
ReactDOM.render(
<Auth0Provider
domain={process.env.REACT_APP_AUTH0_DOMAIN!}
clientId={process.env.REACT_APP_AUTH0_CLIENTID!}
redirectUri={window.location.origin}
audience={process.env.REACT_APP_AUTH0_AUDIENCE}
scope={process.env.REACT_APP_AUTH0_SCOPE}
onRedirectCallback={onRedirectCallback}
>
<Router history={history}>
<ThemeProvider theme={theme}>
<AppAuth0 />
</ThemeProvider>
</Router>
</Auth0Provider>,
document.getElementById("root")
);
} else {
// render passport-local App.tsx
}
An update to our
AppAuth0.tsx component
is needed to conditionally use the auth0Cypress
localStorage item.
In the code below, we conditionally apply a useEffect
block based on being
under test with Cypress (using window.Cypress
).
In addition, we will update the export to be wrapped with
withAuthenticationRequired
if we are not under test in Cypress. This allows
our application to work with the Auth0 redirect login flow
in development/production but not when under test in Cypress.
// src/containers/AppAuth0.tsx
// initial imports ...
import { withAuthenticationRequired, useAuth0 } from "@auth0/auth0-react";
// ...
const AppAuth0 = () => {
const { isAuthenticated, user, getAccessTokenSilently } = useAuth0();
// ...
useEffect(() => {
(async function waitForToken() {
const token = await getAccessTokenSilently();
authService.send("AUTH0", { user, token });
})();
}, [user, getAccessTokenSilently]);
// If under test in Cypress, get credentials from "auth0Cypress" localstorage item and send event to our state management to log the user into the SPA
if (window.Cypress) {
useEffect(() => {
const auth0 = JSON.parse(localStorage.getItem("auth0Cypress")!);
authService.send("AUTH0", {
user: auth0.body.decodedToken.user,
token: auth0.body.access_token,
});
}, []);
} else {
useEffect(() => {
(async function waitForToken() {
const token = await getAccessTokenSilently();
authService.send("AUTH0", { user, token });
})();
}, [isAuthenticated, user, getAccessTokenSilently]);
}
// ...
const isLoggedIn =
isAuthenticated &&
(authState.matches("authorized") ||
authState.matches("refreshing") ||
authState.matches("updating"));
return (
<div className={classes.root}>
// ...
</div>
);
};
// Conditional export wrapped with `withAuthenticationRequired` if we are not under test in Cypress.
let appAuth0 = window.Cypress ? AppAuth0 : withAuthenticationRequired(AppAuth0);
export default appAuth0
Auth0 Rate Limiting Logins
Be aware of the rate limit statement in the Auth0 documentation:
Auth0 Rate Limit - "If a user attempts to login 20 times per minute as the same user from the same location, regardless of having the correct credentials, the rate limit will come into effect. When this happens, the user can make 10 attempts per minute."
This limit can be reached as the size of a test suite grows along with enabling parallelized runs to speed up test run duration.
If you run into this rate limit, a programmatic approach can be added to the
loginByAuth0
command to clear a blocked IP prior to the test run.
Next you'll need to obtain a API token to interact with the Auth0 Management API. This token is a JSON Web Token (JWT) and it contains specific granted permissions for the API.
Add this token as environment variable AUTH0_MGMT_API_TOKEN
to our
Cypress Real World App
.env
with your API token.
// .env
// ... additional keys
AUTH0_MGMT_API_TOKEN = 'YOUR-MANAGEMENT-API-TOKEN'
With this token in place, we can add interaction with the
Auth0 Anomaly remove the blocked IP address endpoint
to our loginByAuth0Api
command. This will send a delete request to
Auth0 Management API anomaly
endpoint to unblock an IP that may become blocked during the test run.
Tip
icanhazip.com is a free, hosted service to find a system's current external IP address.
Cypress.Commands.add('loginByAuth0Api', (username, password) => {
// Useful when rate limited by Auth0
cy.exec('curl -4 icanhazip.com')
.its('stdout')
.then((ip) => {
cy.request({
method: 'DELETE',
url: `https://${Cypress.env(
'auth0_domain'
)}/api/v2/anomaly/blocks/ips/${ip}`,
auth: {
bearer: Cypress.env('auth0_mgmt_api_token'),
},
})
})
// ... remaining loginByAuth0Api command
})