{"id":22165514,"url":"https://github.com/ezrarieben/coturn-credential-api","last_synced_at":"2025-03-24T16:14:07.374Z","repository":{"id":221294082,"uuid":"753343460","full_name":"ezrarieben/coturn-credential-api","owner":"ezrarieben","description":"A ready to deploy REST API written in plain PHP to generate credentials for CoTURN TURN/STUN server.","archived":false,"fork":false,"pushed_at":"2024-02-07T05:25:49.000Z","size":7,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T14:59:36.605Z","etag":null,"topics":["api-rest","coturn","coturn-docker","credential-generator","credentials","php","stun-server","turn","turn-server"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ezrarieben.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}},"created_at":"2024-02-05T23:39:05.000Z","updated_at":"2024-02-07T05:28:41.000Z","dependencies_parsed_at":"2024-02-07T07:31:21.973Z","dependency_job_id":"4950ad38-7a0f-46e5-950a-405b4e2f33ea","html_url":"https://github.com/ezrarieben/coturn-credential-api","commit_stats":null,"previous_names":["ezrarieben/coturn-credential-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezrarieben%2Fcoturn-credential-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezrarieben%2Fcoturn-credential-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezrarieben%2Fcoturn-credential-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezrarieben%2Fcoturn-credential-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ezrarieben","download_url":"https://codeload.github.com/ezrarieben/coturn-credential-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245304873,"owners_count":20593626,"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":["api-rest","coturn","coturn-docker","credential-generator","credentials","php","stun-server","turn","turn-server"],"created_at":"2024-12-02T05:15:08.287Z","updated_at":"2025-03-24T16:14:07.349Z","avatar_url":"https://github.com/ezrarieben.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# coturn-credential-api\n\nA ready to deploy REST API written in plain PHP to generate credentials for [CoTURN](https://github.com/coturn/coturn) TURN/STUN server.\u003cbr /\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n# Table of contents\n\n- [coturn-credential-api](#coturn-credential-api)\n- [Table of contents](#table-of-contents)\n- [Use case](#use-case)\n- [Basic information](#basic-information)\n- [Setup](#setup)\n  - [Configure CoTURN to accept REST API authentication](#configure-coturn-to-accept-rest-api-authentication)\n  - [Basic installation of coturn-credential-api](#basic-installation-of-coturn-credential-api)\n- [Usage](#usage)\n  - [Requesting credentials](#requesting-credentials)\n      - [JavaScript example](#javascript-example)\n  - [API response](#api-response)\n      - [Attributes](#attributes)\n      - [Credential data attributes](#credential-data-attributes)\n      - [Example response](#example-response)\n  - [API errors](#api-errors)\n      - [Example error](#example-error)\n\n# Use case\n\nBecause TURN traffic can be bandwith intensive it is common practice to secure your TURN server with credentials. The problem being, most cases in which a TURN server is implemented are client side, meaning the credentials are exposed. To limit risk of exposure the most common workaround is to implement a REST API that generates a time sensitive username and password. (More details can be found in [Justin Uberti's Internet-Draft](https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00)).\n\nThis API is inspired by [Justin Uberti's Internet-Draft](https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00) and aims to provide a quick and easy solution to generate time sensitive credentials in a format understood by [CoTURN](https://github.com/coturn/coturn).\n\n# Basic information\n\nThe API implements key based authentication to make sure only authorized requests can generate credentials.\n\nYou may want to implement some sort of rate limiting to stop abuse.\n\n# Setup\n\n## Configure CoTURN to accept REST API authentication\n\nBy default [CoTURN](https://github.com/coturn/coturn) uses the 'classic' long-term credentials mechanism.\nTo enable REST API authentication you will need to add the `use-auth-secret` flag to your `/etc/turnserver.conf` config.\n\nThis API uses a static secret to hash the time sensitive password. THe secret will need to be defined in your config using the `static-auth-secret` variable.\n\nExcerpt from `/etc/turnserver.conf`:\n\n```\nuse-auth-secret\nstatic-auth-secret=__SECRET__\n```\n\n## Basic installation of coturn-credential-api\n\nYou will need to have a web server such as NGINX configured and running with PHP in advance.\n\n1. Clone this repo or download it as a zip file [here](https://github.com/ezrarieben/coturn-credential-api/archive/main.zip).\n2. Move all files and folders in the `public` folder to your web root and make sure permissions are set correctly.\n3. Edit `config.inc.php` and set your auth secret to the same secret [configured in CoTURN's server config](#configure-coturn-to-accept-rest-api-authentication).\n\n```php\ndefine('TURN_AUTH_SECRET', \"__SECRET__\");\n```\n\n1. Set API keys in `config.inc.php`.\n    \u003e **NOTE:** The keys below are just for illustrative purposes. You will want to generate your own, possibly using a [random generator](https://www.random.org/strings/).\n\n```php\ndefine('ALLOWED_API_KEYS', array(\n    'BMaV8tJgrHxDUMHZe4813h2K7QK7IAPg',\n    'CQNr3EPDOjnn6JKfkFuaPl3sPy5zpbh0',\n    'imDVt70geDpwbl1r1egpx8IShRg64DO3'\n));\n```\n\n# Usage\n\n## Requesting credentials\n\nCredentials can be generated/requested via GET or POST. Make sure to pass the following variables as POST or GET parameters:\n\n| Name       | Description                                                                                                          | Required |\n| ---------- | -------------------------------------------------------------------------------------------------------------------- | -------- |\n| `username` | Username used to generate credentials                                                                                | **YES**  |\n| `key`      | A valid API key defined during [installation of coturn-credential-api](#basic-installation-of-coturn-credential-api) | **YES**  |\n\n\n#### JavaScript example\n\n```javascript\nconst params = {\n    username: \"testuser\",\n    key: \"BMaV8tJgrHxDUMHZe4813h2K7QK7IAPg\",\n};\n\nconst options = {\n    method: \"POST\",\n    body: new URLSearchParams(params),\n};\n\nfetch(\"https://example.com/\", options)\n    .then((response) =\u003e response.json())\n    .then((data) =\u003e {\n        console.log(data);\n    });\n```\n\n## API response\n\nThe API response is formatted in JSON and contains the following attributes by default:\n\n#### Attributes\n\n| Name      | Description                                                                    | Type                                      |\n| --------- | ------------------------------------------------------------------------------ | ----------------------------------------- |\n| `success` | Boolean value to signify if generating of credentials was successfull          | Boolean                                   |\n| `message` | Message describing either the error that occurred or the credentials generated | String                                    |\n| `data`    | The credential data                                                            | [JSONObject](#credential-data-attributes) |\n\n#### Credential data attributes\n\n| Name       | Description                                                                                                       | Type    |\n| ---------- | ----------------------------------------------------------------------------------------------------------------- | ------- |\n| `username` | Generated username according to TTL defenition in config and username param, in the format that CoTURN expects it | String  |\n| `password` | Base64 encoded password hash as CoTURN expects it.                                                                | String  |\n| `ttl`      | Time to live of the credentials.                                                                                  | Integer |\n\n#### Example response\n\n```json\n{\n    \"success\": true,\n    \"message\": \"Credentials are valid until: 2024-02-06 03:30:00 (UTC)\",\n    \"data\": {\n        \"username\": \"1707233400:testuser\",\n        \"password\": \"+gJJaa/6oHM3DOURkrLYrkPeH9g=\",\n        \"ttl\": 1707233400\n    }\n}\n```\n\n## API errors\n\nIf an error occurrs during credential generation the [`success` attribute](#attributes) in the API response will be set to `false`.\n\u003cbr/\u003eThe error that occurred is described in the [`message` attribute](#attributes).\n\n#### Example error\n\n```json\n{\n    \"success\": false,\n    \"message\": \"API key provided is invalid.\",\n    \"data\": []\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fezrarieben%2Fcoturn-credential-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fezrarieben%2Fcoturn-credential-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fezrarieben%2Fcoturn-credential-api/lists"}