> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/integrations/resource-integrations/auth0.md).

# Auth0

Install P0 for an Auth0 tenant so people can request just-in-time tenant roles, API permissions and organization memberships in it.

With P0 installed for an Auth0 tenant, people can request a tenant role, a permission on one of the tenant's APIs, or membership of an Auth0 organization, with or without a tenant role in it. P0 assigns approved access to the requestor's own Auth0 user. When access ends, P0 takes back what it assigned and nothing else.

{% hint style="info" %}
The Auth0 integration is in beta. Functionality and configuration may change.
{% endhint %}

## How it works

* **You create a Management API application.** P0 acts on your tenant as a machine-to-machine application that you create and authorize for the Auth0 Management API. It reads and changes users' roles, their permissions and organization memberships, and nothing else.
* **You deploy a connector in your cloud.** It runs on AWS Lambda or Google Cloud Run, from Terraform that the installer generates. One connector can serve many tenants.
* **The client secret stays in your secret manager.** You store it in AWS Secrets Manager or Google Secret Manager. The connector reads it, and P0 never does.
* **You choose the email domains the connector acts for.** Only you can change them, on the connector's deployment.
* **P0 matches people by email.** P0 finds the Auth0 user with the email the requestor signs in to P0 with. It never creates or deletes Auth0 users.
* **Approvers see the Auth0 user.** A request shows **Auth0 user ID when requested**. If P0 finds another user at approval, it refuses the request.

For what P0 assigns and takes back for each kind of access, see [Requesting Auth0 access](https://docs.p0.dev/integrations/resource-integrations/auth0/requesting-access.md).

## Before you begin

You need:

* **An Auth0 tenant, by its canonical domain**, such as `acme.us.auth0.com`. A custom domain can't be used.
* **Someone who can create applications in the tenant.**
* **An Auth0 user for each requestor, with their P0 email.** Without one, the request fails.
* [**Terraform**](https://developer.hashicorp.com/terraform/install).

The connector runs on AWS Lambda or Google Cloud Run, and the client secret goes in the same cloud's secret manager. The secret can be in another account or project than the connector.

For a connector on AWS Lambda, you also need:

* [AWS](https://docs.p0.dev/integrations/resource-integrations/aws.md#setting-up-aws-iam-management) **for the connector's account.**
* [AWS Secrets Manager](https://docs.p0.dev/integrations/resource-integrations/aws-secrets-manager.md) **integration for the account that holds the client secret.**
* **Terraform 1.4 or later, run where Docker and the AWS CLI are installed**, with the AWS CLI signed in to the connector's account.
* **Commercial AWS regions** for the connector and the client secret. GovCloud, China, ISO and European Sovereign Cloud regions aren't supported.

For a connector on Google Cloud Run, you also need:

* [Google Cloud](https://docs.p0.dev/integrations/resource-integrations/google-cloud.md#install-iam-management-on-each-project) **for the connector's project.**
* [Google Secret Manager](https://docs.p0.dev/integrations/resource-integrations/google-secret-manager.md) **integration for the project that holds the client secret.**
* **The IAM, Cloud Run and Secret Manager APIs** enabled in the connector's project: `iam.googleapis.com`, `run.googleapis.com` and `secretmanager.googleapis.com`.
* **The `gcloud` CLI.**

## Install Auth0

1. Open the P0 dashboard at [p0.app](https://p0.app) and log in to your organization.
2. In the sidebar, click **Integrations**. Under **Resources**, click **Auth0**.

You install the **Connector** component in steps 1 to 3, usually once. Then you install the **Tenant** component in steps 4 to 7, once for each Auth0 tenant.

### Step 1: Add a connector

You can't change where a connector runs once you add it.

1. Select the **Connector** component, and click **Add connector**. The form is titled **Installing a new connector**.
2. In **Connector ID**, enter a name for the connector, such as `prod`. Use lowercase letters, digits and hyphens, up to 63 characters, starting and ending with a letter or digit.
3. In **Connector hosting**, choose **AWS Lambda** or **Google Cloud Run**, and fill in its fields.

| Hosting              | Field                | What to enter                                                                                                                                                                   |
| -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **AWS Lambda**       | **AWS account ID**   | The account the connector runs in. The list shows the accounts where P0's AWS IAM management is installed.                                                                      |
|                      | **Connector name**   | The name of the connector's Lambda function and IAM role. Use 2 to 64 lowercase letters, digits and single hyphens, starting with a letter and ending with a letter or digit.   |
|                      | **Connector region** | An AWS region, such as `us-west-2`                                                                                                                                              |
| **Google Cloud Run** | **GCP project ID**   | The project the connector runs in. The list shows the projects where P0's Google Cloud IAM management is installed.                                                             |
|                      | **Connector name**   | The name of the connector's Cloud Run service and service account. Use 6 to 30 lowercase letters, digits and hyphens, starting with a letter and ending with a letter or digit. |
|                      | **Connector region** | A Google Cloud region, such as `us-west1`                                                                                                                                       |

Until you install P0's Google Cloud IAM management, you can't choose **Google Cloud Run**, and P0 says: `P0 invokes a connector on Cloud Run as the service account of its Google Cloud integration, which isn't installed. Install P0's Google Cloud IAM management for the connector's project first.`

4. Click **Next**. P0 saves the connector and opens its setup page.

If P0 can't save the connector, it says why under **Error configuring Auth0**. See [#when-you-add-a-connector-or-a-tenant](#when-you-add-a-connector-or-a-tenant "mention").

### Step 2: Set the allowed domains

The connector acts only for people whose email domain matches its allowed domains pattern. Set the pattern in `domain_allow_pattern`, near the top of the connector's Terraform on the setup page, before you apply it. The connector won't start without a valid pattern.

The pattern is a regular expression, tested against the part of an email after the `@`. P0 fills in the domain of the email you're signed in with. For `example.com`:

```terraform
domain_allow_pattern = "^example\\.com$"
```

Terraform strings need each backslash doubled. If P0 doesn't know your email's domain, it fills in `example.com`, which matches nobody, so replace it.

Change the pattern to cover everyone who should be able to request access. For two domains:

```terraform
domain_allow_pattern = "^(example\\.com|example\\.org)$"
```

{% hint style="warning" %}
**Keep the `^` and the `$`.** Without them, a pattern for `example.com` also matches `notexample.com`. Escape each dot as well, because a bare `.` matches any character.
{% endhint %}

* One pattern covers every tenant the connector serves. To allow different domains for different tenants, add a connector for each.
* P0 can't change the pattern. Each tenant's page shows it as **Allowed domains**, and warns you if it leaves out your own email's domain.
* Narrowing the pattern doesn't stop P0 from taking back access it already granted.

### Step 3: Deploy the connector

The setup page's Terraform deploys the connector where step 1 says, and lets P0 invoke it. The connector needs no VPC. See [#what-the-connectors-deployment-creates](#what-the-connectors-deployment-creates "mention").

1. Copy the Terraform, and add it to your configuration with the pattern from step 2. Leave the account or project, the region and the connector name as they are.
2. For a connector on AWS Lambda, before you apply it:
   * If your configuration already has a `required_providers` block, move the snippet's `docker` provider into it and delete the snippet's block.
   * Add the credential settings your other AWS providers use, such as `profile` or `assume_role`, to the snippet's `aws` provider.
3. Apply it.
4. Click **Next**. P0 checks that it can invoke the connector. If the check fails right after you apply, wait a minute and click **Next** again. See [#when-p0-validates-the-install](#when-p0-validates-the-install "mention").
5. On the configure page, click **Finish**. Tenants can pick the connector only after you do.

### Step 4: Add a tenant

Once you add a tenant, you can't change its connector or client ID, or where its secret is and what it's called.

1. On the Auth0 integration's page, select the **Tenant** component, and click **Add tenant**. The form is titled **Installing a new tenant**.
2. Follow the instructions at the top of the form. In the Auth0 Dashboard, go to **Applications**, then **Applications**, and create a **Machine to Machine** application. Authorize it for the **Auth0 Management API** with exactly these scopes, and no others:

```
read:users
read:roles
read:role_members
update:users
create:role_members
delete:role_members
read:resource_servers
read:user_effective_permissions
read:organizations
read:organization_members
read:organization_member_roles
create:organization_members
delete:organization_members
create:organization_member_roles
delete:organization_member_roles
```

The connector needs each scope for these jobs:

| Scope                              | What P0 uses it for                                                                                   |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `read:users`                       | Find the requestor's Auth0 user by email, and read that user's roles and organizations                |
| `update:users`                     | Assign a permission to the requestor's user, and remove it when access ends                           |
| `read:roles`                       | List the tenant's roles for a request, and read the roles the user holds                              |
| `read:role_members`                | Read which roles are assigned to the user                                                             |
| `create:role_members`              | Assign a tenant role to the requestor's user                                                          |
| `delete:role_members`              | Remove that role when access ends                                                                     |
| `read:resource_servers`            | List the tenant's APIs and the permissions each one defines                                           |
| `read:user_effective_permissions`  | Tell a permission assigned to the user from one a role gives, so P0 never removes a role's permission |
| `read:organizations`               | List the tenant's organizations, and the ones the user belongs to                                     |
| `read:organization_members`        | Check whether the user is already a member of an organization                                         |
| `read:organization_member_roles`   | Read the user's roles in an organization                                                              |
| `create:organization_members`      | Add the requestor's user to an organization                                                           |
| `delete:organization_members`      | Remove a membership P0 added when access ends                                                         |
| `create:organization_member_roles` | Assign a role to the user in an organization                                                          |
| `delete:organization_member_roles` | Remove that role when access ends                                                                     |

None of these scopes lets P0 create or delete users, change what a role or an API grants, or change the tenant's settings.

3. Copy the application's client ID from its settings. Keep its client secret for step 5.
4. Back in the form, in **Tenant domain**, enter the tenant's canonical Auth0 domain in lowercase, such as `acme.us.auth0.com`.
5. In **Connector**, pick the connector that acts on this tenant. If you haven't finished one, the field says `Install an Auth0 connector first.` Go back to steps 1 to 3.
6. In **Secret manager provider**, choose the secret manager in the connector's cloud, and fill in its fields.

| Secret manager provider                                 | Field              | What to enter                                                                                                                     |
| ------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **AWS Secrets Manager**, for a connector on AWS Lambda  | **Installation**   | The AWS account the secret is in. The list shows the accounts where P0's AWS Secrets Manager integration is installed.            |
|                                                         | **Secrets region** | The secret's AWS region, such as `us-west-2`                                                                                      |
| **Google Secret Manager**, for a connector on Cloud Run | **Installation**   | The Google Cloud project the secret is in. The list shows the projects where P0's Google Secret Manager integration is installed. |

7. In **Client ID**, enter the application's client ID.
8. In **Client secret's secret**, enter the name of the secret that holds, or will hold, the client secret. Enter the name, not the ARN or the full resource name, and never the client secret itself. In AWS Secrets Manager, the name can't end in a hyphen and six letters or digits, such as `-AbCdEf`.
9. Click **Next**. P0 saves the tenant and opens its setup page.

If the secret is in another AWS account than the connector, encrypt it with a customer-managed KMS key. Another account can't use the default `aws/secretsmanager` key.

The setup page lists five steps. **Create the Management API application** repeats the instructions above, and **Deploy the connector** is already done. Steps 5 to 7 below cover the rest.

### Step 5: Store the client secret

The setup page shows these commands with the secret's name and place filled in.

1. Run this, paste the client secret and press Enter. It reads the client secret without showing it:

```bash
read -rs AUTH0_CLIENT_SECRET
```

2. Create the secret. In AWS Secrets Manager:

```bash
printf %s "$AUTH0_CLIENT_SECRET" | aws secretsmanager create-secret \
  --name <secret-name> \
  --secret-string file:///dev/stdin \
  --region <region>
```

In Google Secret Manager:

```bash
printf %s "$AUTH0_CLIENT_SECRET" | gcloud secrets create <secret-name> \
  --project <project-id> \
  --data-file=-
```

For a secret in another AWS account, the setup page's command also passes `--kms-key-id <kms-key-arn>`. Replace `<kms-key-arn>` with the key's ARN. If the secret already exists, store the client secret as a new version instead, with the command the setup page shows, as in [#change-the-install-later](#change-the-install-later "mention").

3. Clear the client secret from your shell:

```bash
unset AUTH0_CLIENT_SECRET
```

### Step 6: Let the connector read the client secret

1. Copy the Terraform from the setup page, and add it to your configuration.
2. On AWS, add your usual credential settings to the snippet's `aws` provider. If a customer-managed KMS key encrypts the secret, set `kms_key_arn` to the key's ARN.
3. Apply it.

The Terraform grants the connector this, and nothing else:

| Secret manager        | What the Terraform grants                                                                                                                                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AWS Secrets Manager   | A policy on the connector's role, `ReadAuth0ClientSecret-<tenant>`, with `secretsmanager:GetSecretValue` on the secret. If you set `kms_key_arn`, it also has `kms:Decrypt` on that key, through Secrets Manager only.                       |
| Google Secret Manager | `roles/secretmanager.secretAccessor` and `roles/secretmanager.viewer` for the connector's service account, on the secret only. Each adds one member to the secret's IAM policy and replaces nothing. The secret must exist before you apply. |

**If the secret is in another AWS account than the connector**, the setup page has two configurations:

1. Apply the first in the connector's account. Terraform won't plan it until you set `kms_key_arn`.
2. Apply the second in the secret's account, after the connector's own Terraform. It sets the secret's resource policy so the connector's role can read it, and outputs a statement to add to the KMS key's policy.

{% hint style="warning" %}
The second configuration replaces the secret's whole resource policy. If the secret already has one, leave the `aws_secretsmanager_secret_policy` resource out, and add its statement to your policy instead.
{% endhint %}

{% hint style="warning" %}
**Limit the connector's read access to the client secrets of the tenants it serves.** P0 names the secret in each call to the connector, so a call could point it at any other secret it can read.
{% endhint %}

### Step 7: Validate

1. Click **Next**. P0 asks the connector to read the client secret, sign in to the tenant, and check that the application has every scope from step 4.
2. On the tenant's configure page, check that **Allowed domains** is the pattern you set in step 2. If it leaves out the domain of the email you're signed in with, the page warns: `The connector allows the email domains <pattern>, which leaves out your own, <domain>. If people at <domain> should be able to request access in <tenant>, change domain_allow_pattern in the connector's Terraform and apply it.`
3. Click **Finish**. People can't request access in the tenant until you do.

If a check fails, P0 says what to fix under **Error configuring Auth0**. See [#when-p0-validates-the-install](#when-p0-validates-the-install "mention"). If the connector can't read the secret right after you apply the Terraform, wait a few seconds and click **Next** again.

{% hint style="success" %}
People can now request access in the tenant. See [Requesting Auth0 access](https://docs.p0.dev/integrations/resource-integrations/auth0/requesting-access.md).
{% endhint %}

## What the connector's deployment creates

The connector's Terraform gives the connector no secret. Each tenant's Terraform adds read access to that tenant's client secret, as in [#step-6-let-the-connector-read-the-client-secret](#step-6-let-the-connector-read-the-client-secret "mention").

On AWS Lambda:

| Resource                                               | What it's for                                                                                            |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| An ECR repository                                      | Holds the copy of P0's connector image that Lambda runs, with immutable tags                             |
| A CloudWatch log group, `/aws/lambda/<connector-name>` | The connector's logs, kept for 30 days. Change `log_retention_days` to keep them longer or shorter.      |
| An IAM role, named after the connector                 | The role the connector runs as, with `logs:CreateLogStream` and `logs:PutLogEvents` on its own log group |
| The Lambda function                                    | Runs the connector, with no VPC                                                                          |
| A policy on P0's role in the account                   | `lambda:InvokeFunction` on the connector's function, and nothing else                                    |

On Google Cloud Run:

| Resource                                                  | What it's for                                                                                                    |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| A service account, named after the connector              | The identity the connector runs as                                                                               |
| The Cloud Run service                                     | Runs the connector from P0's image on Docker Hub, with no VPC                                                    |
| Two IAM bindings on the service, for P0's service account | `roles/run.invoker`, to invoke the connector, and `roles/run.viewer`, to read the service's URL when you install |

## Install with Terraform

{% hint style="info" %}
The `p0_auth0_*` resources require P0 Terraform provider [v0.74.0](https://github.com/p0-security/terraform-provider-p0/releases/tag/v0.74.0) or later.
{% endhint %}

Instead of the installer, you can install Auth0 with the P0 Terraform provider. See [Manage integrations as code with the P0 Terraform provider](https://docs.p0.dev/getting-started/get-started-with-the-p0-terraform-provider.md). You still create the Management API application and store its client secret, as in [#step-4-add-a-tenant](#step-4-add-a-tenant "mention") and [#step-5-store-the-client-secret](#step-5-store-the-client-secret "mention"). Each resource's page in the Terraform registry has a complete example for each cloud, including the cloud resources. Create the resources in this order:

1. **Stage the connector** with [`p0_auth0_connector_staged`](https://registry.terraform.io/providers/p0-security/p0/latest/docs/resources/auth0_connector_staged). Set `id` and `hosting`. P0 answers with `connector_identity`, the role or service account the connector must run as.
2. **Deploy the connector** where `hosting` says, with its `DOMAIN_ALLOW_PATTERN` environment variable set as in [#step-2-set-the-allowed-domains](#step-2-set-the-allowed-domains "mention"). Pin the image to a published tag and that tag's digest, as the examples do. P0 publishes the tags on Docker Hub.
   * **AWS Lambda:** use the image `p0security/p0-connector-auth0`, copied into Amazon ECR. Give P0's AWS IAM management role `lambda:InvokeFunction` on the function.
   * **Google Cloud Run:** use the image `p0security/p0-connector-auth0-gcloud`, running as the staged service account. Give P0's Google Cloud service account `roles/run.invoker` and `roles/run.viewer` on the service, and set the connector's `INVOKER_SA_EMAIL` environment variable to that service account's email.
3. **Install the connector** with [`p0_auth0_connector`](https://registry.terraform.io/providers/p0-security/p0/latest/docs/resources/auth0_connector), with the same `id` and `hosting` as the staged resource. P0 checks that it can invoke the connector.
4. **Give the connector read access to the client secret**, as in [#step-6-let-the-connector-read-the-client-secret](#step-6-let-the-connector-read-the-client-secret "mention").
5. **Add each tenant** with [`p0_auth0_tenant`](https://registry.terraform.io/providers/p0-security/p0/latest/docs/resources/auth0_tenant). Set `id` to the tenant's canonical domain, and set `connector`, `vault`, `client_id` and `client_secret_name`. Make it depend on the read access.

For example, a tenant whose client secret is in AWS Secrets Manager:

```terraform
resource "p0_auth0_tenant" "acme" {
  id        = "acme.us.auth0.com"
  connector = p0_auth0_connector.prod.id

  vault = {
    type           = "aws-sm"
    account_id     = "123456789012"
    secrets_region = "us-west-2"
  }
  client_id          = "<client-id>"
  client_secret_name = "auth0/acme/mgmt"

  depends_on = [aws_iam_role_policy.read_auth0_client_secret]
}
```

Creating the tenant has P0 validate it through the connector, as in [#step-7-validate](#step-7-validate "mention"). If a check fails, the apply fails with P0's message. Fix what the message names and apply again.

Changing a tenant's `connector`, `vault`, `client_id` or `client_secret_name` replaces the tenant, and changing a connector's `id` or `hosting` replaces the connector.

### Import what you added in the P0 app

If you already added a connector or a tenant in the P0 app, the apply fails and says to import it. Import a connector into both of its resources, and a tenant into its one:

```bash
terraform import p0_auth0_connector_staged.prod prod
terraform import p0_auth0_connector.prod prod
terraform import p0_auth0_tenant.acme acme.us.auth0.com
```

## Access policies

In [Configuring access policies](https://docs.p0.dev/policy-studio/policy-studio/configure-your-first-access-policy.md#resource), Auth0 is the service `auth0`. Its access types are `role`, `permission` and `organization`.

### Available filters

A rule can filter on these properties of a request, each with the key `name`:

| Filter         | What it matches                                                                            | Access types           | Example                   |
| -------------- | ------------------------------------------------------------------------------------------ | ---------------------- | ------------------------- |
| `tenant`       | The tenant's domain, as you entered it in P0                                               | All                    | `acme.us.auth0.com`       |
| `role`         | The tenant role's name. On `organization`, it matches only a request that asks for a role. | `role`, `organization` | `Admin`                   |
| `api`          | The API's identifier                                                                       | `permission`           | `https://api.example.com` |
| `permission`   | The permission's name                                                                      | `permission`           | `read:reports`            |
| `organization` | The organization's name                                                                    | `organization`         | `acme-support`            |

Patterns are unanchored, case-sensitive regular expressions. Use `^` and `$` to match a whole name.

### Example access policy

These policies send requests for any role in `acme.us.auth0.com` to P0 approvers, and deny the `Admin` role in every tenant:

```yaml
- requestor:
    type: any
  resource:
    type: integration
    service: auth0
    accessType: role
    filters:
      tenant:
        effect: keep
        key: name
        pattern: ^acme\.us\.auth0\.com$
  approval:
    - type: p0
- requestor:
    type: any
  resource:
    type: integration
    service: auth0
    accessType: role
    filters:
      role:
        effect: keep
        key: name
        pattern: ^Admin$
  approval:
    - type: deny
```

## Error messages

Once you've fixed the cause of an error, retry what failed.

### When you add a connector or a tenant

P0 checks the form when you click **Next** in [#step-1-add-a-connector](#step-1-add-a-connector "mention") or [#step-4-add-a-tenant](#step-4-add-a-tenant "mention"), and saves nothing if a check fails. The message shows under **Error configuring Auth0**.

| Message                                                                                                                                                                                                | What to do                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `The connector <id> is already added. To change it, remove <id> and add it again.`                                                                                                                     | Open the connector from the list, or choose another ID.                                                                                            |
| `Use lowercase letters, digits and hyphens only, starting and ending with a letter or digit, up to 63 characters.`                                                                                     | Fix the connector ID.                                                                                                                              |
| `Use 2 to 64 characters for the connector name: lowercase letters, digits and single hyphens, starting with a letter and ending with a letter or digit.`                                               | Fix the AWS Lambda **Connector name**.                                                                                                             |
| `Use 6 to 30 characters for the connector name: lowercase letters, digits and hyphens, starting with a letter and ending with a letter or digit. The connector's service account takes the same name.` | Fix the Cloud Run **Connector name**.                                                                                                              |
| `Enter the AWS region the connector runs in, such as us-west-2.`, or a similar message for another account, project or region field                                                                    | Fill in the field it names.                                                                                                                        |
| `P0's Auth0 integration supports only AWS's commercial regions. Enter a commercial region, such as us-west-2.`                                                                                         | Use a commercial AWS region for the connector and the secret.                                                                                      |
| `The Auth0 tenant <tenant> is already added. To change it, remove <tenant> and add it again.`                                                                                                          | Open the tenant from the list.                                                                                                                     |
| `Enter the tenant's canonical Auth0 domain, such as acme.us.auth0.com, in lowercase. A custom domain can't be used: the Auth0 Management API only answers on the canonical one.`                       | Enter `<name>.auth0.com` or `<name>.<region>.auth0.com`, in lowercase.                                                                             |
| `Enter the client ID of the Auth0 machine-to-machine application, as the application's settings show it.`                                                                                              | Copy the **Client ID** from the application's settings.                                                                                            |
| `Pick the connector that acts on this tenant. Install an Auth0 connector first if there's none.`                                                                                                       | Pick a connector, or finish steps 1 to 3 first.                                                                                                    |
| `The client secret must be in the connector's cloud: AWS Secrets Manager for a connector on AWS Lambda, or Google Secret Manager for one on Cloud Run.`                                                | Change **Secret manager provider**.                                                                                                                |
| `Enter the name of the secret that holds, or will hold, the client secret.`                                                                                                                            | Fill in **Client secret's secret**.                                                                                                                |
| `That doesn't look like a secret name. Enter the name of the secret that holds the client secret, not its ARN, its full resource name or the client secret itself.`                                    | Enter the secret's name. If you pasted the client secret itself, rotate it as in [#change-the-install-later](#change-the-install-later "mention"). |
| `Secrets Manager can't find a secret by its name when the name ends in a hyphen and six characters, like -AbCdEf. Use a secret whose name doesn't end that way.`                                       | Choose another secret name.                                                                                                                        |

### When P0 validates the install

P0 validates a connector in [#step-3-deploy-the-connector](#step-3-deploy-the-connector "mention") and a tenant in [#step-7-validate](#step-7-validate "mention"). A failed check shows under **Error configuring Auth0**. In these messages, `<where it runs>` names the connector's function or service, such as `the Lambda function p0-auth0 in AWS account 123456789012, region us-west-2`.

For a connector:

| Message                                                                                                                                                                       | What to do                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `P0 couldn't find <where it runs>. It may still be deploying. Check that the connector's Terraform applied, then retry.`                                                      | Check that the Terraform applied with the account or project, region and name from step 1. |
| `P0 isn't allowed to invoke <where it runs>. The connector's Terraform lets P0's role call lambda:InvokeFunction on the function: check that it applied, then retry.`         | Apply the connector's Terraform. Right after you apply it, wait a few seconds.             |
| `P0 isn't allowed to invoke <where it runs>. The connector's Terraform grants P0 roles/run.invoker on the service: check that it applied, then retry.`                        | Apply the connector's Terraform. Right after you apply it, wait a few seconds.             |
| `P0 isn't allowed to read <where it runs>, so it can't find its URL. The connector's Terraform grants P0 roles/run.viewer on the service: check that it applied, then retry.` | Apply the connector's Terraform.                                                           |
| `<where it runs> has no URL yet. It may still be deploying. Check that the connector's Terraform applied, then retry.`                                                        | Wait for the service to finish deploying.                                                  |
| `P0 found <where it runs>, but it isn't ready yet. It may still be starting. Retry in a minute, and check its logs if it isn't ready by then.`                                | Wait a minute. If it still isn't ready, check its logs.                                    |
| Any other message                                                                                                                                                             | Check the connector's logs.                                                                |

If the allowed domains pattern is missing, blank or not a valid regular expression, the connector doesn't start, and its logs have a line that starts `DOMAIN_ALLOW_PATTERN isn't`. Fix the pattern as in [#step-2-set-the-allowed-domains](#step-2-set-the-allowed-domains "mention"), and apply the Terraform again.

For a tenant, a message from the connector ends with what P0 checked, such as `(P0 checked the client ID and the client secret.)`:

| Message                                                                                                                                                                                                                                                                                                             | What to do                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `The connector <id> isn't installed. Install it again with the same ID and hosting, or remove <tenant> and add it again with another connector.`                                                                                                                                                                    | Add the connector again, as in steps 1 to 3, with the same ID and hosting.                                                                                                                                                                                                                                        |
| `The connector couldn't find the Auth0 client secret <secret>. Check the client secret in the P0 install, and that the secret still exists.`                                                                                                                                                                        | Store the client secret where the setup page shows, as in [#step-5-store-the-client-secret](#step-5-store-the-client-secret "mention"). If you named the wrong secret, remove the tenant and add it again.                                                                                                        |
| `The connector isn't allowed to read the Auth0 client secret <secret>. Grant the connector's identity secretsmanager:GetSecretValue on that secret, and kms:Decrypt on its KMS key if it uses a customer-managed key.`, or the same message naming `secretmanager.versions.access` and `secretmanager.versions.get` | Apply the tenant's Terraform, as in [#step-6-let-the-connector-read-the-client-secret](#step-6-let-the-connector-read-the-client-secret "mention"), with `kms_key_arn` if a customer-managed key encrypts the secret. For a secret in another AWS account, apply both configurations and update the key's policy. |
| `The Auth0 client secret <secret> is empty. Store the Management API application's client secret in it.`                                                                                                                                                                                                            | Store the client secret as a new version, as in [#change-the-install-later](#change-the-install-later "mention").                                                                                                                                                                                                 |
| `Auth0 tenant <tenant> didn't accept the connector's client credentials (<status>): <reason>. Check the client id in the P0 install and the client secret in the connector's secret, and that the application is authorized for the Auth0 Management API.`                                                          | Check the client ID on the tenant's page, the client secret in the secret, and the application's Management API authorization. If the client ID is wrong, remove the tenant and add it again.                                                                                                                     |
| `The connector's application on Auth0 tenant <tenant> is missing Management API scopes: <scopes>. Authorize the application for the Management API with them, then validate again.`, or the same message for one scope                                                                                              | Authorize the application for each scope it lists, as in [#step-4-add-a-tenant](#step-4-add-a-tenant "mention").                                                                                                                                                                                                  |
| `P0 invoked <where it runs>, but it didn't answer as the Auth0 connector. Check that it runs the connector's image, and check its logs, then retry.`                                                                                                                                                                | Apply the connector's Terraform again. If it already runs the connector, check its logs.                                                                                                                                                                                                                          |
| `P0 couldn't reach the connector, <where it runs>. It may have been removed, or P0 may no longer be allowed to invoke it. Check that the connector's Terraform is still applied, then retry.`                                                                                                                       | Check that the connector runs where its page in P0 says, and apply its Terraform again.                                                                                                                                                                                                                           |
| A message that starts `Auth0 tenant <tenant> is rate limiting the connector`, or `Auth0 couldn't answer the connector's request right now`                                                                                                                                                                          | Click **Next** again after the time the message gives, or in a few minutes.                                                                                                                                                                                                                                       |
| `The connector couldn't reach Auth0 tenant <tenant>. Check that it can reach <tenant>, then retry.`                                                                                                                                                                                                                 | Check that the connector can reach the internet, and that the tenant's domain is right.                                                                                                                                                                                                                           |

### On requests

Requestors and approvers see these messages on a request. A failed revoke has a **Retry revoke** button on the request's page. A failed grant has none. For the messages a requestor can fix themselves, see [Requesting Auth0 access](https://docs.p0.dev/integrations/resource-integrations/auth0/requesting-access.md#when-p0-refuses-your-request).

| Message                                                                                                                                                                                               | What to do                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Your email domain isn't allowed for Auth0 tenant <tenant>. Ask your P0 admin to check the connector's allowed domains.`                                                                              | If the requestor should have access, change the pattern as in [#step-2-set-the-allowed-domains](#step-2-set-the-allowed-domains "mention").                                                                                                                                                 |
| `No Auth0 user in <tenant> has your email, <email>. P0 doesn't create Auth0 users: ask your Auth0 admin to add you, then request again.`                                                              | Create an Auth0 user with the requestor's P0 email, or set an existing user's email to it. The requestor then requests again.                                                                                                                                                               |
| `Auth0 tenant <tenant> refused the connector's request (<status>): <reason>`                                                                                                                          | Fix what Auth0's reason names in the Auth0 Dashboard. The requestor then requests again, or you click **Retry revoke**.                                                                                                                                                                     |
| `Auth0 refused to assign the role in organization <organization-id>: <reason>. P0 removed the membership it had added.`                                                                               | Fix what Auth0's reason names. The requestor then requests again.                                                                                                                                                                                                                           |
| `Auth0 refused to assign the role in organization <organization-id>: <reason>. P0 added the membership but couldn't remove it again. Remove <user-id> from <organization-id> by hand.`                | Remove the user from the organization in the Auth0 Dashboard, then fix what Auth0's reason names.                                                                                                                                                                                           |
| `Auth0 tenant <tenant> couldn't find <what it looked for>. Check that it still exists.`                                                                                                               | Check that the user, role, API or organization still exists in the tenant.                                                                                                                                                                                                                  |
| `P0 couldn't finish removing your previous access to <target>. Ask an admin to fix it in Auth0 and finish the revoke in P0, then request again.`                                                      | Open the requestor's earlier request for the same access, fix the cause its error names, and click **Retry revoke**.                                                                                                                                                                        |
| `P0 couldn't reach the Auth0 connector. Ask your P0 admin to check its deployment.`                                                                                                                   | Check that the connector runs where its page in P0 says, and apply its Terraform again. Check that P0's AWS IAM management or Google Cloud IAM management is still installed for its account or project.                                                                                    |
| `P0's Auth0 connector couldn't read the client secret. Ask your P0 admin to check the Auth0 install.`                                                                                                 | Check that the secret named on the tenant's page exists and holds the client secret, and that you applied the tenant's Terraform, as in [#step-6-let-the-connector-read-the-client-secret](#step-6-let-the-connector-read-the-client-secret "mention").                                     |
| A message that starts `There is an unrecoverable error in your organization's Auth0 installation`                                                                                                     | The rest of the message says whether Auth0 rejected the credentials or refused a call. Store the current client secret as a new version of the secret, or authorize the application for every scope in [#step-4-add-a-tenant](#step-4-add-a-tenant "mention"). You don't need to reinstall. |
| `The Auth0 connector for <tenant> isn't installed, so P0 can't grant access in <tenant>. Ask your P0 admin to install it. Access that P0 already granted in <tenant> may need to be removed by hand.` | Install the connector again as in steps 1 to 3, with the ID and hosting it had. Then click **Retry revoke** on any failed revoke, or remove that access in the Auth0 Dashboard.                                                                                                             |
| `Auth0 is temporarily unavailable. Try again in a few minutes.`                                                                                                                                       | Try again in a few minutes.                                                                                                                                                                                                                                                                 |

## Change the install later

* **Rotate the client secret.** Rotate it in Auth0, read it into your shell as in [#step-5-store-the-client-secret](#step-5-store-the-client-secret "mention"), and store it as a new version of the same secret:

  ```bash
  printf %s "$AUTH0_CLIENT_SECRET" | aws secretsmanager put-secret-value \
    --secret-id <secret-name> \
    --secret-string file:///dev/stdin \
    --region <region>
  ```

  Or, in Google Secret Manager:

  ```bash
  printf %s "$AUTH0_CLIENT_SECRET" | gcloud secrets versions add <secret-name> \
    --project <project-id> \
    --data-file=-
  ```

  Then run `unset AUTH0_CLIENT_SECRET`. The connector uses the new version on its next call, so nothing changes in P0 or your Terraform.
* **Change the allowed domains.** Change `domain_allow_pattern` in the connector's Terraform, and apply it again.
* **Copy the Terraform again.** Open a connector or a tenant you've set up, and expand **Show the connector's Terraform**, **Show the Terraform that lets the connector read the client secret**, or **Show the Terraform for the secret's account**.
* **Move a connector, or change a tenant's connector, application or secret.** Remove it, then add it again with the new values. Do this only when no one holds access through P0 in the tenants involved, because P0 can't take access back while a tenant or its connector isn't installed. Check for active grants on the **Activity** tab of [Access Management](https://docs.p0.dev/access-management/access-management.md).
* **Remove a connector.** Remove one only when no tenant uses it. Otherwise P0 can't grant or revoke access in those tenants until you add the connector again with the same ID and hosting, and you may have to remove access by hand.

## Limitations

* **P0 doesn't create Auth0 users.** A requestor needs an Auth0 user with their P0 email.
* **Custom domains can't be used.** You add a tenant by its canonical `auth0.com` domain, even if people sign in on a custom domain.
* **P0 assigns permissions directly.** A permission a user also holds through a role stays when their access ends. Only a direct assignment counts as already holding a permission.
* **Organization roles are tenant roles.** P0 doesn't support Auth0's organization-scoped roles.
* **On AWS, one connector serves a few dozen tenants.** Past that, add another connector.
