How can I remove query parameters, like subscription keys, from an API request URL sent back to the user in APIM?

Question

How can I remove query parameters, like subscription keys, from an API request URL sent back to the user in APIM?

hampton123 1,175

Is it possible to remove query parameters, like subscription keys, from the URL of an API request in APIM after it is processed? Specifically, I want users to be able to enter their subscription key through the URL of their request, but I don't want the key to be visible in the URL sent back to them after the request is processed. Is there a way to do this?

I've tried using the <set-query-parameter> policy in APIM, with no success.

Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T15:03:49.05+00:00

Hi @hampton123 you can send the APIM subscription key as either a header or a QS parameter and you can change the name (from the default) in both cases (REF)

But I'm not sure , based on the question, where you want the data removed

In a simple case I have an API projected through APIM. The API definition is under a product and that has a subscription. In order to access the API through APIM as a API consumer (for example an App developer) I need to include the subscription key
In the event of using a test client , like Postman for example, I can include the subscription key as a QS parameter and that will get sent to APIM. The APIM GW will then forward that request to the backend

So

Are you referring to the second hop, the request from APIM to the backend? Or data returned in the response based on the request context?

Thanks in advance
hampton123 1,175 Reputation points

2023-06-26T15:14:17.7333333+00:00

Hi @Ben Gimblett thank you for your response! Sorry if I wasn't too descriptive in my initial post. When the user sends the request to access the API, I want the URL itself to change to remove the query parameter containing the subscription key. So I want it to change the returned response, hopefully that makes sense.

So when they use the link to the API and include their subscription key in the URL, I want the API to present the information and authenticate the user while also removing the subscription key in the URL.

This part of the API is more for user-friendliness so users won't be as tech-savvy - that's why I'm more focused on passing the key through the URL rather than through the header.
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T15:21:47.59+00:00

No probs - still a bit unsure though... who is the user persona ? Aside from the developer and operator persona an API is not usually consumed directly, but through an Application

Your ask makes sense from a browser / web app perspective where control over the visible URL in the browser can be important

but I'm still trying to map it into my head from an API perspective

for example if I issue a GET through CURL for the following (made up) API

curl https://api.contoso.com/sales?subscription-key=<my key>

Then the response will contain json for my sales list, but the URL remains request context. Changing it is moot (unless it's the case I want my api consumer through apim to issue the request in one way then modify it to fit something else the backend expects. all possible, but , that's a slightly different use case)

Apologies if I'm missing the obvious here ! :)
hampton123 1,175 Reputation points

2023-06-26T16:02:58.99+00:00

@Ben Gimblett It's no problem at all! I'm new to this kind of development so there's a lot of concepts I don't understand and I think it's just how I'm describing the issue.

For context, my API provides users with HTML pages to download/upload files from. They'll just be using the browser to perform these actions. So when they try to access the API, they'll input their subscription key through the URL. Once they submit this information through the URL, they'll be provided with the HTML page where they submit their information.

So using your example I want them to construct their URL like so:

[ https://api.contoso.com/sales?subscription-key=] <my key>

and then once it loads up the HTML page, I want it to present the URL like this:

[ https://api.contoso.com/sales]

Hopefully that makes sense but just let me know if I'm explaining things in a confusing way and I'll try to clarify even further. From what you're saying though it sounds like this is impossible?

My current requirement from my company is that I hide the subscription key for security reasons- like if there's a presentation of the API then they don't want anyone who's watching to see the subscription key.
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T16:22:37.91+00:00

Ahh ok so the endpoint is serving the app to the browser

for example, in SPA (single page apps) you normally access the app html via a given address (usually with a CDN behind) and the app JS then calls back from the browser to load various parts of the page async. As the user uses the app, so more JS calls to load /update content (putting it very basically). The URL may not change at all from the user experience perspective

I dont know too much about BFF (back end for front end) so cant comment

In traditional web apps (before SPA) you'd request a page, which would usually cause the server to redirect you to another page and that would usually mean a change in URL (but again depending on framework)

APIM might be able to help here, but i think the answer depends (and starts on) how the web app is architected - it's more a web app question than APIM/API question - if that makes sense :)
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T16:30:24.3333333+00:00

one more comment: Be careful with subscription key - once issued it's easy to "lose" (e.g. it s a static fact with no real context that can be shared, stolen etc)
In itself its not really an authentication credential, but works well with strong auth/auth - for client apps that's usually OAUTH (using oauth + OIDC or open id connect, for client web apps)

What's concerning me is that your company is putting emphasis on "protecting" the key - and in a client/browser type app that's quite hard - because browsers are not inherently very secure. In traditional web apps, an API key would be hidden, the server side of the web app would recover it (perhaps from config) to call the downstream API, which of course would be entirely hidden from the user/browser
hampton123 1,175 Reputation points

2023-06-26T16:31:25.9733333+00:00

See that's what I was thinking - APIM policies might be able to adjust the URL and I've tried various methods and policies but none of them seem to work. An Azure Function makes up the API so maybe something can be done through VS code but I'm still not 100% sure if I should focus on that or if there's a simple solution in APIM.
hampton123 1,175 Reputation points

2023-06-26T16:35:36.1433333+00:00

Should I be using another service to protect the API? I was thinking about Azure AD B2C but my company hasn't given me access to create a tenant yet, and I've been trying to figure out how to make the experience as user-friendly as possible (when using B2C I'm not sure how to get the JWT token to the API).
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T16:37:09.83+00:00

I am really not a web dev; but the sort of thing I assume your user has the subscription key already (it's a fact they know already) and so if they they request the app (browse to the app via their PC/laptop) and the page has a "go" button with a password text box they can type the key into. On hitting "go" can your script behind the page not just call back to the API building the API query string/URL with subscription key from the info the user entered in the text box? (that's very basic, but you see the idea - make it more an interaction with the page?)
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T16:39:21.28+00:00

Yes B2C would give you identity management for external users (so sign up , sign in etc etc) . AAD could be used if it's internal corp users only (or partner guests). These are the two MS "first party" options

Securing an app with oauth adds complexity (and can add cost under some circumstances) but significantly increases the app security and would be best practice for public web apps/apis particularly where the use is privileged
hampton123 1,175 Reputation points

2023-06-26T16:44:36.9333333+00:00

Just to clarify, you're saying that users should use their information to login into my API after they use the subscription key right? So first they enter the API through submitting the link with the subscription key, then have a login system to then allow users to access the download/upload file portion of the API?

Also maybe AD B2C is the way to go then because there will be external users, is it possible for users to access the API with the subscription key first and then have to sign in using their credentials?
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T19:33:19.1+00:00

Not exactly.

Remember I'm making some assumptions here - i dont have visibility of your requirements or the technology you're using for your website (the functionality/Implementation). This is important because security is about risk.

To illustrate lets take two examples

(1) Bob is a family photographer , families come to Bobs studio and he takes some pictures and generates them a preview link with a query string param which is the "key" (unique to them and the transaction) which will allow them to browse the watermarked / low-res proofs in order to decide which photos to buy.
Does Bob need oauth/B2C and a tonne of security for this ? No. It's low risk, simple stuff. If they "lose" the key or it gets stolen, the impact is negligible.

(2) On the other end of the scale we have Sarah. She's developing an API for banking and credit card customers to download their monthly statements. Is an API key sufficient here. Almost certainly not. The statements contain a lot of sensitive individual data and the whole app will probably need to meet stringent compliance. The App and API in Sarah's case will be protected using fine grain and strong authorization at a minimum and likely with more than one credential.

Bob and Sarah's requirements are vastly different and how they approach securing their Apps and APIs is going to have very different levels of cost, complexity and oversight.

**** - **

In the answer below I've collated some links

Accepted answer

0 additional answers

Your answer

Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T15:03:49.05+00:00

Hi @hampton123 you can send the APIM subscription key as either a header or a QS parameter and you can change the name (from the default) in both cases (REF)

But I'm not sure , based on the question, where you want the data removed

In a simple case I have an API projected through APIM. The API definition is under a product and that has a subscription. In order to access the API through APIM as a API consumer (for example an App developer) I need to include the subscription key
In the event of using a test client , like Postman for example, I can include the subscription key as a QS parameter and that will get sent to APIM. The APIM GW will then forward that request to the backend

So

Are you referring to the second hop, the request from APIM to the backend? Or data returned in the response based on the request context?

Thanks in advance
hampton123 1,175 Reputation points

2023-06-26T15:14:17.7333333+00:00

Hi @Ben Gimblett thank you for your response! Sorry if I wasn't too descriptive in my initial post. When the user sends the request to access the API, I want the URL itself to change to remove the query parameter containing the subscription key. So I want it to change the returned response, hopefully that makes sense.

So when they use the link to the API and include their subscription key in the URL, I want the API to present the information and authenticate the user while also removing the subscription key in the URL.

This part of the API is more for user-friendliness so users won't be as tech-savvy - that's why I'm more focused on passing the key through the URL rather than through the header.
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T15:21:47.59+00:00

No probs - still a bit unsure though... who is the user persona ? Aside from the developer and operator persona an API is not usually consumed directly, but through an Application

Your ask makes sense from a browser / web app perspective where control over the visible URL in the browser can be important

but I'm still trying to map it into my head from an API perspective

for example if I issue a GET through CURL for the following (made up) API

curl https://api.contoso.com/sales?subscription-key=<my key>

Then the response will contain json for my sales list, but the URL remains request context. Changing it is moot (unless it's the case I want my api consumer through apim to issue the request in one way then modify it to fit something else the backend expects. all possible, but , that's a slightly different use case)

Apologies if I'm missing the obvious here ! :)
hampton123 1,175 Reputation points

2023-06-26T16:02:58.99+00:00

@Ben Gimblett It's no problem at all! I'm new to this kind of development so there's a lot of concepts I don't understand and I think it's just how I'm describing the issue.

For context, my API provides users with HTML pages to download/upload files from. They'll just be using the browser to perform these actions. So when they try to access the API, they'll input their subscription key through the URL. Once they submit this information through the URL, they'll be provided with the HTML page where they submit their information.

So using your example I want them to construct their URL like so:

[ https://api.contoso.com/sales?subscription-key=] <my key>

and then once it loads up the HTML page, I want it to present the URL like this:

[ https://api.contoso.com/sales]

Hopefully that makes sense but just let me know if I'm explaining things in a confusing way and I'll try to clarify even further. From what you're saying though it sounds like this is impossible?

My current requirement from my company is that I hide the subscription key for security reasons- like if there's a presentation of the API then they don't want anyone who's watching to see the subscription key.
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T16:22:37.91+00:00

Ahh ok so the endpoint is serving the app to the browser

for example, in SPA (single page apps) you normally access the app html via a given address (usually with a CDN behind) and the app JS then calls back from the browser to load various parts of the page async. As the user uses the app, so more JS calls to load /update content (putting it very basically). The URL may not change at all from the user experience perspective

I dont know too much about BFF (back end for front end) so cant comment

In traditional web apps (before SPA) you'd request a page, which would usually cause the server to redirect you to another page and that would usually mean a change in URL (but again depending on framework)

APIM might be able to help here, but i think the answer depends (and starts on) how the web app is architected - it's more a web app question than APIM/API question - if that makes sense :)
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T16:30:24.3333333+00:00

one more comment: Be careful with subscription key - once issued it's easy to "lose" (e.g. it s a static fact with no real context that can be shared, stolen etc)
In itself its not really an authentication credential, but works well with strong auth/auth - for client apps that's usually OAUTH (using oauth + OIDC or open id connect, for client web apps)

What's concerning me is that your company is putting emphasis on "protecting" the key - and in a client/browser type app that's quite hard - because browsers are not inherently very secure. In traditional web apps, an API key would be hidden, the server side of the web app would recover it (perhaps from config) to call the downstream API, which of course would be entirely hidden from the user/browser
hampton123 1,175 Reputation points

2023-06-26T16:31:25.9733333+00:00

See that's what I was thinking - APIM policies might be able to adjust the URL and I've tried various methods and policies but none of them seem to work. An Azure Function makes up the API so maybe something can be done through VS code but I'm still not 100% sure if I should focus on that or if there's a simple solution in APIM.
hampton123 1,175 Reputation points

2023-06-26T16:35:36.1433333+00:00

Should I be using another service to protect the API? I was thinking about Azure AD B2C but my company hasn't given me access to create a tenant yet, and I've been trying to figure out how to make the experience as user-friendly as possible (when using B2C I'm not sure how to get the JWT token to the API).
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T16:37:09.83+00:00

I am really not a web dev; but the sort of thing I assume your user has the subscription key already (it's a fact they know already) and so if they they request the app (browse to the app via their PC/laptop) and the page has a "go" button with a password text box they can type the key into. On hitting "go" can your script behind the page not just call back to the API building the API query string/URL with subscription key from the info the user entered in the text box? (that's very basic, but you see the idea - make it more an interaction with the page?)
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T16:39:21.28+00:00

Yes B2C would give you identity management for external users (so sign up , sign in etc etc) . AAD could be used if it's internal corp users only (or partner guests). These are the two MS "first party" options

Securing an app with oauth adds complexity (and can add cost under some circumstances) but significantly increases the app security and would be best practice for public web apps/apis particularly where the use is privileged
hampton123 1,175 Reputation points

2023-06-26T16:44:36.9333333+00:00

Just to clarify, you're saying that users should use their information to login into my API after they use the subscription key right? So first they enter the API through submitting the link with the subscription key, then have a login system to then allow users to access the download/upload file portion of the API?

Also maybe AD B2C is the way to go then because there will be external users, is it possible for users to access the API with the subscription key first and then have to sign in using their credentials?
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T19:33:19.1+00:00

Not exactly.

Remember I'm making some assumptions here - i dont have visibility of your requirements or the technology you're using for your website (the functionality/Implementation). This is important because security is about risk.

To illustrate lets take two examples

(1) Bob is a family photographer , families come to Bobs studio and he takes some pictures and generates them a preview link with a query string param which is the "key" (unique to them and the transaction) which will allow them to browse the watermarked / low-res proofs in order to decide which photos to buy.
Does Bob need oauth/B2C and a tonne of security for this ? No. It's low risk, simple stuff. If they "lose" the key or it gets stolen, the impact is negligible.

(2) On the other end of the scale we have Sarah. She's developing an API for banking and credit card customers to download their monthly statements. Is an API key sufficient here. Almost certainly not. The statements contain a lot of sensitive individual data and the whole app will probably need to meet stringent compliance. The App and API in Sarah's case will be protected using fine grain and strong authorization at a minimum and likely with more than one credential.

Bob and Sarah's requirements are vastly different and how they approach securing their Apps and APIs is going to have very different levels of cost, complexity and oversight.

**** - **

In the answer below I've collated some links

Answer 1

Ben Gimblett 4,560 Microsoft Employee

REF comments above

For reference in no particular order

Google have a nice short and balanced doc on API key security here https://cloud.google.com/endpoints/docs/openapi/when-why-api-key(the concepts here are applicable to any architecture or cloud)

There's a couple of simple [SPA] web app examples from MS that include B2C
https://learn.microsoft.com/en-us/azure/active-directory-b2c/configure-authentication-sample-react-spa-app
https://github.com/Azure-Samples/ms-identity-b2c-javascript-spa

In both cases the app itself would be bootstrapped from a static web host/CDN (or static website on Storage) and the first thing the user would do is sign up or sign in. Thereafter API interaction is based on the access token derived from the login (id) token. An API key might be derived from the login (id) token claim or config

For completeness

This is a nice APIM companion doc to the older API OWASP list (we're working on an update as the OWASP top 10 has been updated) . https://learn.microsoft.com/en-us/azure/api-management/mitigate-owasp-api-threats

This is a nice doc on auth and authz concepts in APIM https://learn.microsoft.com/en-us/azure/api-management/authentication-authorization-overview

Hope this helps

hampton123 1,175 Reputation points

2023-06-26T19:45:21.2866667+00:00

@Ben Gimblett I've got to say thank you for all your help throughout the day, you've really helped me try to figure things out! The articles you linked seem very informative and helpful so I'll be using them as a reference when I can use B2C in my company.

One final question, how expensive is B2C to implement?
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-26T20:07:07.4666667+00:00

B2C pricing is based on a Monthly active user charge (MAU) see here for an explainer https://learn.microsoft.com/en-us/azure/active-directory-b2c/billing and here for the actual unit cost by currency https://azure.microsoft.com/en-gb/pricing/details/active-directory-external-identities/
hampton123 1,175 Reputation points

2023-06-26T20:49:10.3466667+00:00

Thank you Ben. That made me think of one final question, would the general user flow be like this:

User accesses the API via a link constructed with the subscription key where they are greeted with a login B2C page, then once they log in they can access the API's services?
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-27T08:37:21.24+00:00

There are a number of options. I think though I would start with the requirement and the process flow around how you generate a subscription key (which is presumably when you configure the API in APIM here) and how that subscription key gets communicated to the customer

It also matters the relationship between subscription key and customer. Is it one to one, one to many etc.

The answer to that will determine how you communicate the key to the customer/individual/app

Options include

*having the customer enter it themselves once logged in (assumes it's been communicated in some other way, for example email) , as part of the application UI and user flow
*having the customer sign up, log in and then having some background logic which recovers the key server side for that given individual / customer / company based on facts you derive from the login claims (the claims available in the id token returned from the identity provider, here B2C)

*if your html/app is "Per customer" and so is the API key you could embed the api key in the config / app content so its there for the call back to the API. The API key is then " discrete " from the customer

*it is also possible to have B2C add custom claims based on other data sources -but this can be significantly more complex to implement

But the process flow depends on the requirements and how securely you want to treat the api key. As per prior comments Its perfectly valid for each API to have the auth/security which best fits its purpose.

The usual flow for a web app using modern auth which is not anonymous (anon meaning anyone can access it any time, public, open) is for the user to login (id token returned to the app) and the app can then request an access token for each api it wants to call - as per tutorials the app => api interaction can be controlled through permissions. What the user can do with the app can also be controlled by permissions derived from the claims returned by the identity provider. An API key is just another "fact" that controls auth to the API (as per google doc linked above) but it's most common for that to be abstracted (not directly available) to the actual app user. API keys are usually only available directly to developer/ops users (the owners of the app depending on the API).

Note:
Remember that APIM can validate an oauth access token when a front end calls a backend api secured by oauth and fronted by apim. This is a good practice for "belt and braces" security.
https://learn.microsoft.com/en-us/azure/api-management/validate-jwt-policy
(note the "validate-jwt-ad" policy is for AAD not B2C at this time)
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-27T08:37:55.47+00:00

please do "accept" the answer above if it's useful (as this helps others :))
hampton123 1,175 Reputation points

2023-06-27T13:44:56.4366667+00:00

Read below comment, sorry I thought my initial comment didn't send so I re-typed it in the below comment
hampton123 1,175 Reputation points

2023-06-27T13:53:51.3033333+00:00

Sorry if this is a duplicate comment, as I thought I sent my comment in here but I don't see it.

The keys will be one-to-one for each customer. So APIM automatically generates subscription keys for the users under their profile in APIM, also blocking all access to the API itself if the subscription key is not provided.

What I was thinking is that first the user pastes their subscription key into the URL first, then once this allows them to entry to the API, they then have to log in using Azure AD B2C. Then once they log in, the token generated from this login is passed directly through to the API, redirecting the user to the pages to either download or upload a file. Does that seem okay? See I would allow the user to sign in first with Azure AD B2C but not having the subscription key completely prevents the user from accessing any part of the API, so it would have to be provided first.
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-27T14:20:58.2866667+00:00

mmm. I still think you need a separation of concerns here

you have (or will have I assume) some form of web app UI

you have the requirement to serve data (in your case upload/download of flat file data via your UI)

the web app UI can and often does have a backend API (very much so for SPA and BFF type architectures)

where you want to restrict functionality to authorized users then it follows users should log into the app before accessing the restricted functionality

API keys are a very very simple single fact credential , a kind of secret required to gain access (and optionally identity the caller)

It makes sense for API because an API is (literally by definition) an Application programming interface.

It makes less sense for a UI ---- put it another way, it's quite unusual to log into a UI with JUST a pin code or single fact (OK, phone apps can work this way, but generally steps and credentials are required to set it all up first and the "pin" is just a short cut / convenience for the already authenticated and logged in device owner)

In the end the decisions are yours based on your requirements - it really goes back to my "bob" and "sarah" comment about what is "good enough". I'm gently pushing because what you're talking about seems a bit unusual - to serve the web app via an API which itself requires an API key (when most often client-side web apps are served from a public static host/CDN).
hampton123 1,175 Reputation points

2023-06-27T14:44:22.96+00:00

Oh gotcha okay, see I have more of a Sarah situation going on here, that's why I was thinking the subscription key would be a good extra layer of security with B2C. You're also right with the UI and the requirement to serve data. But from what I understand you're saying that since this is more of a web app UI situation it's unusual to have to provide an API key to begin with which makes 100% sense. I really don't want to stray too far from normal conventions but I also need the system to be secure. What do you think?

Also, please feel free to point me out in any direction, as I'm still a beginner to this type of development :)
Ben Gimblett 4,560 Reputation points Microsoft Employee

2023-06-27T16:07:14.7166667+00:00

Definitely I would consider using modern / strong auth for a secure app - B2C sounds like it will work for you as you've external users to server, and as per the tutorials samples (linked earlier) use that to secure the UI and the API both.
There's no issue in also using an API key between front end and backend API as an extra layer - but I think your challenge is to manage that in a way you can allow the user to "log in" then either you resolve it for them (if possible), or communicate it to them some other way ahead of their using the app and they enter it as a UI input

:)
hampton123 1,175 Reputation points

2023-06-27T16:26:34.5+00:00

@Ben Gimblett thank you so much for your help! I'll look over the links you sent. I think right now I'll go with the API key and B2C but if it gets too user-unfriendly and becomes difficult to implement with the API then I'll just leave the API key out. Thanks again.

Share via

How can I remove query parameters, like subscription keys, from an API request URL sent back to the user in APIM?

0 additional answers

Your answer