2 Setting Up Security

This chapter describes how to set up security for the applications you develop using the Oracle Communications WebRTC Session Controller JavaScript application programming interface (API) library. For information about configuring security on the web server, see WebRTC Session Controller Security Guide.

Handling Login to WebRTC Session Controller

By default, the WebRTC Session Controller JavaScript API library supports the following authentication methods for your web applications:

Basic authentication. See "Login Using Basic Authentication".
OAuth authentication. See "Login Using OAuth Authentication".
Form-based authentication. See "Login Using Form-Based Authentication".
REST-based authentication. See "Login Using REST Authentication".

Please refer to your server-side configuration documentation to configure authentication-based login and logout on the web server side.

Login Using Basic Authentication

Basic authentication implements access controls using static, standard HTTP headers. This is one of the default authentication methods supported by WebRTC Session Controller Signaling Engine. For more information on Basic authentication, see the Internet Engineering Task Force website at http://tools.ietf.org/html/rfc2617.

When a user attempts to access your application, your application can initiate a login request by sending an HTTPS request to the following uniform resource locator (URL):

https://wsc-host:wsc-port/login

Where:

wsc-host is the host name where WebRTC Session Controller is running.
wsc-port is the listening port for WebRTC Session Controller.

When such a request is made to the URL:

The web browser displays a basic authentication dialog window.
The user enters his credentials.
One of the following occurs:
- If the credentials are valid, the user is authenticated.
- If the credentials are not valid, an error response is displayed.

Redirecting After a Successful Login

You can add the following two optional request parameters to the login URL you define in your application to redirect the user after a successful login:

redirect_uri: Specify the uniform resource identifier (URI) of the page the browser should be redirected to after a successful login.
wsc_app_uri: Specify the URI of the WebRTC Session Controller application configured in WebRTC Session Controller which will be invoked by this client after logging in, such as /ws/webrtc/sample. The WebRTC Session Controller configuration contains a set of domain names valid for the application. This data is used to validate the domain name in the redirect_uri.

The following is an example of an HTTPS login request that redirects the user to a new web page:

https://wsc-host:wsc-port/login?redirect_uri=https://name_of_theDomain.com/index.html&wsc_app_uri=/ws/webrtc/sample

When you redirect users, WebRTC Session Controller Signaling Engine checks to see if the domain name for redirect_uri is set to one of the configured domains for the WebRTC Session Controller application that will be invoked following successful authentication. Your WebRTC Session Controller administrator will have the information you need to access the application.

See Oracle Communications WebRTC Session Controller Extension Developer's Guide for more information.

Login Using OAuth Authentication

OAuth is an open standard for authentication. OAuth 2.0 is one of the default authentication methods supported by WebRTC Session Controller Signaling Engine.

End users attempting to access your application are redirected to supported third-party websites for authentication. Facebook OAuth token authentication is one example. For information on OAuth authentication, see the OAuth website at http://oauth.net/.

You can set up your web applications to employ the end user's OAuth identity by using the OAuth login mechanism. In this scenario, your web applications can use the user's external OAuth identity, such as Facebook or Google identity, to enable the user to log in to WebRTC Session Controller Signaling Engine. Configure OAuth authentication based on the requirements of the selected OAuth security provider.

Understanding OAuth 2.0 Concepts

OAuth is an open standard for authorization that allows subscribers to share their private resources with a third party without having to provide their own security credentials. These resources could be photos, videos, contact lists, location and billing capability, and so on, and are usually stored with another service provider. For example, photos stored on a dedicated photo Web storage site.

OAuth does this by granting requesting (client) applications a token, once access is approved by the resource owner. Each token grants access to a specific resource for a specific period. The requesting application uses the token for access to resources stored with another service provider, instead of the owner's credentials.

A resource can be:

A single file such as a photo or video.
Access to a website, such as the services of a video editing website.
Personal information such as their location or billing capability.

Application can use these Security Assertion Markup Language (SAML) access tokens for single sign-on (SSO) authentication or to provide enhanced security profiles required for using derived values such as signatures or hash-method authentication codes (HMACs), or for client-server integration scenarios where the subscriber may not be present.

Understanding OAuth Terminology

Table 2-1 lists OAuth terminology and definitions.

Table 2-1 OAuth Terminology and Definitions

Term	Definition
Application Client	An application making protected resource requests on behalf of the resource owner and with the resource owner's authorization. The term client does not imply any particular implementation characteristics (for example, whether the application executes on a server, a desktop, or other devices).
Application Instance ID	String that uniquely identifies the Application Instance. One applicationInstanceId can be mapped with one OAuth2 Client Identifier, so that SLA can be proceed for OAuth2 based traffic.
Authentication Server	Server that validates resource owner identity (defined by WebRTC Session Controller?).
Authorization Endpoint	Used to obtain authorization from the resource owner using user-agent redirection.
Authorization Grant	Represents the authorization given by the resource owner to a client application. An authorization grant is a credential representing the resource owner's authorization (to access its protected resources) used by the client to obtain an access token.
Authorization Server	Server that issues authorization codes and access token.
Access Token	Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the client.
Client Identifier	A unique string representing the registration information provided by the client.
Custom Subscriber Manager	Component that authenticates resource owner's username and password with a custom identity store (such as LDAP).
Delegated Authentication	Authentication mode supported by WSC to integrate with 3rd party authentication systems.
Grant Endpoint	URI supported by WSC to post the authentication result to issue the authorization code (defined by WSC).
Group Owner	Owner of the Group URI. Issues authorization token on behalf of the group members. In the example, Google.
Group URI	URI that represents a group of Resource Owners.
OAuth	Open Authorization Protocol
Protocol Endpoint	Network URI representing the location of a service to: obtain an authorization code and other values obtain an access token submit a grant. access a resource
Redirection Endpoint	After completing its interaction with the resource owner, the Authorization Server directs the resource owner's user-agent back to the client. The Authorization Server redirects the user-agent to the client's redirection endpoint previously established with the Authorization Server during the client registration process or when making the authorization request.
Refresh Token	Refresh tokens are credentials used to re-obtain access tokens.
Resource	The Web resource protected by OAuth Protocol.
Resource Owner	An entity capable of granting access to a protected resource. In the operator context this is defined as Resource owner URI (tel: or sip:)
Resource Server	Server that hosts protected resources and validates access token during resource access.
scopeId	Unique string that identifies a resource and used as part of scope-token by application client.
Subscriber Manager	Component in WSC to validate subscribers provisioned in its database.

About the OAuth/WSC Entities and Their Relationships

Figure 2-1 OAuth Flow and Entity Relationships

Description of ''Figure 2-1 OAuth Flow and Entity Relationships''

Figure 2-1 shows an example OAuth protocol flow for a resource access request:

(A) The client requests authorization from the resource owner. The authorization request can be made directly to the resource owner (as shown), or preferably indirectly using the Authorization Server as an intermediary.
(B) The client receives an authorization grant, including a credential representing the resource owner's authorization, expressed using one of four grant types defined in this specification or using an Extension grant type. The authorization grant type depends on the method used by the client to request authorization and the types supported by the Authorization Server.
(C) The client requests an access token by authenticating with the Authorization Server and presenting the authorization grant.
(D) The Authorization Server authenticates the client and validates the authorization grant, and if valid issues an access token.
(E) The client requests the protected resource from the resource server and authenticates by re-sending the access token.
(F) The resource server validates the access token, and if valid, serves the request.

About the OAuth Protocol Endpoints

The OAuth specification defines three types of protocol endpoints.

Redirection Endpoint: The redirection endpoint is a URI used by Authorization Server to return authorization credentials responses from the Authorization Server to the client using the resource owner user-agent.
Authorization Endpoint: The authorization endpoint interacts with the resource owner (typically the subscriber) and obtain an authorization grant which will be issued to an application client by the resource owner. The Authorization Server must first verify the identity of the resource owner before granting the authorization grant. This authorization grant will be exchanged by the application client for an access token.
Token Endpoint: The client uses the token endpoint to obtain an access token by presenting its authorization grant (the authorization code) or refresh token. The token endpoint is used with every authorization grant except for the implicit grant type (since an access token is issued directly).

The OAuth2 Authentication Process

Figure 2-2 shows how OAuth2 authentication process from the client side proceeds when the user clicks the Login button on the web page:

Figure 2-2 OAuth2 Authentication Process

Description of ''Figure 2-2 OAuth2 Authentication Process''

The following process shows the two tasks a WebRTC application performs in the required sequence when a user logs in to the application. Steps 1-12 deal with the OAuth2 login authentication and steps 13-19 with the obtaining of a WebSocket connection to a SIP server.

Your WebRTC application sends a HTTPS GET request to the WebRTC Session Controller Signaling Engine (WSC in the figure).
Example 2-1 HTTPS Login Request from a Chrome Browser

The following is a sample authentication/authorization request generated by an example web application. The end user is redirected to the loginRedirect.html page, at the host and port location where your application resides. The request is shown here with carriage returns added to promote its readability:
```
https://wsc-host:wsc-port/login/google?
client_id=12349876.apps.googleusercontent.com&
redirect_uri=http://wsc-host:wsc-port/login/google&
wsc_app_uri=/ws/webrtc/sample&
response_type=code&
scope=email&
oauth_url=https://accounts.google.com/o/oauth2/auth&
final_redirect_uri=http://custapp-host:custapp-port/wscsample/loginRedirect.html 
```
In the above request:
- client_id specifies the OAuth client ID for the registered WebRTC Session Controller application. This is the client ID you received when you first created and registered the WebRTC Session Controller application with the OAuth provider.
- redirect_uri is the configured login URI in WebRTC Session Controller for a specific OAuth provider. In this case, google.
- wsc_app_uri is your application's URI. In this example, the application is named sample and resides at /ws/webrtc/.
- response_type specifies the supported OAuth response type. The entry code indicates that your server expects to receive an authorization code.
- scope specifies the OAuth scope, indicating which parts of the user's account you wish to access. The value of scope depends on the OAuth provider. This example uses email.
- oauth_url specifies the URL of the OAuth provider's login dialog page.
- final_redirect_uri specifies the location to which Signaling Engine should redirect the user after a successful OAuth login.
WSC does the following:
1. Based on the URL query parameters, identifies that the request is for the OAuth login mechanism.
2. Sends a HTTPS request to the OAuth provider's login dialog page.
  
  This HTTPS request contains the client_id, the redirect_uri, response_type, scope, and state, a recommended security practice in the OAuth specification. WSC generates a unique string as the state parameter and sends it to the OAuth2 provider. In turn, the OAuth2 provider returns this string to WSC.
The user provides his or her credentials to the OAuth provider. In the case of Chrome example, the Gmail login and password. This allows the WSC application to access the user information.
The OAuth provider authenticates the user. It redirects the user back to WebRTC Session Controller with the OAuth access code information along with state as a query parameter.
WSC validates the state that it received from the OAuth provider.
WSC sends a HTTPS POST request to obtain the access token. The request includes the client_id, client_secret, redirect_uri, grant_type set to access_code, and code with code_received.
The OAuth2 provider responds by placing the access token in the response body.
WSC sends a HTTPS GET request with the access token as the query parameter to OAuth Provider. This is a request authorization to obtain details about the user (not the password).
The OAuth2 provider responds with the user information as a JSON data.
WSC sets up the authenticated subject for use in mapping Web credentials to SIP credentials. It populates this authenticated subject with the user name (user's mail with the OAuth provider), and a group name configured in the OAuth security provider, for example "google".

At this point, you can customize the security provision. For example, you can chain additional security providers such that they can add more credential information for the authenticated subject.
WSC verifies the location to which Signaling Engine should redirect the user after a successful OAuth login by validating the value of the final_redirect_uri.
WSC sends the verified final_redirect_uri to the browser where your WebRTC application resides.
The WebRTC application sends a WebSocket request to the Signaling Engine, to register for message events.
The WSC Signaling Engine sets up a Groovy callback with data from the authenticated subject.
The WSC Signaling Engine attempts to register with the SIP Server by calling the SIP REGISTER method.
The registrar for the SIP Server sends back a challenge.
The WSC Signaling Engine sends the SIP credentials in the SIP REGISTER method back to the SIP Server.
The SIP SERVER validates the user's credentials. It registers the user in its database and sends back a success response.
The WebSocket connection with your WebRTC application is now established.

Login Using Form-Based Authentication

Form-based authentication requires your application to implement the logic to obtain and authenticate the username and password from the application user.

If you plan to use form-based authentication in your applications, do the following:

Create a separate web application which enforces form-based authentication for login. For more information on how to create such an application, see Oracle Fusion Middleware Programming Security for Oracle WebLogic Server at:

http://docs.oracle.com/cd/E24329_01/web.1211/e24485/thin_client.htm#autoId11
Deploy this application in the WebRTC Session Controller nodes. For more information, see Oracle Communications WebRTC Session Controller Extension Developer's Guide.

Anyone who logs in to this specific web application is also logged in to WebRTC Session Controller Signalling Engine application.

Login Using REST Authentication

REST stands for representational state transfer, a style of network architecture that complies with the following constraints:

A uniform separation between client and server so that they need be concerned only about the interface between them.
Stateless client and server with each request containing all the necessary information so that neither side needs to store context. The state contains links that the client can use in the future to begin a new state-transition.
Cachable responses that are defined to prevent clients from reusing stale or inappropriate data in responding to further requests.
A layered system in which the client does not know if it's connected to an end or intermediary server. Layered systems can improve scalability, providing load balancing, shared caching, and so on.
Optional code-on-demand that enables a server to transfer Java applets or JavaScript code to a client to temporarily enhance its capabilities.
A uniform interface that enables each part of the architecture to evolve independently.

To enable REST authentication, you must install a REST service provider and enable it through the WLS administration console. See the section on configuring WSC authentication in the WebRTC Session Controller System Administrator's Guide for information on installing and enabling a REST service provider.

When a client logs in, REST authentication occurs as follows:

The client sends the request URI to the WebRTC Session Controller, indicating that the request type is REST authentication:
```
http://wsc-host:wsc-port/login?wsc-app-uri=/ws/webrtc/restauth&redirect-uri=http://successpage.html
```
Where:
- wsc-host is the host name where WebRTC Session Controller is running
- wsc-port is the listening port for WebRTC Session Controller
- successpage.html is the landing page where the browser should be directed after a successful login
WebRTC Session Controller responds and triggers a client authentication pop-up window that prompts the user for a login name and password.
The client sends the login name and password to WebRTC Session Controller.
The WebRTC Session Controller forwards the login name and password to the REST service provider, which validates them.
The REST service provider returns one of the following results:
- A 200 message to indicate that the client authentication was successful
- A 401 message to indicate that the client was not successfully authenticated
On successful authentication, WebRTC Session Controller populates the authentication context, AuthenticateContext, which is defined in the Groovy script library.

Handling Logout from WebRTC Session Controller

When your user logs out of your application or leaves the browser page, your application also logs out of WebRTC Session Controller. You can optionally redirect the user to the web page from where he was directed to your application.

In your application, send an HTTPS request to:

https://wsc-host:wsc-port/logout?redirect_uri=url_to_redirect_to_after_logout

The above request logs out the user from the WebRTC Session Controller domain and redirects the browser to the URI specified by redirect_uri. If redirect_uri is not specified, a message saying that the user has been logged out is displayed.

When an application logs into WebRTC Session Controller, the login is valid for one hour. If the WebSocket is disconnected for any reason within that hour, the application can reconnect without logging in again.After one hour, the user needs to login again for new WebSocket connections to be set up. See Oracle Communications WebRTC Session Controller System Administrator's Guide for information on session timeout if the WebSocket loses its connection.