Step 7 - Onboard as a Dev API

The goal of a Developer Portal is not only to provide API Documentation. In addition, a Developer Portal offers the possibility to try out the API directly from it. It means the Developers will ask for API Keys from this portal and use these keys to try out APIs. Then, the Developer Portal will send a request to the API Gateway with the API-KEY generated.

In this lab, the Infrastructure and API teams will modify the NMS ACM configurations to:

• Infra team action : Enable Authentication for developers on the Dev Portal with OIDC (Keycloak as Identity Provider)
• API team action : Enable API-Key authentication on the Sentence API proxy (so far, there is no authentication on the API Gateway). So that a Developer can use the API-KEY created by the Developer Portal.

Infrastructure team - Steps

The infrastructure team must enable OIDC on the DevPortal instance. To do so, follow these steps.

1. In NMS ACM, in Infrastructure section, go into your team-sentence workspace, then sentence-env environment

2. Click on your devportal-cluster object

3. In the Policies section, click on Manage

   

4. On the row OpenID Connect Relying Party, click on the three dots on the top right and Add Policy

   

5. Keycloak is already configured to authenticate Developers with your Developer Portal listening on http://dev.sentence.com. Configure the policy as below:

   • Choose an OAuth Flow : PKCE
   • App Name : devportal
   • Client ID : devportal
   • Client secret : empty as we are using PKCE (no secret)
   • Scopes : keep only openid
   • Keys : http://10.1.1.4:8080/realms/devportal/protocol/openid-connect/certs
   • Token : http://10.1.1.4:8080/realms/devportal/protocol/openid-connect/token
   • Authorization : http://10.1.1.4:8080/realms/devportal/protocol/openid-connect/auth
   • User Info : http://10.1.1.4:8080/realms/devportal/protocol/openid-connect/userinfo
   • Logout URI : http://10.1.1.4:8080/realms/devportal/protocol/openid-connect/logout

   Note

   The Keycloak configuration console provides all those endpoints. These Keycloak configurations have already been completed.

6. Click Add

7. Click Save and Submit

Note

Now, the Developer Portal instance is ready to authenticate Developers against Keycloak as Identity Provider. Developers are already onboarded in Keycloak.

Note

When a developer is authenticated, they can request their API-Keys

API Team - Steps

The API team must enable API-Key authentication on top of the exposed Sentence API Version 1 so that Developers can use the API Keys requested in the Developer Portal.

1. Switch to Services on the left menu, go to your sentence-app workspace, and edit your sentence-api API proxy (click on the three dots, then Edit Proxy).

   

2. In the Policies section, Add policy for APIKey Authentication

3. Don’t make any changes; click Add

4. Click Save & Publish

Note

Now, the API is protected by APIKey authentication. Every request to the API http://api.sentence.com requires an APIKey header and value.

Developer Team - Test the protected API

Request API keys

1. In Win10, connect to the Developer Portal

2. You should now see a Login button on the top right corner (thanks to the infrastructure team who enabled OIDC)

3. Login as dev1/dev1 on the Keycloak login page. You will be redirected to the DevPortal and authenticated.

   

4. A new menu will appear App Credentials, click on it

   

5. And click on Create org. Name it nginx and click Create

6. Notice there aren’t any credentials. Let’s create one:

   • Click Create credential
   • App name : sentence1
   • API : select sentence-api v1 - This is the version v1 exposed on the API Gateway.
   • Click Generate

Note

You may need to refresh the page to see the newly generated key.

1. You can now expand your sentence1 APIKey to see the value (if not, refresh the page). Copy the value.

   

Test with Postman

1. Open Postman, and select any API GET Call (except for GET Colors). For instance GET Animals

2. Send the request, and you can notice a 401 - Unauthorized. The APIKey is required.

   {
      "message": "Unauthorized",
      "status": "401"
   }
   

3. In the Authorization tab, select API Key and paste the value copied from the Developer Portal into the Value field.

4. Send the request

   

Note

The API Gateway accepts the request. The API Gateway has been automatically updated with the new API Key created by the Developer. Each time a developer creates a new API Key, all API Gateways are updated.

Test with the Developer Portal

The developer portal has one more capability. They can test/try out the API.

1. In the developer portal, click on the APIs menu. If you are logged out, re-login.

   

2. Click on sentence-api doc, then select a GET call from the left side pane (GET /adjectives, for example)

3. Click on Try it out and select the API Key created previously

4. Click Send

   

   Warning

   It should not work. Nothing should happen. The reason is the Developer Portal inserts a CORS header. So we have to enable the CORS policy on the API Gateway.

5. Connect to NMS ACM and edit our API Proxy (in the Services menu)

   

6. In Policies, on CORS click on Add policy

   

7. In the OPTIONS field, add the header apikey into the allow list. Scroll down till the end, and then in the field, enter apikey and click Add Header

   Warning

   It is easy to mistakenly add the header to the CORS list, the OPTIONS list is at the bottom.

   

8. Click Add, Save & Publish

   Note

   Now, the API Gateway will accept requests from the Developer Portal

9. Reconnect and re-login into the Developer Portal, and re-test.

10. You will see the response from the API Gateway in the Developer Portal