Tutorial: Using the Sensedia API Platform for Publisher Authorization

The Events Hub allows you to use an external server to validate client IDs and/or access tokens of publishers who send requests to the Events Hub. One of the options is to use the Sensedia API Platform to do this validation.

Sensedia API Management v5 clients: To validate publishers' client IDs and/or access tokens, you must import the Events Hub authorization API.

Imagine that you are organizing an event at a venue. You want only authorized people to enter. So, you place a security guard at the entrance to check people’s identities. The authorization server acts in the same way. You select the type of validation you want to do and it makes sure it’s carried out.

How does it work?

On the Policies page, you can create security policies to apply to handlers.

The configuration of authorization URLs is done by context. It is one of the markers of the event publication URL, formed by: URL base + context + handler + topic.

There are 5 interceptors available, and 4 need the publisher authorization server to work. They are:

  • Access Token Validation

  • Client ID Validation

  • OAuth Validation

  • JWT Validation

When selecting any of them, you need to configure the authorization URL on the Authorizations screen.

Getting the authorization URL using the Sensedia API Platform

To use the Sensedia API Platform as the policy validation server:

  1. Go to API Design > API Catalog and search for API Events Hub Authorization;

  2. In the API Events Hub Authorization, go to the Environments section;

  3. Choose the environment you want to configure, click on the icon link, and copy the URL. You will need to complement it with interceptor information, so paste it into a file;

  4. Go to the Resources and Operations section and copy the POST path of the interceptor type you will use;

  5. Paste the interceptor’s path at the end of the environment URL. This will be your authorization URL;

  6. With the full URL copied, access Events Hub > Authorizations and find the context that will be validated by this authorization;

  7. Click on the icon icon add1, paste the authorization URL and save.

To register a test context for authorization, in the Environments section, copy the link of your test environment.

The Resources and Operations section is divided between OAuth and JWT. When copying the path of your URL, be aware that:

  • The authorization URL must be generated according to the policies added to the context;

  • If you added OAuth Validation interceptors, copy the OAuth path.

  • If you added JWT Validation interceptors, copy the JWT path.

Configure Client ID Validation

The Client ID Validation interceptor requires a simple client ID validation.

When registering this interceptor for a policy, you need to define the name that will be used to pass the Client ID value (for example, client_id) and where it will be passed in the request (cookie; header; header or cookie; query param; or any).

To use it, follow these steps:

  • In the Sensedia API Platform

    1. Go to Consumers > APPS and click on + Create APP;

    2. In the APIS AND PLANS tab, search for Events Hub Authorization 1.0 and select it in the SELECT ALL PLANS button;

    3. Click on PUBLISH YOUR APP;

  • In the Events Hub

    1. Register the Publisher

      1. With the APP saved, access the Publishers screen;

      2. Place the cursor on the + button and click on Import From API Platform;

      3. Find the APP you registered and click on SAVE;

      4. Click on ADD ENABLED TOPICS and link the publisher to the topic you want;

      5. On the same screen, click on the icon view topics icon to enable the context that will be validated by the interceptor. If you don’t enable any, validation won’t work.

    2. Access the Handler

      1. On the Handler screen, find the one you registered for this validation;

      2. In the Topics tab, copy the URL of the enabled context for the Client ID interceptor.

  • In Postman

    1. In the POST, paste the URL of your context;

    2. Insert the client ID parameter in the request header, with the name matching what you registered for the policy (e.g., client_id) and click Send;

    3. You can check if the request was successful by clicking on the icon event status icon in your handler.

Configure Access Token Validation

The Access Token Validation interceptor requires the validation of an access token. It must be obtained using the OAuth flow chosen by the publisher.

When registering this interceptor for a policy, you need to define the name that will be used to pass the access token value (for example, access_token) and where it will be passed in the request (cookie; header; header or cookie; query param; or any).

To configure it, follow these steps:

  • In the Sensedia API Platform

    1. Go to Consumers > APPS and click on + Create APP;

    2. In the APIS AND PLANS tab, search for Events Hub Authorization 1.0 and select it in the SELECT ALL PLANS button;

    3. Click on PUBLISH YOUR APP.

If you already have an APP with a plan linked to the Events Hub Authorization 1.0 API, you don’t need to do this again.

  • In Postman

    1. Generating the access token

To obtain the token, you must make a request to the OAuth API deployed on your Platform. We’ll show you how to do this using the client-credentials flow:

To understand the other flows available, visit the documentation OAuth 2.0: access token retrieval flows.

1. In POST, make a request to the endpoint <gateway-url>/oauth/access-token;
2. In the header of the request, you must pass:

Authorization : Basic client_id:client_secret

Example of a header with the client_id and client_secret in Base64:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

3. In the body of the request, you must pass the grant_type in the x-www-form-urlencoded format:

"grant_type": "client_credentials"

4. The access token will be generated and returned in the request body, as in the example below:

{
  "access_token": "6c164a82-84a6-3bc4-8122-f777121a4f62",
  "token_type": "access_token",
  "expires_in": 3600
}

  • To test the policy

    1. Copy the URL from your context and paste it into POST;

    2. Insert the access token parameter in the request header, with the same name as the one you registered for the policy (e.g. access_token);

    3. Paste the key of your access token into the value and click Send;

    4. You can check if the request was successful by clicking on the icon event status icon in your handler.

Configure OAuth Validation

The OAuth Validation interceptor requires client ID and access token validation. If you haven’t configured it yet, take a look at the topics:

The client ID and access token values must be passed in the request header.

  • Testing the policy in Postman

    1. Copy the URL from your context and paste it into POST;

    2. Paste your client ID into the header;

    3. Paste your access token into the header;

    4. Click Send;

    5. You can see if the request was successful by clicking on the icon event status icon of your handler.

Configure JWT Validation

The JWT Validation interceptor requires the validation of a JWT token obtained through the JWT OAuth flow.

When registering this interceptor for a policy, you need to define the name that will be used to pass the access token value (for example, access_token) and where it will be passed in the request (header; default JWT header; or query param).

For this interceptor to work, you must register the URL of the JWT authorization of your context in the Authorizations screen.
See how to get the authorization URL using the Sensedia API Platform.

To configure it, follow these steps:

  • In the Sensedia API Platform

    1. Go to Consumers > APPS and click on + Create APP;

    2. In the APIS AND PLANS tab, search for Events Hub Authorization 1.0 and select it in the SELECT ALL PLANS button;

    3. Click on PUBLISH YOUR APP.

If you already have an APP with a plan linked to the Events Hub Authorization 1.0 API, you don’t need to do this again.

  • In Postman

1. Generate the code

To obtain the token, you need to generate the code by making a request to the OAuth API deployed on your Platform.

1. In the POST, make a request to the endpoint <gateway-url>/oauth/grant-code;
2. In the header of the request, you must pass:

Content-Type : application/json

3. In the body, enter the information below. Remember to replace the client ID in the example with your APP’s client ID:

{
  "client_id": "f9212173-e705-373b-a698-61923e378359",
  "extraInfo": {},
  "redirect_uri": "string",
  "state": "string"
}
The redirect_uri needs to be filled in with a URL. For example, you can enter "http://testing.com".

In the response, the code will be returned after the = sign, as in the example below:

{
  "redirect_uri": "string?state=string&code=8748d39f-1d4f-311f-92c6-4b279db1b317"
}

2. Generating the JWT token

With the code copied, you can generate the JWT token:

1. In POST, make a request to the endpoint <gateway-url>/oauth/access-token;
2. In the request header, you must pass:

Authorization : Basic client_id:client_secret

3. In the body, select the json format and pass the information below, with the code number you generated in the previous request:

"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
"code" : "8748d39f-1d4f-311f-92c6-4b279db1b317"

4. The token will be returned in the request response, as in the example below:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. eyJhdWQiOiJsb2NhbGhvc3QiLCJpc3MiOiIxNzIuMTguMC4xIiwic3ViIjoiOWI1Zjc3MWUtNzgyZC0zNTEwLWI2YmEtMzZlOWM2NWJmZDVkIiwiZXhwIjozNjAwLCJpYXQiOjE1Mjg5MTg2MzcsIkFwcDogIjoiRGVtb0FwcCIsIkNvZGU6ICI6IjRlNWIyMTEzLTJkYzYtM2RlNi1iN2ZkLWNkOTYxOTMxZWQyOSIsImxvZ2luIjoidXNlci5sb2dpbiJ9. DVSd_yIKiWqIRpcFUhpB5JT9HMUE4mI5fAcpzs4QOkM",
  "token_type": "access_token",
  "expires_in": 3600
  }

  • Testing the policy in Postman

    1. Copy the URL from your context and paste it into POST;

    2. Paste your JWT token into the header;

    3. Click Send;

    4. You can see if the request was successful by clicking on the icon event status icon of your handler.

Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]