SAML Authentication

GigaFox supports Single sign-on (SSO) through Security Assertion Markup Language (SAML) authentication, a standard protocol for web browser SSO using secure tokens. This gives administrators and security teams more options for user authentication.

This guide will walk through a SSO setup using Keycloak, an open source identity and access management solution. Please note that this guide is a general example and setup details may differ depending on which SSO service is used and the specific setup details for a system.

Prerequisites

Install the following before starting the authentication process:

Download and note the path of the following two prerequisites:

NOTE: It is recommended to setup Keycloak on a separate server than the GigaFox server.

Keycloak SAML setup

  1. In terminal, navigate to Keycloak's /bin directory and run: 
    
    ./standalone.sh -b 0.0.0.0
    Running /standalone.sh with -b 0.0.0.0 allows accessing Keycloak via its hostname or IP address, rather than only accessing via localhost.
  2. On the browser, go to localhost:8080/auth to open Keycloak's administration console.
    3. SAML Keycloak Admin Console
  3. In the administration console: create a user and log into Keycloak as that user.
  4. Create a Keycloak client:
    1. On the Configure menu (left column), click Clients.
    2. On the far top right, click Create.
    3. On the Add Client page, fill in the following fields:
        keycloak Add Client dialog
      • Client ID: GigaFox client name, e.g., http://example.gigafox.com

        NOTE: The Client ID must match the EntityId in the [SAML] section of the plugins.ini file.

      • Client Protocol: saml
      • Client SAML endpoint: (leave blank)
    4. Click Save.
    5. Save will display more fields for the Add Client page. Adjust the following fields:
      • Include AuthnStatement: On
      • Sign Assertion: On
      • Force POST Binding: On
      • Name ID Format: username

        • NOTE: The Name ID Format may differ depending on the GigaFox/devicConnect setup. In some instances, selecting email may be the best option.
        If selecting the username option, in the UserSuffix section of plugins.ini, username must match the domain name or suffix in that username + UserSuffix match the userId.
        e.g., If userId is admin@test.com, then the Keycloak username must be set to admin and the UserSuffix in plugins.ini must be set to @test.com.

      • Valid Redirect URI: GigaFox URL with a wildcard (*) to allow Keycloak to redirect to any URL on the domain, e.g., http://example.gigafox.com/*
      • Base URL: GigaFox URL, e.g., http://example.gigafox.com
  5. Back in the Keycloak admin console, export the RSA certificate needed to complete the SAML assertion signing:
    1. Go to Realm Setting > Keys.
    2. Under Public keys click the Certificate button and copy the content.
    3. In terminal, navigate to the Open SSL directory and run the following commands to decrypt the RSA certificate:
      4. 
   pbpaste | base64 -D > /tmp/key.cer
    
      
   openssl x509 -inform der -in /tmp/key.cer -text
      The decrypted certificate will look as follows: 
      
     Certificate:
       Data:
         Version: 1 (0x0)
         Serial Number: 1356117965294 (0x278ba8871ab)
       Signature Algorithm: sha256WithRSAEncryption
         Issuer: CN=master
         Validity
           Not Before: Feb  4 21:59:25 2019 GMT
           Not After : Feb  4 22:01:05 2029 GMT
         Subject: CN=master
         Subject Public Key Info:
          Public Key Algorithm: rsaEncryption
            Public-Key: (2048 bit)
            Modulus:
              00:b6:1f:96:42:e1:b9:95:e4:47:e0:fe:24:ff:c3:
              b2:3e:23:f6:cf:52:1d:5f:33:45:73:8f:f8:e4:0d:
              1b:e3:fe:a8:42:ee:fe:86:2e:12:e2:21:ed:06:d9:
              63:82:3c:b6:cb:1a:c6:bc:e4:de:d2:70:c1:02:44:
              04:fb:e9:ea:c4:49:08:c3:c6:39:5d:4c:c2:ad:6f:
              18:d5:23:5c:6e:c1:a3:3d:a7:a5:40:e1:d2:43:45:
              12:31:74:fe:4e:1d:8f:30:3e:3d:d3:23:97:4c:b8:
              55:b7:76:b2:07:55:27:61:b5:24:c2:ca:8c:f7:78:
              98:85:f3:72:86:05:a1:91:d8:36:66:10:5e:e8:88:
              1b:66:40:00:d2:17:a2:29:04:aa:ad:cc:15:82:fd:
              ff:64:f8:63:6c:d4:2c:16:3a:c1:10:cb:89:fd:0e:
              2b:34:65:2c:63:00:48:a4:de:35:6c:ec:15:f3:94:
              d3:57:d1:6f:ef:f6:05:ba:0d:bf:82:bc:1c:2f:98:
              6b:2e:24:de:d2:8c:a8:23:f9:c0:ac:56:7e:89:44:
              92:2e:49:b3:b5:4d:bc:00:52:bd:f1:3e:47:99:6c:
              31:e4:55:77:6f:b4:46:07:6c:f5:f2:c4:6e:c8:7c:
              28:bc:76:8e:cf:bc:85:0f:6d:d3:8c:8d:31:a3:30:
              2e:cd
            Exponent: 63557 (0x10001)
       Signature Algorithm: sha256WithRSAEncryption
         96:ab:52:25:74:21:52:f8:58:bd:ac:76:b2:f2:2e:03:89:6d:
         3f:c6:ed:42:c2:ce:61:2d:46:0e:5b:d2:ae:74:1f:2d:d5:6f:
         f5:5f:58:b6:c3:da:08:67:50:e4:14:11:af:fe:ee:60:fa:93:
         21:4c:0d:a6:81:3b:8b:33:2d:e0:44:b5:3e:c7:44:ef:2c:0b:
         64:19:ef:aa:dd:96:34:e4:c9:71:0e:f9:e2:f1:fd:58:a2:b5:
         42:2a:9e:53:68:7f:05:c2:e4:5f:f0:28:fb:5e:cb:eb:15:00:
         4d:f5:b3:73:e4:cd:ae:4c:8d:c7:bd:a5:73:5b:71:9b:f5:b8:
         d4:8f:ea:f8:c3:71:3b:7c:af:b6:1a:e1:e2:8d:6e:42:10:de:
         5b:13:8g:9b:84:68:1c:be:11:de:e7:50:3b:10:c4:88:22:b5:
         c4:5d:a5:07:d0:d5:63:39:d6:04:40:d0:c8:aa:44:e5:30:5e:
         11:48:c3:8b:19:22:de:5e:3a:95:15:58:2e:fe:fb:09:cd:28:
         9b:85:93:76:81:21:80:ff:ae:20:8c:24:a3:4a:95:12:84:7b:
         de:26:1e:dc:7d:9d:91:6d:d3:01:e2:d2:1f:39:3f:7c:4d:c8:
         53:85:67:f1:92:1b:e8:42:ac:b8:7c:f3:33:f3:33:dd:e1:19:
        6c:c3:9b:88
     -----BEGIN CERTIFICATE-----
     vIICmzCCrYMCBgTouodwqzANFgkqhytiGw0tecghjtFDEHBAQsFADAQDergtJYAZ
     ZXIwHhcNMTkwMjA0MjtreaoGRE1OTI1WhcNMjkwMjA0MDjIEubaPKndueohjIwMT
     YXN0ZXIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC2H5ZC4bmV52fg
     /iT/w7I+I/bPORNDKP+KRJSNLFOEUANondanuoiFFiUh1fM0lfjehzj/jkDRvm/q
     RAFTOhnpeirhfT76erEgjpemSQjTxjltS9KvcbgeipfjODHN;bxfUIzxrwqtrok9
     daIGUSNjufhnrtipfCfByofetGHYRvFnVFeFEWUIMGDbghtegfsrujJmF43KfGBa
     1isYOsIQ+4j9Diw0YypnOFoenewnjEopeCNAEiozTRTtE7RTVGzlNhrhjtyCJZ0W
     +MCtVVKDODn2QRfeyuiDTILNVAEYgrtjgjZIvSbS1Tfraerynjhrrb0AweUb3yP0
     nTKkQC7NAgMBAAEwDQYJKoZIhvcNAQELBQADgufheuDNPEMPBdeuSoJDLgEBAJar
     xTgxmdopjfeipEIRPemapoljdNCQIEpmfIfjFIELJFCmQY76vclkferhfTnyNyd7
     za5Mfdf5tpghuHJImlJOPLMMnfNbYZv1uNSO6mldeQIEPMdcnk;vnDcUt7rjieee
     tcNcpQfQuUUDJOEqinfdhsaaopnfeti1W051gRANKRxsqifnegjjlsoosvsMevRO
     JKVKlBSJe99GHr553noep4P3xMyFfrtERSde/GGRRGuThCrfbth6g83Tghn2jui=
     -----END CERTIFICATE-----
    4. Save the decrypted output in /usr/local/deviceconnect with file name keycloak.cer.
  6. If one does not already exist, create a plugins.ini file in /usr/local/deviceConnect.
  7. Add the following to plugins.ini example:
    8. 
   [SAML]
   #Service Provider Address
   EntityId=http://example.gigafox.com

   Providers=SAML_Keycloak

   UserSuffix=

   [SAML_Keycloak]
   # ID Provider Address
   EntityId=http://localhost:8080/auth/realms/master

   Binding=HttpPost

   SingleSignOnServiceUrl=http://localhost:8080/auth/realms/master/protocol/saml

   SigningKeys=KeycloakSigningKey

   [KeycloakSigningKey]
   Path=keycloak.cer
  8. On the browser, go to the GigaFox [SAML] entityId URL which will redirect to the Keycloak login page to log into GigaFox.

SAML plugins.ini Key Description

[SAML]

  • EntityId: The Entity ID of the GigaFox system. This will be used as the SAML issuer value when sending SAML requests to an identity provider. The EntityId must match the Client ID in Keycloak's Add Client page.
  • Providers: A comma separated list of identity providers. The first specified provider is used as the default. Each identity provider should be the name of a separate section in this .ini file which will contain the configuration for that provider.
  • UserSuffix: A suffix to append to the username. Because a SAML identity provider may send the user's name ID in a format that's not an email address compatible with the GigaFox user system, an email domain may be appended to the username to generate the username.

[SAML_Keycloak]

  • EntityId:The Entity ID of the identity provider. This should match the issuer name used by the IDP when sending SAML responses. The issuer value can be found at:
    localhost:8080/auth/realms/master/.well-known/openid-configuration. SAML Keycloak issuer value
  • Binding: The binding method to use. May be HttpPost, HttpRedirect or Artifact. Currently, the HttpPost method is recommended and tested.
  • SingleSignOnServiceUrl: The redirect URL to which SAML authentication requests will be sent. This should be the HTTP endpoint documented by the IDP for SAML binding. To find the SingleSignOnServiceUrl:
    1. On the Keycloak admin console, click Identity Providers.
    2. On the Add provider dropdown menu, select SAML v2.0.
    3. On the Add identity provider page, the Redirect URI value is the SingleSignOnServiceUrl.
  • SigningKeys: A list of valid signing keys used by the identity provider to sign assertions. More than one key can be added by creating a separation tag for each key: 
    
   [KeycloakSigningKey1]
   KeycloakSigningKey1

   [KeycloakSigningKey2]
   PKeycloakSigningKey2

   [KeycloakSigningKey3]
   KeycloakSigningKey3

[KeycloakSigningKey]

  • Path: The path (may be absolute or relative) to the GigaFox data path, /usr/local/deviceconnect where the RSA certificate is stored. Currently must be a DER or PEM encoded X.509 certificate.