Orbital

Managing data sources

Authenticating Orbital to other services

Configuring authentication credentials Orbital provides 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.

taxi.conf
name: com.myproject/demoversion: 0.1.0sourceRoot: 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

Available since 0.36.6

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:

auth.conf
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

auth.conf
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

auth.conf
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

Available since 0.36.6

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:

auth.conf
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

auth.conf
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

auth.conf
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

auth.conf
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)

auth.conf
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" } ]