Page Content
Using EdgeAuth
Once you have integrated the Phenix EdgeAuth library into your backend, generate tokens as described below.
Terms
-
Phenix Customer - Someone wanting to use the Phenix infrastructure for streaming
-
Customer token service - Code written and hosted by the Phenix customer
-
User - An end user wanting to publish or view a stream
-
Phenix Platform - Infrastructure delivering the content stream
-
Token - Cryptographically signed text
-
Other terms as described in the Phenix glossary of terms
Token Types
There are four types of tokens for publishing and streaming:
| Token Type | Permits | Include in Call to Create |
|---|---|---|
| edgeToken | Creation of a session and consumption of streams | default / none |
| publishToken | Creation of a stream | forPublishingOnly() |
| streamToken | Consumption of a stream | forStreamingOnly() |
| authToken | Creation of a session | forAuthenticationOnly() |
An edgeToken is both an authToken and a streamToken. In the Phenix Customer Portal, this type of token is shown as a Viewing token.
edgeToken
The edgeToken is the default token type when no token type is specified.
All that is needed for playback or publishing is a token from the EdgeAuth library, and all that is needed to generate that token is the Application ID and Secret, as well as information about Channels or Rooms. Phenix recommends using short-lived tokens to limit token sharing. You do not need any user information unless you (optionally) want to restrict the token based on user information, e.g., to a particular IP address. See below for details about restricting tokens.
Token Designation
When creating tokens, you need to designate a Channel or a Room (by ID or by Alias). If a Channel or Room is not designated, use of the token will result in Authentication failure as Unauthorized.
In other words, a token generated with an Application ID and secret, but no further restrictions other than expiration time, does not cause an error in the library. This token would allow authentication, but does NOT allow streaming for any channel. A token with no Channel ID, Room ID, Channel Alias, or Room Alias designated will fail to stream. Stream tokens for subscribing cannot be used for both streaming and authorization without any configurations/constraints set.
Call Flow Diagram
An example call flow for an authorization using an edgeToken (which combines both authToken and streamToken) to join a Room or a Channel is shown below.
See the discussion below for details on using the AuthToken when initializing the SDK.
Token Constraints
The design of tokens depends on business logic needs. Token creators can decide how narrow a token's scope is.
Constraints are set when the token is created by the EdgeAuth TokenBuilder library.
Note that the applicationId for the publishing and subscribing tokens must match. For example, if publishing is using an applicationId of mycompany.com, the applicationId used when creating tokens for subscribing must also be mycompany.com.
User and Stream Constraints
Tokens can optionally be restricted by any combination of the following:
-
User Information
-
User IP (remoteAddress)
-
User Session ID (sessionId) (deprecated)
-
-
Publishing/Subscribing Stream Information
-
Origin Stream (originStreamId) - Provide this to create a "view" token; otherwise, a publish token is generated.
-
Channel ID (channelId)
-
Channel Alias (channelAlias)
-
Room ID (roomId)
-
Room Alias (roomAlias)
-
For example, if tokens are specific to a ChannelAlias, and there are multiple Channel Aliases to which a user needs access, the customer's token service needs to provide a separate token for each ChannelAlias.
To allow a publisher to only provide content for a room or channel, create a Publish token that contains the Room ID or Channel ID. If a user can provide content to multiple channels or rooms, multiple Publish tokens must be created.
When you create EdgeAuth access tokens you can associate tags with each of them. This information can be used, for example, to map users to your internal accounting system or to generate billing reports for your customers. These tags will be available for filtering and as an output column in usage reports.
Location Constraints
Tokens can be constrained to either allow or deny authentication based on a user's location.
| Value | Description |
|---|---|
| geo-country-allow=... | Comma separated list of allowed countries in ISO 3166. Example: geo-country-allow=US,UK,DE |
| geo-country-deny=... | Comma separated list of denied countries in ISO 3166. Example: geo-country-deny=US,IN,?? |
| geo-postal-code-allow=... | Comma-separated list of allowed postal codes formatted as strings (i.e., NNNN,NNNNN). Example: geo-postal-code-allow=60609,60616 |
| geo-postal-code-deny=... | Comma-separated list of denied postal codes formatted as strings (i.e., NNNN,NNNNN). Example: geo-postal-code-deny=01748,01721 |
Unmapped IPs
Even the best geo IP databases will not be able to map all
IPs to a country. The special code ?? serves as the country code for any IP
that is not mapped and can be used to identify unmapped IPs.
Postal codes are not universally standardized; be sure to test in order to ensure efficacy.
Token Expiration
Each token must have an expiration time after which it is no longer valid or a duration in seconds during which the token is valid. While the token is valid a user may subscribe to the stream, but after the token has expired the subscription request will fail. Likewise, a user may publish a stream while a publishing token is valid, but cannot begin publishing when the token is no longer valid.
Once subscribed to a stream the user may watch the stream until the stream stops or is terminated, even past the point of token expiration.
Tokens are evaluated when presented to the platform, such as when the SDK attempts to authenticate initially, or following an extended network interruption. If the token has expired, the session will not be authenticated and the application will need to obtain another token.
Subscribing and Publishing
WebSDK
Token usage differs between WebSDK 2.0 and WebSDK 1.0.
WebSDK 2.0
No auth tokens are needed when using WebSDK 2.0. For either subscribing or publishing, only a viewing (edgeToken) or publish token is needed.
WebSDK 1.0
When using WebSDK 1.0, auth tokens are needed to initialize the SDK, along with the viewing and publishing tokens.
Mobile (Android and iOS)
Current mobile platforms require auth tokens to initialize the SDK, along with the viewing and publishing tokens.
Android Platform
iOS Platform
v2023-12-04T20:36:01.000Z