# Authenticating Orbital to other services

> Configuring authentication credentials Orbital provides to other services

Source: https://orbitalhq.com/docs/describing-data-sources/authentication-to-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](https://github.com/lightbend/config#examples-of-hocon) file which lives inside a taxi project within your [workspace](/docs/workspace/overview).

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.

**Note**
auth.conf files support [environment-specific variations](/docs/deploying/configuring-orbital#environment-specific-configuration).


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

Here's a sample config:

```hocon
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}
      }
   ]
}
```


**Note: See also...**
Also check out [Managing Secrets](/docs/deploying/managing-secrets) to see how to securely manage sensitive information in your auth tokens

## Authentication token types
Several authentication scheme types are supported. If you don't see the one you need here, please [get in touch](https://join.slack.com/t/orbitalapi/shared_invite/zt-697laanr-DHGXXak5slqsY9DqwrkzHg).

### 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:

```hocon 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.

**Note**
The single-object syntax (without array brackets) continues to work for backward compatibility when only one authentication scheme is needed.

### Basic authentication

```hocon 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
```hocon 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:

```hocon 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: `
- `Authorization: Bearer `

### Query param
```hocon 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
```hocon 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
```hocon 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)

```hocon 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.

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


**Note: See also...**
Also check out [Managing Secrets](/docs/deploying/managing-secrets) to see how to securely manage sensitive information in your auth tokens

## 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}`:
```json
{
   "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" } ]
```