Authentication

Overview

In production environments, you must ensure that the Gateway Hub has Single Sign-On enabled and is using Kerberos or application keys for authentication.

For more information about configuring SSO, see LDAP configuration and SAML configuration.

Before interacting with Gateway Hub and accessing the stored data, you must acquire a security token. This token must be passed as an HTTP header along with any subsequent requests.

To request a security token, the endpoint GET /token must be used.

Authenticating with Kerberos

If Kerberos authentication is enabled you will need to request an access token when making requests to secure endpoints. This section provides several examples that use curl to make requests.

If you attempt to access a secure endpoint when security is enabled and you do not have an access token, then you will receive a 401 Unauthorised response.

For example if you run curl https://myhub:8081/v0/dataview the response will look similar to below:

{
  ...
  "title" : "Authorization failed"
  "body" : "The request needs a valid authorization token."
  ...
}

To get an access token, you must be logged onto the same Kerberos or Active Directory instance.

Additionally, your version of curl must support SPNEGO to be able to negotiate with Kerberos. To check this run curl -V and check the features list. You should see out put similar to the below:

 curl 7.64.1 (x86_64-apple-darwin20.0) libcurl/7.64.1 (SecureTransport) LibreSSL/2.8.3 zlib/1.2.11 nghttp2/1.41.0
 Release-Date: 2019-03-27
 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
 Features: AsynchDNS GSS-API HTTP2 HTTPS-proxy IPv6 Kerberos Largefile libz MultiSSL NTLM NTLM_WB SPNEGO SSL UnixSockets

To request an access token use the --negotiate and -u options:

curl --negotiate -u : "https://myhub:8081/authorize?response_type=token&client_id=test&state=test"

You will receive a response similar to following:

{
  "access_token" : "abcdef",
  "token_type" : "Bearer",
  "refresh_token" : "...,
  "expires" : 1616674745
}

Note that real access tokens are much longer than shown in this example.

To access a secure endpoint, add your access token to the authorization header of your request using the prefix Bearer as follows:

curl -H "Authorization: Bearer abcdef" https://myhub:8081/v0/dataview