Configurations for RSA OIDC Adapter

RSA-OIDC Application Config

In the application Helm chart, the spec.values.application.config parameter is used to define the main elements for the RSA Admin API. Without clearly defining these parameters, the setup of the RSA Admin API will fail and limit the integration of the other parties with the RSA.

Below is a sample code block illustrating the common values defined in spec.values.application.config followed by tables that provide details and descriptions for each sub-parameter.

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.

Configuration Details

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.servlet.session.cookie.http-only	Whether to use "HttpOnly" cookies for the cookie. Controls whether cookies issued by the server are accessible by scripts running on the user agent (browser). If this value is true, cookies are not accessible by scripts, and will only be used by the browser's HTTP routines	This MUST be set to 'true' for security measures as it follows best practice principles.	Yes
server.servlet.session.secure	Whether to always mark the cookie as secure. This means the cookie will only be sent over HTTPS connections	This MUST be set to 'true' for security measures as it follows best practice principles.	Yes

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.		No
logging.level.com.identos	Controls the level at which the application's configured loggers will be permitted to log.	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

OAuth2 Client Configuration

Parameter	Description	Suggested Value	Required
oauth2-config.client.auth_jwt_expiry	This is the client_assertion JWT expiry value in milliseconds. When generating a token request with private_key_jwt or client_secret_jwt authentication methods, a separate client_assertion JWT is needed to complete the token request. The expiry value defined here applies to this token and starts from the moment the token is created.	6000 (default)	No
oauth2-config.client.callback_endpoint	The Callback URI is where the Federated Provider will redirect the flow after they authorize (or deny) the RSA, and therefore the part of the RSA that will handle authorization codes or access tokens.	/oidc/callback (default)	No

OAuth2 Provider Configuration

Parameter	Description	Suggested Value	Required
oauth2-config.provider.issuer	Issuer URL when acting as an OIDC provider	This should be the same as your server's ingress hostname. See ingress.host in the "Common Helm Chart Properties" section.	Yes
oauth2-config.provider.registration_endpoint	Path to OIDC register endpoint.	/register	No
oauth2-config.provider.authorize_endpoint	The authorization endpoint is used to interact with the resource owner and get the authorization to access the protected resource. This endpoint is usually consumed by the Wallet in an FPX instance to enable users to kickstart creating a connection at the RSA	/discover/authorize	No
oauth2-config.provider.token_endpoint	The token endpoint is used by the Wallet (an OIDC client) in order to get an access token or a refresh token. The access token contains details that denote who has authorized which permissions (scopes) to which application.	/discover/token	No
oauth2-config.provider.jwks_endpoint	The endpoint where the RSA's JSON Web Key Set (JWKS) can be queried.	/jwks	No
oauth2-config.provider.introspection_endpoint	The endpoint available for introspecting tokens generated by the RSA. Within the FPX ecosystem, the introspection_endpoint can be used if the Wallet Server introspects the access token received from the RSA when gaining access/connecting to the RSA.	/oauth2/introspect	No
oauth2-config.provider.user_info_issuer	This value should be set to the user-info issuer. In the RSA’s case, it is the same as the issuer_url.	https://rsa-oidc.test.identos.ca	Yes
oauth2-config.provider.userinfo_endpoint	A protected endpoint to retrieve the user info of the user who logged in to the RSA. This endpoint is used to retrieve the necessary user info requested by the Wallet Server. A Valid OAuth Access Token must be presented to the RSA before access can be gained to this endpoint.	/userinfo	No
oauth2-config.provider.fetch_and_attach_userinfo	This parameter is set when the RSA/implementer wants to include userInfo claims within the id_token that is generated.	true (default)	No
oauth2-config.provider.consent_endpoint	Consent endpoint enables the RSA to behave as an Authentication provider for the actual Resource Server it is abstracting in an FPX instance. In the case of OIDC, if the Resource Server is an OIDC provider, consent endpoint will not be used as OIDC would be federated over to the server itself.	/discover/consent	No
oauth2-config.provider.consent_view_page	The name of the Thymeleaf HTML template page to display during the Consent flow. This page is where the explicit consent claims are requested, and prompts the user whether they would like to proceed with this information transfer.	oidc_authorize	No
oauth2-config.provider.custom_grant_types	This value should be added when the RSA-OIDC needs to accommodate new grantTypes that are not in the default grantType. The application handles this and adds it to the existing default grant types.		No (required if you need to specify custom grant types)

FPX Resource Management Properties

The following parameters are required to enable delegation of resources.

Parameter	Description	Suggested Value	Required
fpx.resourcemanagement.enabled	Whether the Resource Management API is enabled.	false	Yes
fpx.resourcemanagement.userInfoUrl	The path for which the related field should be added to its response as an additional claim. This should be a userinfo response's path on the RSA.	/userinfo	No (required only when Resource Management API is enabled)
fpx.resourcemanagement.scope	The scope which is required on the user's access token in order to acquire FPX resources, including the related field mentioned above.	fpx_rot	No (required only when Resource Management API is enabled)
fpx.resourcemanagement.include_owned_resources	This parameter, when set to true, the /resources endpoint will also include entries for resources in the fpx_resource table owned by the user calling the endpoint.	true	No

FPX OIDC Provider Properties

Parameter	Description	Suggested Value	Required
fpx.oidc.client.pkce.enforced	Whether to enforce the use of proof key for code exchange in requests between the RSA and clients.	false (default)	No
fpx.oidc.provider.self-hosted.enabled	A boolean value to enable/disable self-hosting of authentication and consent when managing a data-source connection. This should be set to false when OIDC is federated to the real Resource Server that the RSA is adapting.	false	Yes
fpx.oidc.provider.federated.enabled	A boolean value to enable/disable federated OIDC. Used when the authentication and and consent handling is handled by the real Resource Server that the RSA is adapting.	true	Yes
fpx.oidc.provider.federated.client_id	The Client ID used by the RSA for the federated OIDC provider of the RSA (which behaves as a OAuth Client)	identos-qa	Yes
fpx.oidc.provider.federated.federated_issuer	The base URL of the Federated OIDC provider.	{OIDC Provider URL}	Yes
fpx.oidc.provider.federated.useDownstreamToken	Determines whether the RSA generated token or the RSA-stored token (the token the RSA received from the Federated Provider) should be used. When OIDC federation is enabled, this value will be set to true.	true	Yes
fpx.oidc.provider.pkce.enforced	Whether to enforce the use of proof key for code exchange in requests between the RSA and providers.	false	Yes
fpx.oidc.provider.JWT-token.enabled	This value determines if generated access tokens are JWTs or opaque strings. If set to true, then a JWT is generated. If set to false, an opaque token is generated.	false (default)	No

RSA Token Expiry Defaults

Parameter	Description	Suggested Value	Required
default.expiry-duration-params.accessTokenLifetimeSeconds	Access token expiry in seconds.	600 (default)	No
default.expiry-duration-params.refreshTokenLifetimeSeconds	Refresh token expiry in seconds.	3600 (default)	No
default.expiry-duration-params.authorizationCodeLifeTimeInSeconds	Authorization Code expiry in seconds.	600 (default)	No

FPX Resource Owner Token Properties

Parameter	Description	Suggested Value	Required
rot.endpoint	The endpoint where the Wallet will negotiate a Resource Server Token which essentially represents user permissions at the RSA. In other words, Resource Owners may delegate the ability to grant access to their resources to other entities (in this case, the RSA)	/discover/complete	Yes
rot.rot_length	This determines the length of the Resource Owner Token.	20	Yes
rot.length		15	Yes
rot.hmac-jwt.numberOfPseudonyms	Denotes the number of representation the RSA may provide to the Wallet to enable the Wallet to re-use the ROT. Applies only for the HMAC-JWT strategy.	10
rot.implementation-strategy	The strategy that will be used to generate the ROT. Currently, only 'HMAC-JWT' and 'simple' are supported.	HMAC-JWT	Yes
rot.hmac-jwt.expiryDurationInSeconds	The expiry duration of the HMAC-JWT Resource Owner Token, in seconds. Only applicable when HMAC-JWT is selected as the rot.implementation.strategy.	1800	Yes

Zuul Properties

Properties for configuration of the Zuul API Gateway framework.

Parameter	Description	Suggested Value	Required
zuul.routes	To forward requests from the RSA that behaves as a Gateway application abstracting the real RS, you need to tell Zuul the routes that it should watch and the services where it should forward requests that are made to those routes. We specify routes by setting properties under zuul.routes		Yes
zuul.routes.userinfo	"userinfo" is an identifier for a Zuul route that we define. The value of this identifier is arbitrary, but should represent the resource or resource server that the route corresponds to. Several sub-properties must be provided beneath each route defined this way.		Yes
zuul.routes.userinfo.path	The path prefix that Zuul looks for in order to identify which requests arriving at the RSA shall be forwarded along this route	/api/**	Yes
zuul.routes.userinfo.url	The location where Zuul will forward all requests that match the criteria set by "zuul.routes.userinfo.path", above.	{OIDC Issuer URL}	Yes
zuul.routes.userinfo.stripPrefix	Whether to strip the prefix defined by "zuul.route.userinfo.path" before forwarding the request	true	Yes
zuul.routes.userinfo.sensitiveHeaders	Defines which headers of the request should be deemed sensitive, and therefore should not be included in the forwarded request.	Cookie,Set-Cookie	Yes

User Restriction API Properties

Parameter	Description	Suggested Value	Required
userrestriction.birthdate.maximumAge	When birthdate is to be used as a restriction parameter, this defines the maximum age for the restriction to be applied	maximumAge	No
userrestriction.birthdate.maximumAge	When birthdate is to be used as a restriction parameter, this defines the minimum age for the restriction to be applied	minimumAge	No
userrestriction.birthdate.after		after	No
userrestriction.birthdate.before		before	No
userrestriction.birthdate.equal		equal	No
userrestriction.birthdate.type		java.util.Date	No
userrestriction.birthdate.dateCheckErrorMessage	A string corresponding to a message variable to display when this restriction is not met	age_requirement_not_met	No
modelViewName.dateRestrictionPage	The name of the Thymeleaf HTML template page to display when the requirements of a user restriction are not met.	account-requirement-not-met	No

Spring Framework Properties

Parameter	Description	Suggested Value	Required
spring.thymeleaf.prefix	Location of template files for Wallet selection and error pages. Can use external sources such as https://	classpath:./templates/	Yes
spring.web.resources.static-locations	Location of static files such as css/html/javascript for template files.	classpath:./static/	Yes
spring.main.allow-bean-definition-overriding	Whether the Spring Framework allows existing Bean definitions to be overriden by new Beans with the same name	true	Yes
spring.output.ansi.enabled	Whether console output will be rendered in colour. This only applies if logging.config is set to classpath:logback-dev.xml. The default compressed JSON output is not coloured.	ALWAYS	No

Database Configuration

Parameter	Description	Suggested Value	Required
spring.flyway.enabled	Enable or disable automatic Flyway migrations.	true	Yes
spring.flyway.locations	Location for DB migration scripts.	classpath:db/migration	Yes
spring.datasource.driverClassName	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-host-domain/rsa_oidc	Yes
spring.datasource.username	Username for database connection.	username	Yes
spring.datasource.password	Password for database connection.	password	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 RSA and the RSA Admin API. 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
spring.jpa.hibernate.naming.physical-strategy	Defines how Java objects map to a database table. Refer to Sprint Boot documentation for more details.	org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl Note: Identos recommends the usage of this default value. Avoid making changes to this parameter unless absolutely necessary.

"App" parameters

These allow customization of the error page displayed when the RSA encounters certain exceptions in its role as an OAuth client. Currently, only the error page uses these parameters but other pages rendered by the RSA may also make use of them.

Parameter	Description	Suggested Value	Required
app.name	The name for the application, displayed in the error page header	Identos	Yes
app.image_directory	The directory where image resources are located within the /resources/static directory	/images/	Yes
app.logo.name	The filename of the image to be used as the application logo	identos.png	Yes

Sample Configuration file

server.port: 8080
server.servlet.session.cookie.http-only: true
server.servlet.session.cookie.secure: false

logging:
  level:
    com.identos: DEBUG
    org.springframework.web: DEBUG
    org.hibernate.SQL: DEBUG
    org.springframework.context.support.PostProcessorRegistrationDelegate: OFF
  config: classpath:logback-spring.xml
       
oauth2-config:
  client:
    auth_jwt_expiry: 6000
    callback_endpoint: /oidc/callback
  provider:
    issuer: http://localhost:8086 
    registration_endpoint: /register
    authorize_endpoint: /discover/authorize
    token_endpoint: /discover/token
    jwks_endpoint: /jwks
    introspection_endpoint: /oauth2/introspect
    user_info_issuer: http://localhost:8086 
    userinfo_endpoint: /userinfo
    fetch_and_attach_userinfo: true
    consent_endpoint: /discover/consent
    consent_view_page: oidc_authorize
    custom_grant_types:
      - test
      - test 2
fpx:
  resourcemanagement:
    enabled: false
    userinfoUrl: /userinfo
    scope: fpx_rot
    include_owned_resources: true
  oidc:
    client:
      pkce:
        enforced:false
    provider:
      self-hosted:
        enabled: false
      federated:
        enabled: true
        client_id: identos-qa
        federated_issuer: {OIDC Provider URL}
        useDownstreamToken: true
      pkce:
        enforced: false
      JWT-token:
        enabled: true
default:
  expiry-duration-params:
    accessTokenLifetimeSeconds: 600   #will set access token to 10 mins
    refreshTokenLifetimeSeconds: 3600  #will set refresh token to 1hr
    authorizationCodeLifeTimeInSeconds: 600  #will set auth code to 10 mins

fpx.oauth.uma.introspection.introspect_locally: false

rot:
  endpoint: /discover/complete
  rot_length: 20
  length: 15
  implementation-strategy: HMAC-JWT
  hmac-jwt:
    expiryDurationInSeconds: 1800
    numberOfPseudonyms: 10

zuul:
  routes:
    userinfo:
      path: /api/**
      url: {OIDC Issuer URL}
      stripPrefix: true
      sensitiveHeaders: Cookie,Set-Cookie

userrestriction:
  birthdate:
    maximumAge: maximumAge
    minimumAge: minimumAge
    after: after
    before: before
    equal: equal
    type: java.util.Date
    dateCheckErrorMessage: age_requirement_not_met

modelViewName:
  dateRestrictionPage: account-requirement-not-met

spring:
  output.ansi.enabled: ALWAYS
  thymeleaf:
    cache: false
    prefix: classpath:./templates/
  web:
    resources:
      static-locations: classpath:./static/
  main:
    allow-bean-definition-overriding: true
  datasource:
    driverName: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://database-host-domain:3306/rsa_oidc?useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC
    username: {{DATABASE_USERNAME}}
    password: {{DATABASE_PASSWORD}}
  flyway:
    enabled: true
    locations: classpath:db/migration
    repairMigrationStrategy:
      enabled: true
    baseline-on-migrate: true
  jpa:
    hibernate:
      dialect: org.hibernate.dialect.MySQL5InnoDBDialect
      ddl-auto: validate
      naming.physical-strategy:   org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl

app:
  name: Identos
  image_directory: /images/
  logo:
    name: identos.png

RSA-OIDC Admin API Application Config

The spec.values.application.config parameter contains multiple sub-parameters that are essential for the proper configuration and setup of the RSA. Below are tables that provide details and descriptions for each sub-parameter followed by a sample code block illustrating the common values defined in spec.values.application.config

Configuration Details

Spring Actuator Configuration

Make the following configurations to enable Spring Actuator and monitor the health of the Resource Server Adapter.

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 RSA-OIDC 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.identos.rsadapteroidc.admin	Controls the level at which the RSA-OIDC Admin API logs will be output.	DEBUG	No
logging.level.com.identos.rsatemplate.admin	Controls the level at which the underlying RSA Admin API library 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
spring.output.ansi.enabled	Enables coloured log output when viewed with a terminal	true	No

Authentication Token Configuration

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

Database Configuration

NOTE: These values should match the values defined for the RSA-OIDC Application Config in the previous section.

Parameter	Description	Suggested Value	Required
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://dbhost/dbname?createDatabaseIfNotExist=true	Yes
spring.datasource.username	Username for database connection.	dbusername	Yes
spring.datasource.password	Password for database connection.	dbpassword	Yes
spring.jpa.generate-ddl	Whether Hibernate is responsible for generating the database schema	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

Sample Configuration File

In the application Helm chart, the spec.values.application.config parameter is used to define the main elements for the RSA Admin API. Without clearly defining these parameters, the setup of the RSA Admin API will fail and limit the integration of the other parties with the RSA.

Below is a sample code block illustrating the common values defined in spec.values.application.config followed by tables that provide details and descriptions for each sub-parameter. The most important configuration is to ensure that the RSA Admin API database section points to the same database as the RSA itself.

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.identos.rsadapteroidc.admin: DEBUG
    com.identos.rsatemplate.admin: DEBUG
    org.springframework.web: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.type: DEBUG

spring.jpa.properties.hibernate.format_sql: true

rsa-admin:
  staticTokens: 
    - {{RSA_ADMIN_STATIC_TOKEN}}
    - {{ANOTHER_RSA_ADMIN_STATIC_TOKEN}}

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://database-host-domain:3306/rsa_oidc?useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC
    username: {{DATABASE_USERNAME}}
    password: {{DATABASE_PASSWORD}}
  output.ansi.enabled: ALWAYS
  jpa:
    generate-ddl: false
    hibernate:
      ddl-auto: validate
      naming.physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl

elide:
  pageSize: 1000
  maxPageSize: 10000
  json-api:
    path: /json-api
    enabled: true
  graphql:
    path: /graphql
    enabled: false
  swagger:
    path: /json-api/openapi
    enabled: true
    name: "RSA OIDC Admin API"
    version: "v1.0"

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.