Security and Policies in OAS export from azure apim

user_2076775 0
Viewed 321

Let’s say I have different backend services exposing their api in azure api management (apim). The different services rely on different security methodologies, e.g. jwt tokens and subscription key. The backend developers specify these differences and upload them to apim using the OpenApi Spec (OAS). Then I find out that Security definitions are ignored so where would the developer have to specify this information? In descriptions instead? Or what is the proper way of conveying security information in apim.

In addition, the apim can have policies set regarding security. These policies are not exposed in OAS either. With the exception of the subscription key, however this is just default behaviour even if one disables the subscription required tag in the api settings in apim, the subscription key is still present in OAS.

So how do one go about informing users about the backend services security and the apims security when it is not present in OAS? Is there some configuration that I am missing?

The idea for my apim is to have different suppliers of backend services so they could have different security levels - It can be specified in OAS - but will not give me anything in the exported version from apim.

In addition, I as an owner of apim will set some security settings - which will still not be present in OAS. So what should the consumer do to understand how to use the backend endpoints exposed in the downloaded OAS’s?

azure-api-management openapi azure
2 Answers

One way to solve this problem is store your keys and secrets on Azure Key Vault and access them from your front end application.

Another way is by using Dapr along with the APIM. Dapr helps in building event-driven, resilient distributed applications. To consume application secrets, Dapr has a dedicated secrets building block API that allows developers to get secrets from a secret store.

Check this Secrets Management document for more information.

Dapr integration in the Azure API Management (APIM) service was released last year only. This new capability enables operations teams to directly expose Dapr microservices as APIs and make those APIs discoverable and easily consumable by developers.

You can check this Microsoft Documentation for more information. Dapr integration in Azure API Management Service.

user_167931500

There's a few parts to this question...

At the company where I work; we use APIM, but we don't define our Open API spec (OAS) in there. IMO APIM is not really intended to be used as an API documentation tool.

We define & document the OASs in Swagger Hub. Swagger Hub are the company behind the Swagger spec, which has since been rebranded to Open API spec. Swagger Hub is a commercial offering, but I think there's also a free tier.

As you're probably aware, you can define multiple security schemes in your Open API spec e.g.

securitySchemes:
    jwt_token:
        type: oauth2
        flows:
            authorizationCode:
                authorizationUrl: {my-authorization-url}
                tokenUrl: {my-token-url}
    apim_subscription_key:
        type: apiKey
        in: header
        name: X-API-KEY

You can then apply these security schemes to your Open API spec (either at the root level or on individual operations).

paths:
    '/{version}/users':
        get:
            summary: 'Search for users'
            description: 'blah'
            security:
                - jwt_token: []
                - apim_subscription_key: []

In Swagger Hub you can 'view documentation' to render the Open API spec in a 'Swagger UI'. You can configure servers to point to different locations (e.g. APIM) when you invoke operations in the Swagger UI e.g.

servers:
    - description: 'localhost'
      url: http://localhost:{port}
      variables:
        port:
            default: "8089"
    - description: 'APIM DEV'
      url: {apim-url}

see here for more information about configuring servers.

In the Swagger UI rendered by your OAS, you click the authorize button and authenticate to one of your specified security schemes as follows:

enter image description here enter image description here

and change the server that you're pointing to via the drop down:

enter image description here

Switch to APIM server and invoke your API operations to call your APIs fronted by APIM.

You can publish the API in Swagger Hub and make the API publicly accessible to your consumers.

In APIM, you'll probably need to implement policies such as validate JWT, but as you've mentioned these don't live in the OAS. Ideally your APIM config would all be in source control, which would includes both the OAS as well as things like APIM policies and other config. It's not actually trivial to do all of this - there's a PluralSight course that I watched recently that was a pretty good overview about how to set up SCM for APIM - see here.

There's an integration in Swagger Hub to publish OASs directly to APIM, which might also be interesting, but I haven't used this as part any workflows. See here.

WRT to your API consumers, you can either

  • Give them your OAS from Swagger Hub, which includes security schemes, servers, etc.
  • Just give them access to the Swagger UI documentation, which is a nice UI for your OAS with the ability to authenticate to your specified security schemes and make API request to your API running in different locations e.g. localhost, or your DEV/SIT/UAT APIs running in Azure behind APIM...
user_8244340
Related