@ondewo/survey-client-angular
v2.1.1
Published
ONDEWO Survey (SURVEY) Client library for Angular
Maintainers
Readme
Overview
@ondewo/survey-client-angular is a compiled version of the ONDEWO SURVEY API using the ONDEWO PROTO COMPILER. Here you can find the SURVEY API documentation.
ONDEWO APIs use Protocol Buffers version 3 (proto3) as their Interface Definition Language (IDL) to define the API interface and the structure of the payload messages. The same interface definition is used for gRPC versions of the API in all languages.
Setup
Using NPM:
npm i --save @ondewo/survey-client-angularUsing GitHub:
git clone https://github.com/ondewo/ondewo-survey-client-angular.git ## Clone repository
cd ondewo-survey-client-angular ## Change into repo-directoy
make setup_developer_environment_locally ## Install dependenciesAuthentication (Keycloak bearer token)
The client attaches the current Keycloak access token as an
authorization: Bearer <token> credential to every gRPC-web (and HTTP) request.
Wire it up once at application bootstrap — supply a TokenProvider (or the
ready-made KeycloakTokenProvider) and register the interceptors:
import {
authHttpInterceptor,
KEYCLOAK_TOKEN_PROVIDER_CONFIG,
KeycloakTokenProvider,
KeycloakTokenProviderConfig,
provideOndewoSurveyAuth
} from "@ondewo/survey-client-angular";
import { provideHttpClient, withInterceptors } from "@angular/common/http";
bootstrapApplication(AppComponent, {
providers: [
{
provide: KEYCLOAK_TOKEN_PROVIDER_CONFIG,
useValue: {
keycloakUrl: "https://auth.example.com/auth",
realm: "ondewo-ccai-platform",
clientId: "ondewo-nlu-cai-sdk-public",
username: "[email protected]",
password: "…"
} satisfies KeycloakTokenProviderConfig
},
provideOndewoSurveyAuth(KeycloakTokenProvider),
provideHttpClient(withInterceptors([authHttpInterceptor]))
]
});Once the providers are registered, injected clients such as SurveysClient are
authenticated automatically — no per-call token handling is required.
The built-in KeycloakTokenProvider
For a technical user the built-in KeycloakTokenProvider logs in against the public SDK Keycloak client
(no client_secret is ever sent) and keeps the access token fresh. It behaves exactly like the token
provider of every other ONDEWO client SDK. Supply its configuration under KEYCLOAK_TOKEN_provideOndewoSurveyAuthR_CONFIG
and register it with provideOndewoSurveyAuth(KeycloakTokenProvider):
import { provideHttpClient, withInterceptors } from "@angular/common/http";
import {
authHttpInterceptor,
KEYCLOAK_TOKEN_provideOndewoSurveyAuthR_CONFIG,
KeycloakTokenProvider,
KeycloakTokenProviderConfig,
provideOndewoSurveyAuth
} from "@ondewo/survey-client-angular";
bootstrapApplication(AppComponent, {
providers: [
provideHttpClient(withInterceptors([authHttpInterceptor])),
{
provide: KEYCLOAK_TOKEN_provideOndewoSurveyAuthR_CONFIG,
useValue: {
keycloakUrl: "https://keycloak.example.com",
realm: "ondewo",
clientId: "ondewo-nlu-cai-sdk-public",
refreshToken: offlineTokenFromYourSecretStore // or: username + password
} satisfies KeycloakTokenProviderConfig
},
provideOndewoSurveyAuth(KeycloakTokenProvider)
]
});A handed-off Keycloak offline token (refreshToken) is what a fleet of clients sharing one technical
user should use: start-up is then one refresh_token grant, and a refused token is never answered with a
password login (Keycloak's brute-force detection counts failed password logins, not refresh grants). A
username + password pair performs one grant_type=password login with scope=offline_access instead;
it only works for a 2FA-exempt technical user. offlineToken is still accepted as a deprecated alias of
refreshToken.
keycloakUrl, realm and clientId are all-or-nothing: all three empty means "no Keycloak" (no login, no
authorization header), any other partial set is rejected. With Keycloak configured, password or
refreshToken is mandatory. tokenExpirationInS bounds the auto-refresh when the session must not outlive
a fixed window; keycloakVerifySsl is accepted for parity with the other SDKs but cannot change a browser's
TLS verification. Every string rendering of the provider shows a set secret as ***REDACTED***.
The refresh runs REFRESH_SKEW_IN_S (30 s) before expiry; a failed refresh is retried after a jittered
backoff (5 s, doubling to 300 s) and never ends the refresh loop. While it fails, getToken() keeps serving
the still-valid token, and only a token that has expired and cannot be refreshed is reported as a
KeycloakAuthenticationError. A request issued while the first login is still in flight waits for it
instead of going out unauthenticated. One WARNING is logged per failed attempt and one INFO on recovery
(through the optional logger, default the console), never with a credential. Providers with the same
credentials on the same HttpClient share one login. The framework-free core is exported as
KeycloakTokenSession for use outside Angular DI.
Credentials that are only known after bootstrap are supplied with await tokenProvider.configure(config);
without a config the provider stays idle. await tokenProvider.whenReady() waits for the first login (e.g.
in an APP_INITIALIZER), and after the server answered UNAUTHENTICATED,
await tokenProvider.ensureFreshToken({ force: true }) renews the token (single-flight, honouring a running
backoff; a refresh never falls back to a password login).
KeycloakTokenError, the error name of earlier releases, is kept as a deprecated alias: it is the very
class KeycloakAuthenticationError, so instanceof checks written against either name keep matching.
Package structure
npm
├── api
│ ├── google
│ │ └── api
│ │ ├── annotations.pb.d.ts
│ │ └── http.pb.d.ts
│ └── ondewo
│ └── survey
│ ├── fhir.pbconf.d.ts
│ ├── fhir.pb.d.ts
│ ├── fhir.pbsc.d.ts
│ ├── survey.pbconf.d.ts
│ ├── survey.pb.d.ts
│ └── survey.pbsc.d.ts
├── esm2022
│ ├── api
│ │ ├── google
│ │ │ └── api
│ │ │ ├── annotations.pb.mjs
│ │ │ └── http.pb.mjs
│ │ └── ondewo
│ │ └── survey
│ │ ├── fhir.pbconf.mjs
│ │ ├── fhir.pb.mjs
│ │ ├── fhir.pbsc.mjs
│ │ ├── survey.pbconf.mjs
│ │ ├── survey.pb.mjs
│ │ └── survey.pbsc.mjs
│ ├── ondewo-survey-client-angular.mjs
│ └── public-api.mjs
├── fesm2022
│ ├── ondewo-survey-client-angular.mjs
│ └── ondewo-survey-client-angular.mjs.map
├── ondewo-survey-api
│ └── README.md
├── index.d.ts
├── LICENSE
├── package.json
├── public-api.d.ts
└── README.mdTLS, mutual TLS and certificates
gRPC encrypts with TLS; in this library the transport is gRPC-web over the browser's fetch/XHR, so TLS
means an https:// endpoint (an Envoy or other gRPC-web proxy in front of the ONDEWO server). The browser owns
the handshake: it verifies the server against its own (OS / browser) trust store, and it presents a client
certificate only from its own certificate store. Application code can neither add a CA nor attach a client identity,
so this package takes no certificate or key. buildGrpcWebHost builds the endpoint URL from the same host /
port / useSecureChannel fields every ONDEWO SDK uses:
| Mode | useSecureChannel | Where the certificates live |
| --- | --- | --- |
| Plaintext (not for production) | false | none; http://, logged with console.warn naming host:port |
| TLS, public CA (system roots) | true (default) | nothing to do: the browser trusts the server certificate |
| TLS, private / custom CA | true (default) | the CA (ca.pem) imported into the OS / browser trust store of every client machine |
| Mutual TLS | true (default) | the proxy requests a client certificate; the browser offers one from the user's certificate store |
For mutual TLS without certificates on the client machines, let the gRPC-web proxy (Envoy) terminate the browser's TLS and use mutual TLS on its upstream connection to the ONDEWO server.
import { GrpcCoreModule } from "@ngx-grpc/core";
import { GrpcWebClientModule } from "@ngx-grpc/grpc-web-client";
import { buildGrpcWebHost } from "@ondewo/survey-client-angular";
@NgModule({
imports: [
GrpcCoreModule.forRoot(),
GrpcWebClientModule.forRoot({
settings: { host: buildGrpcWebHost({ host: "survey.example.com", port: 443 }) } // https://survey.example.com:443
})
]
})
export class AppModule {}Rules the code enforces (GrpcWebEndpointError, whose message names the field, never its value):
useSecureChanneldefaults totrue(https://).falsegiveshttp://and aconsole.warnnaminghost:port.grpcCert,grpcClientCert,grpcClientKey(and the snake_case spellings of the other SDKs' configs) are refused when non-empty, instead of being silently dropped: never ship a private key or certificate in a browser bundle. Empty strings /nullcount as unset (plain TLS).- A bare IPv6 literal is bracketed (
::1→https://[::1]:8443); a bracketed host is left alone. A host with a scheme (https://survey.example.com/grpc) is used as given; thenportmust be omitted, and anhttp://URL together withuseSecureChannel: trueis refused. Ahost:portstring is refused; useport. - The certificate's subject alternative names (SAN) must match the host in the URL; a browser has no
ssl_target_name_override.
Outside a browser (Node.js services, tests, CLIs) use @ondewo/survey-client-nodejs: it takes
the CA and the client certificate / key as PEM content and implements mutual TLS in code. This package runs only in a
browser (Angular, gRPC-web) and has no Node.js transport.
A test PKI with openssl
A CA, a server certificate with SANs, and a client certificate with the clientAuth extended key usage. For tests
only: the keys are unencrypted.
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 365 \
-subj "/CN=Test CA" -keyout ca.key -out ca.pem
printf 'subjectAltName=DNS:localhost,IP:127.0.0.1\nextendedKeyUsage=serverAuth\n' > server.ext
openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
-subj "/CN=localhost" -keyout server.key -out server.csr
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial -days 365 \
-extfile server.ext -out server.pem
printf 'extendedKeyUsage=clientAuth\n' > client.ext
openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
-subj "/CN=my-client" -keyout client.key -out client.csr
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key -CAcreateserial -days 365 \
-extfile client.ext -out client.pem
# the browser imports a client identity as PKCS#12
openssl pkcs12 -export -in client.pem -inkey client.key -certfile ca.pem -out client.p12
chmod 600 *.key *.p12
openssl verify -CAfile ca.pem server.pem client.pemThe gRPC-web proxy serves server.pem / server.key and, for mutual TLS, trusts ca.pem for its clients (Envoy:
require_client_certificate: true with validation_context.trusted_ca). The browser machine imports ca.pem as a
trusted root and, for mutual TLS, client.p12 as a personal certificate.
TLS security notes
- No secret is part of the endpoint config, so nothing in it needs redacting, and this package never logs a config.
- A private key in a web application is readable by anyone who loads the page. Keep client identities in the
browser's certificate store (or a smart card), never in
environment.ts,assets/or the bundle. - A page served over
https://cannot call anhttp://endpoint (mixed content); use plaintext only for local development with the page itself onhttp://localhost.
TLS troubleshooting
The browser reports a failed handshake to gRPC-web as status UNAVAILABLE / UNKNOWN with little detail; the cause
is in the browser's developer tools (Network tab / console):
net::ERR_CERT_AUTHORITY_INVALID: the server certificate is signed by a CA the browser does not trust. Import the CA into the OS / browser trust store, or serve a certificate from a public CA.net::ERR_CERT_COMMON_NAME_INVALID: the host in the URL is not in the certificate's SAN. Connect by the name in the SAN, or reissue the certificate with the host (IP:SAN for an address).net::ERR_BAD_SSL_CLIENT_AUTH_CERT/ERR_SSL_CLIENT_AUTH_CERT_NEEDED: the proxy requires a client certificate and the browser has none (or one the proxy's CA did not sign). Import the user's.p12, and check that the proxy trusts its CA.- Mixed content / blocked request: the page is on
https://and the endpoint onhttp://; useuseSecureChannel: true. - CORS error: not a TLS problem; the gRPC-web proxy must allow the page's origin and the
grpc-webheaders.
