Skip to content

Commit

Permalink
Merge pull request #349 from ant-media/refactor-cors-filter
Browse files Browse the repository at this point in the history 
Update cors-filter.md
  • Loading branch information
@lastpeony
lastpeony authored Sep 6, 2024
2 parents 2ea9318 + 2814866 commit 28437d0
Show file tree
Hide file tree
Showing 6 changed files with 127 additions and 86 deletions.
56 changes: 29 additions & 27 deletions docs/guides/advanced-usage/webhooks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ sidebar_position: 3

# Using webhooks

Ant Media Server provides webhooks for making your system/app know when certain events occurs on the server. Therefore, you can register your URL to Ant Media Server which makes POST request when a live stream is started, finished or recorded. Firstly,  let's look at how to register your backend URL to Ant Media Server as a webhook. After that, we'll provide reference for webhooks.
Ant Media Server provides webhooks for making your system/app know when certain events occurs on the server. Therefore, you can register your URL to Ant Media Server which makes POST request when a live stream is started, finished or recorded. Firstly, let's look at how to register your backend URL to Ant Media Server as a webhook. After that, we'll provide reference for webhooks.
![](@site/static/img/68747470733a2f2f616e746d656469612e696f2f77702d636f6e74656e742f75706c6f6164732f323031382f31312f776562686f6f6b732d333030783237332e706e67.png)

### Register Your Webhook URL
Expand All @@ -23,9 +23,9 @@ Your Ant Media Server now has a default hook which is called when certain events

#### Add Custom Webhook for Streams

Ant Media Server provides creating streams through rest service. Therefore, If you want to specify the webhook URL for each stream, you can use _createBroadcast_ method in the [rest service.](https://github.com/ant-media/Ant-Media-Server/blob/master/src/main/java/io/antmedia/rest/BroadcastRestService.java)  _createBroadcast_ method has Broadcast object parameter which has _listenerHookURL_ field_._
Ant Media Server provides creating streams through rest service. Therefore, If you want to specify the webhook URL for each stream, you can use _createBroadcast_ method in the [rest service.](https://github.com/ant-media/Ant-Media-Server/blob/master/src/main/java/io/antmedia/rest/BroadcastRestService.java) _createBroadcast_ method has Broadcast object parameter which has _listenerHookURL_ field_._

As a result,  you can set _listenerHookURL_ for creating a stream at Ant Media Server.
As a result, you can set _listenerHookURL_ for creating a stream at Ant Media Server.

Here is a sample JSON for using _createBroadcast_ method with [Postman](https://www.getpostman.com/)
```
Expand Down Expand Up @@ -77,40 +77,42 @@ Ant Media Server supports webhook reliability starting from version 2.8.3. When

Ant Media Server will hook to your website using a POST request with "application/x-www-form-urlencoded" as the body. Some example responses are:

* **liveStreamStarted:** Ant Media server calls this hook when a new live stream is started. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables
* **id**:  stream id of the broadcast
* **liveStreamStarted:** Ant Media server calls this hook when a new live stream is started. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables
* **id**: stream id of the broadcast
* **action**: "liveStreamStarted"
* **streamName**: stream name of the broadcast. It can be null.
* **category**:  stream category of the broadcast. It can be null.
* **liveStreamEnded:** Ant Media Server calls this hook when a live stream is ended. It sends **POST(application/x-www-form-urlencoded)**request to URL with following variables.
* **id:** stream id of the broadcast
* **action:** "liveStreamEnded"
* **streamName:** stream name of the broadcast. It can be null.
* **category:** stream category of the broadcast. It can be null.
* **vodReady:** Ant Media Server calls this hook when the recording of the live stream is ended. It sends **POST(application/x-www-form-urlencoded)**request to URL with following variables.
* **id**: stream id of the broadcast
* **action:** "vodReady"
* **vodName:**  vod file name
* **vodId:**  vod id in the datastore
* **endpointFailed:** Ant Media server calls this hook when the RTMP endpoint broadcast went into the failed status. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables
* **id**:  stream id of the broadcast
* **category**: stream category of the broadcast. It can be null.
* **liveStreamEnded:** Ant Media Server calls this hook when a live stream is ended. It sends **POST(application/x-www-form-urlencoded)**request to URL with following variables.
* **id:** stream id of the broadcast
* **action:** "liveStreamEnded"
* **streamName:** stream name of the broadcast. It can be null.
* **category:** stream category of the broadcast. It can be null.
* **vodReady:** Ant Media Server calls this hook when the recording of the live stream is ended. It sends **POST(application/x-www-form-urlencoded)**request to URL with following variables.
* **id**: stream id of the broadcast
* **action:** "vodReady"
* **vodName:** vod file name
* **vodId:** vod id in the datastore
* **endpointFailed:** Ant Media server calls this hook when the RTMP endpoint broadcast went into the failed status. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables
* **id**: stream id of the broadcast
* **action**: "endpointFailed"
* **streamName**: stream name of the broadcast. It can be null.
* **category**:  stream category of the broadcast. It can be null.
* **metadata**:  RTMP URL of the endpoint.
* **publishTimeoutError:** Ant Media server calls this hook when there is a publish time out error, it generally means that the server is not getting any frames. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables
* **id**:  stream id of the broadcast
* **category**: stream category of the broadcast. It can be null.
* **metadata**: RTMP URL of the endpoint.
* **publishTimeoutError:** Ant Media server calls this hook when there is a publish time out error, it generally means that the server is not getting any frames. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables
* **id**: stream id of the broadcast
* **action**: "endpointFailed"
* **streamName**: stream name of the broadcast. It can be null.
* **category**:  stream category of the broadcast. It can be null.
* **encoderNotOpenedError:** Ant Media server calls this hook when the encoder can't be opened. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables
* **id**:  stream id of the broadcast
* **category**: stream category of the broadcast. It can be null.
* **encoderNotOpenedError:** Ant Media server calls this hook when the encoder can't be opened. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables
* **id**: stream id of the broadcast
* **action**: "encoderNotOpenedError"
* **streamName**: stream name of the broadcast. It can be null.
* **category**:  stream category of the broadcast. It can be null.
* **category**: stream category of the broadcast. It can be null.

That's all. As a result, you can now determine the type of the request by using the _action_ parameter within the POST request.

We hope this post will help you to make automation in your project.  Please [keep in touch](https://antmedia.io/#contact) if you have any question. We will be happy if we can help you.
We hope this post will help you to make automation in your project. Please [keep in touch](https://antmedia.io/#contact) if you have any question. We will be happy if we can help you.

> **Attention:** Please process the POST request within your application as quick as possible as the hooks are called within the event loop thread which will not wait for your application to complete complex tasks.
To secure streams using Webhook, refer to the [Webhook Authorization](https://antmedia.io/docs/category/stream-security/webhook-stream-authorization) document.
129 changes: 83 additions & 46 deletions docs/guides/stream-security/cors-filter.md
View file
Original file line number Diff line number Diff line change
@@ -1,67 +1,104 @@
---
title: CORS Filter
description: This guide explains stream security options in Ant Media Server, and how you can Enable Disable, or Accept Undefined Streams.
description: This guide explains stream security options in Ant Media Server and how you can enable, disable, or accept undefined Streams.
keywords: [Enable or Disable Undefined Streams, Accept Undefined Streams, One Time Token Control, Stream security, Ant Media Server Documentation, Ant Media Server Tutorials]
sidebar_position: 7
---

CORS(Cross-Origin Resource Sharing) Filter is enabled and accepts requests from everywhere by default.
The CORS (Cross-Origin Resource Sharing) filter is enabled and accepts requests from everywhere by default.

If you want to customize by yourself CORS Filters in Application, you can access in ```SERVER_FOLDER``` / ```webapps``` / ```{Application}``` / ```WEB-INF``` / web.xml
If you want to customize the CORS filter at the application level, you can access the ```/usr/local/antmedia/webapps/AppName/WEB-INF/web.xml``` file.

```xml
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>io.antmedia.filter.CorsHeaderFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>*</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>GET,POST,HEAD,OPTIONS,PUT,DELETE</param-value>
</init-param>
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>io.antmedia.filter.CorsHeaderFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>*</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>GET,POST,HEAD,OPTIONS,PUT,DELETE</param-value>
</init-param>

<!-- cors.allowed.origins -> * and credentials are not supported at the same time.
If you set to cors.allowed.origins to specific domains and support credentials open the below lines
<init-param>
<!-- cors.allowed.origins -> * and credentials are not supported at the same time.
If you set to cors.allowed.origins to specific domains and support credentials open the below lines
<init-param>
<param-name>cors.support.credentials</param-name>
<param-value>true</param-value>
</init-param>
-->
<init-param>
<param-name>cors.allowed.headers</param-name>
</init-param>
-->
<init-param>
<param-name>cors.allowed.headers</param-name>
<param-value>Accept, Origin, X-Requested-With, Access-Control-Request-Headers, Content-Type, Access-Control-Request-Method, Authorization</param-value>
</init-param>
<async-supported>true</async-supported>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
</init-param>
<async-supported>true</async-supported>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
```

If you want to customize by yourself CORS Filters in Root, you can access in ```SERVER_FOLDER``` / ```webapps``` / ```root``` / ```WEB-INF``` / web.xml
In case, when trying to play the stream via any other domain or integrating the player into any domain then the CORS error can be faced. In that scenario, allow the specific domain and uncomment the commented part as below.

```xml
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>io.antmedia.filter.CorsHeaderFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>*</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>GET,POST,HEAD,OPTIONS,PUT,DELETE</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>io.antmedia.filter.CorsHeaderFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>https://domain:port</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>GET,POST,HEAD,OPTIONS,PUT,DELETE</param-value>
</init-param>

<!-- cors.allowed.origins -> * and credentials are not supported at the same time.
If you set to cors.allowed.origins to specific domains and support credentials open the below lines -->
<init-param>
<param-name>cors.support.credentials</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.headers</param-name>
<param-value>Accept, Origin, X-Requested-With, Access-Control-Request-Headers, Content-Type, Access-Control-Request-Method, Authorization</param-value>
</init-param>
<async-supported>true</async-supported>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
```

If you want to customize the CORS filter in root folder then you can do that by edit `web.xml` file under `/usr/local/antmedia/webapps/root/WEB-INF`

```xml
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>io.antmedia.filter.CorsHeaderFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>*</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>GET,POST,HEAD,OPTIONS,PUT,DELETE</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.headers</param-name>
<param-value>Accept, Origin, X-Requested-With, Access-Control-Request-Headers, Content-Type, Access-Control-Request-Method, Authorization, ProxyAuthorization</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
```

:::info
Quick Learn: [Tomcat CORS Filter](https://tomcat.apache.org/tomcat-8.0-doc/api/index.html?org/apache/catalina/filters/CorsFilter.html)
To learn more about CORS filter, check out [Tomcat CORS Filter](https://tomcat.apache.org/tomcat-8.0-doc/api/index.html?org/apache/catalina/filters/CorsFilter.html)
:::
2 changes: 1 addition & 1 deletion docs/guides/stream-security/jwt-stream-security-filter.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Sending a token parameter with every publish request and play request is require

## Generate JWT Token

JWT Token can be generated in two ways. One way to generate is using the [JWT debugger](https://jwt.io/#debugger-io) and other way is to generate the token using the [JWT token Rest API](https://antmedia.io/rest/#/BroadcastRestService/getJwtTokenV2).
JWT Token can be generated in two ways. One way to generate is using the [JWT debugger](https://jwt.io/#debugger-io) and other way is to generate the token using the [JWT token Rest API](https://antmedia.io/rest/#/default/getJwtTokenV2).

- To generate the token in both ways, ```streamId```, ```expireDate```
and ```type``` parameters are required. The service returns tokenId
Expand Down
2 changes: 1 addition & 1 deletion docs/guides/stream-security/one-time-token-control.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Sending a token parameter with every publish request and play request is require

## Generate One Time Token

The token can be generated with [one-time token](https://antmedia.io/rest/#/BroadcastRestService/getTokenV2) Rest API, gets ```streamId```, ```expireDate``` and ```type``` as query parameters. The service returns tokenId and other parameters as a response.
The token can be generated with [one-time token](https://antmedia.io/rest/#/default/getTokenV2) Rest API, gets ```streamId```, ```expireDate``` and ```type``` as query parameters. The service returns tokenId and other parameters as a response.

It is important that the ```streamId``` and ```type``` parameters are properly defined because ```tokenId``` needs to match with both ```streamId``` and ```type```.

Expand Down
Loading

0 comments on commit 28437d0

Please sign in to comment.