{"id":26802409,"url":"https://github.com/red5pro/red5pro-simple-auth-plugin","last_synced_at":"2025-04-23T02:37:00.914Z","repository":{"id":37587019,"uuid":"161350361","full_name":"red5pro/red5pro-simple-auth-plugin","owner":"red5pro","description":"SimpleAuth Plugin","archived":false,"fork":false,"pushed_at":"2025-01-03T19:18:00.000Z","size":340,"stargazers_count":3,"open_issues_count":6,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T21:17:55.462Z","etag":null,"topics":["authentication","red5pro"],"latest_commit_sha":null,"homepage":"https://www.red5pro.com/docs/server/authplugin.html","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/red5pro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-11T14:58:42.000Z","updated_at":"2024-08-22T07:49:55.000Z","dependencies_parsed_at":"2024-05-02T18:35:05.464Z","dependency_job_id":"1e5284d7-dfc3-49d3-915c-11469f686d2d","html_url":"https://github.com/red5pro/red5pro-simple-auth-plugin","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/red5pro%2Fred5pro-simple-auth-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/red5pro%2Fred5pro-simple-auth-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/red5pro%2Fred5pro-simple-auth-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/red5pro%2Fred5pro-simple-auth-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/red5pro","download_url":"https://codeload.github.com/red5pro/red5pro-simple-auth-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250359029,"owners_count":21417590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","red5pro"],"created_at":"2025-03-29T21:17:59.783Z","updated_at":"2025-04-23T02:37:00.895Z","avatar_url":"https://github.com/red5pro.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SimpleAuth Plugin\n\n* [ABOUT](#about)\n* [PLUGIN CONFIGURATIONS](#plugin-configurations)\n  * [DEFAULT CONFIGURATION](#default-configuration)\n    * [PLUGIN CONFIGURATION PROPERTIES](#plugin-configuration-properties)\n  * [NOTE ON RTMP AGENTS](#note-on-rtmp-agents)\n* [VALIDATORS](#validators)\n  * [FILE AUTHENTICATION VALIDATOR](#the-red5-pro-file-authentication-validator)\n  * [ROUNDTRIP AUTHENTICATION VALIDATOR](#the-red5-pro-roundtrip-authentication-validator)\n* [SPECIAL NOTE (FOR APPLICATION DEVELOPERS)](#special-note-for-application-developers)\n* [ADVANCE - EXTENDING THE PLUGIN](#advance---extending-the-plugin)\n* [CLUSTER SUPPORT](#cluster-support)\n* [ECLIPSE](#eclipse)\n* [BUILD / COMPILE](#build-compile)\n\n---\n\n## ABOUT\nred5pro-simple-auth-plugin is a simple authentication plugin for red5pro which enables you to add simple `connection level authentication` for RTMP, RTSP and WebRTC clients.\n\nPlugin can be configured to attach security to a webapp on-demand by adding a security configuration to the context file (red5-web.xml) of the webapp or by allowing to automatically apply security to each web application deployed on the server.\n\nThe default security configuration of the plugin authenticates connection parameters against a simple .properties file which contains username-password as property-value records. When the plugin is configured to apply security automatically to each webapp, it uses the `simple-auth-plugin.credentials` file located at RED5_HOME/conf directory. Custom security configuration at application level allows you to override this for each application.\n\nThe plugin allows you to enable/disable security for different connection types (RTMP / RTSP / RTC) individually.\n\n---\n\n## PLUGIN CONFIGURATIONS\nThe plugin can be configured via its configuration file  - __RED5_HOME/conf/simple-auth-plugin.properties__.\n\n---\n\n### DEFAULT CONFIGURATION\nThe default plugin configuration should look as shown below:\n\n```\n# Simple-auth Plugin Properties\n\n# Default state of server wide security\nsimpleauth.default.active=false\n\n# Default data source filename [ Default authentication validator is file based ]\nsimpleauth.default.defaultAuthValidatorDataSource=simple-auth-plugin.credentials\n\n# Default state of rtmp security offered by the plugin\nsimpleauth.default.rtmp=true\n\n# Default state of rtsp security offered by the plugin\nsimpleauth.default.rtsp=true\n\n# Default state of rtc security offered by the plugin\nsimpleauth.default.rtc=true\n\n# Global state of rtmp security allowing authentication via query parameters\nsimpleauth.default.rtmp.queryparams=true\n\n# Allowed rtmp agents\nsimpleauth.default.rtmp.agents=*\n```\n\n---\n\n#### PLUGIN CONFIGURATION PROPERTIES\n| Property  |  Type  | Description  | Default value  |   |\n|---|---|---|---|---|\n| simpleauth.default.active  | Boolean  | Defines whether the plugin applies security to all applications by default or not.  | false  |   |\n| simpleauth.default.defaultAuthValidatorDataSource  | String  | Defines the name of the default properties file (in RED5-HOME/conf) used for authentication  |  simple-auth-plugin.credentials |   |\n| simpleauth.default.rtmp  | Boolean  | Defines the state of rtmp security when security is applies to all applications by default  | true  |   |\n| simpleauth.default.rtsp  | Boolean  | Defines the state of rtsp security when security is applies to all applications by default  | true  |   |\n| simpleauth.default.rtc  | Boolean  | Defines the state of rtc security when security is applies to all applications by default  | true  |   |\n| simpleauth.default.rtmp.queryparams  | Boolean  | Defines whether rtmp authentication parameters can be provided in query string or not  |  true |   |\n simpleauth.default.rtmp.agents  | String  | Describes the list of rtmp client types (agents) allowed to connect. This value is extracted from the rtmp client's handshake.By default all client types are allowed. It can be used to block certain types fo rtmp clients from connecting. The list can be a semicolon separated list of agent streings or * | *  |   |\n\n---\n\n### NOTE ON RTMP AGENTS\n\nRTMP agent string is obtained by red5 during handshake with the rtmp client. Each specific type of rtmp client provides a agent string to identify its type. This parameter is popularly addressed as the __flashVer__ string in the RTMP handshake. There are various types of RTMP clients such as flash player for windows / mac / linux, Adobe flash media live encoder (FMLE), WireCast encoder etc: Each client type can be identified by the value it provided in the __flashVer__ string. For more information checkout __[wikipedia](https://en.wikipedia.org/wiki/Real-Time_Messaging_Protocol#Connect)__\n\nThe auth module is designed to look for client's __flashVer__ in the list of permissible agent string specified. * : implies that all agent types are allowed. The check does not look for exact match, but rather whether the __flashVer__ is contained in any one of our agent strings.\n\n---\n\n## VALIDATORS\nValidators are the core classes responsible for carrying out the authentication. While the simple auth plugin core takes care of accepting connection parameters, decoding them and checking for the basic security compliance such as mandatory params, client type etc, the validator component implements the actual authentication. Only the validator component knows the `data source` that it has to validate the credentials \u0026 other params against. The simple auth core has no knowledge of that.\n\nBy default the simple auth plugin is designed to provide a two sample validators out of the box - `Red5ProFileAuthenticationValidator` \u0026 `RoundTripAuthValidator`.Other than these default implementations, you can also write your own custom validators for your particular use case that can validate client parameters against your own data source. To know more about implemnting custom validators, check out the  - **[Extending the plugin](#advance---extending-the-plugin)** section.\n\nIn the sections below we will be taking a look at the sample validator implementations provided with the `simple auth plugin` out of the box. You can select which validator is best for your use case by reading through their descriptions.\n\n### The Red5 Pro File Authentication Validator\n![Red5ProFileAuthenticationValidator Flow](/assets/red5profileauthvalidator.png?raw=true \"File Authentication Validator Flow\")\n\nThe Red5Pro File Authentication Validator implemented by the class `Red5ProFileAuthenticationValidator`, is a simple filesystem validator. The class seeks its data source as a simple `.properties` file on the server's filesystem. The properties file is expected to contain `username-password` as `property-value` combinations.\n\nThe validator expects the default location of the file to be `{RED5_HOME}/conf/simple-auth-plugin.credentials`. However a different file can also be specified using the validator's configuration options as long as the format is same.\n\n__NOTE:__ The `Red5ProFileAuthenticationValidator` component only implements `connection` level security and it does not distinguish between `subscribers` \u0026 `publishers`.\n\nFor detailed information on how to setup the `Red5 Pro File Authentication Validator` check out the [validator's documentation](red5profileauthvalidator.md).\n\n### The Red5 Pro RoundTrip Authentication Validator\n![RoundTripAuthValidator Flow](/assets/red5proroundtripauthvalidator.png?raw=true \"RoundTrip Authentication Validator Flow\")\n\nThe Red5Pro RoundTrip Authentication Validator implemented by the class `RoundTripAuthValidator`, is a remote server  validator. The class seeks its data source on a remote endpoint which accepts parameters from `RoundTripAuthValidator`, carries out the authentication using the intended business logic implemented and finally returns `json` response back to the validator.\n\n__NOTE:__ The `RoundTripAuthValidator` component implements `stream` level security as it allows explicit authentication for permissions regarding `publish` \u0026 `subscribe` actions.\n\nFor detailed information on how to setup the `Red5 Pro File Authentication Validator` check out the [validator's documentation](red5proroundtripauthvalidator.md).\n\n## SPECIAL NOTE (FOR APPLICATION DEVELOPERS)\nTo get this plugin to work properly with your application it is important to follow the application lifecycle. The plugin intercepts the invocation of the method - `public boolean appConnect(IConnection conn, Object[] params)`. Hence it is important that your application's main class `MultithreadedApplicationAdapter` calls the super method properly.\n\nYour application class must make a call to the super method as shown in the snippet.\n\n```java\n@Override\npublic boolean appConnect(IConnection conn, Object[] params) {\n    // your custom logic here\n    return super.appConnect(conn, params);\n}\n```\n\n\u003e Returning a `true` or `false` directly will make your application get out of the plugin's call chain.\n\n---\n\n## ADVANCE - EXTENDING THE PLUGIN\n\n### STEP 1\n\n__Create Your Own Custom Validator__\n\nIf you with to get more out of this plugin such as authenticating against different source etc, you can implement your own validator class by implementing the `IAuthenticationValidator` interface.\n\n__Example :__\n\n```java\npublic class CustomSourceValidator implements IAuthenticationValidator {\n\n    private static Logger logger = Red5LoggerFactory.getLogger(CustomSourceValidator.class, \"CustomSourceValidator\");\n\n    private Object dataSource;\n\n    public CustomSourceValidator() {\n    }\n\n    public CustomSourceValidator(Object dataSource) {\n       this.dataSource = dataSource;\n    }\n\n    @Override\n    public void initialize() {\n       // load / initialize your data source object here\n    }\n\n    @Override\n    public boolean onConnectAuthenticate(String username, String password, Object[] rest) {\n      try {\n          // authenticate here and return a true if authentication is successful, else return false\n      } catch(Exception e) {\n          logger.error(\"Error validating credentials : \" + e.getMessage());\n          return false;\n      }\n    }\n\n    public Object getDataSource() {\n       return dataSource;\n    }\n\n    public void setDataSource(Object dataSource) {\n       this.dataSource = dataSource;\n    }\n}\n```\n\n\u003e NOTE:\n\nThe last parameter of the method `onConnectAuthenticate`will contain connection parameters if a RTMP client passed parameters as array , otherwise the first object of the array will contain a java Map, if the RTMP client pass parameters in query string. For RTSP and RTC clients also the first object of the array will contain a java Map. You will need to iterate over the map to get the parameters and their values as key-value pairs.\n\n### STEP 2\nBefore you can configure the webapp to use your custom validator, it must be deployed on the server. Package your validator classes as a `jar` and deploy the `jar` in either the webapp's lib directory (`RED5_HOME/webapps/{app}/WEB-INF/lib`), or in the server's lib directory (`RED5_HOME/lib`).\n\n### STEP 3\nInstantiate your custom validator using spring in `red5-web.xml` and pass it as a reference to the `simpleAuthSecurity` configuration bean.\n\n```xml\n\u003cbean id=\"authDataValidator\" class=\"com.example.CustomSourceValidator\" init-method=\"initialize\"\u003e\n    \u003cproperty name=\"dataSource\" ref=\"{data-source-object}\" /\u003e\n\u003c/bean\u003e\n\n\u003cbean id=\"simpleAuthSecurity\" class=\"com.red5pro.server.plugin.simpleauth.Configuration\" \u003e\n    \u003cproperty name=\"active\" value=\"true\" /\u003e\n    \u003cproperty name=\"rtmp\" value=\"true\" /\u003e\n    \u003cproperty name=\"rtsp\" value=\"true\" /\u003e\n    \u003cproperty name=\"rtc\" value=\"true\" /\u003e\n    \u003cproperty name=\"rtmpAllowQueryParamsEnabled\" value=\"true\" /\u003e\n    \u003cproperty name=\"allowedRtmpAgents\" value=\"*\" /\u003e\n    \u003cproperty name=\"validator\" ref=\"authDataValidator\" /\u003e\n\u003c/bean\u003e\n```\nThe plugin will now use your custom validator to validate the authentication info.\n\nFor developer convenience, a [`custom-validator-development-kit` has been included with this repository](#red5-pro-simpleauth-custom-validator-kit). The kit is primarily a `maven` project with a basic custom validator class setup. you can utilize the template to build your own custom validator, package it as a `jar` and deploy it along side the simple-auth plugin on the server, with your custom validator configuration in yourt targeted webapp.\n\n---\n\n## CLUSTER SUPPORT\nThis authentication plugin can also be used with [Red5 pro clusters](https://www.red5pro.com/docs/server/clusters.html) built manually or using [streammanager](https://www.red5pro.com/docs/autoscale/).\n\nClustering involves a group of interconnected nodes (origins and edges). A publisher stream is streamed from an origin to one or more edges by the Red5 pro `restreamer`. In the context of a Red5 pro ecosystem ,the restreamer itself is a connection. Hence when the simple auth plugin is turned on, the authentication restriction applies to the `restreamer` as well.\n\nThe `restreamer` consists of two types of connections (IConnection objects). First one is used to `pull` the stream from the source and the second one to publish the stream on edge. The first connection appears as an instance of `org.red5.server.net.rtmp.RTMPMinaConnection`, where as the second one is of type `com.red5pro.server.stream.restreamer.IConnectorShell`.\n\nThe `red5pro-simple-auth-plugin` checks the connection class name for each `IConnection` object during authentication and allows the `com.red5pro.server.stream.restreamer.IConnectorShell` connection to passthrough unconditionally. However the `RTMPMinaConnection` restreamer connection, needs to be authenticated explicitly.\n\nThe `RTMPMinaConnection` restreamer connection carries `cluster-restreamer-context`,  `cluster-restreamer-name` and `restreamer` connection parameters. The param `restreamer` has a value set to the cluster password. The simple auth plugin analyses and translates there connection parameters to authenticable parameters authenticates the `IConnection` against a specific data source.\n\nTo authenticate a `restreamer` connection at origin server, make sure to add the folowing credentials to your authentication datasource.\n\n```\nusername : cluster-restreamer\npassword: \u003ccluster-password\u003e\n```\n\nWhen extending the `red5pro-simple-auth-plugin` busing a `IAuthenticationValidator` or implementing your own custom plugin that needs to work on a Red5 Pro cluster, make sure to check for the `IConnection` type. You can use the following sample snippet to check for a connection types.\n\n```java\nIConnection connection = Red5.getConnectionLocal();\nif (connection instanceof RTMPMinaConnection || connection instanceof RTMPTConnection) {\n    // rtmp client - [ dont forget to check connection params ]\n} else if (connection instanceof IRTSPConnection) {\n    // rtsp client\n} else if (connection instanceof IWebRTCConnection) {\n    // WebRTC client\n} else if (connection instanceof IConnectorShell) {\n    // pass through\n} else {\n    // unknown protocol\n}\n```\n\n---\n\n## ECLIPSE\n* To create the Eclipse IDE files, run this from the project (app or plugin) directory: `mvn eclipse:eclipse`\n\n* The project can be imported into eclipse IDE using :\n__File -\u003e import -\u003e Existing Maven Projects -\u003e {red5pro-simple-auth-plugin root folder}__\n\n---\n\n## BUILD / COMPILE\nYou may compile and build the plugin jar using the following maven command: `mvn`. To deploy `mvn clean deploy -P release` (IR5 Use only).\n\n## PLUGINS SERVER BUILD\nModify `https://github.com/infrared5/red5pro-plugins/blob/master/remote-plugins.json` to build with a different branch for this repository (IR5 Use only).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fred5pro%2Fred5pro-simple-auth-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fred5pro%2Fred5pro-simple-auth-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fred5pro%2Fred5pro-simple-auth-plugin/lists"}