Advanced Server Configuration

# Authentication

Normally MIRACL Trust SSO server acts as an identity provider (IdP) and authenticates against MIRACL Trust Portal trought OIDC (which is the default authentication configuration):

authentication:
  oidc:
    miracl:
      client_id: <YOUR_CLIENT_ID>
      client_secret: <YOUR_CLIENT_SECRET>

The authentication to the IdP server could be setup to proceed to another IdP which supports either SAML or OIDC protocol. The authentication configuration should reflect this following some rules as seen below.

The redirect URL of the SSO is dynamically created depending on the authentication configuration. It is structured as https://<YOUR_SSO_IP>/auth/<PROTOCOL>/<NAME> (i.e. https://<YOUR_SSO_IP>/auth/oidc/miracl for the example above).

  • PROTOCOL should be either oidc or saml depending on the authentication protocol you’re authenticating against to the IdP server.
  • NAME should be the name you have setup the authentication server with.

# OIDC IdP Authentication

If you want to authenticate against another OIDC servers as an IdP, you need to configure it as follows:

authentication:
  oidc:
    <NAME>:
      client_id: <YOUR_CLIENT_ID>
      client_secret: <YOUR_CLIENT_SECRET>
      issuer: ""
      scope: "openid email profile"
      allow_unknown_state: false
  • NAME is the name of the IdP server and participates in the redirect url.
  • client_id and client_secret should be the credentials to the OIDC IdP app.
  • issuer should be the issuer identifier URI of the IdP. If not set, it has a default value pointing to MIRACL MFA Platform.
  • scope contains the claim values you’d like to have returned for the authenticated user of IdP. By default it is “openid email”.
  • allow_unknown_state disables the matching of the OIDC state during the OIDC authentication. Its default value is false.

# SAML IdP Authentication

There are cases when you’d want to use MIRACL Trust SSO server as a proxy between a service provider (SP) and another IdP supporting SAML for authentication. Then you need to configure our server to use SAML authentication to the IdP, i.e. to act as an SP to the IdP. This is done by:

authentication:
  saml:
    <NAME>:
      entity_id: <YOUR_ENTITY_ID>
      idp_metadata: |-
        <YOUR_IDP_METADATA>
      allow_idp_initiated: true
      certificate: |-
        -----BEGIN CERTIFICATE-----
        <YOUR_CERTIFICATE>
        -----END CERTIFICATE-----
      key: |-
        -----BEGIN PRIVATE KEY-----
        <YOUR_PRIVATE_KEY>
        -----END PRIVATE KEY-----
  • NAME is the name of the IdP server and participates in the redirect url.
  • entity_id should be the identifier of an entity that provides SAML-based services.
  • Either idp_metadata_url or idp_metadata should be set with the IDP metadata.
  • allow_idp_initiated specifies should an IDP initiated flow is allowed to this SP connection, by default is true.
  • certificate and key are the RSA public base64 encoded x509 certiricate and private key of our SSO used for signing SAML requests to the IdP.

# Rules

There could be configured different authentication IdPs which is why there are a couple of rules you could use to specify which IdPs to be used for authentication of a specific request from the SP. The rules are structured in a yaml array and are evaluated in the order they are listed in the sso authentication configuration. All rule types could be combined in a rule to achieve the desired differentiation of the SAML requests to the MIRACL Trust SSO in order to choose which IdP to use for authenticating it.

If only method rule is set, it specifies the default method used for authentication by the type and the name of the authentication, structured as type.name. For example, if there is set an OIDC authentication to miracl (the default one) it could be ruled to be the default one by:

authentication:
  rules:
    - method: oidc.miracl

Note that if only one method is listed, it is the default one and it’s not necessary to have authentication rules at all.

parameter rule sets an url parameter which is expected to specify the authentication method of a SAML Request from the SP. For example, if the SSO receives a SAML Request with an url https://<YOUR_SSO_IP>//sso?idp=miracl, it is authenticated with the authentication method specified for param with key ‘idp’ and value ‘miracl’. In order to authenticate this request specificly by the IdP configured under the name oidc.miracl, the following configuration is required:

authentication:
 rules:
  - parameter:
      key: idp
      value: miracl
    method: oidc.miracl
 oidc:
   miracl:
     client_id: <YOUR_CLIENT_ID>
     client_secret: <YOUR_CLIENT_SECRET>

header rule sets the name and value of a request header which is expected to specify the authentication method of the SAML Request. For example, if the SSO receives a SAML Request with header ‘X-Forwarded-For’ and value ‘miracl.trust’ and we want it to be authenticated with the OIDC authentication method under the name of miracl, here is how it needs to be configured:

authentication:
 rules:
  - header:
      key: X-Forwarded-For
      value: miracl.trust
    method: oidc.miracl
 oidc:
   miracl:
     client_id: <YOUR_CLIENT_ID>
     client_secret: <YOUR_CLIENT_SECRET>

You could configure rules to select the authentication method per user privileges by specifying a regular expression for the user_id which is authenticated and/or the name of a defined ldap profile to evaluate. More about configuring ldap and ldap profiles could be read here. In this case the SSO needs to know what is the user_id before evaluating the rule, so additional page to enter it is displayed to the user.

The next example demonstrates how rules could be combined. The user is checked first if he/she could be authorized by the ldap_admins profile. If so, the request is authenticated by saml.myadminidp. If not, the second rule checks if the user id has a domain _miracl.com. If so, the user is authenticated by oidc.miracl. If not, the third rule is evaluated and the user id is checked for domain _gmail.com and evaluated by the ldap_users profile. If both conditions are satisfied, saml.miracl IdP is used. If none of the above are met, oidc.mydefaultidp is applied for any other requests.

authentication:
  rules:
  - ldap: ldap_admins
    method: saml.myadminidp
  - user_id: "^[^@]+@miracl.com$"
    method: oidc.miracl
  - user_id: "^[^@]+@gmail.com$"
    ldap: ldap_users
    method: saml.miracl
  - method: oidc.mydefaultidp
  oidc:
    miracl:
      client_id: <YOUR_MIRACL_CLIENT_ID>
      client_secret: <YOUR_MIRACL_CLIENT_SECRET>
    mydefaultidp:
      client_id: <YOUR_MYDEFAULTIDP_CLIENT_ID>
      client_secret: <YOUR_MYDEFAULTIDP_CLIENT_SECRET>
      issuer: <YOUR_MYDEFAULTIDP_ISSUER_URL>
  saml:
    myidp:
      entity_id: <YOUR_MYIDP_IDP_ENTIDY_ID>
      idp_metadata_url: <YOUR_MYIDP_IDP_METADATA_URL>
      certificate: <YOUR_MYIDP_IDP_CERTIFICATE>
      key: <YOUR_MYIDP_IDP_KEY>
    myadminidp:
      entity_id: <YOUR_MYADMINIDP_IDP_ENTIDY_ID>
      idp_metadata_url: <YOUR_MYADMINIDP_IDP_METADATA_URL>
      certificate: <YOUR_MYADMINIDP_IDP_CERTIFICATE>
      key: <YOUR_MYADMINIDP_IDP_KEY>
ldap:
  server:
    google:
      method: tls
      serverName: ldap.google.com
      address: ldap.google.com:636
      certificate: |-
        -----BEGIN CERTIFICATE-----
        <YOUR_LDAP_CERTIFICATE>
        -----END CERTIFICATE-----
      certificateKey: |-
        -----BEGIN PRIVATE KEY-----
        <YOUR_LDAP_KEY>
        -----END PRIVATE KEY-----
  query:
    ldap_admins:
      server: google
      search:
      - dn: ou=Users,dc=miracl,dc=com
        filter: "(&(mail={{.UserID}})(memberOf=cn=admins,ou=Groups,dc=miracl,dc=com))"
    ldap_users:
      server: google
      search:
      - dn: ou=Users,dc=miracl,dc=com
        filter: "(&(mail={{.UserID}})(memberOf=cn=users,ou=Groups,dc=miracl,dc=com))"

# Change Log Level

/etc/miracl-sso/integrations/log.yaml

log:
  level: INFO

Can be set to “ERROR”, “WARN”, “INFO” or “DEBUG”.

Note that it should not be set to DEBUG in a production environment.

# Stats for System Performance

/etc/miracl-sso/integrations/stats.yaml

The program uses StatsD to collect usage metrics which can then be used with a StatsD-compatible client such as Graphite to visually render key system performance information such as session starts, logins, communicating with the authentication server, spikes in 404 statuses etc.

An example config would be:

stats:
  prefix: miracl-sso
  network: udp
  address: :8125

Note that prefix defines the prefix that is given to each bucket of stats. Address can be in the format of ‘url:port’ or just ‘port’.

The above example would be suitable for a Graphite installation, as Graphite https://github.com/etsy/statsd/blob/master/docs/graphite.md listens on port 8125 by default. A useful Docker image for Graphite can be found at https://github.com/hopsoft/docker-graphite-statsd.

# Session Settings

By default the MIRACL Trust SSO server uses internal memory to store its collected logged in sessions. Below is the default config.

/etc/miracl-sso/integrations/memory.yaml

session:
  store:
    memory:
      cleanup_interval: 60

You could specify Redis as an external storage to improve security or share it between multiple SSO server instances. Redis can be used locally or installed on a separate machine. In a production environment, AWS ElastiCache may be used. You could just enable it by including:

/etc/miracl-sso/integrations/redis.yaml

session:
  store:
    redis:
      network: tcp
      address: :6379
      password: ""

The session has a max_age property which specifies the live time of the session in seconds. By default it’s set to be an hour. If you specify its value to 0, the session is deleted after you authenticate to a service, which means that every time a SP would need an authentication, the sso asks you for your PIN so it could authenticate you again. This is helpful if you use different identities for one SP.

session:
  max_age: 0

The sso session life could be controlled by another property named terminate_on_sp_login. If true, it deletes the session at the moment the saml response is sent to the service provider. It is useful in cases when you need a session, but the user should be required to authenticate again in a subsequent request. Its default value is false.

session:
  terminate_on_sp_login: true