Skip to main content

Configurations for RSA LDAP Extensions

The following YAML configuration template outlines the key items required to enable a gateway relationship between the RSA and an LDAP instance. LDAP is often used by organizations as a central repository for user information and as an authentication service. It can also be used to store the role information for application users.

The RSA-LDAP profile is powered by the base RSA profile (used to protect resources stored in OIDC providers) but has been customized to protect resources stored in an LDAP instance. As a result, much of the configuration stays the same (with slight modifications such as disabling OIDC federation) as required by the base RSA. Additional LDAP-specific configuration has been added to enable an RSA <--> LDAP relationship.

Configuration​

The following table lists the configurable YAML parameters of the LDAP Adapter required to enable a gateway relationship between the RSA and a protected Resource Server. Further details on the config will be detailed later in this document.

YAML Parameters​

ParameterDescriptionDefault
server.portPort at which it will accept requests8080
server.servlet.session.cookie.http-onlyParameter to enable or disable whether browser scripts should be able to access RSA generated cookiesThis MUST be set to 'true' for security measures as it follows best practice principles.
server.servlet.session.cookie.secureIf set to 'true', the cookie will be sent only over HTTPS connections.This MUST be set to 'true' for security measures as it follows best practice principles.
spring.main.allow-bean-definition-overridingA field meant for developers to enable multiple strategies and configurations that are available at run time.This MUST be set to 'true' as this value allows for multiple configurable extensions of the RSA.
`logging.level.org.springframework.webThe amount of granularity displayed for log output. Usually meant to enable developers to debug.TRACE
fpx.oidc.provider.fetchAndAttachUserInfoA Boolean flag used to set whether userInfo claims should be packaged within IDTokens created at the RSA. The Wallet is an OIDC client to the RSA and therefore this value when set to 'true' will enable the Wallet Server (any OIDC client) to read userInfo claims as part of the IDToken(s) it receives from the RSA.true
fpx.oidc.provider.jwks_endpointThe JSON Web Key Set (JWKS) endpoint is a read-only endpoint that contains the 'public keys' information in the JWKS format./jwks
fpx.oidc.provider.authorize_endpointThe 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
fpx.oidc.provider.consent_endpointConsent endpoint enables the RSA to behave as a authentication provider for the real Resource Server it's abstracting in an FPX instance. In the case of OIDC, if the real Resource Server is an OIDC provider, consent endpoint will not be used as OIDC would be federated over to the real RS./oidc/consent
fpx.oidc.provider.consent_view_pageThe name of the HTML/Asset file that displays that provides the GUI where the explicit consent claim is requested in order for what user to verify what data points are being requested about them and whether they would like to proceed with this information transfer. This file would need to be stored under the 'Resources' sub-folder and the name of the file must be the value (excluding the .html suffix)oidc_consent
fpx.oidc.provider.token_endpointThe 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./oidc/token
fpx.oidc.provider.userinfo_endpointA protected endpoint to retrieve the user info of the user who logged in to the RSA. This endpoint is used by the Wallet to retrieve a Resource owner token and is also used by the Service Provider to retrieve the necessary user info requested by them. A valid OAuth Access Token must be presented to the RSA before access can be gained to this endpoint. The Service Provider never explicitly calls this endpoint as it is left for the RSA to internally redirect after ensuring proper authorization has been granted to the Service Provider./oidc/userinfo
fpx.oidc.provider.issuerThe base URL of the OIDC provider responsible for issuing tokens. This will be the base URL of the RSA.The base URL MUST be explicitly provided
fpx.oidc.provider.self-hosted.enabledA 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 off to a real Resource Server.false
fpx.oidc.provider.federated.enabledA Boolean value to enable/disable federated OIDC. Used when the authentication and consent handling is handled by the real Resource Server that the RSA is abstracting.false
fpx.oidc.provider.client.callbackThe 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
consent-view.cssLocation of the CSS file used for the Consent Page (The Login page where users enter their LDAP credentials). The default location resides within the RSA-LDAP project itself.Location of the CSS file. Default is http://{rsa-url}/style.css
ldap.anonymous-read-onlySome LDAP server setups allow anonymous read-only access. The RSA uses its own credentials to authenticate to an LDAP server, but we need to authenticate a user too to create a 'Context' from which a search query will be made. This field, if set to 'false', will ensure that all LDAP queries made against an LDAP server will only be deemed acceptable as long as a known LDAP user is authenticated (as opposed to anonymous lookups).false
ldap.urlsThe LDAP protocol abiding host name of the LDAP server, port at which to access it and base path/initial context that will be used to traverse and combined with the user DN(distinguished name) pattern to ultimately identify individual users within the LDAP tree.
ldap.usernameRead-only Admin credentials will need to be provided where the username and password will correspond to the 'cn' (common name) value and the password value of the 'read-only' admin entry respectively within the LDAP Directory Information Tree.
ldap.passwordRead-only Admin credentials will need to be provided where the username and password will correspond to the 'cn' (common name) value and the password value of the 'read-only' admin entry respectively within the LDAP Directory Information Tree.
ldap.userDnPatternThe userDnPattern property will enable the Spring LDAP authenticator to search and identify a user within the LDAP server. In this case, we are only using a single DN (Distinguished name) pattern. For example, if the username is 'edward' (provided at the Login page of the RSA), the DN used to bind to LDAP will be uid=edward relative to the initial context dc=example,dc=com. Even though the unique username provided at the login form was "edward", the actual name used to authenticate to LDAP will be the full DN 'uid=edward,dc=example,dc=com'.
ldap.keysThe 'keys' attribute here represents a list of all LDAP attributes that will be pulled from the LDAP server and sent back in a valid successful response to a valid authorized userinfo request at the RSA.
Note: Though the list of attributes is configurable, these attributes MUST be available at the LDAP Server itself.
rot.endpointThe endpoint from 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
rot.implementation-strategyThe strategy that will be used to generate the ROT. Currently 'HMAC-JWT' and 'simple' are the two options that can be chosen for this config field. Depending on the strategy specified, the subsequent parameters will vary.simple
rot.simple.rotLengthLength of the Simple Resource Owner Token. This parameter is configured only if 'simple' is selected as the rot.implementation-strategy64 (max supported character count of 255. Recommended usage is 64 to minimize performance issues)
rot.simple.expiryDurationInSecondsThe expiry duration of an ROT specified in seconds when 'simple' is specified as the rot.implementation.strategy.86400
rot.hmac-jwt.numberOfPseudonymsDenotes the number of representation the RSA may provide to the Wallet to enable the Wallet to re-use the ROT. Applicable when HMAC-JWT is selected as the rot.implementation.strategy.10
rot.hmac-jwt.expiryDurationInSecondsThe expiry duration of an HMAC-JWT ROT specified in seconds. Applicable when HMAC-JWT is selected as the rot.implementation.strategy.86400
zuul.debug.requestA developer tool that enables debugging information to accumulate for all requests recognized as Zuul requests i.e (to be forwarded to another server). The debugging information will be specific to the Zuul engine and can only be accessed using code debugging tools. This setting is for internal development teams and does not have any direct impact on end-user experience.false
zuul.routesTo forward requests from the RSA that behaves as a Gateway application abstracting the real RS, you need to tell Zuul (Gateway Technology) the routes that it should watch and the services to which to forward requests that are made to those routes. We specify routes by setting properties under zuul.routes
zuul.routes.userinfoName of the microservice/purpose to which requests are being forwarded to. Goal of this field is only to help you identify which Zuul Gateway relationship are all the sub fields of this field being applied to. For example: If gateway requests are being made for the purposes of retrieving userinfo, you can set the route name to be 'userinfo'. Alternatively you can also insert name of a microservice/server as the value here.
zuul.routes.userinfo.pathThe Path prefix the Zuul looks for in order to identify which requests arriving at the RSA will be forwarded./api/**
zuul.routes.userinfo.urlThe location to which Zuul forwards all requests that match the criteria above set by "zuul.routes.userinfo.path"This should be explicitly provided as the location to which this request is being forwarded to. Generally this will be the userinfo endpoint of the abstracted RS.
zuul.routes.userinfo.sensitiveHeadersAllows you to specify a list of headers that the Federated Provider will ignore when receiving the Zuul forwarded request. By default, Zuul sends all headers (including proxy headers) to the forwarding path. Proxy headers may result in errors with the Federated Provider. This parameter allows for these headers to be blocked.Comma separated list of headers
spring.datasource.driverNameDriver to use for DB connections (only MySQL supported).com.mysql.jdbc.Driver
spring.datasource.urlDriver to use for DB connections.jdbc:mysql://database-hostname/authserver?createDatabaseIfNotExist=true
spring.datasource.usernameUsername for database connection.username
spring.datasource.passwordPassword for database connection.password
spring.jpa.hibernate.dialectSpring Hibernate dialect (only MySQL supported)org.hibernate.dialect.MySQL5InnoDBDialect
spring.jpa.hibernate.show_sqlShow all SQL queries that are run against the database source in the logs.false
spring.jpa.hibernate.generate_ddlA flag that determines whether a SQL Database should be initialized at startup.true
spring.jpa.hibernate.ddl-autoValidate database structure on startup.validate
spring.jpa.hibernate.naming.physical-strategyDefines 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.
spring.thymeleaf.prefixLocation of Thymeleaf template files. Within RSA-LDAP, it is the location of the HTML pages that the application needs to search for to serve up Login and consent thymeleaf pages. For this parameter, you can use external sources such as https://{location-of-folder-holding-all-thymeleaf-templates} in order to provide client customized templates, or use the default "classpath:./templates/". This value means the application will be serving up the default templates that are baked into the docket image by IDENTOSclasspath:./templates/"
spring.resources.static-locationsThis parameter allows Spring Boot to locate and achieve loading of static resources like CSS and JavaScript. The parameter is similar to the thymeleaf.prefix value except that you need to use spring.resources.static-locations. The default is just "classpath:./static/". This parameter supports a comma separated list of all locations that the application will look through to find the specific static content."classpath:./static/"

Sample Configuration​

Base Configuration + LDAP Specific Configuration

## --------------------
## Spring Configuration
## --------------------
server.port: 8080
server.servlet.session.cookie.http-only: true
server.servlet.session.cookie.secure: true
logging.level.org.springframework.web: TRACE
spring.main.allow-bean-definition-overriding: true

## --------------------
## OIDC Provider Configuration to Wallet
## --------------------
fpx:
  oidc:
    provider:
      fetchAndAttachUserInfo: true
      jwks_endpoint: /jwks
      register_endpoint: /register
      authorize_endpoint: /discover/authorize
      consent_endpoint: /discover/consent
      consent_view_page: oidc_authorize
      token_endpoint: /discover/token
      userinfo_endpoint: /userinfo 
      ## This should be the scheme / host the RSA is hosted on
      issuer: https://rs-adapter-ldap.identos.ca
      self-hosted:
        enabled: true
      federated:
        enabled: false
    client:
      callback: /oidc/callback

## Default location for the styling of the consent page resides within RSA-LDAP project itself. Use the value as shown below if the default styling is the preferred choice for styling.
## To override, simply replace the URL with the address of your preferred customized styling changes

consent-view.css: http://{rsa-url}/style.css

ldap:
  anonymous-read-only: false
  urls: ldap://{ldap-url}:{port}/dc=example,dc=com
  username: cn=read-only-admin,dc=example,dc=com
  password: password
  userDnPattern: uid={0}
  keys:
    - mail
    - cn
    - sn
    

rot:
  endpoint: /discover/complete
  implementation-strategy: HMAC-JWT 
  hmac-jwt:
    expiryDurationInSeconds: 1800
    numberOfPseudonyms: 10 ## number of UUIDs issued to the wallet when it requests for ROTs at the ROT issuance endpoint

zuul:
  debug:
    request: true
  routes:
    userinfo:
      path: /api/**
      url: forward:/
      sensitiveHeaders: Cookie,Set-Cookie
      stripPrefix: true
ribbon:
  eureka:
    enabled: false

## --------------------
## Database Connections
## --------------------
spring:
  datasource:
     driverName: com.mysql.jdbc.Driver
    url: jdbc:mysql://databasehostname/rs?useUnicode=true&createDatabaseIfNotExist=true&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC
    username: root
    password: password
  jpa:
    hibernate:
      dialect: org.hibernate.dialect.MySQL5InnoDBDialect
      show_sql: false
      generate_ddl: true
      ddl-auto: update
      naming.physical-strategy:   org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
  thymeleaf:
    prefix: classpath:./templates/
  resources:
    static-locations: classpath:./static/