diff --git a/docs/CUSTOMIZATIONS.md b/docs/CUSTOMIZATIONS.md deleted file mode 100644 index 103137ef5..000000000 --- a/docs/CUSTOMIZATIONS.md +++ /dev/null @@ -1,60 +0,0 @@ -# Custom Development - -For a full example of creating a custom module for the application, see the `pac4j-module` project. - -As a Spring Boot application built with gradle, there are many opportunities available for -custom development against the application. Note that most customizations should be done in -separate modules, not directly modifying the source to the base application. - -## Application Classpath - -To get customizations in the application, one must make the changes available on the application -classpath. Depending on the deployment method, one has a few options for doing this. - -1. Take advantage of the `Properties Launcher` in the executable JAR -2. Put resources in the appropriate `WEB-INF` directory for a WAR deployment - -If one is adding Spring configuration, register the configuration classes with the Spring -Autoconfiguration service by adding a file called `META-INF/spring.factories` to the JAR -file containing the custom java class and referencing any configuration classes: - -```properties -org.springframework.boot.autoconfigure.EnableAutoConfiguration=org.example.SomeConfiguration -``` - -For more information, see [https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-developing-auto-configuration.html#boot-features-locating-auto-configuration-candidates] - -### Executable JAR - -The executable JAR uses the Properties Launcher provided by Spring Boot ([https://docs.spring.io/spring-boot/docs/current/reference/html/executable-jar.html#executable-jar-property-launcher-features]). -The easiest way to add something to the classpath is to create a file named `loader.properties` in the same directory -as the jar with the following: - -```properties -loader.path=libs/ -``` - -The noted directory will be added to the classpath, along with any JAR files contained in the directory. - -### WAR - -If deploying a WAR, one would use the standard packaging for providing items to the classpath. - -* JAR files should be placed in `WEB-INF/lib` -* all other resources should be placed `WEB-INF/classes` - -It is highly recommended that a WAR overlay be used to prevent changing the version fingerprint. Overlay -methods exist for both Maven ([https://maven.apache.org/plugins/maven-war-plugin/overlays.html]) and -Gradle ([https://github.com/scalding/gradle-waroverlay-plugin]) projects. - -## Sample Customization - -For an example of a customization, refer to the `pac4j-module` in the project source. This module overrides the delivered -authentication method to provide a simple SAML authentication method. Along with code changes required, it also shows -how one would tie it together using a Docker image. - -## Use Cases and Strategies - -Some ideas and strategies for customizing the application. - -TBD \ No newline at end of file diff --git a/docs/DATABASE.md b/docs/DATABASE.md deleted file mode 100644 index 09c379ad1..000000000 --- a/docs/DATABASE.md +++ /dev/null @@ -1,45 +0,0 @@ -# Database configuration - -The Shibboleth UI application uses Spring Boot and Spring JPA for database configuration. Out of the box, it ships with -JDBC drivers for H2, MariaDB and Postgres. - -By default, it will use an in-memory H2 database. To change which database is used, one should make changes to the -`applications.properties` or `application.yml` file as appropriate. For further information, refer to the appropriate -JDBC driver documentation. - -```properties -# Database Credentials -spring.datasource.username=shibui -spring.datasource.password=shibui - -# Database Configuration H2 -spring.datasource.url=jdbc:h2:mem:shibui;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE -spring.datasource.platform=h2 -spring.datasource.driverClassName=org.h2.Driver -spring.jpa.database-platform=org.hibernate.dialect.H2Dialect -spring.h2.console.enabled=true - - -# Database Configuration PostgreSQL -#spring.datasource.url=jdbc:postgresql://localhost:5432/shibui -#spring.datasource.driverClassName=org.postgresql.Driver -#spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect - -#Maria/MySQL DB -#spring.datasource.url=jdbc:mariadb://localhost:3306/shibui -#spring.datasource.driverClassName=org.mariadb.jdbc.Driver -#spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MariaDBDialect - -# Liquibase properties -spring.liquibase.enabled=false -#spring.liquibase.change-log=classpath:edu/internet2/tier/shibboleth/admin/ui/database/masterchangelog.xml - -# Hibernate properties -# for production never ever use create, create-drop. It's BEST to use validate -spring.jpa.hibernate.ddl-auto=update -spring.jpa.hibernate.naming.implicit-strategy=org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl -spring.jpa.show-sql=false -spring.jpa.properties.hibernate.format_sql=false - -spring.jpa.hibernate.use-new-id-generator-mappings=true -``` \ No newline at end of file diff --git a/docs/DEFAULTPROPERTIES.md b/docs/DEFAULTPROPERTIES.md deleted file mode 100644 index 75916235a..000000000 --- a/docs/DEFAULTPROPERTIES.md +++ /dev/null @@ -1,72 +0,0 @@ -# Default properties - -This is a reflection of the default `application.properties` file included in the distribution. Note that lines -beginning with `#` are commented out. - -Please refer to the Spring Boot documentation [https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html] -for more information. - -```properties -# Server Configuration -#server.port=8080 - -# Logging Configuration -#logging.config=classpath:log4j2.xml - -logging.level.org.springframework=INFO -logging.level.edu.internet2.tier.shibboleth.admin.ui=INFO - -# Database Credentials -spring.datasource.username=shibui -spring.datasource.password=shibui - -# Database Configuration H2 -spring.datasource.url=jdbc:h2:mem:shibui;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE -spring.datasource.platform=h2 -spring.datasource.driverClassName=org.h2.Driver -spring.jpa.database-platform=org.hibernate.dialect.H2Dialect -spring.h2.console.enabled=true - - -# Database Configuration PostgreSQL -#spring.datasource.url=jdbc:postgresql://localhost:5432/shibui -#spring.datasource.driverClassName=org.postgresql.Driver -#spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect - -#Maria/MySQL DB -#spring.datasource.url=jdbc:mariadb://localhost:3306/shibui -#spring.datasource.driverClassName=org.mariadb.jdbc.Driver -#spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MariaDBDialect - -# Liquibase properties -spring.liquibase.enabled=false -#spring.liquibase.change-log=classpath:edu/internet2/tier/shibboleth/admin/ui/database/masterchangelog.xml - -# Hibernate properties -# for production never ever use create, create-drop. It's BEST to use validate -spring.jpa.hibernate.ddl-auto=update -spring.jpa.hibernate.naming.implicit-strategy=org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl -spring.jpa.show-sql=false -spring.jpa.properties.hibernate.format_sql=false - -spring.jpa.hibernate.use-new-id-generator-mappings=true - -# Set the following property to periodically write out the generated metadata files. There is no default value; the following is just an example -# shibui.metadata-dir=/opt/shibboleth-idp/metadata/generated -shibui.logout-url=/dashboard - -# spring.profiles.active=default - -#shibui.default-password= - -#Actuator endpoints (info) -# Un-comment to get full git details exposed like author, abbreviated SHA-1, commit message -#management.info.git.mode=full - -### -# metadata-providers.xml write configuration - -# Set the following property to periodically write out metadata providers configuration. There is no default value; the following is just an example -# shibui.metadataProviders.target=file:/opt/shibboleth-idp/conf/shibui-metadata-providers.xml -# shibui.metadataProviders.taskRunRate=30000 -``` \ No newline at end of file diff --git a/docs/GETTINGSTARTED.md b/docs/GETTINGSTARTED.md deleted file mode 100644 index eeed8fae3..000000000 --- a/docs/GETTINGSTARTED.md +++ /dev/null @@ -1,55 +0,0 @@ -# Getting Started - -## Requirements - -* Java 8 (note that ONLY Java 8 is supported at this time) - -## Running - -There are currently 2 ways to run the application: - -1. As an executable -1. deployed in a Java Servlet 3.0 container - -Note that some features require encoded slashes in the URL. In tomcat (which is embedded in the war), this can be -allowed with: - -``` --Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true -``` - -In Apache HTTPD, you'll need something like: - -``` - - AllowEncodedSlashes NoDecode - ServerName shibui.unicon.net - ProxyPass / http://localhost:8080/ nocanon - ProxyPassReverse / http://localhost:8080/ - -``` - -Note the `AllowEncodedSlashes NoDecode`. - -### Running as an executable - -`java -jar shibui.war` - -For complete information on overriding default configuration, see [https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html]. - -### Deploying as a WAR - -The application can be deployed as a WAR file in a Java Servlet 3.0 container. Currently, the application must be run in the root context. - -To override default configuration, see [https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html]. -The easiest way to do this in a servlet container is through the use of system properties - -## Authentication - -Currently, the application is wired with very simple authentication. A password for the user `root` -can be set with the `shibui.default-password` property. If none is set, a default password -will be generated and logged: - -``` -Using default security password: a3d9ab96-9c63-414f-b199-26fcf59e1ffa -``` \ No newline at end of file diff --git a/docs/HOME.md b/docs/HOME.md deleted file mode 100644 index 523c3fa38..000000000 --- a/docs/HOME.md +++ /dev/null @@ -1,6 +0,0 @@ -# Shibboleth UI - -* [DATABASE] -* [CUSTOMIZATIONS] -* [INTERNATIONALIZATION] -* [DATABASE] \ No newline at end of file diff --git a/docs/INTERNATIONALIZATION.md b/docs/INTERNATIONALIZATION.md deleted file mode 100644 index 08bc37874..000000000 --- a/docs/INTERNATIONALIZATION.md +++ /dev/null @@ -1,102 +0,0 @@ -# Internationalization Guide - -## About - -The Shibboleth UI leverages the messages_*_*.properties files common to Java/Spring applications. The default files are located in `backend > src > main > resources > i18n`. - -To use a custom file, it is recommended that you make a copy of the appropriate file and add it to the classpath in the -`i18n` package. See [CUSTOMIZATIONS] for more information. For instance, if using the executable JAR and wanting to -customize the English file, one would create a file called `1ibs/i18n/messages_en.properties` in the same directory as the -JAR file and set the appropriate `loader.properties`. - -This will allow any piece of static text in the application to be modified dynamically. - -## Usage - -In the UI code, there are three options for converting the text provided into translated text. - -* Component: `Foo` -* Directive: `` -* Pipe: `{{ action.foo | translate }}` - -In addition, the `application.yml` file is an example of a file where dynamic values from the server, can be populated with an i18n identifier for translation. The json files used to generate the metadata wizards also make use of these identifiers and can be translated. They all use the same `messages.properties` files. - -Here is an example of the identifers and text found in the `messages.properties` files. - -``` -action.cancel=Cancel -action.save=Save -action.delete-type=Delete { type } -``` - -The `action.delete-type=Delete { type }` example shows how dynamic text can be inserted into the translation as well. These values are determined by the application and are populated at runtime based on user interaction. Many of these values can be translated separately. - -## Conventions - -### Choosing an identifier - -To allow for easier identification of relevant strings the identifiers are -provided in the following format - -``` -type.kebab-case-text -``` - -For example - -```html - - - -``` - -Where `type` is one of the provided types listed in [the types section](#types) - -`type` and `text` are separated by two dashes. - -`text` is the text content, dash separated words, all lower case, with -punctuation removed. - -### Types - -The following types are provided: - -* `action` buttons or links that cause a state change within the app -* `label` label for an input or a section -* `message` messages that warn a user of exceptions in interactions, i.e. - validation messages -* `value` text for displaying values such as `true` or `false` -* `branding.*` this special type is used to denote the customizable values located in the `ui > brand.ts` file - -### Localize Text Only - -```html - - - -``` - -### Updating Text - -When updating text, update the identifier to match the new text field. - -```html - - - - - - - -``` diff --git a/docs/METADATAPROVIDERS.md b/docs/METADATAPROVIDERS.md deleted file mode 100644 index 32d02149b..000000000 --- a/docs/METADATAPROVIDERS.md +++ /dev/null @@ -1,22 +0,0 @@ -# Metadata providers - -The application can generate a `metadata-providers.xml` configuration appropriate for use in the Shibboleth IdP. -There are 2 ways to access this configuration: through a web endpoint or a file. - -1. Web endpoint - - A request can be made to the `${ui.baseUrl}/api/MetadataResolvers` to get the - current configuration - -2. File export - - A file can be periodically written to disk. Set the application property `shibui.metadataProviders.target`, - pointing to a spring file resource. Note that there is no value set by default, and nothing will be written - out by default. A file, once defined, will be written every 30 seconds by default. To change the rate, set the - `shibui.metadataProviders.taskRunRate` application property, in milliseconds. - -## Docker considerations - -If writing the file out, one should use a mount in the docker container for the destination. While a bind mount -might be easiest, if running on a Windows host, one might run into problems. This is easily avoided by using a -volume instead. Refer to [https://docs.docker.com/storage/] for more information. \ No newline at end of file diff --git a/docs/METADATASOURCES.md b/docs/METADATASOURCES.md deleted file mode 100644 index 2ec2563b6..000000000 --- a/docs/METADATASOURCES.md +++ /dev/null @@ -1,21 +0,0 @@ -# Metdata Sources - -Metadata sources in the UI are individual metadata artifacts describing single entities, typically -relying parties. There are 2 ways to access these artifacts. - -1. MDQ - - _To be written_ - -2. File export - - Files can be periodically written to disk. Define the application property `shibui.metadata-dir`, - and the files will be written out by default every 30 seconds. Note that there is no default value - set for this property and no file will be written by default. To change the run rate, set the - `shibui.taskRunRate` application property, in milliseconds. - -## Docker considerations - -If writing the files out, one should use a mount in the docker container for the destination. While a bind mount -might be easiest, if running on a Windows host, one might run into problems. This is easily avoided by using a -volume instead. Refer to [https://docs.docker.com/storage/] for more information. \ No newline at end of file diff --git a/docs/SECURITY.md b/docs/SECURITY.md deleted file mode 100644 index b8397ecd9..000000000 --- a/docs/SECURITY.md +++ /dev/null @@ -1,8 +0,0 @@ -# Security - -Security in the system is controlled by Spring Security. - -Currently, the following roles are recognized: - -1. `ADMIN` -1. `USER` \ No newline at end of file