Connection Routing

Overview

The connection routing component allows CDCM to connect to external systems using different authentication mechanisms. The supported authentication mechanisms are:

• OAuth 2.0

• OAuth 1.0a

• Fixed headers (e.g. Basic Auth)

• Forwarded headers

Description

CDCM often interacts with various external systems in an infrastructure. For example, a server-side guard JavaScript may call an external system while verifying that a concept may be saved, or CDCMs creates a UI for the selection of a work product reference by accessing the REST API of Storage Location. These calls to external systems may require different forms of authentication. It is not safe to assume that all external systems may be authenticated using the authenticated users bear token obtained from the customer’s identity provider (IDP hereafter); some system may not be directly integrated with the customers IDP or may not support REST calls using the IDP’s bearer token (e.g. IBM ELM). Also for some external systems it may be desirable to authenticate with a Service Principal (aka technical user).

The Connection routing feature configures the authentication calls to all external systems. For each outbound call to an external system CDCM consults the connection-routing.yml file to determine how this call should be authenticated.

Connection routing enables the user to connect to external systems like IBM ELM or CodeBeamer using various authentication mechanisms. Authentication depends on the external system. IBM ELM uses OAuth 1.0a, while Codebeamer supports OAuth 2.0. Connection routing allows communication to CodeBeamer using OAuth 2.0, while communicating with IBM ELM using OAuth 1.0a in parallel. Connection routing maintains multiple authentications to different external systems and chooses the right authentication mechanisms for external server calls based on their URIs.

By default all outgoing calls to external systems are authenticated using the logged in user’s bear token obtained from the IDP.

Usage

Connection routing let’s you define the type of authentication mechanism, based on a set of URIs with ant paths. An ant path supports optional wildcards. Connection routing will choose the authentication mechanism based on matching ant paths. The connection routing configuration file connection-routing.yml let’s you define a list of external server connections

connection-routing:
  -
    cdcm-connection-id: elm
    methods: ALL
    root-uris:
      - https://my.elm.host1/**
      - https://my.elm.host2/**    

and a list of connections, that define the authentication mechanism used, based on the common key (in this example elm):

  elm:
    connection-type: OAUTH10A
    consumer-key: my-consumer-key
    consumer-secret: my-consumer-secret
    root-services: https://example.com/oauth10a/rootservices
    service-principal-enabled: false

If an outgoing Http request matches https://my.elm.host1/** connection routing will use OAuth 1.0a for authentication with the external server.

Supported authentication mechanisms

The supported authentication mechanism are OAuth 2.0, OAuth1.0a, Fixed Headers and Bearer Token Forward. They operate in different ways and require different connections settings in the connection-routing.yml file.

OAuth 2.0 using a Authorization Code

This uses the standard OAuth 2.0 Flow using the Authorization Grant Authorization Code as described in RFC6749. The user authenticates using the configured IDP and connection routing will use the resulting token for outgoing connections to the external servers.

OAuth 2.0 using Client Credentials

This uses the the standard OAuth 2.0 Flow using the Authorization Grant Client Credentials as described in RFC6749. This is a “technical-user” authentication flow as connection routing only requires the client-id and the client-secret to authenticate with the external servers. No additional user authentication is required.

OAuth 1.0a Standard Flow

This uses the standard OAuth 1.0a Flow as described in the OAuth 1.0a specification. The user authenticates using the configured OAuth 1.0a server and connection routing will use the resulting token for outgoing connections to the external servers.

OAuth 1.0a Technical User Flow

OAuth 1.0a has no notion of a technical user authentication flow. To implement a technical user flow on top of OAuth 1.0a IBM ELM among other systems allow authentication using the consumer-secret and the consumer-key. This is comparable to OAuth 2.0 using the Authorization Grant Authorization Code.

Fixed Header

Fixed header authentication flow takes a set of headers and values and adds them to outgoing requests. This can be used to authenticate via Http Basic Auth by sending an Authorization header with Base64 encoded credentials. This is not limited to the Authorization header. Arbitrary headers and values and therefore even cookies can be set using this authentication flow.

Bearer Token Forward

This authentication flow uses the bearer token in the Authorization header in the incoming request for the request to the external server. This could e.g. be a JWT or an OAuth2.0 token.

Configuration

Connection routing is configured using the file connection-routing.yml. This file has to be put in the application’s working directory.

Kubernetes

The connection-routing.yml can be placed into a kubernetes secret, and mounted into the CDCM container. The name of this secret is "cdcm-connection-routing", the value of is the connection-routing.yml file.

To integrate the connection-routing.yml file into your CDCM deployment, you need to create a secret called “cdcm-connection-routing” in the namespace of your cdcm deployment.

There are two ways to do this:

1. Use kubectl

kubectl create secret generic cdcm-connection-routing --from-file=connection-routing.yml=./connection-routing.yml -n cdcm

2. f the secret has to be created manually or from a vault, use this template:

apiVersion: v1
data:
  connection-routing.yml: <base64 encoded content of the file connection-routing.yml>
kind: Secret
metadata:
  name: cdcm-connection-routing
  namespace: cdcm
type: Opaque

Save the file as connection-routing.yml and apply it with:

kubectl apply -f connection-routing.yml -n <namespace>

Example connection-routing.yml

connection-routing:
  -
    cdcm-connection-id: forward-bearer
    methods: ALL
    root-uris:
      - https://host1/**
      - https://host2/data/**
  -
    cdcm-connection-id: oauth20
    methods: GET,POST
    root-uris:
      - https://host3:4552/v1.0/**

  -
    cdcm-connection-id: oauth10a
    methods: ALL
    root-uris:
      - https://host4/oauth10a/**

  -
    cdcm-connection-id: fixed-headers
    methods: ALL
    root-uris:
      - https://host5:8080/**

connections:
  forward-bearer:
    connection-type: BEARER_TOKEN_FORWARD
  oauth20:
    connection-type: OAUTH20
    client-id: <client-id>
    client-secret: <client-secret>
    user-info-uri: <user-info-uri>
    scopes: openid, profile, email, Sites.Read.All
    authorization-uri: <authorization-uri>
    token-uri: <token-uri>
  oauth10a:
    connection-type: OAUTH10A
    consumer-key: <key>
    consumer-secret: <secret>
    root-services: <root-services-uri>
    service-principal-enabled: false
  fixed-headers:
    connection-type: FIXED_HEADERS
    headers:
      Authorization: <auth-header-value>
      X-Custom-Auth-Header: <custom-auth-header-value>

Reference

Configuration Routing Table

Connections Table

Common entries

OAuth 2.0

OAuth 1.0a

Fixed Headers

Bearer Token Forward

This authentication mechanism has no additional configuration

Links

• RFC 6749: The OAuth 2.0 Authorization Framework

• OAuth 1.0a Specifications

• RFC 7617: The 'Basic' HTTP Authentication Scheme