Home
...
Authorizations
Tutorial - Sensedia API Platform authorizing publishers

Tutorial - Sensedia API Platform authorizing publishers

How to use Sensedia API Platform to authorize publishers.

The Events Hub allows you to use an external server to validate client IDs and/or access tokens of publishers sending requests to the Events Hub.

One option is to use the Sensedia API Platform for this validation.

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

Explanation: Imagine 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 works the same way. You select the type of validation you want to perform, and it ensures the validation is enforced.

How does it work?

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

Authorization URL configuration is done by context. It is one of the markers of the event publishing URL, formed by: Base URL + context + handler + topic.

There are 5 available interceptors, and 4 require the publisher's authorization server to function. 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.

Obtaining the authorization URL with Sensedia API Platform

To use Sensedia API Platform as the validation server for policies:

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

In API Events Hub Authorization, navigate to the Environments section.

Choose the environment you want to configure, click the link icon, and copy the URL.

You will need to append the interceptor information, so paste it into a file.

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

Append the interceptor path to the end of the environment URL. This will be your authorization URL.

With the complete URL copied, go to Events Hub > Authorizations and find the context to be validated by this authorization.

Click the add icon, paste the authorization URL, and save.

TIP
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 into OAuth and JWT. Pay attention when copying the path for your URL:

The authorization URL must be generated respecting the policies applied to the context.
If you added OAuth Validation interceptors, copy the OAuth path.
If you added JWT Validation interceptors, copy the JWT path.

Check out how to configure the available interceptors:

Client ID Validation

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

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

Follow the steps to configure a Client ID Validation:

In Sensedia API Platform:

Go to Consumers > APPS and click + Create APP.

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

Click PUBLISH YOUR APP.

In Events Hub:

Register the publisher:

With the APP saved, go to the Publishers screen.
Hover over the + button and click Import From API Platform.
Find the registered APP and click SAVE.
Click ADD ENABLED TOPICS and link the publisher to the desired topic.
Enable the context to be validated by the interceptor by clicking . If no context is enabled, the validation will not work.

Access the handler:

On the Handler screen, find the one registered for this validation.
In the Topics tab, copy the URL of the context enabled for the Client ID interceptor.

In Postman:

In the POST request, paste the URL of your context.

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

Check if the request was successful in the handler status icon.

NOTE
If you have an APP with a plan linked to the Events Hub Authorization 1.0* API, you don't have to do this again.

No Postman

Generate the access token:

To get the token, you must make a request to the OAuth API deployed on your platform. We will show you how to do this using the client-credentials flow.

TIP
To understand the other available flows, access the OAUTH 2.0: access token acquisition flows documentation.

Make a POST request to the <gateway-url>/oauth/access-token endpoint.
In the header, pass:

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

In the body, pass the grant_type in x-www-form-urlencoded format:
The access token will be returned in the request's body, as in the example below:

Test the policy:

Copy your context URL and paste it into POST.
Insert the access token parameter in the request header, with the same name that you registered for the policy (e.g., access_token).
Click Send.
Check if the request was successful in the handler's status icon.

OAuth Validation

The OAuth Validation interceptor requires the validation of client ID and access token.

If not yet configured, see the topics:

Client ID Validation
Access Token Validation The client ID and access token values must be passed in the request header.

Testing the policy in Postman:

Copy the URL of your context and paste it into the POST request.

Paste the client ID value into the request header.

Paste the access token value into the request header.

Click Send.

Check if the request was successful in the handler status icon.

JWT Validation

The JWT Validation interceptor requires the validation of a JWT token, which must be obtained through the OAuth JWT flow.

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

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

Follow the steps to configure a JWT Validation:

In Sensedia API Platform:

Go to Consumers > APPS and click + Create APP.

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

Click PUBLISH YOUR APP.

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

In Postman:

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.

Make a POST request to the endpoint <gateway-url>/oauth/grant-code.
In the header, pass:
In the body, pass the following information. Remember to replace the example client ID with your APP's client ID.

TIP
The redirect_uri must be filled with a URL. You can use, for example: "http://test.com".

The response will return the code after the = sign, as in the example below:

With the copied code, generate the JWT token:

Make a POST request to the endpoint <gateway-url>/oauth/access-token.
In the header, pass:
In the body, select the json format and pass the following information, including the code number generated in the previous request:

The JWT token will be returned in the response, as in the example below:

Test the policy:

Copy the URL of your context and paste it into the POST request.
Paste the JWT token value into the request header.
Click Send.
Check if the request was successful in the handler status icon.

How happy are you with this page?

Policies

Events Hub Authorization API

Handlers

Authorizations

Subscribers