Partner Identity Authentication

Purpose

This guide defines the requirements and process for integrating an external partner as an identity provider (IdP) with VerifiMe. It covers the two supported integration paths, security requirements, and the work required from both the partner and VerifiMe.

---

Specifications

---

Trust Model

VerifiMe is always the identity provider of record. Partner IdP integration means VerifiMe is delegating the "this person is who they say they are" decision to the partner for a specific authentication event. This is a deliberate trust decision, not a technical default.

Key principles:

• A valid partner token proves the partner's private key signed it. VerifiMe holds only the partner's public key and cannot forge tokens.
• If a fraudulent token appears, the partner's private key leaked. VerifiMe can demonstrate this cryptographically (non-repudiation).
• Partners are never self-service. Every integration requires explicit VerifiMe approval.
• Partner SSO authenticates users during the VerifiMe verification intake only, not as an ongoing VerifiMe login mechanism.

---

Prerequisites

These are non-negotiable before any technical work begins:

1. Trust decision: VerifiMe explicitly approves the partner as a trusted identity source, including a security review of the partner's authentication standards and MFA strength.
2. Integration agreement: The partner accepts liability for unauthorised account access resulting from a compromise of their IdP. The agreement must cover breach notification obligations and, where either party is APRA-regulated, audit rights under CPS 234.
3. Technical contact: Partner nominates an engineering contact for the integration and ongoing support.
4. Data processing agreement (DPA): A signed DPA must be in place before any data flows, covering Australian Privacy Act obligations (particularly APP 8 for overseas partners) and GDPR Article 28 compliance where the partner processes EU-resident data.
5. AML/CTF obligations: VerifiMe's obligations under the AML/CTF Act are not transferred to the partner. The partner's identity assertion is an authentication credential, not a KYC substitute.
6. Availability expectations: The partner's IdP is in the critical path for VerifiMe's verification intake flow. Minimum uptime requirements and incident notification obligations must be agreed before go-live.
7. Digital ID Act 2024: This is a private bilateral arrangement and does not require AGDIS accreditation, but VerifiMe uses the Digital ID Act 2024 framework as a benchmark when assessing partner trust decisions.
8. Verification intake scope: Partner SSO is used exclusively during the VerifiMe verification intake flow. The partner first registers the user via POST /v1/user/invite, which creates a pending VerifiMe account. The user then authenticates via the partner IdP, which allows VerifiMe to securely identify them at the start of the verification intake. Partner SSO is not used again once verification is complete.

---

Supported Integration Paths

Two paths are supported. The choice depends on the partner's technical capability and the desired user experience.

If a partner cannot support either path, they are not suitable as an identity provider. VerifiMe does not support custom or proprietary authentication flows.

---

Path A: Authorisation Code Flow

Defined in RFC 6749 §4.1 and OIDC Core §3.1

How it works

The user is not expected to initiate the authentication flow. Opening the invite URL is sufficient; VerifiMe handles the rest automatically.

What the partner must provide

• OIDC discovery endpoint at /.well-known/openid-configuration (OIDC Discovery §3)
  • Or manually: authorization_endpoint, token_endpoint, jwks_uri, issuer
• Client ID issued to VerifiMe (registered on the partner's authorisation server)
• Client authentication method supported at the token endpoint (Basic auth or client_secret_post); see RFC 6749 §2.3
• Redirect URI whitelist entry for the VerifiMe callback URL for your environment (provided by your VerifiMe technical contact during onboarding)
• id_token signed with RS256 or ES256 (asymmetric; see Security Requirements)
• Profile claims included in id_token: email, given_name, family_name must be present in the ID Token directly (not only at the UserInfo endpoint). Partners must configure their authorisation server accordingly; see OIDC Core §5.4
• nonce echoed back in id_token: VerifiMe always includes a nonce in the authorisation request; the partner must include it in the ID Token (OIDC Core §2)
• state echoed back unchanged in the redirect response (RFC 6749 §4.1.2)

What VerifiMe will do

VerifiMe will register the partner's identity provider configuration and map the partner's claims to VerifiMe user attributes. Authentication is triggered automatically when the user opens the invite URL; no user-facing sign-in option is surfaced. VerifiMe will provide the partner with the client ID and redirect URI required for registration.

---

Path B: CIBA (Client Initiated Backchannel Authentication)

Defined in CIBA Core 1.0

VerifiMe uses Poll mode (CIBA Core §5): VerifiMe polls the partner's token endpoint until the user approves. No callback endpoint is required from VerifiMe.

How it works

The user is not expected to initiate the authentication flow. Opening the invite URL is sufficient. The user never leaves VerifiMe's UI; authentication happens in the partner's app or via push.

What the partner must provide

• OIDC discovery endpoint at /.well-known/openid-configuration including (CIBA Core §4):
  • backchannel_authentication_endpoint (REQUIRED)
  • backchannel_token_delivery_modes_supported must include poll (REQUIRED)
• Backchannel authentication endpoint (CIBA Core §7.1)
  • Content-Type: application/x-www-form-urlencoded
  • Required: scope=openid, login_hint={email} (VerifiMe uses login_hint as the user identifier hint; exactly one of login_hint, login_hint_token, or id_token_hint is required per spec)
  • Optional: binding_message={string} (short text displayed to the user during approval)
  • Returns: auth_req_id (REQUIRED), expires_in (REQUIRED), interval (OPTIONAL; VerifiMe defaults to 5 seconds if absent)
• Out-of-band delivery: push notification, biometric prompt, or in-app approval screen delivered to the user
• Token endpoint supporting the CIBA grant (CIBA Core §10.1):
  • grant_type=urn:openid:params:grant-type:ciba
  • auth_req_id={auth_req_id}
  • Returns id_token, access_token, token_type on completion
  • Returns the following error codes during polling (CIBA Core §11):

• On completion: id_token must meet the same Security Requirements as Path A

What VerifiMe will do

Everything in Path A, plus building the async authentication flow on VerifiMe's side to handle the out-of-band completion.

Note: Path B requires substantially more VerifiMe engineering effort than Path A. Confirm this path is necessary before committing.

---

Security Requirements (both paths)

id_token signing: asymmetric only

Integration policy requirement. RS256 and ES256 are defined in RFC 7518 §3. ACSC ISM Guidelines for Cryptography recommend ECDSA (ES256) in preference to RSA (RS256).

• Partner must sign the id_token with ES256 (preferred) or RS256
• ES256 (ECDSA with P-256) is preferred: smaller key sizes, better performance, and consistent with ACSC ISM cryptographic guidance
• RS256 is accepted where ES256 is not supported; minimum key size: RSA-2048
• HMAC (HS256) is not accepted. A shared secret creates ambiguity about which party signed the token and removes non-repudiation, which is unacceptable for a multi-partner deployment.
• VerifiMe stores only the partner's public key via the partner's JWKS endpoint. The private key never leaves the partner.
• Non-repudiation: a valid asymmetric signature proves the partner's private key produced the token. VerifiMe cannot produce such a token.
• Partners must expose a JWKS endpoint and document their key rotation procedure. VerifiMe caches keys and rotates when a new kid appears.

nonce claim

OIDC Core §3.1.2.1 and §2

• VerifiMe generates a random nonce per authentication attempt and includes it in the authorisation request
• Per OIDC Core §2: "If present in the Authentication Request, Authorization Servers MUST include a nonce Claim in the ID Token." VerifiMe always sends a nonce, making this a de facto requirement for this integration.
• VerifiMe validates the nonce before accepting the token
• Binds the token to the specific authentication attempt and prevents token substitution attacks

state parameter

RFC 6749 §4.1.1 and §4.1.2

• VerifiMe generates a signed state parameter and includes it in the authorisation request
• The partner must echo state back unchanged in the callback redirect
• VerifiMe validates the state before processing the callback
• Prevents CSRF attacks and redirect injection

PKCE

• Partners are not required to support PKCE. VerifiMe acts as a confidential client (server-to-server with a client secret); PKCE provides no additional security benefit in this context. This position will be reviewed when OAuth 2.1 is finalised.

Transport security

All API endpoints involved in this integration (authorisation endpoint, token endpoint, backchannel authentication endpoint, JWKS endpoint) must use TLS 1.3. TLS 1.2 is accepted where TLS 1.3 is not supported by the partner's infrastructure, with forward-secrecy cipher suites required. TLS 1.0, TLS 1.1, and SSL 3.0 are not accepted. Certificates must be issued by a publicly trusted CA; self-signed certificates are not accepted in production.

This aligns with VerifiMe's internal standard (TLS 1.3 for all communications) and ACSC guidance on implementing TLS.

Authentication strength

The cryptographic strength of the id_token is only as strong as the authentication method the partner used to produce it. An RS256-signed token issued after a password-only login provides weak assurance regardless of the signature algorithm.

• The partner should include an acr (Authentication Context Class Reference) claim in the id_token asserting the authentication method used (OIDC Core §2)
• VerifiMe strongly recommends phishing-resistant MFA on the partner side (passkey / FIDO2 / PKI-based), consistent with ACSC Essential Eight ML2. Authentication strength is discussed and agreed during the trust review.
• Partners must agree the acr value(s) in use with VerifiMe during onboarding.

Required id_token claims

OIDC Core §2

---

Account Identification

During the verification intake, VerifiMe identifies the user using the {iss, sub} pair from the partner IdP token, not the email address. Email addresses can be reassigned by an IdP; {iss, sub} ensures the identity assertion is tied to a specific, stable account on the partner's system. The pair is stored in the verification record for audit and non-repudiation purposes.

• The sub claim must be stable and non-reassignable within the partner's namespace, and must not be an email address.
• Partner SSO is scoped to the verification intake. Once verification is complete, subsequent interactions with VerifiMe use VerifiMe's own session mechanisms. Partner SSO is not available as an ongoing login method.
• If no matching invite is found for the authenticating user, the intake is rejected. If the invite has expired, the intake is also rejected and the partner must re-issue an invite via POST /v1/user/invite.

---

What VerifiMe Does Not Support

---

Onboarding Checklist

Partner

• Confirm your system calls POST /v1/user/invite before directing a user to VerifiMe for verification. The SSO authentication step will be rejected if no matching invite exists or if the invite has expired.
• Confirm integration path (Path A or Path B)
• Provide OIDC discovery endpoint URL (or manual endpoint details)
• Provide JWKS endpoint URL (or PEM public key)
• Confirm email, given_name, family_name are included in the id_token (not UserInfo endpoint only)
• Confirm iss, sub, aud, exp, iat are present in id_token
• Confirm nonce is echoed in id_token when sent in the request
• Confirm state is echoed unchanged in callback redirect (Path A)
• Register VerifiMe's redirect URI with your IdP (Path A); contact your VerifiMe technical contact for the exact value
• Issue a client ID to VerifiMe and confirm client authentication method (Path A)
• (Path B only) Confirm backchannel_token_delivery_modes_supported includes poll in discovery document
• (Path B only) Implement backchannel authentication endpoint
• (Path B only) Implement push delivery to user
• (Path B only) Confirm token endpoint supports grant_type=urn:openid:params:grant-type:ciba
• (Path B only) Confirm all CIBA error codes are returned: authorization_pending, slow_down, expired_token, access_denied
• Confirm authentication method used and agree acr value(s) with VerifiMe
• Confirm id_token is signed with ES256 (preferred) or RS256 (minimum RSA-2048)
• Confirm all API endpoints (authorisation, token, JWKS, backchannel) use TLS 1.3 (or minimum TLS 1.2 with forward secrecy)
• Confirm JWKS endpoint is publicly accessible and key rotation procedure is documented
• Confirm sub values are stable and non-reassignable; confirm sub is not an email address
• Self-certify whether your system processes personal data of EU-resident users (required for DPA scoping)