3 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".

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 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.

From the client side, when the user clicks the Login button on the web page, the OAuth process works in the following way:

Your application sends an HTTPS request to the Signaling Engine login URL.
WebRTC Session Controller Signaling Engine does the following:
1. Based on the URL query parameters, identifies that the request is for the OAuth login mechanism.
2. Redirects the browser to the OAuth provider's login dialog page.
The user provides his or her credentials to the OAuth provider.
The OAuth provider authenticates the user and redirects the user back to WebRTC Session Controller with the OAuth access code information.
WebRTC Session Controller Signaling Engine retrieves the OAuth token and user information from the OAuth access code and does the following:
1. Logs the user in to the Signaling Engine domain.
2. Redirects the user back to the final redirect URI specified in your application.

For example, 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.
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.

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 WebRTC Session Controller Extension Developer's Guide.

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

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 WebRTC Session Controller System Administrator's Guide for information on session timeout if the WebSocket loses its connection.