On-premises installation

Authentication

There are three variants of the on-premises installation, each with different authentication methods.

1. Form-based login, with a local file-based user store (free and paid)

This variant is included with the basic installation, and configured to use a form-based login (username and password), with the set of users stored in a file called structurizr.users in the Structurizr data directory (passwords are hashed using bcrypt). A user with the username of structurizr and password of password is created by default. You can add, remove or modify users as needed. Each line in this file should be in the following format:

{username}={hashed password}

A simple utility page is provided to calculate a bcrypt hashed password at {structurizr.url}/bcrypt/{password} (e.g. http://localhost:8080/bcrypt/password).


It is also possible to configure a comma separated list of roles for every user, in a file called structurizr.roles, again in the Structurizr data directory. Each line in this file should be in the following format:

{username}={role1},{role2},{role3}

2. Form-based login, with integration to your LDAP server (paid add-on)

Integration with your LDAP server is also possible by downloading the LDAP variant of the on-premises installation. To configure your LDAP integration, place a copy of the WEB-INF/applicationContext-security-ldap-configuration.xml file into your Structurizr data directory, renamed to ldap.xml, and modify it as needed. Some of our customers have successfully integrated the on-premises installation with FreeIPA and Microsoft Active Directory (via the LDAP binding). If you make any changes to the LDAP configuration, you will need to restart the on-premises installation.

See LDAP server for details on how to configure LDAP.

3. Single sign-on via SAML 2.0 (paid add-on)

Single sign-on is possible via SAML 2.0 integration with your Identity Provider. This has been tested against Auth0, Okta, Keycloak, and Microsoft Azure Active Directory. After downloading the SAML variant of the on-premises installation, here are the basic steps:

  1. Register the Structurizr on-premises application with your Identity Provider. When doing this, you will need a "Reply URL", which is of the form {structurizr.url}/saml/SSO (e.g. http://localhost:8080/saml/SSO).
  2. The structurizr.url property in the structurizr.properties file should be set to the URL where Structurizr is installed (e.g. http://localhost:8080).
  3. The structurizr.saml.entityId property in the structurizr.properties file should be set to the SAML Entity ID that you are using to identify the Structurizr on-premises installation (configured with your Identity Provider when setting up the application/client in step 1).
  4. A copy of your Identity Provider's SAML metadata (XML format) should be saved to a file called saml-idp-metadata.xml in your Structurizr data directory.
  5. Map the IdP username to a SAML attribute named http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  6. Map the IdP roles/groups to a SAML attribute named http://schemas.xmlsoap.org/claims/Group

If you make any changes to the SAML configuration, you will need to restart the on-premises installation. Here are some guides that show how to integrate with different identity providers.