Security

Protocols

Supported protocol is https with the minimum TLS version 1.2

Azure Application Gateway (WAF)

Azure Application Gateway is a web traffic load balancer that enables Green Cargo to handle traffic to our web applications, including APIs available in the Green Cargo API Management platform.

The Web Application Firewall (WAF) service in Azure Application Gateway has built-in rules to prevent the most common attack patterns.
The WAF protects against the following web vulnerabilities:

• SQL-injection attacks

• Cross-site scripting attacks

• Other common attacks, such as command injection, HTTP request smuggling, HTTP response splitting, and remote file inclusion

• HTTP protocol violations

• HTTP protocol anomalies, such as missing host user-agent and accept headers

• Bots, crawlers, and scanners

• Common application misconfigurations (for example, Apache and IIS)

Web Application Firewall has built-in rules to prevent from the most common attack patterns listed in OWASP Top Ten. These rules must be updated continuously to follow the latest attack patterns.

The current active ruleset is the OWASP 3.2, details about the ruleset can be found here: WAF Rules.
If your API requests get blocked, you should have a look at the ruleset to validate that your API client conforms to the rules defined.

Authentication and Authorization

For external users/system outside of GreenCargo organization, the api platform uses OAuth 2.0 (Open Authorization) as a secure and standardized way to access the APIs. The current supported authorization flow is the client credentials flow, which is best suited for Machine-to-Machine (M2M) applications. More information on how (as a client) to implement the client credentials flow can be found in the section Getting started -> How to integrate oAuth.

The client also needs to send the subscription key in an http header named “Ocp-Apim-Subscription-Key”.

Getting started

On-boarding process

1. Send request mail to Green Cargo
   The email must contain information which apis are requested, contact person at Green Cargo and an email address where to send the invitation mail.

2. Green Cargo registers the user, gives the user access to the requested api(s) and sends an email with an invitation link.

3. The user can then sign-in to the developer portal and browse/test the apis that the user have access to.

4. For OAuth:  clientId, secret och scope are sent to the customer

There is also an alternative process where the user can register in the Green Cargo B2C AD. This is the preferred way when integrating with the OAuth flow.

Ask your Green Cargo contact which on-boarding process to use. The OAuth flow is described below.

How to integrate OAuth

As an external party using token based authentication towards Green Cargo API:s, the client secret needs to be refreshed once a year. Green Cargo has developed a process for this including both API Management Developer Portal and the Green Cargo B2C AD. 

The necessary client app registration is created by Green Cargo. And an email I sent to the responsible person, or shared inbox at the external party. 

The email will contain the necessary details for the client credentials flow, and a password to “OneTimeSecret” where the external party can download the client secret. The OneTimeSecret link will come in a separate mail. 

The email is sent from DoNotReply@greencargo.com and will look something like this:

The client app registration for external parties is created in the Green Cargo B2C AD. The user/users that should be able to renew the client secret also need to register in the B2C AD.

OAuth Flow

To be able to use Green Cargo API:s you need to provide both an API Key and a valid Token in every request. The API key is managed directly with self-service, in the API Marketplace Portal by the external party. The API Key is called a Subscription Key, and must be placed in a HTTP header named “Ocp-Apim-Subscription-Key”. 

The Bearer token will be implemented through the OAuth flow. The client (the external party integration/application) needs to fetch a token by using the provided details in the email, and then for every following request to the Green Cargo API provide the token as a Bearer in the Authorization header. This is a standard OAuth flow. 

To integrate OAuth, the client needs to use the provided ClientId, ClientSecret and Scope. 

1. Application sends application's credentials to the Authorization API on the following URL:s. 

Dev: https://login.microsoftonline.com/598846f9-96d3-4d3e-9ce0-8c9ea154ee90/oauth2/token?api-version=2.0 
Test: https://login.microsoftonline.com/598846f9-96d3-4d3e-9ce0-8c9ea154ee90/oauth2/token?api-version=2.0 
Prod: https://login.microsoftonline.com/9a015b52-fe0f-4233-b597-4bf69971f603/oauth2/token?api-version=2.0

The Guid in the URL is the Green Cargo B2C AD Tenant Id, which is the identity provider.

Request body sample:

Postman sample, Test Environment:

2. Authorization Server validates application's credentials. 

3. Authorization Server responds with an access token. 

4. Application uses the access token to call an API  
(the content of the access_token is set in the Authorization header). 
HTTP headers: 
Name: Ocp-Apim-Subscription-Key Value: “your subscription key” 
Name: Authorization Value: Bearer “content of access_token” 

The access token is valid for an hour so the client can reuse the same token if further API calls will be made. 

5. API validates the access token and responds with a http 401 response if the access token is missing or invalid.  Otherwise, the API responds with requested data. 

User registration

To be able to use the Green Cargo API Marketplace, and also manage your Client App Registration Secrets, you need to have an account in Green Cargo B2C AD. 

Use your browser and go to:  

• Dev: https://apimarketplace-d.greencargo.com/signin 

• Test: https://apimarketplace-t.greencargo.com/signin 

• Prod: https://apimarketplace.greencargo.com/signin 

Click the Azure Active Directory B2C button. 

Select the “Sign up now” link. (When you have a B2C account created you click the Sign in button to login to Green Cargo API Marketplace) 

Send a verification code and fill in the fields, including the Company Name. 

Click Create to create your B2C account. 

When logged in to the API Marketplace, you can browse the APIs you have been provided, view the API documentation and API Specification, and use the Test Console to actually test them. 

Renew Client Secrets 

When a client secret is about to expire, the person (or shared mail account) registered as owner for the application, will get reminder emails from Green Cargo. 

The first email will be sent 30 days before secret expiration. 

If a new secret hasn’t been created, a new reminder will be sent 14 days before secret expiration. 

If a new secret hasn’t been created, the last reminder will be sent 7 days before secret expiration. 

When the secret has expired, and no new secret is created and implemented, the integration will stop working. 

The client secret must be updated with the new value, in the external party application, before expiration date of the old one has passed. 

The reminder emails will look something like this: 

Renew a secret 

After receiving a reminder email the following steps explain how to renew a client secret. 

Login with B2C to the API Marketplace. (as explained earlier) 

Go to the API: B2C Mgmt Api External. 

Select the “RenewSecret” endpoint, and click the green Try it button. 

Select authorization_code as the Authorization flow. 
Fill in the ClientId that you got in the reminder email. 

Scroll down and click the Send button at the bottom of the page. 

The new secret will be provided in a separate email with a “OneTimeSecret” link, exactly as the first client secret was provided. 

Just take this new secret and configure your application to use it. 

Contact

API Management Team:

integration@greencargo.com