Configuration in application.yml
If you are going to use API Gateway for Mobile Ticket only, you should use the application_MobileTicket.yml file, which can be found next to the standard application.yml file in the API Gateway zip. For more information, see the Mobile Ticket manual, found on Qmatic World.
There are three configuration files available in the <installation_directory>\conf folder:
• In application.yml, you, for example, select the Orchestra services (entry point connector, service point connector, etc) that you want to expose. You also decide whether or not to use checksum validation.
As soon as
application.yml is saved, API Gateway will be updated. No restart is needed!
Do not use the
tab key, when editing the
application.yml file!
• In logbackAPIGateway.xml, you configure the logging, in the same way as for Orchestra.
• In
ehcache.xml, you configure a number of cache settings, for more information, see
“Cache” .
This section describes all the settings that need to be configured in the application.yml file. We recommend that you configure all these settings at the same time.
API Token and Encrypted Password
After you have run the api-token-generator.bat script to generate an API Token and after you have run the password-encoder.bat script to encrypt your password, enter these into the api-tokens section of the application.yml file, as in the following example (Note that the values in the picture are not valid!):
The user
superadmin should be removed, unless this is a test system.
Enabling HTTPS/SSL
The following picture explains the communication between the Mobile applications and API Gateway, on one hand, and between API Gateway and Orchestra on the other.
It is possible to, for example, use HTTP between Mobile applications and API Gateway and then HTTPS between API Gateway and Orchestra, if wanted.
The
management.ssl setting should be set to
false so that the shut down of API Gateway works as expected.
Running HTTPS from Mobile applications to API Gateway
Uncomment this section in the application.yml file:
ssl:
key-store: classpath:keystore.jks
key-store-password: secret
key-password: password
Make sure that the settings for key-store-password match the password for keystore.jks and that key-password matches the one set for the key/certificate.
If the regular Orchestra instruction has been followed, these are usually the same and they are set to "changeit".
The section should then now look like this:
server:
port: 9090
ssl:
key-store: classpath:keystore.jks
key-store-password: changeit
key-password: changeit
The server will listen only to HTTPS on port 9090.
The password is changeit by default, but can of course be changed.
It is currently not supported to listen on both HTTP and HTTPS, at the same time.
Running HTTPS from API Gateway towards Orchestra
To run HTTPS from API Gateway towards Orchestra, in the application.yml file, update the orchestra.central.url setting, so that it points to an https-url, as in the following example:
orchestra:
# define URL for orchestra central installation
central:
url: https://localhost:8443
Also, to use the SSL trust store for the JVM, uncomment this section:
trustStore: conf/truststore.jks
trustStorePass: changeit
Orchestra’s certificate needs to be imported into the API Gateway trust store. The password is changeit by default but can of course be changed.
To disable SSL certificate verification, uncomment the disableSslCertificateChecks parameter and set it to true.
This should not be used in production systems!
Routes
To configure the Routes settings, follow these steps:
1. Edit the routes section. Here, you define the routes that should be exposed via zuul proxy. These should match the connectors that you selected for the User that you created in Orchestra. In this way, only the needed parts of the system will be exposed.
Example:
zuul:
routes:
entrypoint_api:
path: /rest/entrypoint/**
url: ${orchestra.central.url}/qsystem/rest/entrypoint
servicepoint_api:
path: /rest/servicepoint/**
url: ${orchestra.central.url}/qsystem/rest/servicepoint
Checksum validation
Checksum validation is used, for example, to prevent the security risk where a User could manipulate the order of a Queue, in his/her favour, by for example guessing which Visit Id’s are in front of him/her in the Queue and then removing them.
If the validation fails, an error message is returned.
If you want to disable checksum validation (enabled by default), i.e. a validation of mobile query requests, you need to edit the following parameter in the application.yml file, and set it to false, as in the following example:
# use checksum validation for mobile requests
enableChecksum: false
However, if you want to keep it enabled, you also need to define which proxy routes this should be applied to. By default, this is applied to showing the status and deleting the Visit. The parameter field in the following section defines which path parameter that defines the Visit Id:
# define which proxy routes where checksum validation will be applied
# name of the path parameter defining the visit_id must be defined as a parameter
checksumRoutes:
my_visit_delete:
parameter: ticket
my_visit_current_status:
parameter: visits
CORS Configuration
By default, CORS support is commented out and disabled in API Gateway.
When defining several paths, YAML list formatting is needed (-). See example below.
Example:
http:
cors:
paths:
# Defines configuration for endpoint '/foo'
- path: /foo
allowedOrigins: http://foo.com, http://bar.com
allowedHeaders: X-Foo, X-Bar, Content-Type
exposedHeaders: X-Foo, X-Bar
allowedMethods: GET, POST, PUT, OPTIONS, HEAD, DELETE, PATCH
allowCredentials: true
maxAge: 3600
# Defines configuration for endpoint '/bar'
- path: /bar/**
allowedOrigins: http://bar.com
allowedHeaders: X-Bar, Content-Type
exposedHeaders:Bar
allowedMethods: GET
zuul.ignored-headers: Access-Control-Allow-Credentials, Access-Control-Allow-Origin, Access-Control-Expose-Headers, Access-Control-Allow-Headers
CORS paths attribute prefix:
http.cors.paths
Attribute: path
The path tells which path the CORS configuration shall be applied on.
Required: TRUE
Example:
path: /foo
path: /foo/**
path: /**
Attribute: allowedOrigins
The allowedOrigins corresponds to CORS Http header Access-Control-Allow-Origin and list the acceptable Origin.
A comma separated list is supported.
Required: TRUE
Example:
allowedOrigins: http://foo.com, http://bar.com
allowedOrigins: '*'
Attribute: allowedHeaders
The allowedHeaders corresponds to CORS Http header Access-Control-Allow-Headers.
A comma separated list is supported.
Required: FALSE
Example:
allowedHeaders: X-Foo, X-Bar, Content-Type
allowedHeaders: '*'
Attribute: exposedHeaders
The exposedHeaders corresponds to CORS Http header Access-Control-Expose-Headers.
A comma separated list is supported.
Required: FALSE
Example:
exposedHeaders: X-Foo, X-Bar
exposedHeaders: '*'
Attribute: allowedMethods
The allowedMethods corresponds to CORS Http header Access-Control-Allow-Methods.
A comma separated list is supported.
Required: FALSE
Example:
allowedMethods: GET, POST, PUT, OPTIONS, HEAD, DELETE, PATCH
allowedMethods: '*'
Attribute: allowCredentials
The allowCredentials corresponds to CORS Http header Access-Control-Allow-Credentials.
A boolean value.
Required: FALSE
Example:
allowCredentials: true
Attribute: maxAge
The maxAge corresponds to CORS Http header Access-Control-Max-Age.
A numeric value in seconds.
Required: FALSE
Example:
maxAge: 3600
Duplication of CORS response headers
The Orchestra server that is located inside the API Gateway also returns CORS headers. To avoid duplication of CORS headers sent back to client Zuul configuration property zuul.ignored-headers can be used to ignore specified headers.
Example:
zuul.ignored-headers: Access-Control-Allow-Credentials, Access-Control-Allow-Origin, Access-Control-Allow-Headers, Access-Control-Expose-Headers, Access-Control-Max-Age, Access-Control-Allow-Methods
Log output
During start up, active CORS configuration is printed to log.
Example:
Registered CORS config: CorsPath [path=/**, allowCredentials=true, maxAge=10000, allowedOrigins=[http://foo.com, http://bar.com], allowedHeaders=[header1, header2], exposedHeaders=[header3, header4], allowedMethods=[GET, POST, PUT]]
Example of an application.yml file
# define management endpoint, for instance: http://127.0.0.1:9091/api-gateway/health
# the management endpoint is ONLY available locally
# NOTE: set port to -1 for disabling all management endpoints
management:
address: 127.0.0.1
port: 9091
context-path: /api-gateway
ssl:
enabled: false
# define if which management endpoints should be available
endpoints:
# [POST] shutdown the gateway
# NOTE: needs to be enabled, used by service script.
shutdown:
enabled: true
# [POST] restart the gateway
restart:
enabled: false
# [GET] list all gateway configuration
configprops:
enabled: false
# [GET] list the gateqway enviroment
env:
enabled: false
server:
# define server port for gateway
port: 9090
# ssl:
# key-store: classpath:keystore.jks
# key-store-password: secret
# key-password: password
# define orchestra parameters
orchestra:
# define URL for orchestra central installation
central:
url: http://localhost:8080
# SSL trust store for the jvm
# trustStore: conf/truststore.jks
# trustStorePass: changeit
# disables SSL certificate verification. Warning: do not use in production systems
# disableSslCertificateChecks: false
# use 'password-encoder' script in 'bin' folder script for encoding new password.
# use 'api-token-generator' script in 'bin' folder for generating new token.
api_tokens:
c7a1331a-32d-11e5-bf7f-feff819acdc9f:
user: superadmin
passwd: dWxhbg==
d0516eee-a32d-11e5-bf7f-feff819cdc9f:
user: mobile
passwd: dWxhbg==
# use checksum validation for mobile requests
enableChecksum: true
# define which proxy routes checksum validation will be applied to.
# the name of the path parameter holding the visitId must be specified as parameter: [name] below.
checksumRoutes:
my_visit_delete:
parameter: ticket
my_visit_current_status:
parameter: visits
cache:
# by default the cache metrics connector is only accessable from local machine
allowCacheMetricsFromAllHosts: false
# if true, all requests not matching the rules in cacheRoutes will get cached in the default cache
useDefaultCache: true
# name of cache in ehcache configuration
defaultCacheName: request
# define if unique cache is used for URL query parameters.
defaultCacheUniquePerQueryParameter: false
cacheRoutes:
# Note: the cache for MyVisit/CurrentStatus and MyVisit/Position is specified in ehcache.xml as visitsOnBranchCache
services:
# name of cache in ehcache configuration
cacheName: serviceCache
# REST path pattern matching
match: /services
# defines which zuul routes to apply caching to
routes: mobile_service_v1, mobile_service_v2
# configure if the cache should store a unique value per query parameter string (default false)
uniquePerQueryParameter : false
mobileServices:
cacheName: serviceCache
match: .*
routes: custom_mobile_services
mobileBranches:
cacheName: branches
match: /branches/[0-9]+[/]?$
routes: mobile_service_v2
visits:
cacheName: visitInQueueCache
match: /branches/[0-9]+/queues/[0-9]+/visits[/]?
routes: servicepoint_api
events:
cacheName: eventInQueueCache
match: /branches/[0-9]+/visits/[0-9]+/events[/]?
routes: my_visit_last_queue_event
# Details logging if routing fails. This is off by default not to flood logs if orchestra is down
logZuulExceptions : false
# define routes exposed via zuul proxy
zuul:
routes:
appointment_api:
path: /rest/appointment/**
url: ${orchestra.central.url}/qsystem/rest/appointment
entrypoint_api:
path: /rest/entrypoint/**
url: ${orchestra.central.url}/qsystem/rest/entrypoint
servicepoint_api:
path: /rest/servicepoint/**
url: ${orchestra.central.url}/qsystem/rest/servicepoint
management_information:
path: /rest/managementinformation/**
url: ${orchestra.central.url}/qsystem/rest/managementinformation
mobile_service_v2:
path: /rest/mobile/v2/**
url: ${orchestra.central.url}/qsystem/mobile/rest/v2
mobile_service_v1:
path: /rest/mobile/**
url: ${orchestra.central.url}/qsystem/mobile/rest
calendar_internal_api:
path: /rest/calendar-backend/api/**
url: ${orchestra.central.url}/calendar-backend/api
calendar_public_api:
path: /rest/calendar-backend/public/api/**
url: ${orchestra.central.url}/calendar-backend/public/api
# custom mobile service example
# (authentication against mobile)
# To get a list of branches, use /geo/* if you want to use the gateway branch cache.
# get services for branch - /MobileTicket/branches/[branchId]/services
custom_mobile_branches:
path: /MobileTicket/branches/**
url: ${orchestra.central.url}/qsystem/mobile/rest/v2/branches
# get branches for service - /MobileTicket/services/[serviceId]/branches/
# issue ticket - /MobileTicket/services/[serviceId]/branches/[branchId]/ticket/issue
custom_mobile_services:
path: /MobileTicket/services/**
url : ${orchestra.central.url}/qsystem/mobile/rest/v2/services
# Mobile ticket -authentication against mobile - routes protected by checksum
# delete visit - /MobileTicket/MyVisit/branches/[branchId]/ticket/[visitId]?checksum=[checksum]
my_visit_delete:
path: /MobileTicket/MyVisit/branches/*/ticket/**
url: ${orchestra.central.url}/qsystem/mobile/rest/v2/branches
# get current status of visit - /MobileTicket/MyVisit/CurrentStatus/branches/[branchId]/visits/[visitId]?checksum=[checksum]
my_visit_current_status:
path: /MobileTicket/MyVisit/CurrentStatus/branches/*/visits/*
# custom MyVisit example
# (authentication against orchestra)
# DEPRECATED, use my_visit_current_status instead
# get position in queue - /MobileTicket/MyVisit/Position/branches/[branchId]/queues/[queueId]/visits?visitId=[visitId]
my_visit_queue_position:
path: /MobileTicket/MyVisit/Position/**
url: ${orchestra.central.url}/qsystem/rest/servicepoint
# get last event for visit - /MobileTicket/MyVisit/LastEvent/branches/[branchId]/visits/[visitId]/events?visitId=[visitId]
my_visit_last_queue_event:
path: /MobileTicket/MyVisit/LastEvent/**
url: ${orchestra.central.url}/qsystem/rest/servicepoint
# Note that these paths are here for documentation purposes and can not be changed
geoServiceConnectors:
# get branches - /geo/branches?longitude=[longitude]&latitude=[latitude]&radius=[radius]
mobile_branches:
path: /geo/branches
# get nearest branches - /geo/nearestbranches?longitude=[longitude]&latitude=[latitude]&maxNrOfBranches=[maxNrOfBranches]
mobile_nearest_branches:
path: /geo/nearestbranches
# get branches for service - /geo/services/[serviceId]/branches?longitude=[longitude]&latitude=[latitude]&radius=[radius]
mobile_branches_for_service:
path: /geo/services/*/branches
# get nearest branches for service
# - /geo/services/[serviceId]/nearestbranches?longitude=[longitude]&latitude=[latitude]&maxNrOfBranches=[maxNrOfBranches]
mobile_nearest_branches_for_service:
path: /geo/services/*/nearestbranches
# These URLs are used internally for fetching branches and branches for services but these should normally not be changed.
geoService:
branches_url: ${orchestra.central.url}/qsystem/mobile/rest/v2/branches?longitude=0&latitude=0&radius=2147483647
service_branches_url: ${orchestra.central.url}/qsystem/mobile/rest/v2/services/{serviceId}/branches?longitude=0&latitude=0&radius=2147483647
currentStatus:
visits_on_branch_url: ${orchestra.central.url}/qsystem/mobile/rest/v2/branches/{branchId}/visits
# CORS setup
# Orchestra CORS configuation can be overriden in API Gateway. By default disabled.
# Single path CORS setup example
#http.cors.paths:
# path: /**
# allowedOrigins: '*'
# allowedHeaders: '*'
# exposedHeaders: '*'
# allowedMethods: GET, POST, PUT, OPTIONS, HEAD, DELETE, PATCH
# allowCredentials: true
# maxAge: 10000
# Multiple paths CORS setup example
#http.cors.paths:
# - path: /test1
# allowedOrigins: http://foo.com, http://bar.com
# allowedHeaders: header1, header2
# exposedHeaders: header3, header4
# allowedMethods: GET, POST, PUT
# allowCredentials: true
# maxAge: 10000
# - path: /test2
# allowedOrigins: '*'
# To avoid duplicate CORS headers in response, disable CORS reponse headers using Zuul config
#zuul.ignored-headers: Access-Control-Allow-Credentials, Access-Control-Allow-Origin, Access-Control-Allow-Headers, Access-Control-Expose-Headers, Access-Control-Max-Age, Access-Control-Allow-Methods
