Auth providers

This guide explains how to manage auth providers attached to Frontdoor. Use these steps to list, create, update, and delete providers. Data you send must conform to the JSON Schema of the chosen provider type.

Why this matters

• An auth provider defines how inbound requests are authenticated (for example, OIDC JWT validation, Google OAuth, etc).
• Each provider has a type that determines its configuration schema. Retrieve schemas via the auth provider types guide before creating providers.
• Providers can often be enabled/disabled; updates should be designed to avoid authentication outages.
• When an auth provider is updated, all custom frontend that has the provider configured will be updated.

Assumptions

• The examples assume you have a valid bearer token. If you need help obtaining a token, see Authentication for NetFoundry REST APIs.
• Base URL for all API calls is https://gateway.production.netfoundry.io/frontdoor.
• Expected headers for all API calls:
  • Authorization: Bearer YOUR_ACCESS_TOKEN
  • Accept: application/hal+json or application/json

Tips

• Keep provider names unique and descriptive (e.g., "oidc-okta-prod").
• Start by creating in a staging Frontdoor, verify behavior, then promote to production.
• Use PATCH for small, targeted changes; use PUT when replacing the full definition.

Operations

List auth providers

Request example:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/auth-providers?page=0&size=20&sort=name,asc"

Response example:

{
  "content": [
    { "id": "0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c", "name": "oidc-okta", "type": "OIDC", "enabled": true },
    { "id": "2ab4b3e2-1a2b-4c5d-8e9f-010203040506", "name": "api-keys", "type": "API_KEY", "enabled": true }
  ],
  "pageable": {"pageNumber": 0, "pageSize": 20},
  "totalElements": 2,
  "totalPages": 1
}

Get an auth provider by ID

Request example:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/auth-providers/0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c

Response example:

{
  "id": "0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c",
  "name": "oidc-okta",
  "type": "OIDC",
  "enabled": true,
  "data": {
    "issuer": "https://your-org.okta.com",
    "client_id": "abc123",
    "client_secret": "secure-client-secret",
    "scopes": ["openid", "email", "profile"],
    "supports_pkce": true
  }
}

Create an auth provider

note

Data must validate against the selected type schema.

Request example:

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "oidc-okta",
        "type": "OIDC",
        "data": {
          "issuer": "https://your-org.okta.com",
          "client_id": "abc123",
          "client_secret": "secure-client-secret",
          "scopes": ["openid", "email", "profile"],
          "supports_pkce": true
        }
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/auth-providers

Successful response example:

{
  "id": "0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c",
  "name": "oidc-okta",
  "type": "OIDC",
  "enabled": true,
  "data": {
    "issuer": "https://your-org.okta.com",
    "client_id": "abc123",
    "client_secret": "secure-client-secret",
    "scopes": ["openid", "email", "profile"],
    "supports_pkce": true
  }
}

Partial update of an auth provider

Request example:

curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "oidc-okta-renamed"
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/auth-providers/0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c

Response example:

{
  "id": "0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c",
  "name": "oidc-okta-renamed",
  "type": "OIDC",
  "enabled": true,
  "data": {
      "client_id": "abc123",
      "client_secret": "secure-client-secret",
      "scopes": [
          "openid",
          "email",
          "profile"
      ],
      "issuer": "https://okta.com/o/oauth2/v2/auth",
      "supports_pkce": true
  }
}

Put update an auth provider

Request example:

curl -s -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "oidc-okta",
        "type": "OIDC",
        "data": {
          "client_id": "123abc",
          "client_secret": "other-secure-client-secret",
          "scopes": [
              "openid",
              "email",
              "profile"
          ],
          "issuer": "https://okta.com/o/oauth2/v2/auth",
          "supports_pkce": true
        }
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/auth-providers/0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c

Response example:

{
  "id": "0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c",
  "name": "oidc-okta",
  "type": "OIDC",
  "enabled": true,
  "data": {
      "client_id": "123abc",
      "client_secret": "other-secure-client-secret",
      "scopes": [
          "openid",
          "email",
          "profile"
      ],
      "issuer": "https://okta.com/o/oauth2/v2/auth",
      "supports_pkce": true
  }
}

Delete an auth provider

Request example:

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/auth-providers/0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c

The delete request has an empty response.

Technical notes

Paths

- GET /frontdoor/\{frontdoorId\}/auth-providers[?page=0&size=20&sort=name,asc]
- GET /frontdoor/\{frontdoorId\}/auth-providers/{id}
- POST /frontdoor/\{frontdoorId\}/auth-providers
- PATCH /frontdoor/\{frontdoorId\}/auth-providers/{id}
- PUT /frontdoor/\{frontdoorId\}/auth-providers/{id}
- DELETE /frontdoor/\{frontdoorId\}/auth-providers/{id}

Common errors

400 Bad Request (client error)

{
  "error": "invalid_request",
  "message": "Value for <property> must be of <type>"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

401 Unauthorized (missing/expired token)

{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

403 Forbidden (not_authorized)

{
  "error": "not_found",
  "message": "Frontdoor 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c not found"
}

Possible reasons include:

• Invalid token: The token is not valid.
• The token does not grant access to the requested resource.
• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.