Loading...

Unattended Setup

Once you have completed the manual or automated installation the next step is to install and configure AuthStack itself.

Unattended Setup is executed from the command line. It bypasses the web based AuthStack installer, and is intended for advanced users.

Configuration Values

To provide configuration values, edit the install.json file in the installation root. It contains several sections that need to be filled in. The file itself is excluded from GIT via .gitignore so it can be freely edited.

install.json

Table of contents:

  1. license
  2. mysql
  3. admin
  4. idp
  5. keys

install.json contains self-explanatory keys. File contents is as follows:

{
  "license": {
    "code": ""
  },

  "mysql": {
    "host": "",
    "port": "3306",
    "username": "",
    "password": "",
    "database": ""
  },

  "admin": {
    "username": "",
    "password": ""
  },

  "idp": {
    "EntityId": "",
    "organization": {
      "name": "",
      "displayName": "",
      "url": ""
    },
    "wantsSignedMessages": true,
    "signatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
  },

  "keys": {
    "private": {
      "type": "file",
      "value": "",
      "passphrase": ""
    },
    "x509": {
      "type": "file",
      "value": ""
    }
  }
}

license

This section should contain a valid license. License can be obtained from your customer area at Buckhill's website. License must be provided in a single line, enclosed by quotes.

Example:

{
  "license": {
    "code": "License code here"
  }
}

mysql

mysql section contains MySQL connection configuration. Note: connection character set is set to UTF8 by default. Simply specify the database host, port, username, password and database name which will hold AuthStack tables.

Example:

"mysql": {
  "host": "127.0.0.1",
  "port": "3306",
  "username": "mysql_user",
  "password": "strong_password",
  "database": "database_name"
}

admin

This section contains username and password for the initial system admin user. This user can be altered via command line tools at any time. Username and password specified this way are not strength-checked.

Example:

"admin": {
  "username": "you@your_domain.com",
  "password": "strong_password"
}

idp

This section configures Identity Provider by providing basic information such as EntityId, company details and how to handle requests.

idp.EntityId

EntityId is a unique identifier for a SAML entity. Usually, it's sufficient to have this value equal to the domain where AuthStack is running at. If AuthStack is behind multiple domains and you want EntityId to be dynamic, you can combine it with a template variable {{ url }}.

For example, let's assume there are two domains that use the same backend:

  1. https://01.example.com
  2. https://02.example.com

If you use {{ url }} for EntityId value, AuthStack will dynamically change its EntityId based on domain that was used to access it. You can combine the template variable with regular strings, for example: {{ url }}/saml2.0/IdP/Entity which can produce a value like https:://01.example.com/saml2.0/IdP/Entity.

Example:

{
  "idp": {
    "EntityId": "https://idp.buckhill.co.uk"
  }
}

idp.organization

This section contains values related to your organization. It's exposed in the public metadata document.

Example:

{
  "idp": {
    "organization": {
      "name": "Buckhill Limited",
      "displayName": "Buckhill"
      "url": "https://www.buckhill.co.uk"
    }
  }
}

idp.wantsSignedMessages

watnsSignedMessages should be boolean (true or false). It indicates whether every Service Provider should sign their requests using their private keys. AuthStack verifies signatures using SP public key obtained through metadata exchange. This option should be always set to true so only recognized Service Providers are granted access if well formed SAML Authentication or Logout requests are provided.

Example:

{
   "idp": {
      "wantsSignedMessages": true
  }
}

idp.signatureAlgorithm

Signature digest algorithm for signing public Identity Provider metadata. Can be one of:

  1. http://www.w3.org/2000/09/xmldsig#dsa-sha1
  2. http://www.w3.org/2000/09/xmldsig#rsa-sha1
  3. http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 (preferred, default in web installer)
  4. http://www.w3.org/2001/04/xmldsig-more#rsa-sha384
  5. http://www.w3.org/2001/04/xmldsig-more#rsa-sha512
  6. http://www.w3.org/2000/09/xmldsig#hmac-sha1

Example:

{
   "idp": {
      "signatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
  }
}

keys

keys section contains public and private key which AuthStack uses to sign SAML responses, as well as encrypt SAML messages for Service Providers that require encrypted responses. Public/private keypair is mandatory.

Notes:

  1. Keypair provided this way does not have to be signed by Certificate Authority
  2. Public key must be in x.509 format, which carries information about your organization.
  3. When you generate a keypair through CLI, please provide all the values when asked about them

To generate a keypair, use openssl command from CLI

Example:

$ openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out example.org.crt -keyout example.org.pem

The above will generate a private key and x.509 certificate that's valid for 10 years.

Note; the keypair provided this way does not have to be signed by a Certificate Authority. Important part is that AuthStack has a private/public keypair.

Configuring this section in install.json:

{
  "keys": {
    "private": {
      "type": "file",
      "value": "/var/www/authstack.co.uk/example.org.pem",
      "passphrase": ""
    },
    "x509": {
      "type": "file",
      "value": "/var/www/authstack.co.uk/example.org.crt"
    }
  }
}

Running Unattended Setup

Once the install.json has been configured, run the following command to initiate unattended setup. Please note, this will fail if AuthStack is already installed.

authstack-ctl authstack:install

Previous Article

AuthStack Setup

Next Article

Your First Login

We're happy to talk

Our offices are open 8.30am - 7pm GMT, Monday to Friday - but you can always contact us via email. When we receive your email during opening hours, we aim to respond within 30 minutes or less. Should your email reach us out of hours, we will contact you when the office re-opens.

You can contact us using live chat