MUST be secured with Oauth2.0 token and a subscription key [9]

The client should always send an subscriptionkey in the Apim-Subscription-Key header. Don’t send subscriptionkey in the URL or as a query parameter, as this might cause a security risk. The subscriptionkey identifies the client (app). subscriptionkeys are private and should only be used by the (developer) app they were created for. They can be found in the developer portal -> your developer app. They are preferably not shared by e-mail and definitely not in Postman collections! If necessary, they are best shared by text message (SMS) or according to the security guidelines. Most APIs require an authenticated user. Clients will have to authenticate by proving their credentials and requesting a token from the Token API (v1/oauth/token). The acquired access token can be used to authenticate the user within the other Stedin APIs. The access token must be sent by setting a ‘Bearer token’ in the ‘Authorization’ header in the following manner: Authorization: Bearer {access_token}

SHOULD contain a functional name for the product [87]

API’s belong to a product. A product can have one or multiple APIs. The name of the product should not be the technical project name of the application but the name of the functional solution. The design authority will determine if the name is correct.

MUST validate JWT token [10]

The backend application should validate all relevant aspects of the JWT token. It is advised to make use of a library for your environment to perform the token validation. But it will anyway be helpful to understand the validation details involved. There are also various websites available to parse tokens and view their content. There are client libraries available that help you to acquire a token to invoke an API. And there are server middleware libraries available to help you to validate the incoming tokens.

• Signature
• Issuer
• Expiration
• Audience check
• Has operation specific role or scope

SHOULD define adequate app roles for each API function [11]

A consumer should not be allowed to use more API functions then is allowed. This is accomplished by defining app roles for the separate functions of the API. In its most basic form read and write access should be separated.

MUST setup exclusive access for APIM to backend web service [12]

In addition to the token we prescribe a second “south bound” authentication method to ensure only Azure API Management can invoke the backend web service. Two methods are allowed:

• API key (+ IP whitelisting)
• mTLS

SHOULD use logical name for app registrations based on the application or team name [13]

App registrations should be given a logical name based on the application or team in Stedin. Production app registrations do not include an environment name. For the non-production registration the environment name must be added to the app registration as a suffix between parentheses. Use “Title Case”, so begin every word with a capital letter.

Always create 4 environments, even though the backend has less. This way we always have a working app registration in Azure API Management.

App registration name: <Logical Application Name> (<Environment>)

Examples:

Workday (Development)
Workday (Test)
Workday (Acceptance)
Workday