Deploying the Authorization Server

caution

Please ensure that you have Helm installed correctly before proceeding with the steps outlined below. Refer to Installing Helm for details.

Authorization Server Deployment using Helm Charts

FPX is packaged as a Helm chart. There are two ways to gain access to the chart, either directly via the chart source code, or by adding the remote repository:

$ helm repo add identos https://charts.dev.identos.ca

It should then show up with the command:

$ helm repo list

Finally, to install the Helm chart, run the following command:

$ helm upgrade --install fpx identos/fpxcore -f configuration.yaml --version v2.1.4

During the installation, the components network will be deployed. Installation is complete when you run the following command and all deployments are ready, up-to-date and available (the numbers may differ based on the configuration applied):

$ kubectl get deployments
NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
fpx-authapi          1/1     1            1           2m6s
fpx-authserver       1/1     1            1           2m6s

Assuming that ingress objects were enabled as part of the installation, the deployed HTTP endpoints can be shown:

$ kubectl get ing
NAME                 HOSTS                                  ADDRESS   PORTS     AGE
fpx-authapi          authapi.example.com                    80, 443   6m6s
fpx-authserver       idnserver.example.com                  80, 443   6m6s

Configuration for a Helm chart is provided as a YAML formatted file. The following table lists the configuration parameters, a description and their default values.

note

The first half of the table defines configuration parameters for the Authorization Server and the second half focuses on the parameters for Authorization Server API.

Server Helm Chart Config

Parameter	Description	Default
authorizationServer.enabled	If an Authorization Server should be deployed.	true
authorizationServer.replicaCount	Number of replicas to deploy of the Authorization Server, set to a number > 1 for redundancy purposes.	1
authorizationServer.image.credentials	Name of the secret within the deploy namespace that contains the credentials for the container image.	identos
authorizationServer.image.repository	The repository URL for the container image.	null
authorizationServer.image.tag	The specific tag/version of the docker image.	null
authorizationServer.image.pullPolicy	Pod container pullPolicy setting, see https://kubernetes.io/docs/concepts/containers/images/ for details.	Always
authorizationServer.ingress.enabled	Boolean value enabling or disabling the creation of an ingress record.	false
authorizationServer.ingress.annotations	Any custom annotations for this ingress record.	{}
authorizationServer.ingress.host	Hostname with which an ingress record can be configured.	null
authorizationServer.application.config	Full application configuration for the FPX Authorization Server. Click here for details.	""
authorizationServer.application.enableHTTPS	Setting this value to 'true' will enable full end-to-end TLS encryption to application container.	true
authorizationServer.application.port	TCP Port that application will be listening on.	8080
authorizationServer.extraEnv	Extra environment variables to inject into container.	{}
authorizationServer.nodeSelector	Node selector rules.	{}
authorizationServer.tolerations	Any node taints to tolerate.	{}
authorizationServer.affinity	Any resource affinities for node selection.	{}
authorizationServer.refresh	Useful parameter to force application to restart when new configurations are applied.	1
authorizationServer.deployment.annotations	This will discover deploymentconfigs/deployments/daemonsets/statefulset/rollouts automatically.	null
authorizationServer.ingress.tls.hosts	Hostname of the environment.	null
authorizationServer.keystores.https.alias	The alias (or name) under which the key is stored in the keystore. This needs to be in a base64 encoded format. Refer to the Keystore Creation and Configuration section for details.	null
authorizationServer.keystores.https.enabled	Enable HTTPS.	true
authorizationServer.keystores.https.jwks	The key itself as a md5 encoded PKCS12 KeyStore. This needs to be in a base64 encoded format. Refer to the Keystore Creation and Configuration section for details.	null
authorizationServer.keystores.https.password	The password of the keystore. This needs to be in a base64 encoded format. Refer to the Keystore Creation and Configuration section for details.	null
authorizationServer.keystores.signingKey.enable	Key used for signing/verifying.	null
authorizationServer.suffix	Suffix value for the Auth API application.	null

Admin API Helm Chart Config

Parameter	Description	Default
authorizationApi.enabled	If an Authorization Server should be deployed.	true
authorizationApi.replicaCount	Number of replicas to deploy of the Authorization Server, set to a number > 1 for redundancy purposes.	1
authorizationApi.image.credentials	Name of the secret within the deploy namespace that contains the credentials for the container image.	identos
authorizationApi.image.repository	The repository URL for the container image.	null
authorizationApi.image.tag	The specific tag/version of the docker image.	null
authorizationApi.image.pullPolicy	Pod container pullPolicy setting, see https://kubernetes.io/docs/concepts/containers/images/ for details.	Always
authorizationApi.ingress.enabled	Boolean value enabling or disabling the creation of an ingress record.	false
authorizationApi.ingress.annotations	Any custom annotations for this ingress record.	{}
authorizationApi.ingress.host	Hostname to configure the ingress record with.	null
authorizationApi.application.config	Full application configuration for the FPX Authorization Server. Click here for details	""
authorizationApi.application.enableHTTPS	Full end-to-end TLS encryption to application container.	true
authorizationApi.application.port	TCP Port that application will be listening on.	8080
authorizationApi.extraEnv	Extra environment variables to inject into container.	{}
authorizationApi.nodeSelector	Node selector rules.	{}
authorizationApi.tolerations	Any node taints to tolerate.	{}
authorizationApi.affinity	Any resource affinities for node selection.	{}
authorizationApi.refresh	Useful parameter to force application to restart when new configurations are applied.	1
authorizationApi.ingress.tls.hosts	Hostname of the environment.	null
authorizationApi.ingress.tls.secretName	Refers to the SSL certificates required for HTTPS.	null
authorizationApi.keystores.https.alias	The alias (or name) under which the key is stored in the keystore. This needs to be in a base64 encoded format. Refer to the Keystore Creation and Configuration section for details.	null
authorizationApi.keystores.https.enabled	Enable HTTPS.	true
authorizationApi.keystores.https.jwks	The key itself as a md5 encoded PKCS12 KeyStore. This needs to be in a base64 encoded format. Refer to the Keystore Creation and Configuration section for details.	null
authorizationApi.keystores.https.password	The password of the keystore. This needs to be in a base64 encoded format. Refer to the Keystore Creation and Configuration section for details.	null
authorizationApi.keystores.signingKey.enable	Key used for signing/verifying.	null
authorizationApi.suffix	Suffix value for the Authorization Server API.	null
authorizationApi.deployment.annotations	Allows you to add custom annotations to the deployment object.	null

Keystore Creation and Config

The Authorization Server deployment configuration YAML consists of several parameters that address keystore values. The keystore is used to store the custom signing encryption keys for the Authorization Server and the Authorization Server API. The parameters used to define keystore related values are:

• authorizationServer.keystores.https.alias
• authorizationServer.keystores.https.enabled
• authorizationServer.keystores.https.jwks
• authorizationServer.keystores.https.password
• authorizationServer.keystores.signingKey.enable
• authorizationApi.keystores.https.alias
• authorizationApi.keystores.https.enabled
• authorizationApi.keystores.https.jwks
• authorizationApi.keystores.https.password
• authorizationApi.keystores.signingKey.enable

In order to populate the alias, JWKS key and password parameters, the following steps need to be executed:

1) Generate a keystore and alias key.

2) Apply base64 encoding for the alias name, password and JWKS key.

3) Update these base64 encoded values into the YAML config file.

To generate the key and the keystore, run the following command:

keytool -genkey -v -keystore AS.jks -alias <custom_alias> -keyalg RSA -sigalg SHA256withRSA -keysize 2048  -ext KeyUsage=keyCertSign -validity 10000

IMPORTANT

IMPORTANT: The Keystore alias defined should always be in lower case. The alias can be of alpha-numeric characters only.

To apply the base64 encoding for the alias name, password and JWKS key, run the following commands:

• echo <alias name> | base64
• echo <password> | base64
• echo <JWKS Key> | base64

These commands will return the values in the base64 encoded format. Enter the encoded values in the configuration parameters listed above.

note

For production environments, it is recommended that individual keystores and key values exist for the Authorization Server and the Authorization Server API parameters.

Authorization Server Application Config

The authorizationServer.application.config Helm chart property group contains multiple sub-parameters that are essential for the proper configuration and set up of the Authorization Server. Below is a sample code block illustrating the common values defined in authorizationServer.application.config, followed by tables that provide details and descriptions for each sub-parameter.

server.port: 8080
server.tomcat.remote_ip_header: x-forwarded-for
server.tomcat.protocol_header: x-forwarded-proto
server.error.whitelabel.enabled: false

jwt:
  keystore:
    signerAlg: RS256

i18n:
  defaultLang: en
  allLanguages: fr, en, es
  basename: classpath:./i18n/messages
  cacheEvictFixedRateString: PT8H

logging:
  level:
    com.identos.idn: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.type: TRACE
  location: ../logs

spring:
  main:
    allow-bean-definition-overriding: true
  thymeleaf:
    prefix: classpath:./templates/
  mvc:
    throw-exception-if-no-handler-found: true
    pathmatch.matching-strategy: ant_path_matcher
  web:
    resources:
      add-mappings: false
  jackson:
    serialization.fail-on-empty-beans: false
    mapper.default-view-inclusion: true
  session:
    store-type: jdbc
    jdbc:
      initialize-schema: always
      table-name: SPRING_SESSION
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://fpx-staging-fpx-mysql.fpx-staging.svc.cluster.local/authserver?useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC
    username: root
    password: password
  jpa:
    open-in-view: false
    hibernate:
      dialect: org.hibernate.dialect.MySQL5InnoDBDialect
      show_sql: false
      generate_ddl: true
      ddl-auto: validate
      naming.physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
  flyway:
    locations: classpath:db/migration,classpath:db/development


as-server-domain: https://authserver.fpx-staging.dev.identos.ca


uma:
  wellknown:
    issuer: ${as-server-domain}


oauth2-config:
  client:
    callback_endpoint: /oauth2/callback
  provider:
    issuer: ${as-server-domain}
    register_endpoint: /oauth2/register
    authorize_endpoint: /oauth2/authorize
    token_endpoint: /oauth2/token
    token_revocation_endpoint : ${oauth2-config.provider.token_endpoint}/revoke
    jwks_endpoint: /jwks
    configuration_endpoint: /.well-known/openid-configuration
    account_endpoint: /account
    web_authn_endpoint: /authenticate
    introspection_endpoint: /oauth2/introspect
    userinfo_endpoint: /api/userinfo
    fetch_and_attach_userinfo: true
    consent_endpoint: /discover/consent
    consent_view_page: oidc_authorize
    custom_grant_types:
      - test
      - anotherone


oidc-config:
  client:
    clientDomain: ${as-server-domain}
    responseType: id_token
    scope: "openid"
    callback_endpoint: ${oauth2-config.client.callback_endpoint}


uma-config:
  issuer: ${as-server-domain}
  registrationEndpoint: ${oauth2-config.provider.register_endpoint}
  configurationEndpoint: /.well-known/uma2-configuration
  jwksEndpoint: /jwks
  tokenEndpoint: /transaction/token
  introspectionEndpoint: ${oauth2-config.provider.introspection_endpoint}
  claimsGatheringEndpoint: /transaction/claims-gathering
  revocationEndpoint: /transaction/revocation
  capabilityEndpoint: /transaction/capability
  permissionEndpoint: /transaction/permission
  grantTypesSupported:
    - client_credentials
    - urn:ietf:params:oauth:grant-type:uma-ticket
    - refresh_token
  authzEndpoint: ${oauth2-config.provider.authorize_endpoint}
  callbackEndpoint: ${oauth2-config.client.callback_endpoint}
  permissionUpdateEndpoint: /permission
  permissionAccessTokenEndpoint: ${uma-config.permissionUpdateEndpoint}/token


smart-config:
  enabled: true
  implicitFlowEnabled: false
  issuer: ${as-server-domain}
  registration_endpoint: ${oauth2-config.provider.register_endpoint}
  authorization_endpoint: ${uma-config.authzEndpoint}
  wellknown:
    basePath: /oauth2/.well-known
    configuration_endpoint: /openid-configuration
    jwks_endpoint: /jwks
  token_endpoint: ${uma-config.tokenEndpoint}
  introspection_endpoint: ${uma-config.introspectionEndpoint}
  launch:
    resourceTypePattern: ((http|https)://){0,1}(www.){0,1}hl7.org/fhir/smart-app-launch/scopes-and-launch-context/index.html
    resourceTypeURL: http://hl7.org/fhir/smart-app-launch/scopes-and-launch-context/index.html
    resourceDefinitionTypePattern: https://www.hl7.org/fhir/[RESOURCE_TYPE].html


# FPX specific configuration + configuration shared between multiple protocols

fpx-config:
  versionEndpoint: /.well-known/fpx/version
  wallet:
    walletSelectPage: /select-wallet
    walletSelectSubmitEndpoint: /submit-broker
    rememberWalletFeatureEnabled: false
  registry:
    basePath: /registry
    clients:
      walletEndpoint: /wallet
      umaClientEndpoint: /client
      rsEndpoint: /resource-server
      idpEndpoint: /identity-provider
    resources:
      resourceEndpoint: /resource
      resourceDefinitionEndpoint: ${fpx-config.registry.resources.resourceEndpoint}/resource_definition
      ticketEndpoint: /ticket
  resources:
    select-wallet:
      css: style.css
      logo: logo


fpx:
  oidc:
    client:
      stateSessionKey: fpx-csrf-key
      ignoreCsrfCheck: false
      pkce:
        enforced: false
    provider:
      self-hosted:
        enabled: true
      federated:
        enabled: false
        federated_issuer: {OIDC Provider}
      uma:
        enabled: true
      JWT-token:
        enabled: true
      jwt:
        defaultKeyId: rsa1
      pkce:
        enforced: false
      revoke-token:
        enabled : true
  security:
    authority:
      introspection: uma_protection     


default:
  expiry-duration-params:
    resourceDefinitionExpirySeconds: 1800000
    accessTokenLifetimeSeconds: 300
    refreshTokenLifetimeSeconds: 1800000
    accountSessionTokenLifetimeInSeconds: 3600000000
    agentOidcRequestLifetimeInSeconds : 25920000
    patAccessTokenLifetimeInSeconds: 5000
  length-params:
    permissionTokenLength: 16
    capabilityLength: 20
    accountSessionTokenLength: 24
    umaRequestIdLength: 24


app:
  name: Identos
  logo: identos.png
  error-page-redirect-url: ${as-server-domain}
  error-page-title: Error

Global Server Parameters

Configuration directives that are used for overall application configuration.

Parameter	Description	Suggested Value	Required
server.port	Application port to listen for client connections on.	8080	Yes
server.tomcat.remote_ip_header	Header to use as remote IP address for client connections.	x-forwarded-for	No
server.tomcat.protocol_header	Header to use as remote protocol for client connections.	x-forwarded-proto	No
server.error.whitelabel.enabled	Whether the server will display a generic error page	false	No
jwt.keystore.signerAlg	The algorithm to use when signing JWTs	RS256	Yes

Localization

Configuration directives for localization support.

Parameter	Description	Suggested Value	Required
i18n.defaultLang	Default language used for localization.	en	Yes
i18n.allLanguages	Comma separated list of language strings to support localization for i.e. "en, fr".	en	Yes
i18n.basename	Location for localization strings to use in static template files.	classpath:./i18n/messages	Yes
i18n.cacheEvictFixedRateString:	Defines the frequency for cached localized string (locale,key) to be evicted and re-located from a source.	PT8H	No

Logging

Parameter	Description	Suggested Value	Required
logging	See https://docs.spring.io/spring-boot/docs/2.3.5.RELEASE/reference/html/spring-boot-features.html#boot-features-logging for logging customizations.	null	No
logging.level.com.identos	Controls the level at which the application's configured loggers will be permitted to log. This applies only to loggers that exist in a package that begins with "com.identos".	DEBUG	No. If not set, defaults to INFO level
logging.config	Sets the configuration file for application logging. This value will output structured logs in compressed, single-line JSON format. To view the logs in a human-readable format (i.e. for development purposes), this value can be set to classpath:logback-dev.xml.	classpath:logback-spring.xml	No. If not set, defaults to classpath:logback-spring.xml.

Spring Framework Properties

Configuration for the Spring framework. Additional information on these properties can be found here.

Parameter	Description	Suggested Value	Required
spring.main.allow-bean-definition-overriding	Whether the Spring Framework allows existing Bean definitions to be overridden by new Beans with the same name.	true	Yes
spring.thymeleaf.prefix	Location of template files for Wallet selection and error pages. Can use external sources such as https://	classpath:./templates/	Yes
spring.mvc.throw-exception-if-no-handler-found	Returns an exception for 404 errors and allows the administrator to define a custom response	true	Yes
spring.mvc.pathmatch.matching-strategy	This parameter is related to the spring.web.resources.add-mappings parameter and enables mapping via an ant path.	ant_path_matcher	Yes
spring.web.resources.add-mappings	Defines whether to use spring default resource mappings - default mappings have been replaced with specifically configured mappings	false	Yes
spring.jackson.serialization.fail-on-empty-beans	If enabled or set to 'true', an exception is thrown to indicate empty objects as non-serializable types; if disabled (false), they are serialized as empty Objects, i.e. without any properties.	false	Yes
spring.jackson.mapper.default-view-inclusion	All properties not explicitly marked as being part of a JSON view, are serialized.	true	Yes

Database Configuration

Database configuration for the authorization server.

Parameter	Description	Suggested Value	Required
spring.session.store-type	Session store type.	jdbc	No
spring.session.jdbc.initialize-schema	Database schema initialization mode.	always	No
spring.session.jdbc.table-name	Name of the database table used to store sessions.	SPRING_SESSION	No
spring.datasource.driver-class-name	Driver to use for DB connections (only mysql supported).	com.mysql.cj.jdbc.Driver	Yes
spring.datasource.url	Connection string to use for DB connections.	jdbc:mysql://database-hostname/authserver	Yes
spring.datasource.username	Username for database connection.	username	Yes
spring.datasource.password	Password for database connection.	password	Yes
spring.jpa.open-in-view	Enable/Disable Spring open in view.	false	Yes
spring.jpa.hibernate.dialect	Spring hibernate dialect (only MySQL supported).	org.hibernate.dialect.MySQL5InnoDBDialect	Yes
spring.jpa.hibernate.show_sql	Show all SQL queries that are run against the database source in the logs.	false	No
spring.jpa.hibernate.generate_ddl	A flag that determines whether a SQL Database should be initialized at start-up.	true	Yes
spring.jpa.hibernate.ddl-auto	There are two options to manage the underlying database schema when working with JPA and Hibernate (leveraged by all backend IDENTOS components): 1) You can encapsulate schema changes in migration scripts and use a tool, like Flyway, to apply the migration scripts upon starting the application. This is the method we will use to generate and update the schema for the authorization server and the Admin Server. 2) You can generate or update the database schema from the JPA and Hibernate entity mappings (extrapolate the domain classes/entity mappings of the deployed server and auto generate the database schema) the using the hbm2ddl.auto tool. We will not use this method to generate the schema for any of the components. This is why the value for this field should be set to "validate" as this option instructs Hibernate to ONLY validate the underlying database schema against the entity mappings.	validate	Yes
spring.flyway.locations	Location for DB migration scripts.	classpath:db/migration,classpath:db/development	Yes

OAuth 2 Configuration Settings

Configuration parameters required to successfully set up the OAuth 2 protocol.

Parameter	Description	Suggested Value	Required
oauth2-config.client.callback_endpoint	Endpoint used on callbacks with the Authorization Server in its role as an OAuth client.	/oauth2/callback	Yes
oauth2-config.provider.issuer	Issuer URL used by the Authorization Server for the OAuth 2 protocol.	AS Server Domain Name	Yes
oauth2-config.provider.register_endpoint	Endpoint for Dynamic Client Registration.	/oauth2/register	Yes
oauth2-config.provider.authorize_endpoint	Defines the OAuth 2 authorization endpoint of the Authorization Server. It needs to be appended to the issuer URL defined in the parameter above.	/oauth2/authorize	Yes
oauth2-config.provider.token_endpoint	URL of the Authorization Server's token endpoint.	/oauth2/token	Yes
oauth2-config.provider.jwks_endpoint	URL of the Authorization Server's JWK Set document, containing the signing keys the client uses to validate signatures from the Authorization Server.	/jwks	Yes
oauth2-config.provider.configuration_endpoint	Path to OIDC configuration endpoint.	/.well-known/openid-configuration	Yes
oauth2-config.provider.account_endpoint	Path to OIDC account endpoint.	/account	Yes
oauth2-config.provider.web_authn_endpoint	Path to OIDC web authentication endpoint.	/authenticate	Yes
oauth2-config.provider.introspection_endpoint	URL of the Authorization Server's OAuth 2.0 introspection endpoint.	/oauth2/introspect	Yes
oauth2-config.provider.userinfo_endpoint	URL of the Authorization Server's userinfo endpoint.	/api/userinfo	Yes
oauth2-config.provider.fetch_and_attach_userinfo	Whether to fetch and attach userinfo.	true	Yes
oauth2-config.provider.consent_endpoint	URL of the Authorization Server's OIDC consent endpoint.	/discover/consent	Yes
oauth2-config.provider.consent_view_page	Identifier of the HTML template to use when displaying the consent page.	oidc_authorize	Yes
oauth2-config.provider.custom_grant_types	Custom grant types may be specified here.		No
oauth2-config.provider.token_revocation_endpoint	Path to token revocation API if enabled	${oauth2-config.provider.token_endpoint}/revoke	No

OIDC Configuration Settings

OIDC configuration settings including both client / server settings.

Parameter	Description	Suggested Value	Required
oidc-config.client.clientDomain	This must be set to the host address of the Authorization Server itself. This, along with the value set for oidc-config.client.callbackEndpoint are appended to build the redirect URI parameter as part of its OIDC transaction with the Wallet Server (an OIDC relationship where Wallet Server is the provider to the Authorization Server).	https://authorizationserver.com	Yes
oidc-config.client.responseType	OIDC response type on successful token endpoint call. Suggested value causes an id_token return at the token endpoint.	id_token	Yes
oidc-config.client.scope	Scope applied to the initial OAuth authorize call made by the Authorization Server to the Wallet to create an outgoing identity request - enabling user to log in to FPX.	openid	Yes
oidc-config.client.callbackEndpoint	Path to OIDC callback endpoint for generating an authorization code after authentication.	/transaction/callback	Yes

Application Settings

General application settings that are relate to html pages served directly from the Authorization Server, such as error pages.

Parameter	Description	Suggested Value	Required
app.name	Name of the application displayed on the error page.	Sample Application	No
app.logo	Filename of the image to be used as the application logo.	logo.png	No
app.error-page-redirect-url	Redirect URL when redirecting from the default error page.	Yes
app.error-page-title	Name of the error page as displayed on the error page header.	Error	No

UMA Configuration Settings

UMA configuration settings including endpoint and supported grant types.

Parameter	Description	Suggested Value	Required
uma-config.issuer	Issuer of tokens generated by the server, should be the location of the Authorization Server itself.	https://authorizationserver.com	Yes
uma-config.registrationEndpoint	Path to UMA registration endpoint.	/register	Yes
uma-config.configurationEndpoint	Path to UMA configuration discovery endpoint.	/.well-known/uma2-configuration	Yes
uma-config.jwksEndpoint	Path to UMA JWKS endpoint.	/jwks	Yes
uma-config.tokenEndpoint	Path to UMA token introspection endpoint.	/transaction/introspect	Yes
uma-config.introspectionEndpoint	Path to UMA introspection endpoint.	/transaction/introspect	Yes
uma-config.claimsGatheringEndpoint	Path to UMA claims gathering endpoint.	/transaction/claims-gathering	Yes
uma-config.revocationEndpoint	Path to UMA revocation endpoint.	/transaction/revocation	Yes
uma-config.capabilityEndpoint	Path to UMA capability endpoint.	/transaction/capability	Yes
uma-config.permissionEndpoint	Path to UMA permissions endpoint.	/transaction/permission	Yes
uma-config.grantTypesSupported	Grant types supported.	["client_credentials", "urn:ietf:params:oauth:grant-type:uma-ticket", "refresh_token"]	Yes
uma-config.authzEndpoint	Path to UMA authorization endpoint.	/transaction/authorize	Yes
uma-config.callbackEndpoint	Path to UMA callback endpoint.	/transaction/callback	Yes
uma-config.permissionUpdateEndpoint	Path to UMA permission update endpoint.	/permission	Yes
uma-config.permissionAccessTokenEndpoint	Path to UMA permission token endpoint.	/permission/token	Yes

SMART on FHIR Configuration Settings

Parameter	Description	Suggested Value	Required
smart-config.enabled	SMART on FHIR enabled flag	true	Yes
smart-config.issuer	SMART on FHIR token issuer, should be the URL to the Authorization Server.	https://authorizationserver.com	Yes
smart-config.registration_endpoint	SMART on FHIR registration endpoint.	/register	Yes
smart-config.authorization_endpoint	SMART on FHIR authorize endpoint.	/oauth2/authorize	Yes
smart-config.wellknown.basepath	Base path for SMART on FHIR well known path.	/oauth2/.well-known	Yes
smart-config.wellknown.configuration_endpoint	Path to OAuth 2.0 configuration discovery endpoint. This is appended to {smart-config.wellknown.basepath}	/openid-configuration	Yes
smart-config.wellknown.jwks_endpoint	SMART on FHIR JWKS endpoint.	/jwks	Yes
smart-config.token_endpoint	SMART on FHIR token endpoint.	/transaction/token	Yes
smart-config.introspection_endpoint	SMART on FHIR introspection endpoint.	/transaction/introspect	Yes
smart-config.launch.resourceTypePattern	The REGEX pattern with which SMART resources' type parameter must conform to.	((http	https)://){0,1}(www.){0,1}hl7.org/fhir/smart-app-launch/scopes-and-launch-context/index.html
smart-config.launch.resourceTypeURL	Static resource type of the SMART launch resource, shared when attempting to access information in order to use a SMART on FHIR app.	http://hl7.org/fhir/smart-app-launch/scopes-and-launch-context/index.html	Yes

FPX Server Configuration Settings

Base Authorization Server configuration, including registry endpoints and Wallet usage configuration.

Parameter	Description	Suggested Value	Required
fpx-config.versionEndpoint	Endpoint to display the FPX version.	/.well-known/fpx-version	Yes
fpx-config.wallet.walletSelectPage	Endpoint to display the Wallet selection template page.	/select-wallet	Yes
fpx-config.wallet.walletSelectSubmitEndpoint	Endpoint where the Wallet selection template page will be submitted.	/submit-broker	Yes
fpx-config.wallet.rememberWalletFeatureEnabled	Enable or disable the remember wallet feature within the selection template.	false	Yes
fpx-config.registry.basePath	Base path for all registry endpoints.	/registry	Yes
fpx-config.registry.clients.walletEndpoint	Registry endpoint for Wallets.	/wallet	Yes
fpx-config.registry.clients.umaClientEndpoint	Registry endpoint for UMA clients.	/client	Yes
fpx-config.registry.clients.rsEndpoint	Registry endpoint for resource servers.	/resource-server	Yes
fpx-config.registry.clients.idpEndpoint	Registry endpoint for identity providers.	/identity-provider	Yes
fpx-config.registry.resources.resourceEndpoint	Registry endpoint for resources.	/resource	Yes
fpx-config.registry.resources.resourceDefinitionEndpoint	Registry endpoint for resource definitions.	/resource/resource_definition	Yes
fpx-config.registry.resources.ticketEndpoint	Registry endpoint for tickets.	/ticket	Yes

Parameter	Description	Suggested Value	Required
fpx.oidc.client.stateSessionKey	Key to use for session state parameter.	fpx-csrf-key	Yes
fpx.oidc.client.ignoreCsrfCheck	Defines whether to not perform a cross-site request forgery check.	false	Yes
fpx.oidc.client.pkce.enforced	Defines whether to enforce the use of proof key for code exchange.	false	Yes
fpx.oidc.provider.self-hosted.enabled	Defines whether the Authorization Server will act as an identity provider.	true	Yes
fpx.oidc.provider.federated.enabled	Defines whether the Authorization Server will federate to an external identity provider.	false	Yes
fpx.oidc.provider.federated.federated_issuer	The issuer URL to use when the federation setting is enabled	{OIDC Provider}	Yes
fpx.oidc.provider.uma.enabled	Defines whether the Authorization Server will use UMA protocol.	true	Yes
fpx.oidc.provider.JWT-token.enabled	Defines whether the Authorization Server will use JWTs.	true	Yes
fpx.oidc.provider.jwt.defaultKeyId	The default ID key for the JWT.	rsa1	Yes
fpx.oidc.provider.pkce.enforced	Defines whether to enforce the use of proof key for code exchange.	false	Yes
fpx.security.authority.introspection	Granted authority to use for introspection.	uma_protection	Yes
fpx.oidc.provider.revoke-token.enabled	Defines whether clients are able to Revoke access tokens and refresh tokens	true	No, default true

Server defaults and expiry values

Basic defaults including token length and expiry for those same tokens.

Parameter	Description	Suggested Value	Required
default.expiry-duration-params.resourceDefinitionExpirySeconds	Resource definition maximum expiry when shared in seconds.	1800000	Yes
default.expiry-duration-params.accessTokenLifetimeSeconds	Access token expiry in seconds.	300	Yes
default.expiry-duration-params.refreshTokenLifetimeSeconds	Refresh token expiry in seconds.	300	Yes
default.expiry-duration-params.accountSessionTokenLifetimeInSeconds	Account session token expiry in seconds.	3600000000	Yes
default.expiry-duration-params.agentOidcRequestLifetimeInSeconds	Wallet OIDC request expiry in seconds.	25920000	Yes
default.expiry-duration-params.patAccessTokenLifetimeInSeconds	Permission access token expiry for Resource Servers in seconds.	5000	Yes
default.length-params.permissionTokenLength	String length of the randomly generated IDs of permissions.	16	Yes
default.length-params.capabilityLength	String length of the randomly generated IDs of capabilities.	20	Yes
default.length-params.accountSessionTokenLength	String length of the randomly generated IDs of account session tokens.	24	Yes
default.length-params.umaRequestIdLength	String length of the randomly generated IDs of UMA requests.	24	Yes

Authorization Server Admin API Application Config

The authorizationApi.application.config parameter is used to define the main elements for the Authorization Server API - the administrative API for the Authorization Server. Without clearly defining these parameters, the setup of the AS API will fail and limit the integration of the other parties with the Authorization Server.

Below is a sample code block illustrating the common values defined in authorizationApi.application.config followed by a table that provides details and descriptions for each sub-parameter. The most important configuration is to ensure that the Authorization Server API database section points to the same database as the Authorization Server.

Note that the values shown for spring.datasource.username and spring.datasource.password are placeholders and should be replaced with credentials for the specific database used in your deployment.

server.port: 8080
server.error.include-binding-errors: ALWAYS
server.error.include-exception: true
server.error.include-message: ALWAYS
server.error.include-stacktrace: ALWAYS

management:
  endpoint:
    health:
      livenessState.enabled: true
      readinessState.enabled: true
      probes:
        enabled: true
  endpoints:
    web:
      exposure:
        include: "health"

logging:
  level:
    com.sbic.idn: DEBUG
    org.springframework.web: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.type: TRACE

spring.jpa.properties.hibernate.format_sql: true

as-admin:
  staticTokens: 
    - {{AS_ADMIN_STATIC_TOKEN}}
    - {{ANOTHER_AS_ADMIN_STATIC_TOKEN}}

spring:
  session:
    store-type: jdbc
    jdbc:
      initialize-schema: always
      table-name: SPRING_SESSION   
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://fpx-staging-fpx-mysql.fpx-staging.svc.cluster.local:3306/authserver
    username: {{DATABASE_USERNAME}}
    password: {{DATABASE_PASSWORD}}
  output.ansi.enabled: ALWAYS
  jpa:
    generate-ddl: false
    hibernate:
      ddl-auto: validate
      show-sql: true
      naming.physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl

elide:
  modelPackage: 'com.sbic.idn.entity'
  pageSize: 1000
  maxPageSize: 10000
  json-api:
    path: /json-api
    enabled: true
  graphql:
    path: /graphql/api/v1
    enabled: false
  swagger:
    path: /json-api/openapi
    enabled: true
    version: "v1.0"
    name: AuthServer Admin API

Spring Actuator Configuration

Make the following configurations to enable Spring Actuator and monitor the health of the Authorization Server. By default, these

Parameter	Description	Suggested Value	Required
management.endpoint.health.livenessState.enabled	This parameter configures whether the liveness state health check is enabled or not.	true	No
management.endpoint.health.readinessState.enabled	This parameter configures whether the readiness state health check is enabled or not.	true	No
management.endpoint.health.probes.enabled	This parameter configures whether the liveness and readiness probes are enabled or disabled. The value should be in Boolean, which means when the value is set to "true", the health probes will be enabled. This parameter is inter-related to the management.endpoint.health.livenessState.enabled and management.endpoint.health.readinessState.enabled parameters described above which means that the value of one of these parameters along with the value of management.endpoint.health.probes.enabled must be set to true for the functionality to work.	true	No
endpoints.web.exposure.include	There are various actuator endpoints that allow us to monitor and interact with the application. Each endpoint can be enabled and disabled individually. This parameter allows us to configure the specific actuator endpoint that we need enabled. In this case, the "health" endpoint is being enabled to get information on the health of the application.	health	No

Logging and Response Output

These settings control what should be logged and at what level of detail, as well as the information returned in Authorization Server Admin API error responses. Because this is an Admin API, we are not concerned with stack traces and application internals being returned in responses. Therefore, these can be left as default for the majority of use cases.

Parameter	Description	Suggested Value	Required
server.error.include-binding-errors	The server will not be prevented from including binding errors in error response payloads.	ALWAYS	No
server.error.include-exception	The server will not be prevented from including exceptions in error response payloads.	true	No
server.error.include-message	The server will not be prevented from including messages in error response payloads.	ALWAYS	No
server.error.include-stacktrace	The server will not be prevented from including stack traces in error response payloads.	ALWAYS	No
logging.level.com.sbic.idn	Controls the level at which the Authorization Server Admin API logs will be output.	DEBUG	No
logging.level.org.springframework.web	Controls the level at which the Spring framework Web logs will be output.	DEBUG	No
logging.level.org.hibernate.SQL	Controls the level at which the Hibernate framework SQL logs will be output.	DEBUG	No
logging.level.org.hibernate.type	Controls the level at which the Hibernate framework SQL binding type logs will be output.	DEBUG	No
spring.jpa.properties.hibernate.format_sql	This will format the SQL that is output to the logs to make it more readable.	true	No

Authentication Token Configuration

Parameter	Description	Suggested Value	Required
as-admin.staticTokens	Defines an array of values for static authorization tokens. The Authorization Server Admin API will expect one of these values to be included as an Authorization header on all requests.	a UUID	Yes

Database Configuration

Database configuration for the Authorization Server API.

Parameter	Description	Suggested Value	Required
spring.session.store-type	Session store type.	jdbc	No
spring.session.jdbc.initialize-schema	Database schema initialization mode.	always	No
spring.session.jdbc.table-name	Name of the database table used to store sessions.	SPRING_SESSION	No
spring.datasource.driver-class-name	MySQL Driver name.	com.mysql.cj.jdbc.Driver	Yes
spring.datasource.url	Driver to use for DB connections.	jdbc:mysql://fpx-staging-fpx-mysql.fpx-staging.svc.cluster.local:3306/authserver	Yes
spring.datasource.username	Username for database connection.	root	Yes
spring.datasource.password	Password for database connection.	password	Yes
spring.jpa.hibernate.dialect	Spring hibernate dialect (only MySQL supported).	org.hibernate.dialect.MySQL5InnoDBDialect	Yes
spring.jpa.generate-ddl	A flag that determines whether a SQL Database should be initialized at start-up.	false	Yes
spring.jpa.hibernate.ddl-auto	There are two options to manage the underlying database schema when working with JPA and Hibernate (leveraged by all backend IDENTOS components): 1) You can encapsulate schema changes in migration scripts and use a tool, like Flyway, to apply the migration scripts upon starting the application. This is the method we will use to generate and update the schema for the authorization server and the Admin Server. 2) You can generate or update the database schema from the JPA and Hibernate entity mappings (extrapolate the domain classes/entity mappings of the deployed server and auto generate the database schema). We will not use this method to generate the schema for any of the components. This is why the value for this field should be set to "validate" as this option instructs Hibernate to ONLY validate the underlying database schema against the entity mappings.	validate	Yes

JSON API Configuration

The parameters under the elide section are used to expose JSON APIs and configure their URL paths. IDENTOS recommends that these be left at the default values. For more information, refer to Elide Setup.