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.*" {

   }
}

​

Authentication token types

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

​

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
  }
}

​

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" } ]