How to bring your own IDP as key manager for WSO2 APIM
Let’s configure your own IDP to handle security with WSO2 APIM
WSO2 API Manager comes with a built-in component called “key manager” which is capable of managing the tokens that are required when accessing APIs. But there can be many situations where an organization might be already using an Identity Provider (IDP) such as Okta, Ping, AzureAD, or even WSO2 Identity Server. Given that these IDPs are capable of handling most of the security-related requirements of an organization, it makes sense to use the same IDP to secure the APIs while using an API management solution such as WSO2 API Manager. In this article, I’m going to explain how to configure a 3rd party IDP as the key manager for WSO2 API Manager.
Let’s assume that you have Okta as your IDP and you need to configure that with WSO2 APIM so that Okta acts as the key manager. The following documentation link has a step-by-step guide on configuring Okta as the key manager.
What we are doing here is that get the details of the authorization server which is already configured on the Okta side (or creating a new authz server) and using that detail to configure Okta as 3rd party KM on WSO2 APIM. Also, we create an application on the Okta side to represent WSO2 APIM as a service provider. Once we are done with the configuration, we can see the newly added key manager on the developer portal side when generating tokens. At the same time, this is visible on the API publisher side when creating APIs. You can select the Okta KM and generate a token and then use that to consume the API.
There is a small catch here on the try-it tool. It will only allow you to generate tokens from the built-in KM. You have to generate the token in the token generation page and paste the token when using the try it tool.
Once you configure Okta as KM, the real-world use cases require understanding the flow beyond trying it out with the developer portal. That is where most people get confused since it required a better understanding of the overall process which is not exposed when using the try-it tool in the developer portal.
The figure below depicts a scenario where we configure Okta as 3rd party key manager with WSO2 API Manager.
As per the above figure, once we configure Okta as KM following the documentation, we need to build an application such as a web or mobile application to access the APIs that are protected with WSO2 APIM and Okta. Given below is a list of steps involved when accessing an API from a mobile or web application in a real world use case.
Step 0) We register the application with Okta and generate a client ID (cid) and client secret(cs). Once we have this, we need to use that and subscribe to the related API on the WSO2 APIM side. You can use the developer portal to achieve this.
Step 1) Now the application is all set and it has a subscription for the API. An end user will try to access the application and that user needs to first authenticate with the application.
Step 2) The user will be redirected to the IDP (Okta) from the application and the user will provide the credentials to authenticate him/her self.
Step 3) If the credentials are valid, the IDP will redirect the user back to the application with the required token (based on the grant type). Here the application and the IDP will do the OAuth dance based on the grant type and the application will end up getting an access token (JWT) to call the API.
Step 4) Now the application will call the WSO2 API gateway with the access token received in the previous token. By default this token is sent over the “Authorization” header.
Step 5) The WSO2 API gateway will validate the access token at the gateway level and if the token is valid and the subscription details are valid, it will pass the request to the backend.
Step 6) Backend service will respond to the request with the details
Step 7) API gateway will transfer the response back to the client.
One thing to remember here is that the application that you are registering here with Okta is different than the application that we created while configuring Okta as KM.
In addition to this flow, if there is a need to send end-user details to the backend service, you can generate a JWT within the API gateway and pass it to the backend as depicted in the figure below.
In this case, a new header called “X-JWT-Assertion” will be used to send the JWT generated by the gateway to send details to the backend.
