Create the Auth0 application secret for AWS

Do not use this page for a Microsoft Entra ID hosting. Complete the Auth0 application setup first.

Before you begin

You need:

• the deployment AWS account and Region;
• permission to create a Secrets Manager secret there;
• the Auth0 tenant domain, client ID, and client secret from the Markyard Regular Web Application; and
• a stable Markyard organization identifier such as org_acme.

The organization identifier is a Markyard data boundary, not an Auth0 organization or tenant name. Choose it once and never change it after users or documents exist.

1. Generate the cookie key

On a trusted administrative workstation, generate 64 random bytes encoded as unpadded base64url:

openssl rand -base64 64 | tr '+/' '-_' | tr -d '=\n'

Copy the result directly into the secret document. Do not put it in a ticket, chat, source-control repository, or shared command history.

2. Build the secret document

Create the following JSON document in a secure temporary editor and replace every uppercase placeholder:

{
  "authCookieKey": "GENERATED_COOKIE_KEY",
  "oidcProvidersJson": "[{\"id\":\"auth0\",\"display_name\":\"Auth0\",\"organization_id\":\"org_CUSTOMER\",\"issuer_url\":\"https://AUTH0_TENANT_DOMAIN/\",\"client_id\":\"AUTH0_CLIENT_ID\",\"client_secret\":\"AUTH0_CLIENT_SECRET\",\"scopes\":[\"openid\",\"profile\",\"email\"],\"require_email_verified\":true}]"
}

Important details:

• oidcProvidersJson is a string containing a JSON array, so its inner quotation marks remain escaped.
• The array contains exactly one provider.
• Keep id as auth0; the deployment configuration must use the same provider ID.
• Use the exact Auth0 custom or tenant domain used as the OIDC issuer and keep the trailing /.
• Keep require_email_verified enabled. Users need a verified email address.
• Do not add extra top-level keys.

Validate the JSON locally with a security-approved JSON tool without sending it to an online formatter.

Optional Auth0 directory search and role sharing

Without directory credentials, users can still authenticate. Add directory credentials only when Markyard should search Auth0 users and use Auth0 RBAC roles as shareable groups.

Create a separate Auth0 Machine-to-Machine Application, authorize it for the Auth0 Management API, and grant only the Management API scopes required to read users and roles: read:users and read:roles. Auth0 documents the production client-credentials flow in Get Management API access tokens.

Add this directory object inside the single provider object before converting it to the escaped oidcProvidersJson string:

{
  "kind": "auth0",
  "management_base_url": "https://AUTH0_TENANT_DOMAIN",
  "client_id": "AUTH0_DIRECTORY_CLIENT_ID",
  "client_secret": "AUTH0_DIRECTORY_CLIENT_SECRET",
  "audience": "https://AUTH0_TENANT_DOMAIN/api/v2/"
}

Use the untrailed base URL for management_base_url. Keep these credentials separate from the browser application's client secret, rotate them under your credential policy, and retest user search, role search, and role-derived access after rotation.

3. Store the secret in AWS

In the deployment account and Region:

1. Open AWS Secrets Manager and select Store a new secret.
2. Select Other type of secret.
3. Open Plaintext and paste the complete outer JSON object.
4. Use the AWS managed Secrets Manager key, or select the customer-managed KMS key named in your deployment design.
5. Name the secret for the installation, for example markyard/production/application.
6. Do not configure automatic rotation for this compound secret. Coordinate application credential rotation with a deployment and sign-in check.
7. Store the secret and copy its complete ARN, including AWS's six-character suffix.

AWS cautions that secret values placed directly in shell commands can be recovered from shell history or process inspection. The console or a security-approved file-based AWS CLI workflow avoids putting the value on the command line. See Create an AWS Secrets Manager secret.

Delete the temporary plaintext document securely after confirming that the secret is stored and recoverable by authorized operators.

4. Complete the deployment configuration

Set the deployment configuration values to:

{
  "auth": {
    "providerId": "auth0",
    "applicationSecretArn": "COMPLETE_SECRET_ARN"
  }
}

When the secret uses a customer-managed KMS key, also add its complete key ARN as applicationSecretKmsKeyArn.

Return to Deploy Markyard in your AWS account to validate, review, and deploy the stacks.

Rotate credentials

For an Auth0 client-secret rotation:

1. Schedule a maintenance window and create or rotate the Auth0 credential.
2. Update only the relevant client-secret value inside oidcProvidersJson; preserve the cookie key, provider ID, issuer, and organization identifier.
3. Save a new Secrets Manager secret version.
4. Run the deployment diff and deployment so ECS starts a new task definition referencing the current secret.
5. Verify browser sign-in and, when enabled, directory and role search.
6. Revoke the superseded credential after validation.

Troubleshooting

• Provider mismatch: the provider object and deployment configuration must both use auth0.
• OIDC discovery failure: verify the exact HTTPS issuer domain and trailing /.
• Email rejected: confirm that Auth0 supplies email and email_verified: true for the user.
• Directory 401 or 403: confirm the Machine-to-Machine Application, Management API audience, client credentials, and read:users and read:roles grants.
• Secret validation failure: confirm the outer object has exactly two keys, the inner provider array contains exactly one object, and the cookie key decodes to 64 bytes.