title | description | services | documentationcenter | author | manager | editor | ms.assetid | ms.service | ms.workload | ms.tgt_pltfrm | ms.topic | ms.date | ms.author |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
How to delegate user registration and product subscription | Learn how to delegate user registration and product subscription to a third party in Azure API Management. | cfowler | 8b7ad5ee-a873-4966-a400-7e508bbbe158 | mobile | article | apimpm |
Delegation allows you to use your existing website for handling developer sign in/sign up and subscription to products, as opposed to using the built-in functionality in the developer portal. It enables your website to own the user data and perform the validation of these steps in a custom way.
Nov 14, 2018 Client applications that need to consume the published APIs must include a valid subscription key in HTTP requests when they make calls to those APIs. To get a subscription key for accessing APIs, a subscription is required. For more information about subscriptions, see Subscriptions in Azure API Management. Learn the Azure API Management terminology. Complete the following quickstart: Create an Azure API Management instance. Also, complete the following tutorial: Import and publish your first API. Create and publish a product. Click on Products in the menu on the left to display the Products page.
[!INCLUDE premium-dev-standard-basic.md]
To delegate developer, sign in and sign up to your existing website, you'll need to create a special delegation endpoint on your site. It needs to act as the entry-point for any such request initiated from the API Management developer portal.
The final workflow will be as follows:
To begin, let's first set-up API Management to route requests via your delegation endpoint. In the Azure portal, search for Security in your API Management resource and then click the Delegation item. Click the checkbox to enable 'Delegate sign in & sign up'.
Now you need to create the delegation endpoint. It has to perform a number of actions:
Receive a request in the following form:
http://www.yourwebsite.com/apimdelegation?operation=SignIn&returnUrl={URL of source page}&salt={string}&sig={string}
Query parameters for the sign in / sign up case:
Verify that the request is coming from Azure API Management (optional, but highly recommended for security)
Compute an HMAC-SHA512 hash of a string based on the returnUrl and salt query parameters (example code provided below):
HMAC(salt + 'n' + returnUrl)
Compare the above-computed hash to the value of the sig query parameter. If the two hashes match, move on to the next step, otherwise deny the request.
Verify that you are receiving a request for sign in/sign up: the operation query parameter will be set to 'SignIn'.
Present the user with UI to sign in or sign up
If the user is signing-up you have to create a corresponding account for them in API Management. Create a user with the API Management REST API. When doing so, ensure that you set the user ID to the same value as in your user store or to an ID that you can keep track of.
When the user is successfully authenticated:
request a single-sign-on (SSO) token via the API Management REST API
append a returnUrl query parameter to the SSO URL you have received from the API call above:
for example, https://customer.portal.azure-api.net/signin-sso?token&returnUrl=/return/url
redirect the user to the above produced URL
In addition to the SignIn operation, you can also perform account management by following the previous steps and using one of the following operations:
You must pass the following query parameters for account management operations.
Delegating product subscription works similarly to delegating user sign in/-up. The final workflow would be as follows:
To enable the functionality, on the Delegation page click Delegate product subscription.
Next, ensure the delegation endpoint does the following actions:
Receive a request in the following form:
http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={product to subscribe to}&userId={user making request}&salt={string}&sig={string}
Query parameters for the product subscription case:
Verify that the request is coming from Azure API Management (optional, but highly recommended for security)
To generate the public/private key pair, enter this in the Command Prompt: ssh-keygen At the first prompt, “Enter file in which to save the key,” press Enter to save it in the default location. Generate ssh public private key pair. To generate an SSH key pair on UNIX and UNIX-like platforms using the ssh-keygen utility: Navigate to your home directory: $ cd $HOME. Run the ssh-keygen utility, providing as filename your choice of file name for. Enter a passphrase for the private key, or press Enter to create a private key.
Compute an HMAC-SHA512 of a string based on the productId, userId, and salt query parameters:
HMAC(salt + 'n' + productId + 'n' + userId)
Compare the above-computed hash to the value of the sig query parameter. If the two hashes match, move on to the next step, otherwise deny the request.
Process product subscription based on the type of operation requested in operation - for example, billing, further questions, etc.
On successfully subscribing the user to the product on your side, subscribe the user to the API Management product by calling the REST API for subscriptions.
These code samples show how to:
The same code works for the productId and userId with slight modification.
C# code to generate hash of returnUrl
NodeJS code to generate hash of returnUrl
[!IMPORTANT]You need to republish the developer portal for the delegation changes to take effect.
For more information on delegation, see the following video:
[!VIDEO https://channel9.msdn.com/Blogs/AzureApiMgmt/Delegating-User-Authentication-and-Product-Subscription-to-a-3rd-Party-Site/player]
-->This tutorial shows how to import an OpenAPI Specification backend API in JSON format into Azure API Management. Microsoft provides the backend API and hosts it on Azure at https://conferenceapi.azurewebsites.net?format=json.
Once you import the backend API into API Management, your API Management API becomes a facade for the backend API. You can customize the facade to your needs in API Management without touching the backend API. For more information, see Transform and protect your API.
In this tutorial, you learn how to:
In the Azure portal, search for and select API Management services.
On the API Management screen, select your API Management instance.
This section shows how to import and publish an OpenAPI Specification backend API.
In the left navigation of your API Management instance, select APIs from the API Management section. Openssl rsa key pair generation.
Select the OpenAPI tile, and then select Full on the pop-up screen.
On the Create from OpenAPI specification screen, use the values from the following table to create your API.
A red star next to a field on the form indicates that the field is required. You can set API values during creation or later by going to the Settings tab.
Setting | Value | Description |
---|---|---|
OpenAPI specification | https://conferenceapi.azurewebsites.net?format=json | The service implementing the API. API management forwards requests to this address. |
Display name | After you enter the preceding service URL, API Management fills out this field based on the JSON. | The name displayed in the developer portal. |
Name | After you enter the preceding service URL, API Management fills out this field based on the JSON. | A unique name for the API. |
Description | After you enter the preceding service URL, API Management fills out this field based on the JSON. | An optional description of the API. |
URL scheme | HTTPS | Which protocols can be used to access the API. |
API URL suffix | conference | The suffix appended to the base URL for the API Management service. API Management distinguishes APIs by their suffix, so the suffix must be unique for every API for a given publisher. |
Products | Unlimited | Association of one or more APIs. Each API Management instance comes with two sample products: Starter and Unlimited. You publish an API by associating the API with a product, Unlimited in this example. You can include several APIs in a product and offer them to developers through the developer portal. To add this API to another product, type or select the product name. Repeat this step to add the API to multiple products. You can also add APIs to products later from the Settings page. To get access to the API, developers must first subscribe to a product. When they subscribe, they get a subscription key that's good for any API in that product. If you created the API Management instance, you're an administrator already, so you're subscribed to every product in the instance. |
Tags | Tags for organizing APIs for searching, grouping, or filtering. | |
Version this API? | Select or deselect | For more information about versioning, see Publish multiple versions of your API. |
Note
To publish the API, you must associate it with a product. You can do that from the Settings page.
Select Create.
If you have problems importing an API definition, see the list of known issues and restrictions.
You can call API operations directly from the Azure portal, which provides a convenient way to view and test the operations.
In the left navigation of your API Management instance, select APIs from the API Management section, and then select Demo Conference API.
Select the Test tab, and then select GetSpeakers. The page shows Query parameters and Headers, if any. The Ocp-Apim-Subscription-Key is filled in automatically for the subscription key associated with this API.
Select Send.
The back end responds with 200 OK and some data.
In this tutorial, you learned how to:
Advance to the next tutorial to learn how to create and publish a product: