Download the PHP package sk-id-solutions/smart-id-php-client without Composer

Smart-ID PHP client

This library supports Smart-ID API v3.

Table of contents

• Introduction
• Features
• Requirements
• Getting the library
• Changelog
• How to use it with RP API v3
  • Test accounts for testing
    • Uploading certificates to demo OCSP
  • Setting up SmartIdClient
  • Setting up the connector
    • Setting up HTTPS public key pinning
  • Device link flows
    • Device link authentication session
      • Using the request builder
      • Using request objects directly
    • Generating QR code or device link
    • Examples of allowed device link interactions
  • Notification-based flows
    • Differences between notification-based and device link flows
    • Notification-based authentication session
      • With semantics identifier
      • With document number
    • Examples of allowed notification-based interactions
  • Querying session status
    • Session status response
      • End result values
      • End result to exception mapping
    • Polling for final session status
    • Single status query
  • Validating authentication response
    • Setting up trusted CA certificates
    • OCSP certificate revocation checking
    • Validating device link authentication
    • Validating notification-based authentication
    • Web2App flow validation
    • Validating callback URL with CallbackUrlUtil
  • Extracting user identity
  • Additional request properties
    • Requesting IP address of user's device
  • Exception handling
• Logging

Introduction

The Smart-ID PHP client can be used for easy integration of the Smart-ID solution to information systems or e-services.

Features

• User authentication (device link and notification-based flows)
• SmartIdClient facade for simplified integration
• Built-in HTTPS public key pinning for secure API communication
• QR code and Web2App device link URL generation
• ACSP_V2 signature protocol with RSA-PSS verification
• SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384, SHA3-512 hash algorithm support
• Certificate trust chain validation with full signatureAlgorithmParameters validation
• OCSP certificate revocation checking via AIA or designated responder
• Verification code calculation
• CallbackUrlUtil for Web2App/App2App callback URL creation and validation
• Optional PSR-3 logging support

Requirements

• PHP >= 8.4
• ext-openssl (for certificate parsing and signature verification)
• ext-json (for API request/response serialization)
• ext-curl (for HTTPS pinning via CURLOPT_PINNEDPUBLICKEY)

Getting the library

Install via Composer:

Changelog

Changes introduced with new library versions are described in CHANGELOG.md.

How to use it with RP API v3

Import the relevant classes from the Sk\SmartId namespace:

Test accounts for testing

Test accounts for testing

Note: Smart-ID Basic level accounts (certificate level ADVANCED) are not supported in the demo environment.

Uploading certificates to demo OCSP

Smart-ID demo certificates are not automatically available in the demo AIA OCSP responder (aia.demo.sk.ee). To make them available for OCSP revocation checking, upload them via SK's certificate upload interface:

• Upload page: https://demo.sk.ee/upload_cert/ — upload certificates and set their OCSP status (good/revoked/unknown)
• Download demo certificates: https://sid.demo.sk.ee/portal/login — log in to the Smart-ID self-service portal to download certificates
• Demo OCSP info: https://github.com/SK-EID/ocsp/wiki/SK-OCSP-Demo-environment

Setting up SmartIdClient

SmartIdClient is the main entry point for using Smart-ID services. It wires together the connector, session status poller, and request builders.

You can also use the connector directly for lower-level control (see Setting up the connector).

Setting up the connector

Configure to use with Smart-ID Demo environment

Setting up HTTPS public key pinning

HTTPS public key pinning is used to prevent man-in-the-middle attacks against the Smart-ID API connection.

Live SSL certificates: https://sk-eid.github.io/smart-id-documentation/https_pinning.html#_rp_api_smart_id_com_certificates

Demo SSL certificates: https://sk-eid.github.io/smart-id-documentation/https_pinning.html#_sid_demo_sk_ee_certificates

Demo / testing

For development against sid.demo.sk.ee, the SDK bundles demo keys:

Providing SSL public key hashes manually

For production, you must configure your own SPKI hashes. Download the current certificates from SK's HTTPS pinning documentation and extract each certificate's SPKI hash:

Then provide the hashes:

Loading hashes from a directory

You can load hashes from a directory of .key files (each containing one sha256//... hash):

Loading hashes from an environment variable

When hashes are stored in a single environment variable (e.g. from .env or container config):

A custom separator can be provided as the second argument:

Loading hashes from an array (secret managers, config files)

When your secret manager or configuration returns an array of hash strings:

All methods that accept hashes (addPublicKeyHash(), fromString(), fromArray()) validate every hash immediately and throw \InvalidArgumentException if the format is invalid or the input is empty.

Device link flows

Device link flows are the more secure way to ensure the user who started the authentication is in control of the device. More info: https://sk-eid.github.io/smart-id-documentation/rp-api/device_link_flows.html

Device link authentication session

Request parameters

• relyingPartyUUID — Required. UUID of the Relying Party.
• relyingPartyName — Required. Friendly name of the Relying Party, limited to 32 bytes in UTF-8 encoding.
• certificateLevel — Level of certificate requested. Possible values: QUALIFIED, ADVANCED. Defaults to QUALIFIED.
• hashAlgorithm — Hash algorithm for signatures. Supported: SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384, SHA3-512. Defaults to SHA-512.
• interactions — Required. Array of DeviceLinkInteraction objects defining the allowed interactions in order of preference.
• initialCallbackUrl — Optional. HTTPS callback URL for Web2App same-device flows. Set via withCallbackUrl() on the builder.
• nonce — Optional. Random string, up to 30 characters. Used to override idempotent behaviour (if the same request is made within a 15-second window, the same response is returned unless a nonce is provided).
• capabilities — Optional. Array of capability strings. Used only when agreed with Smart-ID provider.
• requestProperties — Optional. Set shareMdClientIpAddress to true to request the IP address of the user's device (see Requesting IP address).

Response parameters

• sessionID — String used to query the session status.
• sessionToken — Unique token linking this session between RP, RP-API, and the mobile app.
• sessionSecret — Base64-encoded secret key. Keep on backend only, never expose to client.
• deviceLinkBase — Base URI for forming device link or QR code URLs.

Using the request builder

The builder automatically generates the RP challenge and calculates the verification code. If needed, you can provide your own RP challenge:

Using request objects directly

For lower-level control, construct request objects directly:

Generating QR code or device link

Documentation: https://sk-eid.github.io/smart-id-documentation/rp-api/device_link_flows.html

To use the Smart-ID demo environment, you must specify SchemeName::DEMO as the scheme name (use ->withDemoEnvironment() or ->withSchemeName(SchemeName::DEMO)). See: https://sk-eid.github.io/smart-id-documentation/environments.html#_demo

Device link parameters

• deviceLinkBase — Value from session-init response.
• deviceLinkType — QR or WEB2APP.
• sessionToken — Token from the session response.
• elapsedSeconds — Seconds since the session-init response was received. Required for QR codes.
• lang — User language. Default: eng.
• schemeName — Controls environment. Default: SchemeName::PRODUCTION. Use SchemeName::DEMO for demo.
• callbackUrl — Required for Web2App flows. Must be HTTPS.
• brokeredRpName — Optional. Name of the brokered Relying Party, used when acting as a broker. Included in authCode calculation and must match during validation.

Generating QR code URL

QR code URLs must be refreshed every second because the authCode changes based on elapsed time to prevent replay attacks.

Using the DeviceLinkBuilder for more control:

Generating Web2App URL

For mobile web browsers where the user can open the Smart-ID app directly:

Overriding default values

Examples of allowed device link interactions

An app can support different interaction types, and a Relying Party can specify preferred interactions with or without fallback options. For device link flows, the available interaction types are limited to displayTextAndPIN and confirmationMessage. displayTextAndPIN is used for short text with PIN-code input, while confirmationMessage is used for longer text with Confirm and Cancel buttons and a second screen to enter the PIN-code.

Example 1: confirmationMessage with fallback to displayTextAndPIN

The RP's first choice is confirmationMessage; if not available, then fall back to displayTextAndPIN.

Example 2: confirmationMessage only (no fallback)

If the interaction is not supported by the app, the process will fail if no fallback is provided.

Notification-based flows

Differences between notification-based and device link flows

• Notification-based flow — Push notification is sent directly to the user's Smart-ID app. Requires knowing the user's identity (document number or semantics identifier) beforehand. More vulnerable to phishing; recommended to use after user identity has been established via device link flow. No QR codes needed.
• Device link flow — Generates QR codes or deep links. Supports anonymous authentication where the user's identity is not required beforehand. QR code must be refreshed every second.

Notification-based authentication session

Request parameters

• relyingPartyUUID — Required. UUID of the Relying Party.
• relyingPartyName — Required. Friendly name of the Relying Party.
• documentNumber or semanticsIdentifier — Required (one of). Identifies the user.
• certificateLevel — Optional. QUALIFIED or ADVANCED. Defaults to QUALIFIED.
• hashAlgorithm — Optional. Supported: SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384, SHA3-512. Defaults to SHA-512.
• interactions — Required. Array of NotificationInteraction objects defining the allowed interactions in order of preference.
• nonce — Optional. Random string, up to 30 characters. Used to override idempotent behaviour (if the same request is made within a 15-second window, the same response is returned unless a nonce is provided).
• capabilities — Optional. Array of capability strings.
• requestProperties — Optional. Set shareMdClientIpAddress to true to request the IP address of the user's device (see Requesting IP address).

Response parameters

• sessionID — String used to query the session status.

Initiating with semantics identifier

More info about Semantics Identifiers: ETSI EN 319 412-1

Jump to Querying session status for an example of session status polling.

Initiating with document number

Examples of allowed notification-based interactions

Notification-based flows support additional interaction types compared to device link flows. Available types are displayTextAndPIN, confirmationMessage, and confirmationMessageAndVerificationCodeChoice.

Example 1: confirmationMessageAndVerificationCodeChoice with fallback to confirmationMessage and displayTextAndPIN

The RP's first choice is confirmationMessageAndVerificationCodeChoice; the second choice is confirmationMessage; the third choice is displayTextAndPIN.

Example 2: confirmationMessageAndVerificationCodeChoice only (no fallback)

Process will fail if interaction is not supported and there is no fallback.

Querying session status

Session status response

The session status response includes various fields depending on whether the session has completed or is still running:

• state — RUNNING or COMPLETE
• result.endResult — Outcome of the session (see End result values below).
• result.documentNumber — Document number returned when endResult is OK. Can be used in further authentication requests to target the same device.
• signatureProtocol — ACSP_V2 for authentication.
• signature — For ACSP_V2: contains value, serverRandom, userChallenge, flowType, signatureAlgorithm, signatureAlgorithmParameters.
• cert — Certificate info: value (Base64-encoded X.509 DER) and certificateLevel (QUALIFIED or ADVANCED).
• interactionTypeUsed — The interaction type that was actually used for the session (e.g., displayTextAndPIN, confirmationMessage).
• ignoredProperties — Array of property names from the request that were not recognized by the server.
• deviceIpAddress — IP address of the user's device, if requestProperties.shareMdClientIpAddress was set to true and the feature is enabled for your account.

End result values

The result.endResult field may contain the following values:

• OK — Session completed successfully.
• USER_REFUSED — User refused the session.
• USER_REFUSED_CERT_CHOICE — User has multiple accounts and pressed Cancel on device choice screen.
• USER_REFUSED_DISPLAYTEXTANDPIN — User pressed Cancel on the displayTextAndPIN interaction screen.
• USER_REFUSED_VC_CHOICE — User pressed Cancel on the verification code choice screen.
• USER_REFUSED_CONFIRMATIONMESSAGE — User pressed Cancel on the confirmationMessage screen.
• USER_REFUSED_CONFIRMATIONMESSAGE_WITH_VC_CHOICE — User pressed Cancel on the confirmationMessageAndVerificationCodeChoice screen.
• USER_REFUSED_INTERACTION — User pressed Cancel on the interaction screen. result.details contains info about which interaction was canceled.
• TIMEOUT — User did not respond in time.
• DOCUMENT_UNUSABLE — Session could not be completed due to an issue with the document.
• WRONG_VC — User selected the wrong verification code.
• REQUIRED_INTERACTION_NOT_SUPPORTED_BY_APP — The requested interaction is not supported by the user's app.
• PROTOCOL_FAILURE — An error occurred in the signing protocol.
• EXPECTED_LINKED_SESSION — Server expected a device link session but received a notification-based session (or vice versa).
• SERVER_ERROR — Technical error occurred at the server side and the process was terminated.
• ACCOUNT_UNUSABLE — The user's Smart-ID account is unusable for this operation.

End result to exception mapping

When using SessionStatusPoller, non-OK end results are automatically converted to typed exceptions:

Note: UserRefusedInteractionException extends UserRefusedException. The poller checks for USER_REFUSED_INTERACTION first, so catching UserRefusedException after UserRefusedInteractionException handles all other user refusal variants.

Polling for final session status

Using SessionStatusPoller to poll until the session completes:

The poller automatically throws typed exceptions for error results (see Exception handling).

You can configure polling parameters:

Single status query

For device link flows where you need to generate a fresh QR code every second, use single status queries:

Or query the connector directly:

Validating authentication response

It is critical to validate the authentication response to ensure the signature and certificate are trustworthy.

Setting up trusted CA certificates

OCSP certificate revocation checking

OCSP revocation checking is enabled automatically when creating a validator via SmartIdClient::createAuthenticationResponseValidator(). The checker verifies that the end-entity certificate has not been revoked by reading the OCSP responder URL from the certificate's Authority Information Access (AIA) extension.

Note: For the demo environment, you must first upload your test certificates to the demo OCSP responder — see Uploading certificates to demo OCSP.

Validating device link authentication

The validator performs the following checks:

1. Session state is COMPLETE and result is OK
2. Signature protocol is ACSP_V2
3. Certificate level meets the requested level (if specified)
4. Certificate is signed by a trusted CA and within its validity period
5. Certificate basic constraints (not a CA certificate)
6. Certificate policies contain Smart-ID scheme OIDs
7. Certificate key usage includes digitalSignature
8. Certificate Extended Key Usage includes Smart-ID authentication or clientAuth
9. signatureAlgorithmParameters validation (hashAlgorithm, saltLength, maskGenAlgorithm, trailerField)
10. RSA-PSS signature verification against the ACSP_V2 payload

Validating notification-based authentication

Validation is the same as device link. The only difference is how the session was initiated — the validation step uses the same AuthenticationResponseValidator::validate() method.

Web2App flow validation

When using Web2App or App2App flows, the Smart-ID app redirects the user back to the Relying Party via the callback URL. The received callback URL will contain additional query parameters that must be validated.

Example callback URL for authentication:

Validation steps:

1. Verify that the value query parameter matches the random value you included when creating the callback URL.
2. Verify sessionSecretDigest matches Base64URL(SHA-256(Base64Decode(sessionSecret))) where sessionSecret is from the session init response.
3. For authentication flows, verify userChallengeVerifier — its SHA-256 hash (Base64URL-encoded) must match signature.userChallenge from the session status response.

Validating callback URL with CallbackUrlUtil

The CallbackUrlUtil helper simplifies creating and validating callback URLs for Web2App/App2App flows.

Creating a callback URL with a random token

Validating session secret digest from callback

When the Smart-ID app redirects back to your callback URL, validate the sessionSecretDigest query parameter:

Extracting user identity

After successful validation, the AuthenticationIdentity object provides:

The document number can be retrieved from the session result for future requests:

Additional request properties

Requesting IP address of user's device

For the IP address to be returned, the service provider (SK) must enable this option for your account. More info: https://sk-eid.github.io/smart-id-documentation/rp-api/3.0.3/request_properties.html

The same withShareMdClientIpAddress() method is available on both DeviceLinkAuthenticationRequestBuilder and NotificationAuthenticationRequestBuilder.

Exception handling

The library provides specific exceptions for different error scenarios. All exceptions extend SmartIdException.

Permanent exceptions

These indicate client-side configuration or input errors.

• InvalidParametersException — Invalid request parameters (HTTP 400).
• UnauthorizedException — Invalid RP credentials (HTTP 401) or user not found (HTTP 403).

User action exceptions

These cover scenarios where user actions or inactions lead to session termination.

• UserRefusedException — User refused the operation.
• UserRefusedInteractionException — User pressed Cancel on a specific interaction screen. Extends UserRefusedException. Use getInteraction() to see which interaction was canceled (from result.details).
• SessionTimeoutException — User did not respond within the allowed timeframe.
• WrongVerificationCodeException — User selected the wrong verification code.
• RequiredInteractionNotSupportedException — The required interaction type is not supported by the user's app.

User account exceptions

• UserAccountException — Problems with the user's Smart-ID account.
  • isNoSuitableAccount() — No suitable account found (HTTP 471).
  • isPersonShouldViewApp() — User should view Smart-ID app or self-service portal (HTTP 472).
  • isClientTooOld() — Client-side API too old (HTTP 480).
• DocumentUnusableException — The requested document cannot be used.

Protocol and server exceptions

• ProtocolFailureException — An error occurred in the signing protocol.
• ServerErrorException — Technical error occurred at the Smart-ID server side.

Validation exceptions

• ValidationException — Thrown during response validation: certificate trust, signature mismatch, etc.

Technical exceptions

• TechnicalErrorException — Thrown for technical errors during processing (e.g., malformed responses, unexpected data formats).

Server-side exceptions

• SmartIdException — Smart-ID service temporarily unavailable (HTTP 5xx) or other unclassified errors.
• UnderMaintenanceException — System is under maintenance (HTTP 580). Retry the request later.
• SessionNotFoundException — Session not found (HTTP 404).

Example of handling exceptions

Logging

The SDK supports optional PSR-3 logging. Pass any LoggerInterface implementation (e.g. Monolog) to SmartIdClient and AuthenticationResponseValidator. If no logger is provided, a NullLogger is used and no output is produced.

What is logged

Note: The SDK never logs request/response bodies, personal data, or secrets. Only metadata such as URLs, status codes, and session IDs are logged.

Using with SmartIdClient

The logger is passed as the last constructor parameter and automatically propagated to the connector, session status poller, and request builders.