Installation guide¶

This document describes how to setup and install Sequel Security and setup connected services. The guide describes the typical installation of Sequel Security applications and is targeted mainly at IT professionals. Please accept defaults during installation unless they are not specified. Ensure no users are active in the environment before proceeding with installation, this includes batch users.

If there are any errors during installation, close Sequel.Deployment.Manager.exe and reopen it before retrying.

Pre-Requisite Information¶

Logging database¶

All Sequel Security applications have the ability to log information, errors, etc. to a logging database. This is important to have configured as it helps troubleshooting when we run into problems. The Deployment Manager does not create the logging database, it can only create the main database so this needs to be created beforehand and then referenced in the logging database settings during installation (Global Settings \ Environment Settings \ Logging settings).

Installation Information¶

After reviewing the pre-requisite information and before starting installation with the Deployment Manager, we recommend becoming familiar with this guide and the design of the Security applications like the different types of authentication, certificates, components, scaling-out options, etc. All of these necessary topics can be found below in this section.

As a suggestion, before installing security, we recommend you to ensure the pre-installation check-list has been completed. All checks in this list are covered in this document during the next sections.

Public vs. Private URLs¶

In the Sequel Security applications some communications are done using internal URLs and others are done using external ones. The internal URLs are private and are defined in the internal settings of the applications and can only be accessed between certain servers and applications in a private network, the external ones are public and can be accessed by external clients (like a web browser). Some examples of use are:

• Public URLs are for interactive users: logging in users, redirection that affect the browser, browser navigation, etc.
• Private URLs are for service-to-service communication.

The public and private URLs are always going to be the same and are so by default when using the Deployment Manager to install the Sequel Security applications for private networks (like configuration environments or system test environments, that does not require to be exposed to internet). For production environments, where the application is exposed to internet those URL are different. If for example we are deploying to an AWS, we have a private IPv4 and a public IPv4 address. We could then use these different addresses to maintain internal communication through our private AWS network to add that extra layer of security.

Another use case for different private and public URLs is for the use of load balancers. It can be either on premise load balancers or Amazon's Elastic Load Balancing (ELB). The load balancer will normally need a public facing address otherwise it cannot listen to external requests from the Internet. Then, the communication between the load balancer and the instances underneath will ideally use private addresses to keep the internal traffic in the private network.

The installation process will always ask us for the URL of the service (this is the private) and the public URL.

If some URL includes a path it's highly recommended to set this value using the PascalCase naming convention and follow this convention on all applications referring to this URL.

References:

• https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-instance-addressing.html#using-instance-addressing-common

Domains¶

It's important to keep in mind the use of domains and sub-domains when installing Security as they need to be correctly set for the cookies to be visible on the same domain by all the Sequel applications. This has to be done this way so that the single sign out and single sign in can function correctly, and also so that different Sequel clients can't see the cookies from another client. Below is an example of how the public URLs should look versus how they shouldn't so that we can better understand the differences:

• Bad configuration for 2 different clients:
  • securityclient1.sequel.com
  • workflowclient1.sequel.com
  • securityclient2.sequel.com
  • workflowclient2.sequel.com

As we can see here, this is a common mistake, as the domain here is actually "sequel.com", therefore both clients have all applications on the same domain so their cookies are visible between them, so when closing the session from one client it will close the sessions from the others as well. However, because of how the token are granted the user does not have access to other environments; but they will override the cookies causing strange behaviors in the navigation.

• Correct configuration for 2 different clients:
  • security.client1.sequel.com
  • workflow.client1.sequel.com
  • security.client2.sequel.com
  • workflow.client2.sequel.com

Here we have a correct configuration as the domain and the subdomain for each client are different "client1.sequel.com" for the first and "client2.sequel.com" for the second, so the cookies are only visible on their respective domains and SSI and SSO will work in an isolated manner as expected.

During the installation, the security domain and the public security domain are asked. The public security domain is defined with the CookieDomain attribute during installation process, this attribute specifies which hosts are allowed to receive the cookie. For allowing sub-domains, this value must be prefixed with a dot. As a sample, uat.sequel.com will be used for the domain, while .uat.sequel.com will be used for sub-domains too. In general, the dot prefixing the domain is preferred as we use sub-domains.

SSL Certificate¶

For a secure connection to be made between the web browser and the Sequel Security applications, or between different services inside the Sequel Security applications, it's necessary for the connection to be encrypted using HTTPS (default and recommended binding protocol configured in the Deployment Manager). For this, the web server must have a valid SSL certificate installed, issued by a Certificate Authority.

To obtain and install this certificate on IIS for a Windows Server please consult the following guide: https://www.digicert.com/kb/csr-creation-ssl-installation-iis-10.htm.

For an AWS instance please refer to Amazon's Certificate Manager (https://aws.amazon.com/certificate-manager/) for creating and managing SSL certificates. There is also an AWS Certificate Manager Private Certificate Authority (https://aws.amazon.com/certificate-manager/private-certificate-authority/) that extends the certificate manager's capabilities to both public and private certificates for use in EC2 instances.

With the certificate created and installed on the server we need to retrieve it's thumbprint as it is a required parameter during installation. We can find this value in the 'Details' tab of the certificate which will be in the servers certificate store. This value is for the parameter Global Settings \ IIS Settings \ Https Certificate Thumbprint of the Deployment Manager.

Managing certificates for the public and private URLs¶

Previously, we have spoken about public and private URLs. We need to take these into account for the SSL certificates too, because we want to use the same certificate for both the internal and the external URLs (multi-domain certificates). To achieve this, we need to use Subject Alternative Names (SAN) which allows us to add a list of valid domains for one specific certificate. This can also be found in the 'Details' tab of the certificate and can be modified there. The main DNS Name it should contain will be the external URL, we need to make sure the internal URLs are added too.

References:

• https://www.digicert.com/ssl/
• https://www.digicert.com/multi-domain-ssl/
• https://www.digicert.com/csr-creation-ssl-installation-iis-10.htm
• https://www.digicert.com/subject-alternative-name.htm

The URL where the Sequel Authentication application is (or will be) available (protocol://subdomain.domain.tld/path) is case-sensitive and it's highly recommended to set this value using the PascalCase naming convention (e. g. protocol://subdomain.domain.tld/Authentication) and follow this convention on all applications referring to this URL. Same rule should be applied for all services. This is required for some cookies that are defined at path; a request-path matches a given cookie-path if at least one of the following conditions holds:

• The cookie-path and the request-path are identical.
• The cookie-path is a prefix of the request-path, and the last character of the cookie-path is %x2F ("/").
• The cookie-path is a prefix of the request-path, and the first character of the request-path that is not included in the cookie-path is a %x2F ("/") character.

Scaling-out¶

An important feature with the Sequel Security applications is the ability to scale-out each application, therefore being able to balance out the load across different servers when a lot of traffic is expected. Let's quickly go over each application and why this would be useful and what to take into account:

• Administration: the Security Administration web app is a simple SPA application developed using React capable of handling plenty of requests as not many users will be connected simultaneously plus it's content is mostly static, so the only reason to have several servers would be for failover reasons, if one server fails, we can redirect traffic to the other. Because of this, there are no special concerns of things to take into account if this component were scaled out.
• Authorization: the same applies for Authorization, main reasons for using several servers would be for failover and there isn't anything in particular to take into consideration. Authorization receives plenty of requests but has a cache system in place to maximize speed and stability.
• Authentication: this would probably be the most ideal one to scale-out as Authentication receives many requests regarding logins, log-outs, token verification, handling session timeouts, etc. If used, we must make sure that the all other applications are pointing to the Authentication's public load balancer URL. We must also keep in mind that when scaling out servers with Duende IdentityServer they each have to share the ASP.NET Core data protection keys. Without this they act independently and the applications will log in and out depending on the server that was hit (more information on this here: https://docs.duendesoftware.com/identityserver/v6/deployment/). The recommended setting for scaling out the authentication service is setting DataProtectionSettings.Mode to Database.
• Security API: scaling out the Security API can also be of great use as the API retrieves plenty of information from the database to respond to many requests from different applications. Just like Authentication, the only thing to consider is to make sure all the rest of the applications (especially Authorization) are pointing to the APIs public load balancer URL.

Security behind Load Balancers¶

When deploying Security to AWS behind a Load Balancer or behind any Reverse Proxy (like nginx, traefik, kong...) and HTTPS is required, Security must trust some headers sent by the Load Balancers/Reverse Proxies. Failing to do so, Security will not work properly, with errors like unable to log in in Administration or infinite redirection loop in Authentication. To enable the trust on these headers, set the TrustForwardedHeaders setting to true on Security API, Authentication and Authorization.

Certificate generation for signing tokens¶

In production, we need a constant self signed certificate that will be used by the Authentication server to sign tokens. To achieve this we need to use the makecert and pvk2pfx utilities to create a pair of certificates. These two executables can normally be used in a Visual Studio Developer Command Prompt, if not, then they can be found in the Windows Software Development Kit for the specific version of Windows being used (https://developer.microsoft.com/en-us/windows/downloads/sdk-archive). After installing the required version, the executables, by default, will be in 'C:\Program Files (x86)\Windows Kits\'.

We will need to generate a Certificate Authority and a Personal Information Exchange (that contains a Private Key and a Public Key).

• _makecert -n "CN=NameOfCertificate" -a sha256 -sv signing-certificate.pvk -r signing-certificate.cer_

  • This will create a new self-signed certificate with it's public key in 'signing-certificate.cer' which is exposed to clients so that they can validate tokens, and it's private key in 'signing-certificate.pvk' used to sign the tokens.

• _pvk2pfx -pvk signing-certificate.pvk -pi PASSWORD -spc signing-certificate.cer -po PASSWORD -pfx signing-certificate.pfx_

  • This will combine the PVK and CER files into a single PFX file containing both the public and private keys for the certificate.

This PFX file can now be used. In the installation process with the Deployment Manager when we come across the parameter 'Signing certificate: file' here we will need to introduce the path of the PFX file. It's recommended to simply copy and paste this file in '{DeploymentManagerRoot}\Packages\Authentication\Files', this way the certificate is in the root of where all the Authentication server files are and this parameter can be filled with just the name of the certificate and not worry about the path (e.g 'Signing certificate: file': signing-certificate.pfx).

The parameter 'Signing certificate: password' during installation is the 'PASSWORD' value used to create the PFX file.

Important: Certificate used in production environments must be unique. Do not reuse the same production certificate in other environments it will cause a high security breach.

References:

• http://amilspage.com/signing-certificates-idsv4/
• https://devblogs.microsoft.com/aspnet/asp-net-core-authentication-with-identityserver4/

Authentication providers¶

There are 3 different authentication providers available in the Security apps, so 3 different ways of signing in. We can enable each of them during the installation process to activate them on the Authentication page and then use whichever one we want. They can be found during the Deployment Manager installation in the section Installation Parameters\Sequel Security\Authentication Server.

Sequel identity¶

Sequel Identity or Password based. The most typical way to sign in to the Security apps is with user accounts created through the Security Admin website that are stored directly into the Security database. By default, we should create an initial ADMIN user with the Deployment Manager, this will allow us to use the Sequel identity method to sign in with the user name and password chosen for our ADMIN user and then start creating new users that will also be able to sign in with this method.

Windows Authentication¶

To make use of the Windows Authentication sign in method, a pre-requisite is to have this feature activated in Windows. To do this, we must tick the option to activate and install Windows Authentication on the server. It can be found under 'Server roles' if using a Windows Server or under 'Windows features' if using a normal Windows OS. The option is located:

• Windows Server: Web Server (IIS) \ Web Server \ Security \ Windows Authentication
• Windows: Internet Information Services \ World Wide Web Services \ Security \ Windows Authentication

Once we have this, we must configure the Authentication settings of the Internet Information Services (IIS) on the server where the Authentication server is installed (or will be). Both the 'Anonymous Authentication' and 'Windows Authentication' settings must be set to 'Enabled'. Lastly, when making use of this method to sign in we first have to make sure we have a Sequel user created with the same username as the one used to sign into the Windows session we are currently using. For example, if my username in Windows is 'ABC123', then there must be a user in the Sequel Security database with this same username or SsoUsername.

Microsoft Azure Active Directory¶

This provider uses the Microsoft login service to authenticate users. Before using it, it's necessary to register the Sequel Authentication application in Microsoft's application registration portal by creating a new app (https://apps.dev.microsoft.com/). Once we have done this we will need to set or retrieve three values:

• Client secret: we must create a new client secret in Microsoft's application registration portal and save it.
• Application (client) ID: generated automatically when we have added our new app.
• Redirect URLs: we must set a new redirect URL which represents the URL Microsoft redirects us to after authenticating a user. It must match with the value of the setting 'LoginSettings:IdentityProvidersSettings:Microsoft:CallbackPath' in the appsettings.json file of Authentication. By default, this value is set to '/signing-microsoft', therefore this redirect URL should look something like this: 'https://{AuthenticationServer}/Authentication/signing-microsoft'.

ISO ClaimSearch¶

This provider uses elements provided by ISO ClaimSearch to authenticate users. We need to set two values:

• Login Url: ISO ClaimSearch login page. Users will be redirected to this URL if they are not already authenticated in ISO ClaimSearch.
• Session Validation Endpoint: Endpoint to check if user have a valid ISO ClaimSearch's session.

Okta¶

This provider uses a Okta to authenticate users. Before using it, it's necessary to register the Sequel Authentication application in the Okta domain. Once we have done this we will need to set or retrieve three values:

• Domain: Okta's domain (e.g. mycompany.okta.com)
• ClientId: ID generated by Okta for the application.
• Client secret: Secret generated by Okta for the application.
• AuthorizationServerId: ID of authorizations server. Used default if no value is provided.

JumpCloud¶

This provider uses a JumpCloud to authenticate users. Before using it, it's necessary to register the Sequel Authentication application as SAML SSO application in JumpCloud console. Once we have done this we will need to set or retrieve three values:

• SPEntityId: Unique identifier used by configured Service Provider
• LoginUrl: JumpCloud URL for the login process (e.g. https://sso.jumpcloud.com/saml2/security-authentication).
• X509SigningCertificate: X509 certificate used JumpCloud SSO Application for signing its responses.

SMTP¶

If we are using the Sequel identity authentication provider then one required functionality is the ability to reset passwords. For this to work we will need a working SMTP server so that the Security applications can send the corresponding user a confidential email containing the link to reset their password.

The settings to take into account and therefore the information you will need from the SMTP to be used are the following:

• Installation Parameters \ Security API \ SMTP host name: host name or IP address of the SMTP server.
• Installation Parameters \ Security API \ SMTP host port: port number to connect to the SMTP server.
• Installation Parameters \ Security API \ SMTP host username: user name of the email account that will be used on the SMTP server. Keep it empty if the SMTP server does not support authentication (seen in some AWS deployments).
• Installation Parameters \ Security API \ SMTP host password: password of the email account that will be used on the SMTP server.

• Installation Parameters \ Security API \ Secure socket options: allows us to configure SSL for sending email in different ways. Possible options:

  • None: No SSL or TLS encryption should be used. This setting is the most common in AWS deployments.
  • Auto: Allow to decide automatically which SSL or TLS options to use (default). If the server does not support SSL or TLS, then the connection will continue without any encryption.
  • SslOnConnect: The connection should use SSL or TLS encryption immediately.
  • StartTls: Elevates the connection to use TLS encryption immediately after reading the greeting and capabilities of the server. If the server does not support the STARTTLS extension, then the connection will fail and a NotSupportedException will be thrown.
  • StartTlsWhenAvailable: Elevates the connection to use TLS encryption immediately after reading the greeting and capabilities of the server, but only if the server supports the STARTTLS extension.

• Installation Parameters \ Security API \ Validate server certificate: determines whether or not the SMTPs server certificate should be validated. Defaults to true; if false, the server certificate will always be trusted and not be validated.

• Installation Parameters \ Security API \ Enable send forgot password email: determines whether or not the ability to reset passwords via email is possible.
• Installation Parameters \ Security API \ Forgot password email address: email address that will be used for sending the forgot password link.

reCAPTCHA¶

In the Security Authentication web application, when requesting a password reset because we have forgotten our password or because we are simply requesting an initial one, there is a captcha verification before being able to click on the 'Reset Password' button. We are using Google's reCAPTCHA v2 system (https://www.google.com/recaptcha) and it is necessary for every installation to have their own captcha created and configured from Google's reCAPTCHA admin console.

To be able to generate V2 captchas we need to select the "V3 Admin Console" option in the link above. As the "Get Started with Enterprise" option will lead us to the Google Cloud console which only generates Enterprise Captcha keys.

Here, we need to register a new web site filling in it's name, the type of reCAPTCHA (select v2) and a domain it is valid for. The domain is important as here we will need to enter in the URI where the Sequel Authentication Server is (or will be) available (subdomain.domain.tld). Lastly, we can configure how restrictive the check is, from simply showing a checkbox to having to classify photos, for example.

During the installation process of Authentication we will encounter 3 parameters related to the captcha. One to enable it or not, and then the data site key and the secret key, both can be found in the settings section of the previously configured web site in the Google admin console for reCAPTCHA.

Databases¶

Regarding the databases used in the Sequel Security applications, we have the following:

• multi-tenancy database: contains the list of valid tenants that can access the apps. Each tenant is represented by a row in the multi-tenancy.Tenant table and contains the connection string for that tenant's main database. Current version supports only a single tenant.
• Main database: the connection string for the main database does not appear in any of the applications settings, it is set in the multi-tenancy database as explained above. This is the most important database as it contains the roles, securables, users, etc. It is important to make sure the multi-tenancy database is set correctly during the installation process and that the main database is correctly set in its corresponding tenant row also.
• Logging database: used for saving logs and needs to be created prior to installation as explained in the 'Pre-Requisite Information' at the beginning of this guide.

It's important to note that the isolation level of all databases should be set to "read committed snapshot", this means the database engine uses row versioning and snapshot isolation as the default, instead of using locks to protect the data.

Also, if using high-availability and disaster-recovery SQL servers then the 'Always On availability groups' (AG) feature must be activated. For this the parameter Global Settings \ Data Sources \ AG enabled in the Deployment Manager must be set to true. This will set the 'MultiSubnetFailover' option of the connection strings to true.

References:

• https://docs.microsoft.com/en-GB/dotnet/framework/data/adonet/sql/snapshot-isolation-in-sql-server
• https://docs.microsoft.com/en-GB/sql/database-engine/availability-groups/windows/always-on-availability-groups-sql-server

Swagger¶

The Authorization and the Security API applications use Swagger (https://swagger.io/) for easy access to all the API calls and their documentation. This is especially useful for internal use when testing but we don't want Swagger to be activated in production. For this, both the Installation Parameters \ Security API \ Swagger Enabled and the Installation Parameters \ Authorization Server \ Swagger Enabled parameters should be set to false when installing the applications for a client.

Deployment Manager¶

The installation in deployment manager is structured in three modules: database, web components and sync services. Our recommendation is start installing the database first and then the web components. If the sync services are required, it will be installed after installing the other modules.

Databases¶

For installing the multi-tenancy and single tenant (aka security) databases with the vanilla configuration for authorization and the specific authentication configuration for the security services in this environment.

More information at database installation guide.

Security applications¶

For installing Sequel Security Web services:

• Security API
• Authentication Server
• Authorization Server
• Administration Web

More information at application installation guide.

Sync Services¶

There are two synchronization services related with security:

• The Security Sync Service, that is responsible of keeping up to date the security schema on Sequel Workflow, Sequel Broking, Sequel UW, and Sequel Claims databases with information from the Security service. Each target database requires a sync service configured; in some cases, like Sequel Claims, this service has been replaced by an specific version owned by Claims.
• The LDAP Sync Service, that is responsible of synchronization of users, roles and groups at Security from a Windows AD. This service is optional and depends on project requirements.
• The Azure AD Sync Service, that is responsible of synchronization of users, roles and groups at Security from a Azure AD. This service is optional and depends on project requirements.

More information at sync services installation guide.

Other settings¶

There are other settings included at the appsettings.json files that are not configurable during installation with the Deployment Manager:

Administration¶

Authentication¶

Authorization¶

Security API¶

Sync Services¶

Allows us to install services used to synchronize data related to security.

• Security Sync Service, synchronize the information stored in the security services with the information stored in Origin or Claims. The version included in the security package is basic version that synchronizes just some information. We highly recommend to install the versions provided by Origin and Claims products as those products have customized versions for this synchronization process. This service consumes information from Security, and never writes.
• LDAP sync service. This is only required for synchronizing users and AD groups (memberships) with Sequel Security Services. This service reads information from a LDAP server and pushes changes to the security service API.
• Azure AD sync service. This is only required for synchronizing users and AD groups (memberships) with Sequel Security Services. This service reads information from Azure AD and pushes changes to the security service API.

More information at sync services installation guide.