Authenticating Orbital to other services

Orbital will pass authentication headers to upstream services when sending requests.

Configuration is managed through an auth.conf file, present in a Taxi project in your workspace.

​

auth.conf file

Authentication tokens are defined in a file named auth.conf - a HOCON file which lives inside a taxi project within your workspace.

The location of your auth.conf file is configured inside the taxi.conf file in your project, using an additionalSources entry with a key of @orbital/config

By convention, the auth.conf lives at orbital/config/auth.conf, but this is configurable.

name: com.myproject/demo
version: 0.1.0
sourceRoot: src/
 additionalSources: {
     "@orbital/config" : "orbital/config/*.conf"   
 }

Here’s a sample config:

authenticationTokens {

   // The fully qualified name of a service, as defined in a taxi schema.
  // Should be surrounded in quotes.
   "com.acme.MyService" {
      type = OAuth2
      // ... see below for examples
   }

   // You can also use wildcards in the name of the service, to use the same credentials for
   // all matching services
   "com.hamilton.*" {
      type = HttpHeader
      value = ${API_TOKEN}
   }

   // Since version 0.36.6: Use an array to configure multiple authentication schemes
   // that will all be applied to the same request
   "com.example.MultiAuthService": [
      {
         type: HttpHeader
         value: ${API_KEY}
         headerName: "X-API-Key"
      },
      {
         type: QueryParam
         parameterName: "token"
         value: ${QUERY_TOKEN}
      }
   ]
}

​

Authentication token types

Several authentication scheme types are supported. If you don’t see the one you need here, please get in touch.

​

Multiple authentication schemes per service

A service can be configured with multiple authentication schemes that will all be applied to the same request. This is useful when an API requires multiple forms of authentication (e.g., an API key header plus a query parameter).

To configure multiple authentication schemes, use an array syntax:

authenticationTokens {
  "com.foo.TestService": [
    {
      type: HttpHeader
      value: ${API_KEY}
      headerName: "X-API-Key"
    },
    {
      type: QueryParam
      parameterName: "apiKey"
      value: ${API_SECRET}
    },
    {
      type: Cookie
      cookieName: "session"
      value: ${SESSION_TOKEN}
    }
  ]
}

All authentication schemes in the array will be applied to requests sent to the service, in the order they are defined.

​

Basic authentication

authenticationTokens {

  // The fully qualified name of a service, as defined in a taxi schema. 
  // Should be surrounded in quotes.
  "com.foo.TestService" {
     type: Basic
     username: jimmy
     password: password
  }
}

​

HTTP Header

authenticationTokens {

  // The fully qualified name of a service, as defined in a taxi schema.
  // Should be surrounded in quotes.
  "com.foo.TestService" {
     type: HttpHeader
      // Mandatory
      value: letMeIn
      // Optional, defaults to Bearer
      prefix: "Token",
      // Optional, defaults to Authentication
      headerName: Auth
  }
}

​

Multiple HTTP Headers

Some APIs require multiple authentication headers (for example, both an organization key and an authorization key). You can configure multiple HTTP headers using the array syntax:

authenticationTokens {
  "com.acme.ApiService": [
    {
      type: HttpHeader
      value: ${ORG_API_KEY}
      headerName: "X-Organization-Key"
      prefix: ""  // No prefix for this header
    },
    {
      type: HttpHeader
      value: ${USER_AUTH_TOKEN}
      headerName: "Authorization"
      prefix: "Bearer"
    }
  ]
}

This configuration will add both headers to every request sent to com.acme.ApiService:

• X-Organization-Key: <ORG_API_KEY value>
• Authorization: Bearer <USER_AUTH_TOKEN value>

​

Query param

authenticationTokens {

  // The fully qualified name of a service, as defined in a taxi schema. 
  // Should be surrounded in quotes.
  "com.foo.TestService" {
     type: QueryParam
     parameterName: authKey
     value: letMeIn
  }
}

​

Cookie

authenticationTokens {

  // The fully qualified name of a service, as defined in a taxi schema. 
  // Should be surrounded in quotes.
  "com.foo.TestService" {
     type: Cookie
     cookieName: authKey
     value: letMeIn
  }
}

​

OAuth2

authenticationTokens {

  // The fully qualified name of a service, as defined in a taxi schema. 
  // Should be surrounded in quotes.
  "com.foo.TestService" {
     type: OAuth2
     accessTokenUrl: "https://auth.com/tokens"
     clientId: ABC
     clientSecret: DEF
     scopes: [ "profile" , "image" ]

     // One of AuthorizationCode, RefreshToken, ClientCredentials
     grantType: AuthorizationCode
     // One of Basic, Post, JWT
     method: Post

     // Optional. Only required if grantType is RefreshToken
     refreshToken: LMNOP
  }
}

​

Mutual Authentication (mtls)

authenticationTokens {

  // The fully qualified name of a service, as defined in a taxi schema. 
  // Should be surrounded in quotes.
  "com.foo.TestService" {
     type: MutualTls
     // Absolute Path of the KeyStore Path containing private keys for mutual Authentication
     keystorePath: /opt/service/orbital/test-service-mtls.jks
     // Password for the Key Store
     keystorePassword: orbital
     // Absolute Path of the Trust Store 
     truststorePath: /opt/service/orbital/test-trust-service-mtls.jks
     truststorePassword: orbital
  }
}

​

Using environment variables

Environment variables can be used in authentication config files.

authenticationTokens {
   "com.acme.MyService" {
      tokenType = AuthorizationBearerHeader
      value = ${foo} // The enviroment variable of 'foo' is read and substituted
   }
}

​

Other configuration approaches

Authentication configuration is always persisted to the file described above. However, there are ways of adding / removing to the configuration without requiring file access.

​

UI configuration

Authentication tokens can be added, modified and deleted through the UI, via the Authentication Manager.

Changes made here are persisted in the configured authentication file.

​

REST API

Authentication tokens can be added, modified and deleted through the REST API:

​

Create or update token

POST to /api/tokens/service/{serviceName}:

{
   "tokenType" : "AuthorizationBearerHeader",
   "value" : "yourAPIToken"
}

​

Deleting a token

Deletes a token

DELETE to /api/tokens/service/{serviceName}

​

Listing configured tokens

It is possible to list the configured tokens. However, the token values are not returned.

GET to /api/tokens

[ { "serviceName" : "com.foo.MyService", "tokenType" : "AuthorizationBearerHeader" } ]