The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust"; |
| 2 | import { Unowned } from "alchemy/AdoptPolicy"; |
| 3 | import { isResolved } from "alchemy/Diff"; |
| 4 | import { createPhysicalName } from "alchemy/PhysicalName"; |
| 5 | import * as Provider from "alchemy/Provider"; |
| 6 | import { Resource } from "alchemy/Resource"; |
| 7 | import { unwrapRedacted } from "alchemy/Util/data"; |
| 8 | import * as Effect from "effect/Effect"; |
| 9 | import * as Predicate from "effect/Predicate"; |
| 10 | import type * as Redacted from "effect/Redacted"; |
| 11 | import * as Stream from "effect/Stream"; |
| 12 | import { CloudflareEnvironment } from "../CloudflareEnvironment.ts"; |
| 13 | import type { Providers } from "../Providers.ts"; |
| 14 | import { listAllZones } from "../Zone/lookup.ts"; |
| 15 | import { |
| 16 | findByName, |
| 17 | findByType, |
| 18 | getIdp, |
| 19 | isSingletonType, |
| 20 | type ObservedIdp, |
| 21 | toAttributes, |
| 22 | } from "./IdentityProviderLookup.ts"; |
| 23 | |
| 24 | const TypeId = "Cloudflare.Access.IdentityProvider" as const; |
| 25 | type TypeId = typeof TypeId; |
| 26 | |
| 27 | /** |
| 28 | * The type of identity provider. Determines which `config` fields are |
| 29 | * meaningful — see Cloudflare's IdP integration docs for the per-type |
| 30 | * shapes. Immutable — changing the type triggers a replacement. |
| 31 | */ |
| 32 | export type IdentityProviderType = |
| 33 | | "onetimepin" |
| 34 | | "azureAD" |
| 35 | | "saml" |
| 36 | | "centrify" |
| 37 | | "facebook" |
| 38 | | "github" |
| 39 | | "google-apps" |
| 40 | | "google" |
| 41 | | "linkedin" |
| 42 | | "oidc" |
| 43 | | "okta" |
| 44 | | "onelogin" |
| 45 | | "pingone" |
| 46 | | "yandex" |
| 47 | | "cloudflare" |
| 48 | | (string & {}); |
| 49 | |
| 50 | /** |
| 51 | * The full, untyped per-type configuration surface of an identity |
| 52 | * provider. Re-exports distilled's request shape so the complete |
| 53 | * Cloudflare config surface (OAuth client credentials, OIDC endpoints, |
| 54 | * SAML certs and SSO targets, SCIM claims, …) is available without |
| 55 | * re-declaring the structure. Prefer the per-type configs |
| 56 | * ({@link OidcConfig}, {@link SamlConfig}, {@link AzureADConfig}, …) — |
| 57 | * they are enforced by the discriminated {@link IdentityProviderProps}. |
| 58 | */ |
| 59 | export type IdentityProviderConfig = zeroTrust.CreateIdentityProviderForAccountRequest["config"]; |
| 60 | |
| 61 | /** |
| 62 | * OAuth client credentials shared by every OAuth/OIDC-based IdP type. |
| 63 | */ |
| 64 | export interface OAuthClientConfig { |
| 65 | /** |
| 66 | * OAuth client ID issued by the identity provider. |
| 67 | */ |
| 68 | clientId: string; |
| 69 | /** |
| 70 | * OAuth client secret. Pass a `Redacted` value (e.g. |
| 71 | * `yield* Config.Redacted("GITHUB_CLIENT_SECRET")`) to keep it out of |
| 72 | * plan output and state. Cloudflare masks this field on read, so it |
| 73 | * diffs against the previously declared props rather than observed |
| 74 | * cloud state. |
| 75 | */ |
| 76 | clientSecret: string | Redacted.Redacted<string>; |
| 77 | } |
| 78 | |
| 79 | /** |
| 80 | * Configuration for the built-in one-time PIN login method. Takes no |
| 81 | * parameters — users receive a PIN at their email address. |
| 82 | */ |
| 83 | export interface OneTimePinConfig {} |
| 84 | |
| 85 | /** |
| 86 | * Configuration for the simple social OAuth providers: `github`, |
| 87 | * `facebook`, `linkedin`, and `yandex`. |
| 88 | */ |
| 89 | export interface SocialOAuthConfig extends OAuthClientConfig {} |
| 90 | |
| 91 | /** |
| 92 | * Configuration for the `google` identity provider. |
| 93 | */ |
| 94 | export interface GoogleConfig extends OAuthClientConfig { |
| 95 | /** |
| 96 | * Custom OIDC claims to capture from the token and make available in |
| 97 | * Access policies. |
| 98 | */ |
| 99 | claims?: string[]; |
| 100 | /** |
| 101 | * The claim to use as the user's email address. |
| 102 | */ |
| 103 | emailClaimName?: string; |
| 104 | /** |
| 105 | * Enable Proof Key for Code Exchange (PKCE) on the OAuth flow. |
| 106 | */ |
| 107 | pkceEnabled?: boolean; |
| 108 | } |
| 109 | |
| 110 | /** |
| 111 | * Configuration for the `google-apps` (Google Workspace) identity |
| 112 | * provider. |
| 113 | */ |
| 114 | export interface GoogleAppsConfig extends GoogleConfig { |
| 115 | /** |
| 116 | * The Google Workspace domain users authenticate from, |
| 117 | * e.g. `mycompany.com`. |
| 118 | */ |
| 119 | appsDomain: string; |
| 120 | } |
| 121 | |
| 122 | /** |
| 123 | * Configuration for the `azureAD` (Microsoft Entra ID) identity |
| 124 | * provider. |
| 125 | */ |
| 126 | export interface AzureADConfig extends OAuthClientConfig { |
| 127 | /** |
| 128 | * The Entra ID directory (tenant) ID. |
| 129 | */ |
| 130 | directoryId: string; |
| 131 | /** |
| 132 | * Import Entra ID group membership into Access policies. |
| 133 | */ |
| 134 | supportGroups?: boolean; |
| 135 | /** |
| 136 | * Send the Cloudflare-managed Conditional Access policy context to |
| 137 | * Entra ID. |
| 138 | */ |
| 139 | conditionalAccessEnabled?: boolean; |
| 140 | /** |
| 141 | * OIDC prompt behavior on the Microsoft login page. |
| 142 | */ |
| 143 | prompt?: "login" | "select_account" | "none"; |
| 144 | /** |
| 145 | * Custom OIDC claims to capture from the token and make available in |
| 146 | * Access policies. |
| 147 | */ |
| 148 | claims?: string[]; |
| 149 | /** |
| 150 | * The claim to use as the user's email address. |
| 151 | */ |
| 152 | emailClaimName?: string; |
| 153 | /** |
| 154 | * Enable Proof Key for Code Exchange (PKCE) on the OAuth flow. |
| 155 | */ |
| 156 | pkceEnabled?: boolean; |
| 157 | } |
| 158 | |
| 159 | /** |
| 160 | * Configuration for the `centrify` identity provider. |
| 161 | */ |
| 162 | export interface CentrifyConfig extends OAuthClientConfig { |
| 163 | /** |
| 164 | * The Centrify account URL, e.g. `https://abc123.my.centrify.com`. |
| 165 | */ |
| 166 | centrifyAccount: string; |
| 167 | /** |
| 168 | * The Centrify application ID, e.g. `exampleapp`. |
| 169 | */ |
| 170 | centrifyAppId: string; |
| 171 | /** |
| 172 | * Custom OIDC claims to capture from the token and make available in |
| 173 | * Access policies. |
| 174 | */ |
| 175 | claims?: string[]; |
| 176 | /** |
| 177 | * The claim to use as the user's email address. |
| 178 | */ |
| 179 | emailClaimName?: string; |
| 180 | } |
| 181 | |
| 182 | /** |
| 183 | * Configuration for the `okta` identity provider. |
| 184 | */ |
| 185 | export interface OktaConfig extends OAuthClientConfig { |
| 186 | /** |
| 187 | * The Okta account URL, e.g. `https://dev-abc123.okta.com`. |
| 188 | */ |
| 189 | oktaAccount: string; |
| 190 | /** |
| 191 | * The Okta authorization server ID to use, when not the default. |
| 192 | */ |
| 193 | authorizationServerId?: string; |
| 194 | /** |
| 195 | * Custom OIDC claims to capture from the token and make available in |
| 196 | * Access policies. |
| 197 | */ |
| 198 | claims?: string[]; |
| 199 | /** |
| 200 | * The claim to use as the user's email address. |
| 201 | */ |
| 202 | emailClaimName?: string; |
| 203 | /** |
| 204 | * Enable Proof Key for Code Exchange (PKCE) on the OAuth flow. |
| 205 | */ |
| 206 | pkceEnabled?: boolean; |
| 207 | } |
| 208 | |
| 209 | /** |
| 210 | * Configuration for the `onelogin` identity provider. |
| 211 | */ |
| 212 | export interface OneloginConfig extends OAuthClientConfig { |
| 213 | /** |
| 214 | * The OneLogin account URL, e.g. `https://mycompany.onelogin.com`. |
| 215 | */ |
| 216 | oneloginAccount: string; |
| 217 | /** |
| 218 | * Custom OIDC claims to capture from the token and make available in |
| 219 | * Access policies. |
| 220 | */ |
| 221 | claims?: string[]; |
| 222 | /** |
| 223 | * The claim to use as the user's email address. |
| 224 | */ |
| 225 | emailClaimName?: string; |
| 226 | /** |
| 227 | * Enable Proof Key for Code Exchange (PKCE) on the OAuth flow. |
| 228 | */ |
| 229 | pkceEnabled?: boolean; |
| 230 | } |
| 231 | |
| 232 | /** |
| 233 | * Configuration for the `pingone` (PingOne) identity provider. |
| 234 | */ |
| 235 | export interface PingoneConfig extends OAuthClientConfig { |
| 236 | /** |
| 237 | * The PingOne environment identifier. |
| 238 | */ |
| 239 | pingEnvId: string; |
| 240 | /** |
| 241 | * Custom OIDC claims to capture from the token and make available in |
| 242 | * Access policies. |
| 243 | */ |
| 244 | claims?: string[]; |
| 245 | /** |
| 246 | * The claim to use as the user's email address. |
| 247 | */ |
| 248 | emailClaimName?: string; |
| 249 | /** |
| 250 | * Enable Proof Key for Code Exchange (PKCE) on the OAuth flow. |
| 251 | */ |
| 252 | pkceEnabled?: boolean; |
| 253 | } |
| 254 | |
| 255 | /** |
| 256 | * Configuration for a generic `oidc` identity provider. |
| 257 | */ |
| 258 | export interface OidcConfig extends OAuthClientConfig { |
| 259 | /** |
| 260 | * The authorization endpoint of the IdP, |
| 261 | * e.g. `https://idp.example.com/authorize`. |
| 262 | */ |
| 263 | authUrl: string; |
| 264 | /** |
| 265 | * The token endpoint of the IdP, e.g. `https://idp.example.com/token`. |
| 266 | */ |
| 267 | tokenUrl: string; |
| 268 | /** |
| 269 | * The JWKS endpoint of the IdP, e.g. `https://idp.example.com/keys`. |
| 270 | */ |
| 271 | certsUrl: string; |
| 272 | /** |
| 273 | * OAuth scopes to request, e.g. `["openid", "email", "profile"]`. |
| 274 | */ |
| 275 | scopes?: string[]; |
| 276 | /** |
| 277 | * Custom OIDC claims to capture from the token and make available in |
| 278 | * Access policies. |
| 279 | */ |
| 280 | claims?: string[]; |
| 281 | /** |
| 282 | * The claim to use as the user's email address. |
| 283 | */ |
| 284 | emailClaimName?: string; |
| 285 | /** |
| 286 | * Enable Proof Key for Code Exchange (PKCE) on the OAuth flow. |
| 287 | */ |
| 288 | pkceEnabled?: boolean; |
| 289 | } |
| 290 | |
| 291 | /** |
| 292 | * A SAML attribute translated into a request header on the origin. |
| 293 | */ |
| 294 | export interface SamlHeaderAttribute { |
| 295 | /** |
| 296 | * The SAML attribute to read. |
| 297 | */ |
| 298 | attributeName?: string; |
| 299 | /** |
| 300 | * The request header to write the attribute value into. |
| 301 | */ |
| 302 | headerName?: string; |
| 303 | } |
| 304 | |
| 305 | /** |
| 306 | * Configuration for a generic `saml` identity provider. |
| 307 | */ |
| 308 | export interface SamlConfig { |
| 309 | /** |
| 310 | * The IdP entity ID / issuer URL. |
| 311 | */ |
| 312 | issuerUrl: string; |
| 313 | /** |
| 314 | * The IdP's SSO target URL Access redirects sign-ins to. |
| 315 | */ |
| 316 | ssoTargetUrl: string; |
| 317 | /** |
| 318 | * The IdP's public signing certificate(s), PEM bodies without the |
| 319 | * BEGIN/END markers. |
| 320 | */ |
| 321 | idpPublicCerts: string[]; |
| 322 | /** |
| 323 | * The SAML attribute carrying the user's email address. |
| 324 | */ |
| 325 | emailAttributeName?: string; |
| 326 | /** |
| 327 | * SAML attributes to capture and make available in Access policies. |
| 328 | */ |
| 329 | attributes?: string[]; |
| 330 | /** |
| 331 | * SAML attributes to translate into request headers on the origin. |
| 332 | */ |
| 333 | headerAttributes?: SamlHeaderAttribute[]; |
| 334 | /** |
| 335 | * Sign the SAML authentication request. |
| 336 | */ |
| 337 | signRequest?: boolean; |
| 338 | } |
| 339 | |
| 340 | /** |
| 341 | * SCIM provisioning configuration for an identity provider. |
| 342 | */ |
| 343 | export interface IdentityProviderScimConfig { |
| 344 | /** |
| 345 | * Enable SCIM provisioning from the IdP into Cloudflare Access. |
| 346 | * @default false |
| 347 | */ |
| 348 | enabled?: boolean; |
| 349 | /** |
| 350 | * How user identity updates from SCIM affect existing Access sessions. |
| 351 | */ |
| 352 | identityUpdateBehavior?: "automatic" | "reauth" | "no_action"; |
| 353 | /** |
| 354 | * Deprovision a user's seat when SCIM deprovisions the user. |
| 355 | * @default false |
| 356 | */ |
| 357 | seatDeprovision?: boolean; |
| 358 | /** |
| 359 | * Revoke a user's session when SCIM deprovisions the user. |
| 360 | * @default false |
| 361 | */ |
| 362 | userDeprovision?: boolean; |
| 363 | } |
| 364 | |
| 365 | /** |
| 366 | * Props shared by every identity provider type. |
| 367 | */ |
| 368 | export interface IdentityProviderBaseProps { |
| 369 | /** |
| 370 | * Display name shown to users on the Access login page. Used as a |
| 371 | * stable identifier so the provider can locate the IdP by name during |
| 372 | * adoption / state recovery. If omitted, a unique name is generated |
| 373 | * from the app, stage, and logical ID. |
| 374 | * |
| 375 | * @default ${app}-${stage}-${id} |
| 376 | */ |
| 377 | name?: string; |
| 378 | /** |
| 379 | * Zone to scope the identity provider to (legacy zone-level Access). |
| 380 | * When omitted, the IdP is created at the account level — the modern |
| 381 | * Zero Trust organization scope. |
| 382 | * |
| 383 | * Stable — moving an IdP between scopes triggers a replacement. |
| 384 | */ |
| 385 | zoneId?: string; |
| 386 | /** |
| 387 | * SCIM provisioning configuration. Mutable. |
| 388 | */ |
| 389 | scimConfig?: IdentityProviderScimConfig; |
| 390 | } |
| 391 | |
| 392 | /** |
| 393 | * Input properties of an identity provider — a discriminated union on |
| 394 | * `type`, so each provider type only accepts (and requires) its own |
| 395 | * config fields. Secret fields (e.g. `clientSecret`) are masked by |
| 396 | * Cloudflare on read, so they diff against the previously declared props |
| 397 | * rather than observed cloud state. |
| 398 | */ |
| 399 | export type IdentityProviderProps = IdentityProviderBaseProps & |
| 400 | ( |
| 401 | | { |
| 402 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 403 | type: "onetimepin"; |
| 404 | /** One-time PIN takes no configuration. */ |
| 405 | config?: OneTimePinConfig; |
| 406 | } |
| 407 | | { |
| 408 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 409 | type: "github" | "facebook" | "linkedin" | "yandex"; |
| 410 | /** OAuth client credentials for the social provider. */ |
| 411 | config: SocialOAuthConfig; |
| 412 | } |
| 413 | | { |
| 414 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 415 | type: "google"; |
| 416 | /** Google OAuth configuration. */ |
| 417 | config: GoogleConfig; |
| 418 | } |
| 419 | | { |
| 420 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 421 | type: "google-apps"; |
| 422 | /** Google Workspace configuration. */ |
| 423 | config: GoogleAppsConfig; |
| 424 | } |
| 425 | | { |
| 426 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 427 | type: "azureAD"; |
| 428 | /** Microsoft Entra ID configuration. */ |
| 429 | config: AzureADConfig; |
| 430 | } |
| 431 | | { |
| 432 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 433 | type: "centrify"; |
| 434 | /** Centrify configuration. */ |
| 435 | config: CentrifyConfig; |
| 436 | } |
| 437 | | { |
| 438 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 439 | type: "okta"; |
| 440 | /** Okta configuration. */ |
| 441 | config: OktaConfig; |
| 442 | } |
| 443 | | { |
| 444 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 445 | type: "onelogin"; |
| 446 | /** OneLogin configuration. */ |
| 447 | config: OneloginConfig; |
| 448 | } |
| 449 | | { |
| 450 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 451 | type: "pingone"; |
| 452 | /** PingOne configuration. */ |
| 453 | config: PingoneConfig; |
| 454 | } |
| 455 | | { |
| 456 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 457 | type: "oidc"; |
| 458 | /** Generic OIDC configuration. */ |
| 459 | config: OidcConfig; |
| 460 | } |
| 461 | | { |
| 462 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 463 | type: "saml"; |
| 464 | /** Generic SAML configuration. */ |
| 465 | config: SamlConfig; |
| 466 | /** |
| 467 | * The UID of the SAML encryption certificate set assigned to |
| 468 | * this identity provider. Only meaningful for SAML IdPs with |
| 469 | * response encryption configured. |
| 470 | */ |
| 471 | samlCertificateSetId?: string; |
| 472 | } |
| 473 | | { |
| 474 | /** The identity provider type. Immutable — changing it triggers a replacement. */ |
| 475 | type: "cloudflare"; |
| 476 | /** The Cloudflare-managed (WARP) IdP takes no user configuration. */ |
| 477 | config?: IdentityProviderConfig; |
| 478 | } |
| 479 | ); |
| 480 | |
| 481 | export interface IdentityProviderAttributes { |
| 482 | /** UUID of the identity provider, assigned by Cloudflare. */ |
| 483 | identityProviderId: string; |
| 484 | /** Cloudflare account that owns the identity provider. */ |
| 485 | accountId: string; |
| 486 | /** Zone the IdP is scoped to, or `undefined` for account-scoped IdPs. */ |
| 487 | zoneId: string | undefined; |
| 488 | /** Display name of the identity provider. */ |
| 489 | name: string; |
| 490 | /** The identity provider type. */ |
| 491 | type: IdentityProviderType; |
| 492 | /** Server-generated SCIM base URL (when SCIM is enabled). */ |
| 493 | scimBaseUrl: string | undefined; |
| 494 | /** |
| 495 | * SCIM provisioning secret. Returned once when SCIM is first enabled |
| 496 | * and carried forward in state afterwards (the API masks it on read). |
| 497 | */ |
| 498 | scimSecret: Redacted.Redacted<string> | undefined; |
| 499 | /** Whether SCIM provisioning is enabled. */ |
| 500 | scimEnabled: boolean; |
| 501 | } |
| 502 | |
| 503 | export type IdentityProvider = Resource< |
| 504 | TypeId, |
| 505 | IdentityProviderProps, |
| 506 | IdentityProviderAttributes, |
| 507 | never, |
| 508 | Providers |
| 509 | >; |
| 510 | |
| 511 | /** |
| 512 | * A Cloudflare Zero Trust Access identity provider — the login method |
| 513 | * (one-time PIN, generic OIDC/SAML, or a named provider like GitHub, |
| 514 | * Google, Okta, or Azure AD) users authenticate with before Access |
| 515 | * policies evaluate. |
| 516 | * |
| 517 | * Props are a discriminated union on `type`: each provider type only |
| 518 | * accepts (and requires) its own config fields, so a missing |
| 519 | * `directoryId` on an `azureAD` IdP or a GitHub config on an `oidc` IdP |
| 520 | * is a compile-time error. The `type` is immutable (config shapes are |
| 521 | * disjoint per type — changing it replaces the IdP); name, config, and |
| 522 | * SCIM settings converge in place. Cloudflare masks secret config fields |
| 523 | * (`clientSecret`, API tokens) on read, so those fields diff against |
| 524 | * your previously declared props instead of observed cloud state. |
| 525 | * |
| 526 | * By default the IdP is created at the account level (the modern Zero |
| 527 | * Trust organization scope); pass `zoneId` to scope it to a single zone |
| 528 | * (legacy zone-level Access). Moving between scopes replaces the IdP. |
| 529 | * ### Creating an Identity Provider |
| 530 | * **Example:** One-time PIN (no external dependencies) |
| 531 | * ```typescript |
| 532 | * const otp = yield* Cloudflare.Access.IdentityProvider("Pin", { |
| 533 | * type: "onetimepin", |
| 534 | * }); |
| 535 | * ``` |
| 536 | * |
| 537 | * **Example:** Generic OIDC provider |
| 538 | * ```typescript |
| 539 | * const oidc = yield* Cloudflare.Access.IdentityProvider("Sso", { |
| 540 | * type: "oidc", |
| 541 | * config: { |
| 542 | * clientId: "my-client-id", |
| 543 | * clientSecret: "my-client-secret", |
| 544 | * authUrl: "https://idp.example.com/authorize", |
| 545 | * tokenUrl: "https://idp.example.com/token", |
| 546 | * certsUrl: "https://idp.example.com/keys", |
| 547 | * scopes: ["openid", "email", "profile"], |
| 548 | * }, |
| 549 | * }); |
| 550 | * ``` |
| 551 | * |
| 552 | * **Example:** GitHub with the client secret from config |
| 553 | * ```typescript |
| 554 | * const github = yield* Cloudflare.Access.IdentityProvider("GitHub", { |
| 555 | * type: "github", |
| 556 | * config: { |
| 557 | * clientId: "my-client-id", |
| 558 | * clientSecret: yield* Config.Redacted("GITHUB_CLIENT_SECRET"), |
| 559 | * }, |
| 560 | * }); |
| 561 | * ``` |
| 562 | * |
| 563 | * **Example:** Microsoft Entra ID (Azure AD) |
| 564 | * ```typescript |
| 565 | * const entra = yield* Cloudflare.Access.IdentityProvider("Entra", { |
| 566 | * type: "azureAD", |
| 567 | * config: { |
| 568 | * clientId: "my-client-id", |
| 569 | * clientSecret: "my-client-secret", |
| 570 | * directoryId: "my-tenant-id", |
| 571 | * supportGroups: true, |
| 572 | * }, |
| 573 | * }); |
| 574 | * ``` |
| 575 | * |
| 576 | * **Example:** Zone-scoped IdP (legacy zone-level Access) |
| 577 | * ```typescript |
| 578 | * const zoneIdp = yield* Cloudflare.Access.IdentityProvider("ZoneSso", { |
| 579 | * zoneId: zone.zoneId, |
| 580 | * type: "github", |
| 581 | * config: { |
| 582 | * clientId: "my-client-id", |
| 583 | * clientSecret: "my-client-secret", |
| 584 | * }, |
| 585 | * }); |
| 586 | * ``` |
| 587 | * |
| 588 | * ### Restricting an Application to an IdP |
| 589 | * **Example:** Allow only this IdP on an Access application |
| 590 | * ```typescript |
| 591 | * yield* Cloudflare.Access.Application("Admin", { |
| 592 | * domain: "admin.example.com", |
| 593 | * allowedIdps: [oidc.identityProviderId], |
| 594 | * }); |
| 595 | * ``` |
| 596 | * |
| 597 | * @see https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/ |
| 598 | * |
| 599 | * @resource |
| 600 | * @product Access |
| 601 | * @category Cloudflare One (Zero Trust) |
| 602 | */ |
| 603 | export const IdentityProvider = Resource<IdentityProvider>(TypeId); |
| 604 | |
| 605 | /** |
| 606 | * Returns true if the given value is an IdentityProvider resource. |
| 607 | */ |
| 608 | export const isIdentityProvider = (value: unknown): value is IdentityProvider => |
| 609 | Predicate.hasProperty(value, "Type") && value.Type === TypeId; |
| 610 | |
| 611 | export const IdentityProviderProvider = () => |
| 612 | Provider.succeed(IdentityProvider, { |
| 613 | stables: ["identityProviderId", "accountId", "zoneId", "type"], |
| 614 | |
| 615 | diff: Effect.fn(function* ({ olds, news, output }) { |
| 616 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 617 | if (!isResolved(news)) return undefined; |
| 618 | if ((output?.accountId ?? accountId) !== accountId) { |
| 619 | return { action: "replace" } as const; |
| 620 | } |
| 621 | // Config shapes are disjoint per type — model a type change as a |
| 622 | // replacement even though the API technically allows the PUT. |
| 623 | const oldType = output?.type ?? olds?.type; |
| 624 | if (oldType !== undefined && oldType !== news.type) { |
| 625 | return { action: "replace" } as const; |
| 626 | } |
| 627 | // Scope change (zone <-> account, or a different zone) replaces. |
| 628 | if (output !== undefined || olds !== undefined) { |
| 629 | const oldZone = output?.zoneId ?? olds?.zoneId; |
| 630 | if ((oldZone === undefined) !== (news.zoneId === undefined)) { |
| 631 | return { action: "replace" } as const; |
| 632 | } |
| 633 | // zoneId is Input<string>; compare only once both are concrete. |
| 634 | if ( |
| 635 | typeof oldZone === "string" && |
| 636 | typeof news.zoneId === "string" && |
| 637 | oldZone !== news.zoneId |
| 638 | ) { |
| 639 | return { action: "replace" } as const; |
| 640 | } |
| 641 | } |
| 642 | return undefined; |
| 643 | }), |
| 644 | |
| 645 | read: Effect.fn(function* ({ id, output, olds }) { |
| 646 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 647 | const acct = output?.accountId ?? accountId; |
| 648 | const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined); |
| 649 | |
| 650 | // Owned path — refresh by the cached id. Carry the SCIM secret |
| 651 | // forward from prior output; the API never returns it on GET. |
| 652 | if (output?.identityProviderId) { |
| 653 | const observed = yield* getIdp(zoneId, acct, output.identityProviderId); |
| 654 | if (observed) { |
| 655 | return toAttributes(observed, zoneId, acct, output.scimSecret); |
| 656 | } |
| 657 | } |
| 658 | |
| 659 | // Cold read — locate by deterministic name. Access IdPs carry no |
| 660 | // ownership markers, so report the match as Unowned to gate adoption. |
| 661 | const name = yield* resolveName(id, olds?.name ?? output?.name); |
| 662 | let match = yield* findByName(zoneId, acct, name); |
| 663 | // The singleton types (`cloudflare`, `onetimepin`) exist at most once |
| 664 | // per scope and their display name is user-irrelevant (the managed |
| 665 | // WARP IdP's is often "") — locate them by type when the name scan |
| 666 | // misses so adoption works regardless of the declared name. |
| 667 | const type = olds?.type ?? output?.type; |
| 668 | if (!match && isSingletonType(type)) { |
| 669 | match = yield* findByType(zoneId, acct, type); |
| 670 | } |
| 671 | if (match) { |
| 672 | return Unowned(toAttributes(match, zoneId, acct, output?.scimSecret)); |
| 673 | } |
| 674 | return undefined; |
| 675 | }), |
| 676 | |
| 677 | list: Effect.fn(function* () { |
| 678 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 679 | |
| 680 | // Account-scoped collection — exhaustively paginate the account's |
| 681 | // identity providers and hydrate each into the `read` Attributes |
| 682 | // shape. The SCIM secret is masked by the API on list, so it is |
| 683 | // carried as undefined (there is no prior state to thread through). |
| 684 | const accountIdps = yield* zeroTrust.listIdentityProvidersForAccount |
| 685 | .pages({ accountId }) |
| 686 | .pipe( |
| 687 | Stream.runCollect, |
| 688 | Effect.map((chunk) => |
| 689 | Array.from(chunk).flatMap((page) => |
| 690 | (page.result ?? []).map((idp) => |
| 691 | toAttributes(idp as unknown as ObservedIdp, undefined, accountId, undefined), |
| 692 | ), |
| 693 | ), |
| 694 | ), |
| 695 | ); |
| 696 | |
| 697 | // Zone-scoped IdPs (legacy zone-level Access) — fan out across the |
| 698 | // account's zones. Zones without zone-level Access reject the |
| 699 | // route; skip them. |
| 700 | const zones = yield* listAllZones(accountId); |
| 701 | const zoneGroups = yield* Effect.forEach( |
| 702 | zones, |
| 703 | (zone) => |
| 704 | zeroTrust.listIdentityProvidersForZone.pages({ zoneId: zone.id }).pipe( |
| 705 | Stream.runCollect, |
| 706 | Effect.map((chunk) => |
| 707 | Array.from(chunk).flatMap((page) => |
| 708 | (page.result ?? []).map((idp) => |
| 709 | toAttributes(idp as unknown as ObservedIdp, zone.id, accountId, undefined), |
| 710 | ), |
| 711 | ), |
| 712 | ), |
| 713 | Effect.catchTag("Forbidden", () => Effect.succeed([])), |
| 714 | ), |
| 715 | { concurrency: 10 }, |
| 716 | ); |
| 717 | |
| 718 | // The zone route can echo account-level IdPs back — keep each IdP |
| 719 | // once, under the scope that owns it. |
| 720 | const seen = new Set(accountIdps.map((idp) => idp.identityProviderId)); |
| 721 | return [ |
| 722 | ...accountIdps, |
| 723 | ...zoneGroups.flat().filter((idp) => !seen.has(idp.identityProviderId)), |
| 724 | ]; |
| 725 | }), |
| 726 | |
| 727 | reconcile: Effect.fn(function* ({ id, news, olds, output }) { |
| 728 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 729 | // A scope change replaces (see diff), so news' scope is the scope. |
| 730 | const zoneId = news.zoneId as string | undefined; |
| 731 | const generatedName = yield* createPhysicalName({ id }); |
| 732 | |
| 733 | // 1. Observe — the cached id is a hint; fall back to a name scan |
| 734 | // (and, for the singleton types, a type scan) so out-of-band |
| 735 | // deletes / lost state converge. |
| 736 | let observed = output?.identityProviderId |
| 737 | ? yield* getIdp(zoneId, accountId, output.identityProviderId) |
| 738 | : undefined; |
| 739 | if (!observed) { |
| 740 | observed = yield* findByName(zoneId, accountId, news.name ?? generatedName); |
| 741 | } |
| 742 | // Singleton types (`cloudflare`, `onetimepin`) exist at most once per |
| 743 | // scope — creating a second one is rejected by the API, so an |
| 744 | // existing one found by type is ours to converge (ownership is gated |
| 745 | // upstream: `read` reports it as Unowned and the engine only lets |
| 746 | // reconcile run once adoption is approved). |
| 747 | if (!observed && isSingletonType(news.type)) { |
| 748 | observed = yield* findByType(zoneId, accountId, news.type); |
| 749 | } |
| 750 | |
| 751 | // Singletons keep their observed display name when none is declared — |
| 752 | // renaming the managed WARP IdP to a generated physical name on |
| 753 | // adoption would be surprising. Everything else defaults to the |
| 754 | // deterministic physical name (the resource's cold-read identity). |
| 755 | const name = |
| 756 | news.name ?? (isSingletonType(news.type) && observed ? observed.name : generatedName); |
| 757 | |
| 758 | // 2. Ensure — create with the full desired body when missing. Names |
| 759 | // are not unique on Cloudflare's side, so there is no |
| 760 | // AlreadyExists race to tolerate for the non-singleton types (a |
| 761 | // singleton conflict is caught by the type scan above). |
| 762 | if (!observed) { |
| 763 | const created = yield* createIdp(zoneId, accountId, { |
| 764 | name, |
| 765 | type: news.type, |
| 766 | config: unwrapRedacted(news.config ?? {}), |
| 767 | scimConfig: news.scimConfig, |
| 768 | samlCertificateSetId: samlCertificateSetIdOf(news), |
| 769 | }); |
| 770 | return toAttributes(created as ObservedIdp, zoneId, accountId, output?.scimSecret); |
| 771 | } |
| 772 | |
| 773 | // 3. Sync — the update API is a PUT of the full desired state. |
| 774 | // Non-secret aspects (name, SCIM enablement) diff against |
| 775 | // observed cloud state; the config diffs against the previously |
| 776 | // declared props because Cloudflare masks secrets on read. |
| 777 | const dirty = |
| 778 | observed.name !== name || |
| 779 | JSON.stringify(unwrapRedacted(news.config ?? {})) !== |
| 780 | JSON.stringify(unwrapRedacted(olds?.config ?? null)) || |
| 781 | samlCertificateSetIdOf(news) !== samlCertificateSetIdOf(olds) || |
| 782 | (news.scimConfig !== undefined && !sameScim(observed.scimConfig, news.scimConfig)); |
| 783 | if (dirty) { |
| 784 | const updated = yield* updateIdp(zoneId, accountId, observed.id ?? "", { |
| 785 | name, |
| 786 | type: news.type, |
| 787 | config: unwrapRedacted(news.config ?? {}), |
| 788 | scimConfig: news.scimConfig, |
| 789 | samlCertificateSetId: samlCertificateSetIdOf(news), |
| 790 | }); |
| 791 | return toAttributes(updated as ObservedIdp, zoneId, accountId, output?.scimSecret); |
| 792 | } |
| 793 | |
| 794 | return toAttributes(observed, zoneId, accountId, output?.scimSecret); |
| 795 | }), |
| 796 | |
| 797 | delete: Effect.fn(function* ({ output }) { |
| 798 | // An IdP referenced by an application's `allowedIdps` can fail |
| 799 | // deletion — applications referencing the id as an Input get correct |
| 800 | // destroy ordering. A missing IdP (AccessIdentityProviderNotFound, |
| 801 | // Cloudflare code 12135) means we're done. |
| 802 | yield* deleteIdp(output.zoneId, output.accountId, output.identityProviderId).pipe( |
| 803 | Effect.catchTag("AccessIdentityProviderNotFound", () => Effect.void), |
| 804 | ); |
| 805 | }), |
| 806 | }); |
| 807 | |
| 808 | /** |
| 809 | * The request body shared by the scoped create/update helpers. |
| 810 | */ |
| 811 | interface IdpBody { |
| 812 | readonly name: string; |
| 813 | readonly type: IdentityProviderType; |
| 814 | readonly config: IdentityProviderConfig; |
| 815 | readonly scimConfig: IdentityProviderScimConfig | undefined; |
| 816 | readonly samlCertificateSetId: string | undefined; |
| 817 | } |
| 818 | |
| 819 | /** |
| 820 | * The SAML encryption certificate set, when the props are the `saml` |
| 821 | * variant. Narrowing helper — `samlCertificateSetId` only exists on the |
| 822 | * SAML member of the props union. |
| 823 | */ |
| 824 | const samlCertificateSetIdOf = (props: IdentityProviderProps | undefined): string | undefined => |
| 825 | props?.type === "saml" ? props.samlCertificateSetId : undefined; |
| 826 | |
| 827 | const createIdp = (zoneId: string | undefined, accountId: string, body: IdpBody) => |
| 828 | zoneId !== undefined |
| 829 | ? zeroTrust.createIdentityProviderForZone({ zoneId, ...body }) |
| 830 | : zeroTrust.createIdentityProviderForAccount({ accountId, ...body }); |
| 831 | |
| 832 | const updateIdp = ( |
| 833 | zoneId: string | undefined, |
| 834 | accountId: string, |
| 835 | identityProviderId: string, |
| 836 | body: IdpBody, |
| 837 | ) => |
| 838 | zoneId !== undefined |
| 839 | ? zeroTrust.updateIdentityProviderForZone({ |
| 840 | zoneId, |
| 841 | identityProviderId, |
| 842 | ...body, |
| 843 | }) |
| 844 | : zeroTrust.updateIdentityProviderForAccount({ |
| 845 | accountId, |
| 846 | identityProviderId, |
| 847 | ...body, |
| 848 | }); |
| 849 | |
| 850 | const deleteIdp = (zoneId: string | undefined, accountId: string, identityProviderId: string) => |
| 851 | zoneId !== undefined |
| 852 | ? zeroTrust.deleteIdentityProviderForZone({ zoneId, identityProviderId }) |
| 853 | : zeroTrust.deleteIdentityProviderForAccount({ |
| 854 | accountId, |
| 855 | identityProviderId, |
| 856 | }); |
| 857 | |
| 858 | const resolveName = (id: string, name: string | undefined) => |
| 859 | Effect.gen(function* () { |
| 860 | // `""` is a legitimate declared name (the managed `cloudflare` IdP's |
| 861 | // display name is empty) — only generate when no name was declared. |
| 862 | if (name !== undefined) return name; |
| 863 | return yield* createPhysicalName({ id }); |
| 864 | }); |
| 865 | |
| 866 | const sameScim = ( |
| 867 | observed: ObservedIdp["scimConfig"], |
| 868 | desired: IdentityProviderScimConfig, |
| 869 | ): boolean => { |
| 870 | const o = observed ?? {}; |
| 871 | const sameBool = (a: boolean | null | undefined, b: boolean | undefined) => |
| 872 | b === undefined || (a ?? false) === b; |
| 873 | return ( |
| 874 | sameBool(o.enabled, desired.enabled) && |
| 875 | sameBool(o.seatDeprovision, desired.seatDeprovision) && |
| 876 | sameBool(o.userDeprovision, desired.userDeprovision) && |
| 877 | (desired.identityUpdateBehavior === undefined || |
| 878 | (o.identityUpdateBehavior ?? "no_action") === desired.identityUpdateBehavior) |
| 879 | ); |
| 880 | }; |