Advanced configuration

How to download Security service:

You can download the Security service image by using docker command:

docker pull tshio/security

We keep the image on our public DockerHub.

How to set up Security service in your docker-compose file:

  security:
    image: tshio/security:latest
    working_dir: /app/build/services/security
    command: api
    hostname: security
    environment:
      ACCESS_TOKEN_SECRET: secret1234
      ACCESS_TOKEN_EXPIRATION: 1000
    ports:
      - "50050:50050"
    depends_on:
      - postgres
      - redis

You can configure security service by environment variable. The variables allow you to overwrite the default setting of the Security service. You can find a full variables list below.

Security service depends on two other containers to work properly: DB (Postgres in this situation) and cache (Redis). Therefore we need to use depends_on property.

If you would like to initialize the database with users and policy that you already have, you can do it by creating a new directory e.g. init-data-volume with two files in it: users.json and policy.json. After that you need to add volumes to security container in your docker-compose.

    volumes:
      - ./init-data-volume/:/app/services/security/init-data-volume

users.json schema:

[
    {
      "username": "user1",
      "password": "passw0rd",
      "attributes": ["attr1", "attr2"]
    },
    {
      "username": "user2",
      "password": "passw0rd",
      "attributes": ["attr1", "attr2"]
    }
]

policy.json schema:

[
    {
      "resource": "res1",
      "attribute": "attr1"
    },
    {
      "resource": "res1",
      "attribute": "attr2"
    },
    {
      "resource": "res2",
      "attribute": "attr1"
    },
    {
      "resource": "res2",
      "attribute": "attr1"
    },
    {
      "resource": "res1",
      "attribute": "attr1"
    },
    {
      "resource": "res1",
      "attribute": "attr1"
    }
]

Social login

Security allows to login using Facebook / Google / Microsoft Azure. In order to use those, configure environment variables. It is possible to have multiple social login options active at the same time.

Google Auth

  security:
    image: tshio/security:latest
    working_dir: /app/build/services/security
    command: api
    hostname: security
    environment:
      ACCESS_TOKEN_SECRET: secret1234
      ACCESS_TOKEN_EXPIRATION: 1000
      OAUTH_ENABLED_PROVIDERS: "google"
      OAUTH_GOOGLE_CLIENT_ID: 1024671591387-1h85kq8p747478ouqinaq5tm5953u17.apps.googleusercontent.com
      OAUTH_GOOGLE_CLIENT_SECRET: GMHPdnTRGLmelReTFHxNBfU
    ports:
      - "50050:50050"
    depends_on:
      - postgres
      - redis

Facebook Auth

  security:
    image: tshio/security:latest
    working_dir: /app/build/services/security
    command: api
    hostname: security
    environment:
      ACCESS_TOKEN_SECRET: secret1234
      ACCESS_TOKEN_EXPIRATION: 1000
      OAUTH_ENABLED_PROVIDERS: "facebook"
      OAUTH_FACEBOOK_CLIENT_ID: 95901699118315
      OAUTH_FACEBOOK_CLIENT_SECRET: b184620eea19a283573c38b614e9dc5
    ports:
      - "50050:50050"
    depends_on:
      - postgres
      - redis

Microsoft Azure Auth

  security:
    image: tshio/security:latest
    working_dir: /app/build/services/security
    command: api
    hostname: security
    environment:
      ACCESS_TOKEN_SECRET: secret1234
      ACCESS_TOKEN_EXPIRATION: 1000
      OAUTH_ENABLED_PROVIDERS: "microsoft"
      OAUTH_MICROSOFT_CLIENT_ID: 95901699118315
      OAUTH_MICROSOFT_CLIENT_SECRET: b184620eea19a283573c38b614e9dc5
    ports:
      - "50050:50050"
    depends_on:
      - postgres
      - redis

Multiple providers

  security:
    image: tshio/security:latest
    working_dir: /app/build/services/security
    command: api
    hostname: security
    environment:
      ACCESS_TOKEN_SECRET: secret1234
      ACCESS_TOKEN_EXPIRATION: 1000
      OAUTH_ENABLED_PROVIDERS: "microsoft,google,facebook"
      OAUTH_MICROSOFT_CLIENT_ID: 95901699118315
      OAUTH_MICROSOFT_CLIENT_SECRET: b184620eea19a283573c38b614e9dc5
      OAUTH_FACEBOOK_CLIENT_ID: 95901699118315
      OAUTH_FACEBOOK_CLIENT_SECRET: b184620eea19a283573c38b614e9dc5
      OAUTH_GOOGLE_CLIENT_ID: 1024671591387-1h85kq8p747478ouqinaq5tm5953u17.apps.googleusercontent.com
      OAUTH_GOOGLE_CLIENT_SECRET: GMHPdnTRGLmelReTFHxNBfU
    ports:
      - "50050:50050"
    depends_on:
      - postgres
      - redis

Mailer configuration

Security comes with built-in mailer. This allows you to send reset password / user creation emails directrly from it. Of course you can change templates if required. By default mailer is turned off. Use environment variables to turn it on:

  security:
    image: tshio/security:latest
    working_dir: /app/build/services/security
    command: api
    hostname: security
    environment:
      ACCESS_TOKEN_SECRET: secret1234
      ACCESS_TOKEN_EXPIRATION: 1000
      MAILER_TYPE: standalone
      MAILER_SMTP_HOST: "mailhog"
      MAILER_SMTP_PORT: 1025
      MAILER_SMTP_SECURE: "false"
      MAILER_NEW_PASSWORD_SPA_URL: "http://localhost:3000/auth/reset-password"
    ports:
      - "50050:50050"
    depends_on:
      - postgres
      - redis

By default it will built in templates. If you want to use a custom ones then remember to mount them to a specific volume:

  security:
    image: tshio/security:latest
    working_dir: /app/build/services/security
    command: api
    hostname: security
    environment:
      ACCESS_TOKEN_SECRET: secret1234
      ACCESS_TOKEN_EXPIRATION: 1000
      MAILER_TYPE: standalone
      MAILER_SMTP_HOST: "mailhog"
      MAILER_SMTP_PORT: 1025
      MAILER_SMTP_SECURE: "false"
      MAILER_NEW_PASSWORD_SPA_URL: "http://localhost:3000/auth/reset-password"
    ports:
      - "50050:50050"
    volumes:
      - ./templates:/app/services/security/src/utils/mailer/templates  
    depends_on:
      - postgres
      - redis

Currently we support 3 templates:

  • create-user - used for new users
  • reset-password - used to get new password
  • reset-password-token - used to get link to website where you can set a new password

The structure of templates directory need to match:

templates:
  create-user:
    default:
      subject.pug - template for subject
      content.pug - template for content
  reset-password:
    default:
      subject.pug - template for subject
      content.pug - template for content    
  reset-password-token:
    default:
      subject.pug - template for subject
      content.pug - template for content

Default templates

Create user

Subject

= `Welcome ${name}`

Content

h1 Thank you for creating an account
p Hi #{name}
p Your login: #{user}

Reset password

Subject

= "Reset password"

Content

h1 Your password has been changed successfully!
p Hi #{name}, your new password is: #{password}

Reset password token

Subject

= "Reset password initialized"

Content

h1 Reset password initialized!
p Hi #{name}, go to <a href="#{spaUrl}?token=#{token}">reset password page</a>

Production usage

It is recommended to create a project specific image of security that will ba based on tshio/secuirty and contain premade policies, users and email templates (if using standalone version). The easiest way to do so is to create your own Dockerfile:

FROM tshio/security:latest as security

COPY templates /app/services/security/src/utils/mailer/templates
COPY init-data-volume /app/services/security/init-data-volume

Notification about changes in policies and users

Each time the policy is added or removed you can be informed about it. Also changes in users (adding/removing attributes, adding/removing users, changing activation state of the user) triggers notification. The payload of notification is object implementing Event interface (defined in shared/event-dispatcher/index.ts). Curently the module can emit the following events:

  • PolicyAddedEvent:
class PolicyAddedEvent {
  name: string;
  payload: PolicyEventPayload;
}
  • PolicyRemovedEvent:
class PolicyRemovedEvent {
  name: string;
  payload: PolicyEventPayload[];
}
  • UserAddedEvent:
class UserAddedEvent  {
  name: string;
  payload: UserEventPayload;
}
  • UserRemovedEvent:
class UserRemovedEvent  {
  name: string;
  payload: UserEventPayload;
}
  • UserActivatedEvent:
class UserActivatedEvent  {
  name: string;
  payload: UserEventPayload;
}
  • UserDeactivatedEvent:
class UserDeactivatedEvent  {
  name: string;
  payload: UserEventPayload;
}
  • UserAttributeAddedEvent
class UserAttributeAddedEvent  {
  name: string;
  payload: UserEventPayload;
}
  • UserAttributeRemovedEvent
class UserAttributeRemovedEvent  {
  name: string;
  payload: UserEventPayload;
}

The types of payload are defines as:

  • PolicyEventPayload:
interface PolicyEventPayload {
  id: string;
  attribute: string;
  resource: string;
}
  • UserEventPayload:
interface UserEventPayload {
  userId: string;
  attributes: UserEventAttributePayload[];
}
  • UserEventAttributePayload:
interface UserEventAttributePayload {
  id: string;
  name: string;
}

You can configure callback URLs (one or more) of the notification by setting environment variable EVENT_DISPATCHER_CALLBACK_URLS. By default this variable is empty so no notifications are sent.

Supported environment variables

API_URL:

  • Description: The URL where the application is available outside
  • Default: ""

PASSWORD_REGEX:

  • Description: Regexp used for password validation
  • Default: ".{8,}"

PASSWORD_VALIDATION_ERROR

  • Description: Error message if the password doesn't match regexp
  • Default: "password must be at least 8 characters"

PASSWORD_RANDOM:

  • Description: The variable specifies if users that will be created from the file should have a random password generated or a password should be provided in the user's file.
  • Default: false

PASSWORD_RANDOM_MAX_LENGTH:

  • Description: The variable specifies the length of the random generated password.
  • Default: 8

API_KEY_REGEX:

  • Description: Regexp that shows how the api-key suppose to look like
  • Default: ".{8,}"

REDIS_URL:

  • Description: The variable specifies URL to Redis.
  • Default: "redis://redis:6379"

REDIS_PREFIX:

  • Description: The variable specifies Redis prefix.
  • Default: "rad-modules:security:"

ACCESS_TOKEN_EXPIRATION:

  • Description: The variable specifies how long the access token will be valid in seconds
  • Default: 600

ACCESS_TOKEN_SECRET:

  • Description: The variable specifies secret that will be used for access token
  • Default: "secret1"

REFRESH_TOKEN_EXPIRATION:

  • Description: The variable specifies how long the refresh token will be valid in seconds IMPORTANT!: REFRESH_TOKEN_EXPIRATION should be greater than ACCESS_TOKEN_EXPIRATION
  • Default: 1200

REFRESH_TOKEN_SECRET:

  • Description: The variable specifies secret that will be used for refresh token
  • Default: "secret2"

CONNECTION_STRING:

  • Description: The variable specifies the database connection string
  • Default: "postgres://postgres:password@postgres:5432/users"

DB_LOGGING:

  • Description: The variable specifies if the logging in the database should be turned on
  • Default: true

OAUTH_ENABLED_PROVIDERS"

  • Description: The variable specifies which OAuth providers are enabled.
  • Default: ""
  • Available: "google, facebook, microsoft, other"

OAUTH_CLIENT_ID: Deprecated

  • Description: The variable specifies the id of external OAuth provider
  • Default: ""

OAUTH_SECRET: Deprecated

  • Description: The variable specifies the secret for external OAuth provider
  • Default: ""

OAUTH_DEFAULT_ATTRIBUTES:

  • Description: A comma-separated list of default attributes assigned to a new oauth user
  • Default: []

OAUTH_ALLOWED_DOMAINS: Deprecated

  • Description: A comma separated list of domains that are allowed to login using oauth
  • Default: []

OAUTH_GOOGLE_CLIENT_ID:

  • Description: The variable specifies the id of external Google OAuth provider
  • Default: ""

OAUTH_GOOGLE_CLIENT_SECRET:

  • Description: The variable specifies the secret for external Google OAuth provider
  • Default: ""

OAUTH_GOOGLE_CLIENT_ALLOWED_DOMAINS:

  • Description: A comma separated list of domains that are allowed to login using Google OAuth
  • Default: []

OAUTH_MICROSOFT_CLIENT_ID:

  • Description: The variable specifies the id of external Microsoft OAuth provider
  • Default: ""

OAUTH_MICROSOFT_CLIENT_SECRET:

  • Description: The variable specifies the secret for external Microsoft OAuth provider
  • Default: ""

OAUTH_MICROSOFT_CLIENT_ALLOWED_DOMAINS:

  • Description: A comma separated list of domains that are allowed to login using Microsoft OAuth
  • Default: []

OAUTH_FACEBOOK_CLIENT_ID:

  • Description: The variable specifies the id of external Facebook OAuth provider
  • Default: ""

OAUTH_FACEBOOK_CLIENT_SECRET:

  • Description: The variable specifies the secret for external Facebook OAuth provider
  • Default: ""

OAUTH_CREATE_USER_ACCOUNT

  • Description: The variable specifies if a user logged via OAuth provider should have an account created in the DB after the login flow
  • Default: false

CREATE_USER_ACCOUNT_ON_OAUTH Deprecated

  • Description: The variable specifies if a user logged via OAuth provider should have an account created in the DB after the login flow
  • Default: false

INITIAL_USERS_DATA_JSON_PATH:

  • Description: The variable specifies the path to file with initial data for the "User" table
  • Default: "/app/services/security/init-data-volume/users.json"

INITIAL_POLICIES_DATA_JSON_PATH:

  • Description: The variable specifies the path to file with initial data for the "Policies" table
  • Default: "/app/services/security/init-data-volume/policy.json"

LOG_LEVEL:

  • Description: The variable specifies the level of logging logs by the logger available options: "error", "warn", "help", "info", "debug", "verbose", "silly"
  • Default: "debug"

REQUEST_LOGGER_FORMAT:

  • Description: All requests are logged so the DevOps can check if the request comes from a user or other service (we use morgan library to log information). We created our format to display information but fill free to use one of build-in morgan library available options: "combined", "common", "dev", "short", "tiny"
  • Default: ":remote-addr :method :url :status :response-time ms - req-body :body - api-key :apiKey - authorization :authorization"

REQUEST_BODY_KEYS_TO_HIDE:

  • Description: We don't want to look at our users' private data so by default we hide some common properties. If you want to cheng that please provide your string with words you want to hide separated with coma ,
  • Default: "password,token,accessToken,accessKey,authorization"

IS_USER_ACTIVATION_NEEDED:

  • Description: The variable specifies if activation link is sent to user after registration
  • Default: false

TIME_TO_ACTIVE_ACCOUNT_IN_DAYS:

  • Description: The variable specifies how long activation link is valid (in days)
  • Default: 3

SUPER_ADMIN_USERNAME:

  • Description: The variable specifies super admin login (the user which has all rights)
  • Default:"superadmin"

SUPER_ADMIN_PASSWORD:

  • Description: The variable specifies super admin password
  • Default:"superadmin"

MAILER_TYPE:

  • Description: The variable specifies mailer configuration (available options: disabled, standalone, external)
  • Default: disabled

MAILER_URL:

  • Description: The variable specifies mailer service URL
  • Default: http://localhost/

MAILER_NEW_PASSWORD_SPA_URL

  • Description: The variable specifies client app URL which will be send in reset password email
  • Default: http://localhost:3000/new-password

MAILER_SMTP_POOL:

  • Description: The variable specifies standalone mailer pool option. Set to true to use pooled connections instead of creating a new connection for every email
  • Default: true

MAILER_SMTP_HOST:

  • Description: The variable specifies the hostname or IP address to connect to
  • Default: localhost

MAILER_SMTP_PORT:

  • Description: The variable specifies the port to connect to (defaults to 587 if is secure is false or 465 if true)
  • Default: 465

MAILER_SMTP_SECURE:

  • Description: If true the connection will use TLS when connecting to server. If false then TLS is used if server supports the STARTTLS extension. In most cases set this value to true if you are connecting to port 465. For port 587 or 25 keep it false
  • Default: true

MAILER_SMTP_USER:

  • Description: The variable specifies the SMTP username
  • Default: ""

MAILER_SMTP_PASS:

  • Description: The variable specifies the SMTP password
  • Default: ""

MAILER_TEMPLATE_CREATE_USER:

  • Description: Path to email template for create new user confirmation
  • Default: "/app/services/security/src/utils/mailer/templates/create-user/default/"

MAILER_TEMPLATE_RESET_PASSWORD:

  • Description: Path to email template for reset password confirmation
  • Default: "/app/services/security/src/utils/mailer/templates/reset-password/default/"

MAILER_TEMPLATE_RESET_PASSWORD_TOKEN:

  • Description: Path to email template for reset password token confirmation
  • Default: "/app/services/security/src/utils/mailer/templates/reset-password-token/default/"

MAILER_SENDER_NAME:

  • Description: Sender name
  • Default: "Joe Doe"

MAILER_SENDER_EMAIL:

  • Description: Sender name
  • Default: "joe.doe@example.com"

SUPER_ADMIN_ROLE:

  • Description: The variable specifies super admin role
  • Default: "ROLE_SUPERADMIN"

SUPER_ADMIN_ATTRIBUTES:

  • Description: The variable specifies an array of super admin attributes
  • Default:["ROLE_SUPERADMIN"]

ADMIN_PANEL_ADD_USER:

  • Description: The variable specifies what attribute is required to add a new users
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_EDIT_USER:

  • Description: The variable specifies what attribute is required to edit a users
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_DEACTIVATE_USER:

  • Description: The variable specifies what attribute is required to deactivate a users
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_DELETE_USER:

  • Description: The variable specifies what attribute is required to delete a users
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_RESET_PASSWORD:

  • Description: The variable specifies what attribute is required to reset the password for a users
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_ADD_POLICIES:

  • Description: The variable specifies what attribute is required to add new policies
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_POLICIES:

  • Description: The variable specifies what attribute is required to read policies
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_REMOVE_POLICIES:

  • Description: The variable specifies what attribute is required to remove policies
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_ADD_ATTRIBUTE_TO_USER:

  • Description: The variable specifies what attribute is required to add police attributes for a user
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_REMOVE_ATTRIBUTE_TO_USER:

  • Description: The variable specifies what attribute is required to remove police attributes from a user
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_USER_ID:

  • Description: The variable specifies what attribute is required to an endpoint which allow to get user's id by username
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_USER

  • Description: The variable specifies what attribute is required to an endpoint which allow to get user
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_USERS

  • Description: The variable specifies what attribute is required to an endpoint which allow to get all users
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_USERS_BY_RESOURCE_NAME

  • Description: The variable specifies what attribute is required to an endpoint which allow to get all users by policy resource
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_ATTRIBUTES

  • Description: The variable specifies what attribute is required to an endpoint which allow to get policy attributes
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_CREATE_ACCESS_KEY:

  • Description: The variable specifies what attribute is required to create api key
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_REMOVE_ACCESS_KEY:

  • Description: The variable specifies what attribute is required to remove api key
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_ACCESS_KEYS:

  • Description: The variable specifies what attribute is required to read api keys
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_USER:

  • Description: The variable specifies what attribute is required to get user by user id
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_USERS:

  • Description: The variable specifies what attribute is required to read users
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_USERS_BY_RESOURCE_NAME:

  • Description: The variable specifies what attribute is required to read users by resource name
  • Default: "ADMIN_PANEL"

ADMIN_PANEL_GET_ATTRIBUTES:

  • Description: The variable specifies what attribute is required to read attributes
  • Default: "ADMIN_PANEL"

INITIAL_API_KEYS

  • Description: If you need API keys to communicate with the security service on the module start you need to provide these keys in string separated by a comma "," e.g. "3add29a2-f629-c17a-0464-fb4415b24e13,875c2b9d-0cb5-5d98-39d3-bb2cc3dc0ca8"
  • Default: []

AUTHENTICATION_STRATEGY:

  • Description: The variable specifies which authentication strategy will be enabled.
    • Accepted values: custom, keycloak
  • Default: custom

KEYCLOAK_CLIENT_CONFIG_JSON_PATH:

  • Description: The variable specifies the path to keycloak realm import file.
  • Default: "/app/services/security/init-data-volume/keycloak.json"

KEYCLOAK_REALM_NAME

  • Description: Realm name. A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control.
  • Default: "rad-security-auth"

KEYCLOAK_ADMIN_USERNAME

  • Description: Keycloak user name with admin roles
  • Default: "admin"

KEYCLOAK_ADMIN_PASSWORD

  • Description: Password for the KEYCLOAK_ADMIN_USERNAME
  • Default: "password"

KEYCLOAK_CLIENT_SECRET

  • Description: For confidential clients, a client secret
  • Default: "7680c12c-4430-40e0-8968-b73c99b4dcf0"

KEYCLOAK_CLIENT_ID

  • Description: Keycloak OpenID client name
  • Default: "rad-security"

KEYCLOAK_SECURITY_CLIENT_ID

  • Description: Keycloak OpenID client ID
  • Default: "6c3465b1-2674-4704-a940-c41194dbd95"

EVENT_DISPATCHER_CALLBACK_URLS

  • Description: Callback URLs of notifications that are sent after changes in policies and users, comma separated.
  • Default: ""
← Keycloak integrationAttribute-based access control →