Skip to content

Quick start

This walkthrough takes you from a new tenant to a passing test in about five minutes. It uses the Client Id/Secret test, because it needs nothing more than an OAuth client you already have, such as an Auth0, Okta or Entra ID application.

Before you begin

You need:

  • A Helena account (see Sign up).
  • The token endpoint, client ID and client secret of an OAuth client that is allowed to use the client credentials grant.
  • A token endpoint that is reachable over public HTTPS. Helena cannot reach private networks or plain HTTP.

1. Choose an environment

The Environment dropdown at the top of the sidebar shows the environment you are working in. New tenants start with Default, which is fine for now. To keep production checks separate, create more environments under Environments. See Environments.

2. Create a test

  1. In the sidebar, open Authentication → Client Id/Secret and select New test.
  2. Fill in the form:
    • Name: for example Auth0 – CI client.
    • Token endpoint: for example https://YOUR_TENANT.auth0.com/oauth/token.
    • Client ID and Client secret: your client's credentials. The secret is encrypted and never shown again.
    • Client authentication: leave this as client_secret_basic unless your provider requires client_secret_post. Auth0 requires client_secret_post.
    • audience parameter: required by Auth0 (your API identifier). Leave it blank for most other providers.
    • The target should: Issue a token.
  3. Save the test.

3. Run it

On the test page, select Run now. Helena opens the run, which updates every couple of seconds until it finishes.

4. Read the result

The run page shows:

  • Status:
    • passed: every assertion held.
    • failed: at least one assertion did not hold.
    • error: Helena could not complete the run, for example because the URL was blocked or the connection failed.
  • Steps: each request Helena sent and the response it got. Secrets and tokens are fingerprinted.
  • Assertions: what was checked, what was expected and what actually happened.

If the run failed, the failed assertions tell you which requirement your target missed. A common example is a missing Cache-Control: no-store header on the token response. See Test Logs for how to read a run in detail.

5. Add a negative test

A security integration should refuse what it must refuse. Create a second test with a revoked or deliberately wrong secret, and set The target should to Refuse the client. It passes when the token endpoint refuses the credentials with an RFC 6749 error response.

6. Run it on a schedule or from CI

  • Schedule. Edit the test, enter a Cron expression (UTC) such as 0 * * * * (hourly), and turn on Run on schedule. See Scheduling.
  • CI/CD. Create a service account with the write scope, then trigger the test from your pipeline:
curl -s -X POST -H "Authorization: Bearer $HELENA_TOKEN" -H 'Content-Type: application/json' \
  -d '{"wait": true}' \
  "https://app.helena.dev/api/v1/environments/$ENV_UUID/tests/$TEST_UUID/runs" \
  | jq -e '.data.status == "passed"'

See CI/CD examples for complete GitHub Actions and GitLab CI jobs.