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.
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.
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.
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.
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:
Based on the URL query parameters, identifies that the request is for the OAuth login mechanism.
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:
Logs the user in to the Signaling Engine domain.
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.
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.
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.
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.