Suricate

This repository contains the source code of the Suricate application.

Table of Contents

• Download
• Install
• Configuration
  • Default Configuration
  • Database
    • H2 vs PostgreSQL
    • Initialization with Flyway
  • Authentication
    • LDAP vs Database
    • Social Login
      • GitHub
      • GitLab
      • Redirection to Front-End
      • Name Parsing Strategy
    • Personal Access Token
  • Widgets
    • Encryption
    • Repositories
• Swagger UI
• Contribution

Download

You can download Suricate as a fat jar from the project's releases page on GitHub at https://github.com/michelin/suricate/releases.

Please note that Java 21 is required starting from Suricate 2.8.0 (Java 8 before).

Additionally, a Docker image of the solution is available at https://hub.docker.com/repository/docker/michelin/suricate.

Install

Suricate is built on the Spring Boot framework and can be configured using a Spring Boot configuration file, which includes a sample file located at src/main/resources/application.properties.

If necessary, you can override the properties from the default application.properties file by following the Spring Boot externalized configuration guide. For example, you can create a custom /config/application.properties or set the --spring.config.location system property when running the fat jar file:

java -jar suricate.jar --spring.config.location=classpath:\,file:C:\myCustomLocation\

Alternatively, you can use the provided docker-compose file to run the application and use a volume to override the default properties:

docker-compose up -d

After running the command, the application will be accessible on http://localhost:8080/.

Configuration

Default Configuration

By default, Suricate:

• runs on a H2 file database
• provides a sign-in/sign-up authentication mode based on the database

Database

H2 vs PostgreSQL

Suricate supports running on different database management systems (DBMS):

• H2
• PostgreSQL

You can define the DBMS you want to use in the application.properties file with the spring.profiles.active parameter:

spring.profiles.active: ### Provider should be 'h2' or 'postgresql'

It will activate the default application-DBMS.properties configuration file with the required properties for the chosen DBMS.

You will still need to define your database connection properties in the application.properties file:

spring.datasource.url:
spring.datasource.username:
spring.datasource.password:

Please note that the application-DBMS.properties files activate Flyway to automatically set up the database structure (tables, constraints, etc.) and the minimum required functional data.

Initialization with Flyway

Suricate uses Flyway to manage the database initialization. It is enabled by default to automatically set up the database structure (tables, constraints, etc.) and the minimum required functional data at the first start of the application.

Depending on the database management system you use, Flyway will use the appropriate scripts located in the src/main/resources/flyway folder.

Flyway stores the current version of the database in a table named schema_version defined by the following property:

spring.flyway.table: schema_version

Flyway can be deactivated by setting the following property to false:

spring.flyway.enabled: false

Authentication

Suricate provides multiple types of authentication that can be activated or deactivated based on your requirements.

All the authentication modes deliver a JWT token that is used to authenticate the user on the Back-End. You can configure the JWT token using the following properties:

application.authentication.jwt.signingKey: 'changeitchangeitchangeitchangeit'
application.authentication.jwt.tokenValidityMs: 86400000

The signing key should be at least 256 bits long (since Suricate v2.8.0) and should be changed for each environment.

Database

You can log in to Suricate using the database after the sign-up step.

You can choose this authentication mode using the following YAML property:

application.authentication.provider: 'database'

LDAP

You can log in to Suricate an LDAP.

You can choose this authentication mode using the following YAML property:

application.authentication.provider: 'ldap'

If you choose the ldap authentication mode, you must specify the following additional properties:

application.authentication.ldap.url:
application.authentication.ldap.userSearchFilter:
application.authentication.ldap.firstNameAttributeName:
application.authentication.ldap.lastNameAttributeName:
application.authentication.ldap.mailAttributeName:
application.authentication.ldap.username:
application.authentication.ldap.password:
application.authentication.ldap.userSearchBase:
application.authentication.ldap.userDnPatterns:

Social Login

Suricate supports authentication with GitHub and GitLab. You can configure social login using the application-social-login.properties file, which you can activate by running the application with the social-login profile.

When you activate social login, you can activate or deactivate a social login mode by adding or removing it from the property:

application.authentication.socialProviders: gitlab,github

GitHub

To log in using GitHub, you must specify the following properties:

spring.security.oauth2.client.registration.github.client-id: <github-client-id>
spring.security.oauth2.client.registration.github.client-secret: <github-client-id>

GitLab

To log in using GitLab with OIDC, you must specify the following properties:

spring.security.oauth2.client.registration.gitlab.client-id: <gitlab-client-id>
spring.security.oauth2.client.registration.gitlab.client-secret: <gitlab-client-secret>
spring.security.oauth2.client.registration.gitlab.authorization-grant-type: authorization_code
spring.security.oauth2.client.registration.gitlab.redirect-uri: http://localhost:8080/login/oauth2/code/gitlab
spring.security.oauth2.client.provider.gitlab.issuer-uri: https://gitlab.com
spring.security.oauth2.client.registration.gitlab.scope: read_user,openid,profile,email

To log in using GitLab with OAuth2, you must specify the following properties:

spring.security.oauth2.client.registration.gitlab.client-id: <gitlab-client-id>
spring.security.oauth2.client.registration.gitlab.client-secret: <gitlab-client-secret>
spring.security.oauth2.client.registration.gitlab.authorization-grant-type: authorization_code
spring.security.oauth2.client.registration.gitlab.redirect-uri: http://localhost:8080/login/oauth2/code/gitlab
spring.security.oauth2.client.provider.gitlab.issuer-uri: https://gitlab.com
spring.security.oauth2.client.registration.gitlab.scope: read_user
spring.security.oauth2.client.provider.gitlab.user-info-uri: https://gitlab.com/api/v4/user
spring.security.oauth2.client.provider.gitlab.user-name-attribute: username

Redirection to Front-End

The social login is based on OAuth2/OIDC and is handled by the Back-End. After a successful or failed authentication with a social network, the Back-End redirects to the Front-End.

The Back-End uses the following methods to redirect to the Front-End in this order:

• A given redirect_uri query parameter provided by the Front-End to the Back-End in the authorization request ( e.g., http://localhost:8080/api/oauth2/authorization/github?redirect_uri=/login). The host can even be different (e.g., http://localhost:8080/api/oauth2/authorization/github?redirect_uri=http://localhost:4200/login)
• The referer in this authorization, but it can be hidden or lost after a redirection to the ID provider.
• A default target URL defined in the Back-End.

The first option is currently used.

The other options are defined by the following properties:

application.authentication.oauth2.defaultTargetUrl: http://localhost:4200/login
application.authentication.oauth2.useReferer: false

Name Parsing Strategy

By default, Suricate parses the user's first name and last name from the ID provider using the format "Firstname Lastname". However, you can also configure Suricate to parse the first name and last name based on the case ( upper/lower) using the following property:

application.authentication.socialProvidersConfig.<provider>.nameCaseParse: true

Simply replace <provider> with the appropriate social provider, such as github or gitlab.

Personal Access Token

The application allows for the generation of personal access tokens, which can be used for authentication. The following properties are used for token generation and verification:

application.authentication.pat.prefix: sup
application.authentication.pat.checksumSecret: changeit

It is recommended to update the checksumSecret with a different secret for each environment, to enhance security.

The prefix is used by the application to identify the token type and parse it.

Widgets

Here is given the guidelines to configure the widgets.

Encryption

Sensitive widget parameters such as passwords or tokens are encrypted in the database. You must change the encryption key for each environment using the following property:

jasypt.encryptor.password: changeitchangeitchangeitchangeit

Repositories

The first time you start the application, you'll need to configure a repository of widgets. To do this, navigate to the repositories tab and add a new repository. You can choose to add either a local or remote repository (such as GitLab or GitHub).

If you don't have a repository yet, you can create your own widgets repository by following the instructions provided in the official open-source widgets GitHub repository, or use this repository directly.

To configure this repository in Suricate, use the following settings:

Name: [ Enter a name of your choice ]
URL: https://github.com/michelin/suricate-widgets.git
branch: master
login: [ Your GitHub login ]
password: [ Your GitHub password ]

Swagger UI

Suricate provides a Swagger UI to test the API. You can access it at http://localhost:8080/swagger-ui/index.html.

You can authenticate using the POST /api/v1/auth/signin endpoint and then use the Authorize button to add the JWT token in the Authorization header.

Note: The authentication through social login is not supported yet by the Swagger UI.

Contribution

We welcome contributions from the community! Before you get started, please take a look at our contribution guide to learn about our guidelines and best practices. We appreciate your help in making Suricate a better tool for everyone.