twiliogo

README

TwilioGo

A Golang library for twilio server side SDK.

NOTE: update adds video grant support

Installation

Install the package with go:

# original
go get github.com/xaviiic/twilioGo

# updated
go get github.com/digitaldreamer/twiliogo

Import the package to your go file:

import (
    "github.com/digitaldreamer/twiliogo"
)

Usage

Access Token

Access Tokens are short-lived tokens that you can use to authenticate Twilio Client SDKs like Video and IP Messaging. You create them on your server to verify a client's identity and grant access to client API features.

To create an access token, pass the Twilio API account information first.

// first create token with twilio api configurations
token := twiliogo.NewAccessToken(accountID, keyID, secret)
// setup token identity
token.SetIdentity(identity)

Once you have created a token instance, you can add access grant with desired API features.

// grant token access to programmable conversation API
grant := twiliogo.NewConversationGrant(configurationProfileID)
token.AddGrant(grant)

// grant token access to video API
grant := twiliogo.NewVideoGrant(room)
token.AddGrant(grant)

Then transform token to JWT format for client side usages.

jwt, err := token.ToJWT()

Capability Token

Capability tokens allow you to add Twilio capabilities to web and mobile applications without exposing your AuthToken in JavaScript or any other client-side environment.

Create a capability token instance first with API account information.

capability := twiliogo.NewCapability(accountID, authToken)

Then setup the capabilities of token and output a JWT format token.

// allow incoming connections
capability.AllowClientIncoming(clientName)
// allow outgoing connections
capability.AllowClientOutgoing(appID, nil)
jwt, err := capability.ToJWT()

Chaining

Generating token steps can be chained together.

token, err := twiliogo.NewAccessToken(accountSid, apiKey, apiSecret).
    SetIdentity(identity).
    AddGrant(twiliogo.NewConversationGrant(configurationSid)).
    SetTTL(30 * time.Minute).
    ToJWT()

License

Copyright 2016 xaviiic

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

Overview

Package twilio provides server side authentication utilities for applications to integrate with Twilio service.

Access Tokens are short-lived tokens that can be used to authenticate Twilio Client SDKs like Video and IP Messaging. See detail in https://www.twilio.com/docs/api/rest/access-tokens.

Capability Tokens are a secure way of setting up your device to access various features of Twilio, allowing you to add Twilio capabilities to web and mobile applications without exposing your AuthToken in any client-side environment. See detail in https://www.twilio.com/docs/api/client/capability-tokens.

Index

• Variables
• type AccessToken
  • func NewAccessToken(accountSid, keySid, keySecret string) *AccessToken
  • func (a *AccessToken) AddGrant(grant Grant) *AccessToken
  • func (a *AccessToken) SetIdentity(identity string) *AccessToken
  • func (a *AccessToken) SetNotBefore(notBefore time.Time) *AccessToken
  • func (a *AccessToken) SetTTL(ttl time.Duration) *AccessToken
  • func (a *AccessToken) ToJWT() ([]byte, error)
  • func (a *AccessToken) ToJWTWithMethod(method crypto.SigningMethod) ([]byte, error)
• type Capability
  • func NewCapability(accountSid, authToken string) *Capability
  • func (c *Capability) AllowClientIncoming(clientName string) *Capability
  • func (c *Capability) AllowClientOutgoing(appSid string, appParams map[string]string) *Capability
  • func (c *Capability) AllowEventStream(filters string) *Capability
  • func (c *Capability) SetTTL(ttl time.Duration) *Capability
  • func (c *Capability) ToJWT() ([]byte, error)
• type Grant
  • func NewConversationGrant(sid string) Grant
  • func NewIPMessagingGrant(serviceSid, endpointID, deploymentRoleSid, pushCredentialSid string) Grant
  • func NewVideoGrant(room string) Grant

Variables

var (
	// ErrMissingAccountSid is returned if trying to sign a JWT token without
	// setup account sid information.
	ErrMissingAccountSid = errors.New("twilio accounSid not set")
	// ErrMissingAuthToken is returned if trying to sign a JWT token without setup
	// account auth token information.
	ErrMissingAuthToken = errors.New("twilio auth token not set")
	// ErrMissingKeySid is returned if trying to sign a JWT token without setup key sid.
	ErrMissingKeySid = errors.New("twilio key sid not set")
	// ErrMissingKeySecret is returned if trying to sign a JWT token without setup key secret.
	ErrMissingKeySecret = errors.New("twilio key secret not set")
	// ErrUnsupportedAlgorithm is returned if trying to format token in JWT but using
	// unsupported signing method.
	ErrUnsupportedAlgorithm = errors.New("signing method is not supported")
	// ErrEmptyIdentity is returned if trying to sign a jwt access token without
	// setup an identity.
	ErrEmptyIdentity = errors.New("generate access token for empty identity")
)

Types

type AccessToken

type AccessToken struct {
	// contains filtered or unexported fields
}

AccessToken is a builder struct to setup and generate JSON Web Token for accessing twilio services.

func NewAccessToken

func NewAccessToken(accountSid, keySid, keySecret string) *AccessToken

NewAccessToken creates a default access token instance. The account information must not be empty otherwise an error is emitted while formatting to JWT.

func (*AccessToken) AddGrant

func (a *AccessToken) AddGrant(grant Grant) *AccessToken

AddGrant adds a permission grant to this access token. Optional.

func (*AccessToken) SetIdentity

func (a *AccessToken) SetIdentity(identity string) *AccessToken

SetIdentity sets the identity of this access token. This field must be set before generating a JWT.

func (*AccessToken) SetNotBefore

func (a *AccessToken) SetNotBefore(notBefore time.Time) *AccessToken

SetNotBefore sets the time before which the token is not accepted for processing.

func (*AccessToken) SetTTL

func (a *AccessToken) SetTTL(ttl time.Duration) *AccessToken

SetTTL sets the time to live of this access token. By default, the expiration time is one hour after token is signed as JWT.

func (*AccessToken) ToJWT

func (a *AccessToken) ToJWT() ([]byte, error)

ToJWT transforms token into JWT format to access twilio services. The token is signed with HS256 algorithm.

func (*AccessToken) ToJWTWithMethod

func (a *AccessToken) ToJWTWithMethod(method crypto.SigningMethod) ([]byte, error)

ToJWTWithMethod transforms token into JWT format and signed by a specified method.

type Capability

type Capability struct {
	// contains filtered or unexported fields
}

Capability is a builder struct to setup and generate Capability Token for twilio client communication.

func NewCapability

func NewCapability(accountSid, authToken string) *Capability

NewCapability creates a default capability token instance. The account information must not be empty otherwise an error is emitted while formatting to JWT.

func (*Capability) AllowClientIncoming

func (c *Capability) AllowClientIncoming(clientName string) *Capability

AllowClientIncoming adds the permissions to allow incoming connections to a specified twilio client name.

func (*Capability) AllowClientOutgoing

func (c *Capability) AllowClientOutgoing(appSid string, appParams map[string]string) *Capability

AllowClientOutgoing adds permissions to allow twilio client making outgoing connections.

func (*Capability) AllowEventStream

func (c *Capability) AllowEventStream(filters string) *Capability

AllowEventStream add permissions to allow twilio client subscribing to event streams.

func (*Capability) SetTTL

func (c *Capability) SetTTL(ttl time.Duration) *Capability

SetTTL sets the time to live of this capability token. By default, the expiration time is one hour after token is signed as JWT.

func (*Capability) ToJWT

func (c *Capability) ToJWT() ([]byte, error)

ToJWT transforms token into JWT format for twilio client usage.

type Grant

type Grant interface {
	// Key is the identifier of a permission.
	Key() string
	// Payload defines how permission data is marshaled in an access token.
	Payload() interface{}
}

Grant defines interface of twilio permission model. Any structures implement this interface can be bundled into a twilio access token.

func NewConversationGrant

func NewConversationGrant(sid string) Grant

NewConversationGrant creates a new permission grant for twilio conversation service.

func NewIPMessagingGrant

func NewIPMessagingGrant(serviceSid, endpointID, deploymentRoleSid, pushCredentialSid string) Grant

NewIPMessagingGrant creates a new permission for twilio ip messaging service.

func NewVideoGrant

func NewVideoGrant(room string) Grant

NewVideoGrant creates a new video grant for twilio video conversation service.