README

Quick summary

Sentry Identity Server is an Authorization server implementing the OAuth2 specification. It consists of two components:

  1. Sentry Gateway - the authorization server
  2. Sentry Admin - an administration console to configure Sentry Gateway

Summary

Sentry Admin and Gateway are deployed as WAR files to an Apache Tomcat container. They run as separate applications pointing to the same database. Both the Admin and Gateway are deployed as split WARs to allow for custom modules to be loaded dynamically.

Pre-requisites

# Type Name Version Download
1 Platform Java 8.0 (1.8) https://tomcat.apache.org/download-80.cgi
2 Application Server Apache Tomcat 8.0+ https://tomcat.apache.org/download-80.cgi
3 Database Oracle 11.0+ http://www.oracle.com/technetwork/indexes/downloads/index.html#database
PostgreSQL 8.0+ https://www.postgresql.org/download/
MYSQL 5.0+ http://dev.mysql.com/downloads/

Setup Sentry Admin

This section describes the Sentry Admin setup procedure

Environment variables

E-mails

The following environment variables are optional, but required on Admin server if e-mails are to be sent from the system. E-mails are sent to Invite users and to Reset passwords:

  • SENTRY_MAIL_HOST
  • SENTRY_MAIL_PORT
  • SENTRY_MAIL_USERNAME
  • SENTRY_MAIL_PASSWORD

To use the custom email templates instead of default email templates provided by sentry, create the email templates and provide the template location to the below environment variable.

  • EMAIL_TEMPLATE_DIRECTORY

Gateway URL

Both the Admin and Gateway need to know the external URL that the Gateway is exposed on. This is used to compose the URLs for various browser redirections during the OAuth flows. This can be configured in the Admin UI (Admin Functions->Settings) or set as an environment variable

  • DEFAULT_SENTRY_GATEWAY_URL

    Admin and Gateway servers

Username Persistence Time

Username persistence time(hours) can be configured using the below options. Default time is set to 24 hours.

  • USERNAME_PERSISTENCE_HOURS

    username will be populated on the login page username input field.

Log paths

Auditing

DEFAULT_AUDIT_LOG_PATH - if auditing is enabled and configured to write to a log file, this environment variable is required. This can also be set in the Admin UI (Admin Functions->Settings).

Admin and Gateway servers

Server Logs
Using environment variables
  • SENTRY_ADMIN_LOG_PATH - admin server log location

    Admin server only

Database setup

Sentry currently supports the following databases:

  1. Oracle
  2. PostgreSQL
  3. MySQL

  4. The scripts to install the initial schemas are available in the src/main/db directory of the respective admin source tree - ${SENTRY_HOME}/admin/sentry-admin/src/main/db/

  5. The JDBC drivers are available at admin/sentry-admin/setup/jdbc-drivers/. Please copy the appropriate drive the server library path. This is typically $TOMCAT_HOME/lib for Apache Tomcat.

    Note: If you are redistributing Sentry as part of your product, please refer to the licensing for the drivers as there could be restrictions on redistributions

  6. Setup Datasource - Add the following Resource configuration to the context configuration for both Admin and Gateway servers:

       <Resource name="jdbc/sentryDB" auth="Container"  type="javax.sql.DataSource"
        username="<username>"
        password="<password>"
        driverClassName="<driver_class>"
        url="<jdbc_url>"
        maxTotal="<connection_pool_max>"
        maxIdle="<connection_pool_max_idle>"
        validationQuery="<database_validation_query>" />
    

Please refer to the container (Tomcat) documentation for descriptions of the above configuration parameters.

Deployment checklist

Deployment consists of the following steps as described above. This applies to both the servers.

  1. Download the Sentry Admin and Sentry Gateway WAR files from Sentryiam.com repository (http://www.sentryiam.com/releases/sentry-.zip)
  2. Setup two instances of Apache Tomcat with the desired configurations (ports, front-end web servers, load balancing etc.)
  3. Configure the Tomcat environments with the appropriate Sentry environment variables
  4. Configure the database with the scripts
  5. Configure the Resource within Tomcat pointing to the database
  6. Copy the JDBC driver to the library location
  7. Copy the application WAR file to the webapp location
  8. Start the server

Initial access

  1. The following browsers are supported:
    1. Google Chrome v51+ (recommended)
    2. Firefox v46+
    3. IE v11+
    4. Safari v10+ (MacOS only)
  2. Launch the Sentry Admin by browsing to http(s)://:/sentryadmin
  3. On initial access, Sentry Admin will prompt to setup a Super Admin account that can be used to administer the Sentry product.

Initial superadmin account creation

When the sentryadmin is installed, initially a registration screen is displayed and the user has to create a superadmin account.

Configuration

Sentry Gateway URL

Sentry gateway url can be configured using admin UI

From the Admin Functions->Settings screen in sentry admin application

Audit Log Path

Default audit log path can be configured using the below options

From the Admin Functions->Settings screen in sentry admin application

Setup Sentry Gateway

This section describes the Sentry Gateway setup procedure

Environment variables

E-mails

The following environment variables are optional, but required on Gateway server if e-mails are to be sent from the system. E-mails are sent to Invite users and to Reset passwords:

  • SENTRY_MAIL_HOST
  • SENTRY_MAIL_PORT
  • SENTRY_MAIL_USERNAME
  • SENTRY_MAIL_PASSWORD

To use the custom email templates instead of default email templates provided by sentry, create the email templates and provide the template location to the below environment variable.

  • EMAIL_TEMPLATE_DIRECTORY

Gateway URL

Gateway need to know the external URL that the Gateway is exposed on. This is used to compose the URLs for various browser redirections during the OAuth flows. This can be configured in the Admin UI (Admin Functions->Settings) or set as an environment variable

  • DEFAULT_SENTRY_GATEWAY_URL

Gateway server

Gateway custom error page

To use the custom error page instead of default error page provided by sentry, create a custom error page and set the location to the below environment variable.

  • CUSTOM_ERROR_PAGE_PATH - custom error html page path

Gateway server only

Gateway sign the tokens

To use the external key instead of in-memory key provided by sentry, create a key and set the location to the below environment variable.

  • INTERNAL_TOKEN_SIGNING_KEY - Path where symmetric keys are located with read/write permissions

Gateway server only

Log paths

Auditing

DEFAULT_AUDIT_LOG_PATH - if auditing is enabled and configured to write to a log file, this environment variable is required. This can also be set in the Admin UI (Admin Functions->Settings).

Google reCaptcha

Sentry validates the login attempt fails, we can configure the threshold value for the login fail attempts, after that google reCaptcha will be shown.

Register with the google reCaptcha and get the details. Registration link: https://www.google.com/recaptcha/intro/index.html

set the following As an environment variable

| Name | Value | Description

– | ---- | ---- | — | 1 | SENTRY_LOGIN_FAILED_ATTEMPT_THRESHOLD | integer | number of fail attempts limit 2 | GOOGLE_RECAPTCHA_KEY | text | Site key provided by google 3 | GOOGLE_RECAPTCHA_SECRET | text | Secret key provided by google 4 | GOOGLE_RECAPTCHA_VERIFYURL | text | google provide verify URL for the server side integration to validate the reCaptcha values.

Server Logs
Using environment variables
  • SENTRY_GATEWAY_LOG_PATH - gateway server log location

    Gateway server only

Database setup

Sentry currently supports the following databases:

  1. Oracle
  2. PostgreSQL
  3. MySQL

  4. The scripts to install the initial schemas are available in the release folder - ${<version>}/db/scripts/

  5. The JDBC drivers are available at admin/sentry-admin/setup/jdbc-drivers/. Please copy the appropriate drive the server library path. This is typically $TOMCAT_HOME/lib for Apache Tomcat.

    Note: If you are redistributing Sentry as part of your product, please refer to the licensing for the drivers as there could be restrictions on redistributions

  6. Setup Datasource - Add the following Resource configuration to the context configuration for both Admin and Gateway servers:

       <Resource name="jdbc/sentryDB" auth="Container"  type="javax.sql.DataSource"
        username="<username>"
        password="<password>"
        driverClassName="<driver_class>"
        url="<jdbc_url>"
        maxTotal="<connection_pool_max>"
        maxIdle="<connection_pool_max_idle>"
        validationQuery="<database_validation_query>" />
    

Please refer to the container (Tomcat) documentation for descriptions of the above configuration parameters.

Deployment checklist

Deployment consists of the following steps as described above. This applies to both the servers.

  1. Download the Sentry Admin and Sentry Gateway WAR files from Sentryiam.com repository(http://www.sentryiam.com/releases/sentry-.zip).
  2. Setup two instances of Apache Tomcat with the desired configurations (ports, front-end web servers, load balancing etc.)
  3. Configure the Tomcat environments with the appropriate Sentry environment variables
  4. Configure the database with the scripts
  5. Configure the Resource within Tomcat pointing to the database
  6. Copy the JDBC driver to the library location
  7. Copy the application WAR file to the webapp location
  8. Start the server

Initial access

  1. The following browsers are supported:
    1. Google Chrome v51+ (recommended)
    2. Firefox v46+
    3. IE v11+
    4. Safari v10+ (MacOS only)
  2. Launch the Sentry Admin by browsing to http(s)://:/sentryadmin
  3. On initial access, Sentry Admin will prompt to setup a Super Admin account that can be used to administer the Sentry product.

Initial superadmin account creation

When the sentryadmin is installed, initially a registration screen is displayed and the user has to create a superadmin account.

Configuration

Sentry Gateway URL

Sentry gateway url can be configured using admin UI

From the Admin Functions->Settings screen in sentry admin application

Audit Log Path

Default audit log path can be configured using the below options

From the Admin Functions->Settings screen in sentry admin application

Questions/Problems?

Please contact your Rivet representative.