TLS Profiles in IBM API Connect v5 - Archive Post

This blog has been posted to retain an article written in September 2018 in my personal blog. Whilst it covers an older version of the product which is out of support in April 2022 it still might provide a useful reference for TLS Profiles for API Connect

Date: 2018/09/12 

by Aiden Gallagher & Peter Reeves (our podcast)

Introduction 

In API Connect - as in any system - transmission of data across a network can be protected and secured from tampering or theft using by using x509 key pairs in a key store and trust store. Messages can be secured for a number of reasons and in different ways, this provides:

• Confidentiality - Encryption of messages to ensure they are not read by unintended parties.
• Integrity - Signing messages to ensure they haven’t been altered in transit.
• Non-Repudiation - Ensuring messages are sent by a specific author or program. 

In API Connect, a TLS Profile is created. This references: 

a) certificates to be presented as part of authentication, and 

b) trust stores to validate other applications’ certificates.

The TLS Profile has the settings for the TLS version and whether mutual authentication should be used.

Please see - TLS Profiles in APIC: Cloud Manager Console and API Manager at the bottom of this article for images of the TLS Profiles within API Connect.

This article will cover configuring TLS profiles on APIC - both for inbound and outbound traffic. The reader is expected to be comfortable with basic APIC topologies, the basic infrastructure of DataPower, and a basic understanding of x509 certificates. For introductions to these topics, see the below links:

https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.cmc.doc/ssl.html 
http://www.redbooks.ibm.com/redbooks/pdfs/sg247620.pdf

Authentication

When two applications wish to communicate with each other through an API Connect architecture, they can specify three different levels of authentication; 

No Authentication	Requires no Client-ID headers to be presented
One-way authentication	Expects the sender to provide certificates that the receiver trusts.
Mutual authentication.	Requires both applications to present certificates that the other trusts.

 

No Authentication

Figure 1 - No Authentication

In Figure 1, an example is given of a request and response where no authentication is required or provided. 

1. APP1 makes a request to APP2 across a network. 
2. APP2 accepts the request and sends a response.

In this implementation, any application that has a network connection to APP2 is able to make a request. Providing they have the correct credentials, and a well-formed request, a response will be given. Messages sent without being signed are susceptible to being stolen or read during transit, and malicious requests may be made to APP2 such as a denial of service attack.

One-way Authentication using TLS Profiles

Figure 2 - One-way Authentication

In Figure 2, an example is given of a request and response where the receiving application expects the sender to provide a certificate which it trusts.

1. APP1 makes a request to APP2. 
2. APP2 establishes whether it trusts messages received from APP1.
1. APP2 expects a certificate to be provided. APP1 has provided a certificate.
2. APP2 validates whether the certificate is signed by a trusted Client Authority (CA).
3. APP2 accepts the request and sends a response.

This level of authentication allows a server or receiving application to verify that an application making a request is trusted, and prohibits unauthorised applications gaining information it shouldn’t.

 For the client, this allows the request message to be protected through signing.  

Mutual Authentication 

Mutual Authentication works by a client and a server performing a handshake. This uses Secure Sockets Layer (SSL) and Transport Layer Security (TLS) Protocols which have a specific handshake procedure to describe how the two applications can authenticate each other for secure message sending and receiving.

Below is an overview of how the handshake works based on the section 7.4 of the TLS RFC: https://tools.ietf.org/html/rfc5246#section-7.4

Figure 3 - TLS Handshake

There are eleven steps for completing a TLS Handshake as shown in Figure 3 - TLS Handshake:

1. Initially the server needs to make a ‘hello’ request to the client in order initiate the trust sequence. The two applications at this point can exchange security enhancement capabilities and reset configurations such as the hash and encryption algorithms. The server is entitled to make the request at any time and can repeat the process if it needs to but needs to know about the client before it can make this request.
2. Typically, the server won’t know about the client until a connection is made, so for most first-time connections the first step will be for the client to send a ‘hello’ to the server as an introduction of itself to the server. After this first connection the client will respond with a ‘hello’ whenever the server makes a hello request.
3. The server will respond to the client ‘hello’ with its own ‘hello’ with the purpose of choosing an algorithm that both the server and the client accept.
4. The server will also send a certificate immediately following the server ‘hello’, except for anonymous negotiations. This provides the certificate chain of the server. The same structure of certificate will need to be used by the client later. 
5. The server will also send a server key exchange if the certificate is not sent or does not provide enough data to complete the handshake. It should also only be sent providing the method is legal - RSA, DH_DSS, DH_RSA methods, for example, are not legal. 
6. Providing that the negotiation is not anonymous, the server will request a client certificate. Anonymous servers requesting client certificates will fail. 
7. The server tells the client it has finished sending all the information that it can or will send. At which point the client will validate that the server certificates are valid.
8. If a client certificate had been requested - in step 6 - the client will provide a certificate chain. If there are no available certificates, the client will send a blank certificate which the server can choose to accept or reject for continuing the handshake process. 
9. The client must then send their client key exchange, which provides the clients key information. This will either be an RSA-encrypted secret or a set of applicable parameters to approve a pre-master key with the server.
10. At this point the client send a verification message for the associated client certificate.
11. The server and the client now exchange cipher specifications and send a finished message. The two must confirm the messages received are the same. This then establishes a trusted connection which allows application data to be shared between the two applications.

Mutual Authentication TLS using TLS Profiles

Figure 4 - Mutual Authentication using TLS Profiles

In Figure 4 - Mutual Authentication using TLS Profiles, an example is given of mutual authentication when using TLS Profiles. 

1. APP1 makes a request to APP2. 
2. While invoking the TLS handshake, APP1 presents its certificates from the associated TLS Profile. The presented certificate is validated against APP2s Certificate Authorities (CA) trusted certificate chain stored in the TLS Profiles trust store.
3. APP2 also presents its certificates to APP1 which completes the TLS handshake by also validating against the APP1 Certificate Authorities (CA) trusted certificate chain stored in the TLS Profiles trust store.
4. Once the TLS Handshake is completed a response is given to any further requests whilst all the objects in both TLS Profiles remain valid.

A trust store may have one or all of the following three objects in its trust store certificate; 

• Root CA - A root CA is a self-signed certificate that issues trusted certificates for use to applications and services. By having the Root CA in the trust store, implicit trust of any and all certificates signed by the Root CA is given. This leaves an application open to malicious use by any entity with access to a Root CA signed certificate.
• Intermediate CA - To protect the Root CA keys, an intermediate CA can be issued and used in a trust store. This provides a link to the Root without exposing it. Using this CA gives a subset of applications access to the Root CA, reducing the risk of malicious connections to an application.
• Common Name (CN) Certificate - Trusting a CN certificate means that traffic has to originate from a DNS domain that matches the CN. This gives a much more restricted trusted access to an application.

Each trust store object gives different layers of protection to the application which should be considered when creating the trust store certificate. 

In API Connect, the three authentication types need to be considered for all of the following situations;

• When an application is calling an API deployed on the API Gateway Domain.
• When an API on the DataPower Domain is calling another API locally.
• When an API is calling out from the DataPower Domain to another application (externally hosted microservices, application, API, database etc.). 

TLS Profiles in API Connect

High Level Overview

• Each API Connect DataPower Service creates a DataPower Domain on the servers included on the service (v5): https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.cmc.doc/config_gateway.html
• A DataPower Service (Domain) must define a TLS Profile.
• If a TLS Profile is not defined by the user, the default TLS Profile will be used.
• Inbound traffic is managed by the TLS Profile that is referenced by the DataPower Services.
• Outbound traffic is managed by TLS Profiles that are;
• Defined, managed and made Public in the Cloud Manager Console - which makes them available to all Organisations and therefore all APIs. Caution: This will mean any Provider Organisation in the API Hub can use the TLS Profile and thus may have certificates to allow access to systems they should not have access to.
• Defined and managed within an Organisation on API Manager.
• APIs must include TLS Profiles in their swagger definitions/yaml. Please see Example API Yaml with TLS Profile at the bottom of the article.
• TLS Profiles are stored on DataPower Servers within the Domain
• TLS Profiles are expected in a p12 format
• To be able to change a TLS Profile for a DataPower Service in the CMC, all servers must first be deleted from the Service.

To create a TLS Profile, follow the below knowledge centre instructions:
https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.cmc.doc/ssl.html 
https://www.ibm.com/support/knowledgecenter/en/SSFS6T/com.ibm.apic.apionprem.doc/task_apionprem_ssl.html 

API Connect Traffic Flows using TLS Profiles

In this section, some flows will show how TLS Profiles can be used within API Connect to secure traffic flowing through it and its associated objects. In each scenario, we will begin from a blank APIC topology featuring a single API Gateway with no APIs or products published, a single Management Server which entails both the APIM and CMC. Three applications are shown; a database, MicroService and a secondary Gateway, these represent any and all downstream applications that could be used.

Note: In the diagrams, Domains will be shown in the CMC where they are logically described and managed in APIC by an APIC administrator. In reality, the configuration is pushed to the API Gateway where the traffic flows through, not through the CMC or the Management Server. 

Default Settings

This scenario describes how API Connect protects traffic flow if used without any changes being made post-install.  

Use Case: A consumer Application (APP1) wishes to get information from a record owned by the provider company. An API is published that calls a downstream service, which in turn connects to the system of record and responds with the required data.

Figure 5 - Default Settings

1. API1 is published to the Dev Domain with no TLS Profile in the definition.
2. APP1 calls API1 using one-way authentication by accepting the gateway’s self-signed certificate.
3. API1 invokes an API on the Internal Gateway which does not enforce mutual authentication TLS for inbound traffic, thus the APIs request is processed without any TLS certificate on its part.
4.  A response to the request is received from the system of record and passed back to APP1 through both the internal and APIC API Gateway. 

API Defined TLS Profile

This scenario describes how API Connect presents certificates to downstream applications by setting a TLS Profile in the API definition.  

Use Case: A consumer Application (APP1) wishes to get information from a record owned by the provider company. An API is published that calls a downstream service which enforces one-way authentication. The downstream service then connects to the system of record and responds with the required data.

Figure 6 - API Defined TLS Profile

1. API1 is published to the domain with a TLS Profile in the definition
2. APP1 calls API1 using one-way authentication by accepting the gateway’s self-signed certificate.
3. API1 calls the downstream service API presenting certificates in TLS Profile. The downstream service and API1 complete one-way authentication with the presented certificate validated against the downstream service’s trust store.
4. A response to the request is received from the system of record and passed back to APP1 through both the internal and APIC API Gateway.

Domain Level Mutual Authentication

This scenario describes how API Connect completes mutual authentication for inbound traffic and presents certificates to downstream applications.  

Use Case: A consumer Application (APP1) wishes to get information from a record owned by the provider company. An API is published that calls a downstream service which enforces one-way authentication. The downstream service then connects to the system of record and responds with the required data.

Figure 7 - Domain Level Mutual Authentication

1. API1 is published to the domain with a TLS Profile in the definition. The TLS Profile is created in API Manager and does not enforce Mutual Authentication.
2. APP1 calls API1 but must first complete a TLS Handshake.
3. Mutual Authentication is successfully completed.
4. API1 calls the downstream service API presenting certificates in TLS Profile 4. The downstream service and API1 complete one-way authentication with the presented certificate validated against the downstream service’s trust store.
5. A response to the request is received from the system of record and passed back to APP1 through both the internal and APIC API Gateway.

Outbound Mutual Authentication

This scenario describes how API Connect completes Mutual Authentication TLS Handshake for downstream traffic.  

Use Case: A consumer Application (APP1) wishes to get information from a record owned by the provider company. An API is published that calls a downstream service which enforces mutual authentication. The downstream service then connects to the system of record and responds with the required data.

Figure 8 - Outbound Mutual Authentication

1. API1 is published to the domain with a TLS Profile in the definition. This TLS profile enforces mutual authentication on outbound connections to the microservice.
2. APP1 calls API1 using one-way authentication by accepting the gateway’s self-signed certificate.
3. API1 then invokes an API on a downstream microservice but must first complete a TLS Handshake.
4. Mutual Authentication TLS handshake is completed successfully.
5. A response to the request is received from the system of record and passed back to APP1 through the microservice and the APIC API Gateway. 

Total Mutual Authentication

This scenario describes how API Connect completes Mutual Authentication for both inbound and outbound traffic.

Use Case: A consumer Application (APP1) wishes to get information from a record owned by the provider company. All communication in and out of the API Gateway must complete mutual authentication. 

Figure 9 - Total Mutual Authentication

1. API1 is published to the domain with a TLS Profile in the definition.
2. APP1 calls API1 but must first complete a TLS Handshake.
3. Mutual Authentication is successfully completed.
4. API1 then invokes an API on a downstream microservice but must first complete a TLS Handshake.
5. Mutual Authentication TLS handshake is completed successfully.
6. A response to the request is received from the system of record and passed back to APP1 through the microservice and the APIC API Gateway.

APIs calling same domain APIs

This scenario describes how API Connect completes Mutual Authentication with API calls made to other APIs on the same API Gateway.

 Use Case: A consumer Application (APP1) wishes to get information from a record owned by the provider company. All communication in and out of the API Gateway must complete mutual authentication. API1 uses OAuth, which is defined in API2, and uses mutual authentication due to the configuration settings on the API Gateway.

 

Figure 10 - APIs calling same domain APIs

1. Both APIs are published to the domain with TLS Profiles in the definitions (API1 and the DataPower Service use a public TLS Profile which enforces MATLS).
2. APP1 calls API1 but must first complete a TLS Handshake.
3. Mutual Authentication is successfully completed.
4. API1 then invokes API2 which resides on the same domain. It completes Mutual Authentication with the DataPower Domain – like an external application calling the domain as the Domain expects mutual authentication from all incoming traffic indiscriminately.
5. API2 then invokes an API on a downstream microservice but must first complete a TLS Handshake.
6. Mutual Authentication TLS handshake is completed successfully.
7. A response to the request is received from the system of record and passed back to APP1 through the microservice and the APIC API Gateway.

Summary

Securing APIs and the traffic that flows through an API Connect architecture is an important task that needs considering early on in the design phases of an architecture. Enabling TLS and mutual authentication is always going to be harder in an existing infrastructure that is already serving traffic, so it is important to understand the flows and considerations as early as possible.

This article should give a good understanding of how API Connect traffic will flow and how to secure messages passing through the system in a secure way.

TLS Profiles in APIC

Cloud Manager Console

Figure 11 - TLS Profiles in the Cloud Manager Console 

API Manager

Figure 12 - TLS Profiles in API Manager

Figure 13 - TLS Profile Trust Store and Present Certificate

Example API Yaml with TLS Profile

Figure 14 - API Specification with TLS Profile

IBM API Connect Naming Conventions

**NOTE: Though I am an IBMer, these are naming conventions I personally endorse but are not necessarily endorsed by IBM as an organisation as per all posts on my blog**

Introduction

IBM API Connect has a host of free text variable, parameter, profile and component names. Whilst these are and can be named whatever you like, it is good to follow some uniform naming standards.

Often each new business, value stream, brand, department and individual people will have specific ways in which they like to name. This leads to every object being named different for each new department and team. To alleviate this, I have created the following naming conventions which can be used.

Table of Contents

Introduction

Case Study

Naming Objects as ‘Default’

Display Names and Object Names

1     API Development

  1.1       APIs

  1.2       Product

  1.3       Plans

2     Topology

  2.1       Provider Organisations

  2.2       Catalog

  2.3       Spaces

  2.4       Communities

    2.4.1     Developer Organisations

    2.4.2     Applications

  2.5       Management Services

    2.5.1     Service Name

    2.5.2     Server Name

  2.6       DP Services

    2.6.1     Service Name

    2.6.2     Server Name

    2.6.3     Extensions

  2.7       User Registries

  2.8       Roles

  2.9       TLS Profile

    2.9.1     Cloud Console

    2.9.2     APIs

  3     Developer Portal

    3.1       Roles

    3.2       Developer Portal Modules

  4     v2018.x

    4.1       Availability Zone

    4.2       Portal, Analytics and Gateway Service(s)

    4.3       OAuth Provider

Case Study

All examples described in this document will reference an imaginary Commercial Bank called UKBank that specialises in Mortgages, Loans and Current Accounts, they also provide open APIs for bank locators etc.

The Bank is using Organisations as their environments i.e. SIT01, OAT01, NFT01, LUAT01, PROD01. Their catalogs relate directly to their specialisations with spaces in Current Accounts to isolate traffic for their payments from balance enquiries.

Naming Objects as ‘Default’

Where possible, no object in the API Connect Cloud should be left with a default name of ‘Default’. This causes confusion, makes email notifications difficult to follow and can lengthen routine maintenance and management processes as an understanding of what each element does is made apparent.

Display Names and Object Names

In API Connect, most objects have both a display name - sometimes referred to as a Title - and a ‘name’ which refers to the object name. Where appropriate, both display and functional names have been given.

1      API Development

1.1   APIs

There are many well documented conventions for naming APIs and will often follow company preference. 

IBM have released a guide for APIs in past redbooks: Getting Started with IBM API Connect Concepts and Architecture Guide (http://www.redbooks.ibm.com/redpapers/pdfs/redp5349.pdf) 

Additionally, there are articles that describe API needs around versioning and standard formatting of naming, versioning and url etc. (https://www.ibm.com/developerworks/library/mw-1710-phillips/index.html)

https://api.ukbank.co.uk/mortgages/v1.0/rates

https://api.sandbox.ukbank.co.uk/loan/v1.1/quote  

https://developer.ukbank.co.uk/v1.0/balance

1.2   Product

Products contain a logical grouping of APIs which will be callable once a Developer Organisation has subscribed to its plan. The Product should accurately describe the purpose of the collection of APIs. 

Product names should include dashes and not underscores and should not contain numbers. Version numbers should not be defined in the Product name, this causes confusion as it is static against the dynamic version number that displays next to the Product.

If there is a need to differentiate between brands these are appended in brackets at the end of the product.

Title	Name
Current Account Information (England)	current-account-information-england
Current Account Information (Scotland)	current-account-information-scotland
Mortgage Offers (England)	mortgage-offers-england
Mortgage APR (England)	mortgage-apr-england
Mortgage Payments (UKBank)	mortgage-payments-ukbank

1.3   Plans

Plans are used for rate limiting of API Calls and monetization of APIs. Developer Organisation subscribe an Application to a Plan, not a Product. Each product can have multiple plans which will have different costs and potentially rate limits. Additionally, different plans may conform to predefined contract agreements between third parties, public and internal users.

When an Organisation has a predefined, well documented and well understood convention for logical grouping of APIs and their limits, these should be continued in plan names. This would typically map to a standard selection of upgrades.

Plan 1 - Title	Plan 1 - Name	Plan 2 - Title	Plan 2 - Name	Plan 3 - Title	Plan 3 - Name
Basic	basic	Standard	standard	Advanced	advanced
Bronze	bronze	Silver	silver	Gold	gold
Small	small	Medium	medium	Large	large

2      Topology

2.1   Provider Organisations

Provider Organisations might be named after an environment i.e. SIT01 or by an Organisations business unit i.e. UK Sales, UK HR.

An Organisations display name may be several words, each beginning with a capital letter. Its logical name must represent the display name, it must not contain spaces but instead should use a dash rather than an underscore. For best display and reference, it is recommended that the Organisation not be any more than 2 words and 15 characters (Maximum length: 81 characters).

Where multiple environments may exist of the same type i.e. System Integration Test, the environments unique identifier should be two numbers after the environments abbreviations beginning at ‘01’ through ‘99’.

Display Name	Name
OAT01	oat01
SIT01	sit01
SIT02	sit02
LUAT01	luat01
UK Sales	uk-sales
UK HR	uk-hr

2.2   Catalog

Catalogs provide a logical separation for Products and their APIs with an Organisation. They also determine the developer portals that will be used for subscription of Plans within APIs as catalogs can have a single Developer Portal Site and therefore each catalog can push only to a single portal site. The actual name given to a catalog depends on the chosen distribution of Products, APIs and intended use of Organisations, though it commonly becomes split by a brand or value stream.

Catalogs names should be a single descriptive word. However, if a double worded Catalog is used it should not use camel-case and should have capitals for the first letter of each word and a space used for the display name. 

Display Name	Name
Mortgages	mortgages
Open	open
Loans	loans
Current Accounts	current-accounts

2.3   Spaces

Spaces provide a separation of Products and APIs within a single Catalog. Each space should describe the separation it is bringing with its name. 

Spaces names should be single word and descriptive. However, if a double worded Space is used it should not use camel-case and should have capitals for the first letter of each word and a space used for the display name. 

Display Name	Name
Balance	balance
Payments	payments
England Stores	england-stored
England Regulations	england-regulations

2.4   Communities

2.4.1     Developer Organisations

Developer Organisations can be created both on a Portal site and also on the management server. Typically, the Portal Site would be explored by external entities either external to the business itself or external to Provider teams, brands and value streams. Internal Developer Organisation such that have their Developer Organisations created for them will be defined in the API Manager WebUI. 

The naming convention to be applied here should follow existing internal naming solutions for applications. Where no existing convention exists, the format should follow the format of Organisation-ValueStream-TeamName.

Developer Organisation

UKBank-HR-Compensation

UKBank-Mortgages-Test

UKBank-Mortgages-Development

UKBank-Mortgages-View

2.4.2     Applications

Applications should be created with its goal and purpose in mind. The name of these applications should be concise, should all be lower case and obvious what the application does.

Title

hr-employee-payment

hr-employee-illness

mortgage-test-ivt001

mortgage-test-ivt002

mortgage-test-ivt003

mortgage-test-endtoend

2.5   Management Services

2.5.1     Service Name

In IBM API Connect v5, there is a single management service called Management. This cannot be changed. 

2.5.2     Server Name

Server names should reference the server address/hostname being used. This helps easily identify management servers and issues that may arise i.e. dissociation. 

Where server names already exist within the company or organisation, this standard should be used and the name used throughout. This consistency allows interdepartmental teams to quickly understand and identify issues.

Server Name	Server Address
MGR0012	10.132.41.12 mgrsrvr0012.prod.machine

2.6   DP Services

2.6.1     Service Name

Services should be named relating to the Organisation they are being used by and should be named in a descriptive form of the domain they are representing. This service will be used by catalogs and spaces to define the gateway services they will use, so a descriptive name is important.

Title

SIT01 Mortgages DP Service

OAT01 Current Account Payments DP Service

PROD01 Open APIs

2.6.2     Server Name

Server names should reference the Organisation or Domain they are being used for and should be identifiable to the server they are representing to avoid confusion for debugging. We use gateway identifiers to precede the server identifier.

Server Name	Server Address
SIT01 GWY0022	10.132.41.22 gwysrvr0022.prod.machine

2.6.3     Extensions

Extensions are deployed to a single domain. They should include a version number which can be incremented as and when changes are made. Alternatively, or in conjunction with the version number, a date stamp may be appended to the end of the string to further describe when the extension was compiled. Names should be descriptive of the function being performed, should not contain spaces but instead dashes. The file should use full words and not abbreviations.

Filename

api-certificate-updates-v1.0.zip

api-certificate-updates-20180101-0323.zip

api-certificate-updates-v1.0-20180101-0323.zip

2.7   User Registries

A User Registry should be easily identifiable to anyone looking at the system. Typically, it would describe what component it is for, where the registry is based and then the fact it is a user registry.

The name cannot contain spaces, should be entirely in lowercases but should be shorter than the Title/Display Name. The registry location and “user registry” should be condensed to just the first letter of each.

Display Name	Name
API Manager Local User Registry	api-manager-lur
Cloud Manager Docker User Registry	cloud-manager-dur

2.8   Roles

Each role within API Manager can have multiple words for its Title/Display Name to a maximum of 81 characters (to be represented equivalently in the name). These should describe the type of permission being given.

The name must be lowercase and use dashes instead of spaces.

Display Name	Name
Community Viewer	community-viewer
Role Assigner	role-assigner

2.9   TLS Profile

TLS profiles can be used for communication with the API Connect Cloud Manager and the Gateway or for a TLS handshake with a load balancer. These cloud-based TLS Profiles are defined in the Cloud Manager. 

Additionally, TLS profiles can be defined in the API Manager to be used by APIs to call either other APIs on the same gateway or some form of implementation layer downstream such as an internal load balancer or microservice.

2.9.1     Cloud Console

The name given for Cloud based TLS Profiles should have the following format; component-tls-side-profile, component relates to where the profile is used, and side is whether it is a server or client profile. The Display Name/Title is the same but with spaces instead of dashes.

Display Name	Name
Default TLS Server Profile	default-tls-server-profile
SNI TLS Client Profile	sni-tls-client-profile

2.9.2     APIs

TLS Profiles to be used by APIs for handshakes to endpoints should have the following format; purpose-tls­-location. Where purpose should show the intended use of the profile and location should describe the endpoint where the handshake will occur. The Display Name/Title is the same but with spaces instead of dashes.

Display Name	Name
Authorise API TLS IHS	authorise-api-tls-ihs

3      Developer Portal

The developer portal is a server which stored all the information about each of the Clouds portal sites. There are limited objects that require naming conventions within the Portal such as Roles, Page Names and Drupal Modules.

3.1   Roles

Roles should follow the rules already defined earlier in the document: Roles. 

3.2   Developer Portal Modules

Modules within the Developer Portal allow additional functionality with the Portal Site such as configuration of LDAP for portal delegated user registry, live chat functions, OpenID Connect and many more.

Module names within the Developer Portal should follow Drupal Standards. 

https://www.drupal.org/docs/8/creating-custom-modules/naming-and-placing-your-drupal-8-module

4      v2018.x

4.1   Availability Zone

Availability Zones should be descriptive and are organised by regions, global separation, or for physical/logical separation of datacentres. The Title can use spaces, capitals, lowercase etc. but a short one or two-word title is preferred. Abbreviation may be used

Title	Name
US Availability Zone	us-availability-zone
Hampshire Availability Zone	hants-availability-zone
Newport Availability Zone	newport-availability-zone
LDN South Availability Zone	london-south-availability-zone

4.2   Portal, Analytics and Gateway Service(s)

Services should describe the type of service and match the location for the availability zone. There should be no spaces and each new word should start with a capital letter. Abbreviations should match those in the Availability Zone.

Title	Name
USPortal	us-portal
USGateway	us-gateway
HampshireAnalytics	hants-analytics
LDNSouthPortal	ldn-south-portal

4.3   OAuth Provider

OAuth Title should match the OAuth Provider being used exactly.

Title	Name
Zendesk	zendesk
Ubuntu One	ubuntu-one