Skip to content

CONTRACT.md

Latest commit

 

History

History
389 lines (312 loc) · 26.6 KB

CONTRACT.md

File metadata and controls

389 lines (312 loc) · 26.6 KB
Raw

External Phone Provider Function: Language-Agnostic Contract

This defines the shared contract for JavaScript, Python and .NET. See production limitations before production use.

Naming. EPP means External Phone Provider. App settings use the EPP_ prefix; the request and delivery models are Envelope, DeliveryContext and DispatchRequest. Documentation names do not change the external JSON fields or microsoft.mfa.otpDeliver.v1 version.

The design is one dispatch engine + registered provider adapters, with one selected provider per deployment. API-specific paths, headers, payloads and status rules belong in adapters, not this guide.

1. HTTP API

Endpoint: POST /api/SendOtp (Functions HTTP trigger, authLevel: anonymous). Easy Auth is the only caller-authentication boundary and runs before the handler; the application has no token validator or function-key gate. This is the interface SAS (StrongAuthenticationService) calls. SAS sends an Entra bearer JWT as part of its protocol; Easy Auth validates it, not the handler. PII (phone number + the rendered message, which contains the passcode) is encrypted inside a JWE; the cleartext envelope carries routing/scheduling only.

Request headers

Header Notes
Authorization consumed by platform authentication, not parsed or echoed by handler
User-Agent caller-supplied identifier; not interpreted or logged
x-ms-correlation-id tracing only; fallback for envelope correlationId, not authentication
x-ms-client-request-id per-attempt tracing id (used as messageId), not authentication

Forwarded headers, including x-ms-client-principal, do not establish trust by themselves and cannot replace the required Easy Auth gate. The handler does not use them to authenticate callers or forward the incoming Authorization header to the provider. Configure Easy Auth as described in section 5.

EPP request body: Envelope (cleartext envelope)

Field Required Notes
type yes exactly microsoft.mfa.otpDeliver.v1; unknown versions are rejected
tenantId no opaque request routing metadata; never selects the trusted issuer, signing keys or provider
correlationId no sign-in tracing metadata
channel yes request delivery channel: 1/sms or 2/voice; not deployment configuration
mode yes request delivery mode: 1/live or 2/evaluation; evaluation does not deliver
ttlSeconds no positive JSON integer, at most 2147483647; null, booleans, strings, fractions and nonpositive values are rejected. Use canonical integer notation (60, not 60.0 or 6e1) across runtimes
encryptedDeliveryContext yes JWE compact serialization (see below)

Canonical integer notation is a caller requirement, not a portable raw-JSON-token check: JavaScript's JSON parser normalizes 60.0 and 6e1 to 60, while Python/.NET reject those representations here. Always send 60 to obtain the same result across runtimes; no custom JSON tokenizer is used.

Unknown type, invalid ttlSeconds, unsupported channel or mode, or missing/empty encryptedDeliveryContext → 400. Arrays, objects and booleans are not channel/mode values.

These are request data, not settings to provision. The TTL check validates the supplied value; it does not verify passcode expiry or implement a delivery deadline. Deployment trust comes only from the required platform authentication and caller allowlist, not the body or tracing headers.

encryptedDeliveryContext (JWE)

Alg: RSA-OAEP-256 (CEK wrap) + A256GCM (content). The JOSE protected header carries kid; this sample uses the single configured RSA private key (EPP_DECRYPTION_KEY_PEM, a Key Vault reference in Azure), not a multi-key lookup. The compact JWE must have exactly five non-empty segments and at most 16,384 characters; alg/enc are pinned (only RSA-OAEP-256 + A256GCM accepted) and the AES-GCM auth tag is verified before any plaintext is used. Decrypted plaintext = DeliveryContext:

The original compact JWE is passed unchanged to the JOSE library. Parsing header fields for the advisory key-ID check must not replace the original protected-header bytes used for authentication.

All three HTTP-handler suites use shared policy cases: the allowed pair succeeds, while RSA-OAEP, A128GCM and A256CBC-HS512 alternatives return 400 decryption_failed without provider I/O. Decryption uses the same policy before live/evaluation branching, so the matrix runs once per language. Tag tampering and original-header-byte tests remain.

Field Required Notes
nonce yes value the endpoint MUST echo to prove decryption
phoneNumber yes caller supplies an E.164 string; full E.164 validation is an implementation gap
message yes fully rendered, localized text containing the passcode; text-message adapters forward it unchanged, while Soprano voice extracts the first six consecutive digits
extension no office-voice contract field; not currently forwarded by the shared dispatch model
locale no voice selection input where supported by the selected adapter
riskContext no contextual request data; no risk-policy evaluation is implemented here
textToVoice no legacy structured speech input; current Soprano adapters ignore it

Decryption failure → 400. Missing nonce / phoneNumber / message → 400.

For Soprano live voice, the adapter finds the first six consecutive digits in message, preserving leading zeros, and splits the rendered text into beforePasswordText, password, and afterPasswordText. It uses a nonblank SAS locale as language, falling back to en-US, and sends fixed gender: 1 and loop: 2. The resulting object is sent as voice.text2voice without a top-level text field. A message without a six-digit sequence fails closed before provider HTTP. No additional environment settings are required. Soprano SMS continues to forward message unchanged, and evaluation continues to skip provider-specific validation and I/O. Soprano uses OAuth client-assertion exchange. The outbound user-assigned managed identity obtains an api://AzureADTokenExchange/.default assertion for the existing multitenant application, which then requests the configured provider scope. Existing platform caller authentication is unchanged.

Soprano provider JWT

The Function obtains one provider token through the shared OAuth credential resolver using the setup-generated EPP_PROVIDER_TENANT_ID, EPP_PROVIDER_SCOPE, EPP_OUTBOUND_CLIENT_ID, and EPP_OUTBOUND_MI_CLIENT_ID. EPP_PROVIDER_AUTH_MODE=oauth matches the Soprano adapter. EPP_PROVIDER_ENDPOINT is the complete selected send URL and is not modified by the adapter. The calling app registration and outbound user-assigned identity must share a home tenant; the calling app must be multitenant and provisioned/authorized in the provider tenant. The app's federated credential trusts the identity's principal ID, home-tenant v2 issuer, and api://AzureADTokenExchange audience. Key Vault identity selection remains independent.

Only the final application token is sent as Authorization: Bearer .... No Soprano API ID/key, managed-identity assertion, or incoming SAS token is forwarded. Missing settings, token-acquisition failure, blank tokens, or tokens with 30 seconds or less remaining lifetime fail before provider HTTP; there is no API-key fallback. Evaluation skips acquisition. A provider rejection is not retried. Tokens are treated as opaque: the Function checks SDK expiry metadata, not custom JWT claims. Soprano remains responsible for signature, issuer, audience, expiry, permissions, and account validation.

Credential instances are reused for the configured tenant/application/identity; each acquisition uses the selected scope. JavaScript and .NET pass one 2.5-second cancellation signal/token through both exchange stages. Python uses 2.5-second connect/read inactivity timeouts, not a total deadline. Configured SDK transport retries are disabled. Managed-identity discovery may involve additional SDK operations; this is not an end-to-end delivery deadline. JavaScript suppresses SDK logs only in the acquisition's asynchronous context. Python filters Azure Identity/Core/MSAL records on configured handlers in that context; configure logging sinks before handling requests. .NET disables credential diagnostics. Keep platform body tracing off and never log credential objects or tokens.

When migrating from the earlier optional-JWT branch, replace EPP_PROVIDER_APPLICATION_ID with EPP_OUTBOUND_CLIENT_ID and EPP_PROVIDER_MI_CLIENT_ID with EPP_OUTBOUND_MI_CLIENT_ID. Remove EPP_PROVIDER_JWT_ENABLED; it no longer controls authentication. Reuse the exact provider scope selected by setup and replace old base URLs with complete send URLs. These source changes do not update deployed settings or establish provider authorization. Earlier QA4 tests of API keys plus JWT do not validate the current Bearer-only configuration or production endpoints.

See Microsoft's managed-identity federation guidance.

Use a SAS locale supported by the selected Soprano endpoint and account. On QA4, an API-key voice request using en returned HTTP 400 with error code 400101; the same request structure using en-US returned HTTP 201 with ENROUTE on September 15, 2026. This confirms acceptance, not handset receipt or audio quality. When SAS omits the locale, the adapters use en-US.

The supplied Soprano Connect Voice PDF describes a different API: POST /voice/voice_orderApiCreate.do with form-encoded fields, subAction=20, and numeric language IDs (1 is default English). Its password fields are beforePassword, passwordText, and afterPassword. This adapter follows the reference integration's JSON /messages/omnimsg contract instead; do not mix the form API's language IDs, field names, or ApiResponse.StatusCode response format with this JSON interface.

JWE provides payload confidentiality and integrity, not SAS caller authentication. Anyone with the public key can encrypt a request. The nonce acknowledges decryption; it is not an authentication credential or replay protection, and a fixed nonce cannot substitute for Easy Auth.

EPP response (JSON)

{ "nonce": "<echo of request nonce>", "correlationId": "<echo>", "providerStatus": "accepted" }

accepted/pending are not failures (provider queued it; acceptance ≠ delivery to the handset). The endpoint returns 200 on acceptance (any 2xx counts as transport acceptance). On 2xx with a matching nonce, SAS treats the send as handled. Nonce mismatch / non-2xx / timeout → SAS falls back to native CAPP delivery. Evaluation mode returns 200 + nonce echo without delivering.

Live handlers await provider acceptance; they do not launch background delivery after replying. Handler failures omit the nonce and accepted status and return a sanitized error with a request ID and, after envelope processing, a correlation ID. Platform rejections happen before the handler and do not use this application response contract.

Validation failures return error: "bad_request" and a fixed reason in every language. Envelope checks run in this order: object shape, version, encrypted-context presence, channel, mode, TTL. Reasons are invalid JSON body, invalid envelope, unsupported envelope type, encryptedDeliveryContext is required, unsupported channel, unsupported mode, invalid ttlSeconds or ttlSeconds expired. A decrypted context missing a required nonblank string returns incomplete delivery context. Reasons never include supplied values or exception text. JWE failures return error: "decryption_failed" without a cryptographic reason or nonce.

Evaluation (generic shutter)

The only shared non-delivery control is the existing incoming mode: 2 or mode: "evaluation", for every provider and language. On Azure, Easy Auth still authenticates the caller before the handler validates the envelope and decrypts the JWE with integrity checks. Provider lookup, provider Key Vault reads and outbound provider HTTP are skipped. No provider name, endpoint or credentials are needed. Platform authentication and resolution of the decryption-key reference may still require network access. Core Tools has no Easy Auth; local evaluation must remain loopback-only, without tunnels.

There is no diagnostic environment flag. A live request is not an evaluation request. Adapter-specific wire fields, where required by an API, remain internal and cannot enable a separate non-delivery mode.

2. Outcome → HTTP status mapping

The provider's parsed status is mapped via the adapter's responseMapping to an outcome, then to an HTTP status. Fail-closed: an unknown/unmapped status is treated as Fail. An unsuccessful provider HTTP response cannot become Continue because its body contains a success-looking status. Explicit Block/StepUp outcomes remain non-success responses.

Outcome HTTP When
Continue 200 recognized success status
Block 403 provider says blocked
StepUp 409 provider signals step-up / fraud escalation
Fail 429 provider returned 429
Fail 401 provider returned 401/403 (auth)
Fail 400 other provider 4xx
Fail 502 other provider error, or missing credential/endpoint
N/A 504 request to the provider timed out
N/A 502 network error to the provider (non-timeout)

3. Provider adapter contract

Each provider is one unit exposing three things:

  • manifest: protocol facts only:
    • id: provider id selected by EPP_PROVIDER_NAME; its complete request URL is EPP_PROVIDER_ENDPOINT
    • auth: either { mode: 'apiKey', keyVaultSecretName, identityKeyVaultSecretName? } or { mode: 'oauth' }; unsupported modes fail closed
    • responseMapping: map of provider status → Continue | Fail | Block | StepUp (+ default)
  • buildRequest({ channel, endpoint, dispatch, credential, env }) → { url, method, headers, body }
  • parseResponse({ httpStatus, ok, json }) → ParsedResponse, containing success, providerHttpStatus, optional providerMessageId, providerStatusName, providerStatusCode and providerStatusDescription (snake_case attributes in Python, PascalCase in .NET).

The adapter reads its API-specific JSON and constructs a normalized ParsedResponse object: JavaScript, Python, .NET. The engine reads named properties/attributes rather than provider JSON or string-key response dictionaries. Optional values default to null/None; a status name takes precedence over a code during outcome mapping, as before. Custom Python adapters must return ParsedResponse, not the former dictionary.

This model is internal: do not serialize it into the endpoint response or log its fields. Public HTTP responses still expose only the existing nonce/correlation/status or sanitized error contract. Provider requests are serialized only when building the outbound HTTP body; incoming provider JSON is parsed once and normalized inside its adapter. No serialization framework or provider-specific class hierarchy is required.

Adapters require registration in the chosen runtime. Consult the selected adapter and its manifest for required credentials and options: the manifest declares authentication and protocol mappings; the implementation reads adapter-specific options from app settings. Individual API contracts remain in the adapters; the onboarding credential naming table lists the exact manifest secret names for provisioning and authorized local tests. Keep that table aligned with the manifests; never include secret values in documentation or the settings sample.

Telesign EPP integration

SMS and Voice use the complete provider-approved URLs selected from the provider profile. The adapter supplies recipient.phone_number, the unchanged message.text, optional message.language, one selected channels[].channel, and correlation_id. Keep the leading + in the E.164 phone number.

Phase 1 supports Basic and Digest; this sample implements Basic only. Per Telesign's authentication instructions, the header is Authorization: Basic <base64(UTF8(customer-id:api-key))>, using the raw Customer ID and API Key strings from Key Vault. Do not decode the API key first, send the API key alone, or substitute a key identifier. The guide's Basic YOUR_API_KEY is abbreviated, not the literal encoding. Provider-token authentication is described as Phase 2 and is not implemented for Telesign here.

The optional account_lifecycle_event and originating_ip fields are reserved for future intelligence capabilities. They are omitted; do not infer an originating address from the Function or synthesize account events to fill them.

Telesign's X-Shutter-Mode: true suppresses delivery at the provider while still calling its endpoint. It is appropriate for an explicitly authorized, direct provider diagnostic, not normal OTP delivery. The production adapter does not add or forward this header. Function evaluation mode remains separate: it validates/decrypts and skips all provider HTTP. A successful provider shutter probe is not evidence that an SMS was delivered or a Voice call was placed. Enabling the API globally also does not prove that a particular Customer ID/API Key pair is authorized for this integration.

4. Configuration (app settings / env)

Set by provisioning. Identical names across all languages.

Key Purpose
EPP_PROVIDER_NAME registered id of the selected provider; <adapter-id> is a placeholder, not a bundled default
EPP_PROVIDER_ENDPOINT complete absolute HTTPS request URL for the selected channel/region, with a hostname, port 1–65535, and no userinfo or fragment; redirects are not followed
EPP_PROVIDER_CHANNEL optional configured sms or voice route; when set, other live-request channels fail closed
EPP_PROVIDER_ENDPOINT_REGION selected global or eu route label; informational at runtime
EPP_PROVIDER_AUTH_MODE must match the selected adapter (apiKey for Telesign, oauth for Soprano)
EPP_PROVIDER_TENANT_ID selected provider tenant; added to the Step 1 app's allowed-tenants preview and used as the OAuth authority for Soprano
EPP_PROVIDER_SCOPE Soprano OAuth scope
EPP_OUTBOUND_CLIENT_ID, EPP_OUTBOUND_MI_CLIENT_ID client application and user-assigned identity used for Soprano client-assertion exchange
EPP_PROVIDER_ACCOUNT_NAME sender/source only when required by the selected adapter
EPP_PROVIDER_TIMEOUT_MS trimmed ASCII decimal milliseconds; default 1500 for missing/invalid/nonpositive values; capped at 2500. Not a whole-invocation deadline
EPP_DECRYPTION_KEY_PEM single RSA private key for JWE decryption, PEM or base64-encoded PEM; use a Key Vault secret reference in Azure, not a plaintext private key in shared settings
EPP_ENCRYPTION_KEY_ID optional expected JWE kid; after successful decryption, a mismatch emits only encryption_key_id_mismatch. Advisory, not a key selector or authentication check
KEY_VAULT_URL Key Vault URI for API-key providers
AZURE_CLIENT_ID set for a user-assigned managed identity

Telesign credentials live in Key Vault, under the names in its manifest, and are fetched via managed identity. Soprano exchanges an outbound managed-identity assertion for a token in the configured provider tenant/scope. Do not put provider secrets in code or app settings.

Caller trust is configured in Easy Auth, not application environment variables: pin the trusted tenant issuer, the endpoint-app audience and the authorized SAS caller application ID. Incoming tenantId is routing metadata and cannot select any of these. There is no application host-detection guard or backup token validation. See platform onboarding.

Default provider and configuration readers

Provision EPP_PROVIDER_NAME with the customer's selected provider, plus the complete selected channel/region EPP_PROVIDER_ENDPOINT and matching authentication settings. A missing or unknown provider fails closed; there is no implicit default or automatic failover. Request-body provider fields are not used.

The shared configuration readers are JavaScript readConfig, Python read_config, and .NET AppConfig.Read. They return named configuration objects for encryption and the selected provider, not caller-authentication settings. Key Vault settings are read by JavaScript's configuration object and by the Python/.NET secret resolvers. Provider-specific options remain ordinary app settings passed to the selected adapter.

JSON parsing and type checks stay at the request boundary. Downstream code uses Envelope, DeliveryContext and DispatchRequest models (documented object shapes in JavaScript, dataclasses in Python, and classes/records in .NET). Named .NET response records preserve the existing wire names and optional-field omission. Object construction does not replace validation or coerce invalid input.

All customers call the same POST /api/SendOtp handler in their chosen language. Its registry selects the configured adapter, which builds the provider's SMS or voice API call. Purchasing an unsupported provider does not install an adapter: add and register that provider's adapter first. Purchase, subscription activation and changing tenant policy belong to provisioning, not this Function.

5. Required behaviors

  • Fail-closed: only Continue → 200 accepted; unknown status → Fail.
  • Managed identity: Key Vault access via managed identity only (user-assigned if AZURE_CLIENT_ID set, else system-assigned). No static credentials.
  • Privacy: never log phone numbers, passcodes, nonce values, bearer tokens, API keys, JWE headers/payloads, raw exceptions or provider responses. There is no plaintext diagnostic override. Each handler writes one summary with a generated request ID, the first 16 lowercase hex characters of the correlation ID's SHA256 hash, HTTP status, elapsed milliseconds and evaluation flag. Original wire correlation IDs and the required nonce echo remain unchanged. Hashes are pseudonymous, not anonymous; restrict log access and retention. A configured encryption-key-ID mismatch adds a fixed warning, never either key ID or the JWE header. Disable SDK, platform and proxy body tracing separately.
  • Platform authentication only: enable Easy Auth with requireAuthentication=true, unauthenticatedClientAction=Return401 and requireHttps=true. Configure the trusted tenant issuer and allowedAudiences for the endpoint app, plus a nonempty allowedApplications list pinned to the authorized SAS caller application ID. No excluded path may bypass authentication for SendOtp. The trigger remains authLevel: anonymous; there is no application token validation or function-key fallback. The platform rejects unauthenticated requests with 401 and denies callers outside the allowlist before the handler. Never expose the endpoint to the public internet with Easy Auth off or bypassed. Core Tools supplies no Easy Auth: local execution must bind only to loopback, with no tunnels or public forwarding. Neither request data, JWE decryption, a fixed nonce nor forwarded principal headers authenticate the SAS caller.
  • Timeout boundaries: platform authentication and Key Vault retrieval happen outside the outbound HTTP timer. Python uses connect/read inactivity timeouts, not a hard elapsed-time deadline. The cap therefore does not guarantee a 3.2-second end-to-end response, especially on cold starts. A timed-out POST may already have been accepted; avoid blind retries that duplicate messages.

6. Lightweight tests

Each language keeps lightweight offline tests covering representative application checks for:

  • Bundled adapter request formats and static provider credentials.
  • Fail-closed outcomes, missing credentials, HTTPS guards and timeouts.
  • Envelope validation and real JWE decryption/tamper rejection.
  • Evaluation without provider I/O.
  • Awaited delivery, nonce acknowledgement and privacy-safe logging.

The sample deliberately omits exhaustive input permutations and SDK internals. These tests use local keys and mocked external services; they do not send SMS and do not test Easy Auth or platform authorization. Separate deployed security tests are required for missing/invalid credentials, wrong issuer or audience, unauthorized caller, HTTPS enforcement and SendOtp route protection. An authorized evaluation must succeed without provider I/O. These checks do not replace provider integration or handset-delivery checks. See deployment verification.

Production limitations

This is a sample, not production certification. Successful provider acceptance and nonce checks do not prove handset delivery or support for every provider feature.

  • The Function imports one private PEM through a Key Vault secret reference and decrypts in-process; vault-resident cryptographic operations and overlapping key rotation are not implemented.
  • The Preview 1 setup guide requires asynchronous delivery after acceptance. This sample still waits for the provider and has no durable queue or automatic retry implementation; it does not satisfy that timing architecture merely because the setup script deploys it.
  • The outbound timeout is not an end-to-end deadline. Cold starts, platform authentication and Key Vault access can exceed the caller's budget; Python uses connect/read inactivity timeouts.
  • Voice text is forwarded unchanged. Digit-by-digit rendering required by the setup guide must be verified for the chosen voice integration; unspaced numeric text is not guaranteed to be spoken correctly.
  • Full body-size/content-type and E.164 validation, subscription provisioning, certification, least-cost routing and voice-callback workflows are outside this sample. Native fallback belongs to the caller, not this Function.

See setup compatibility for credential provisioning, endpoint format and unsupported setup options.