This chapter describes WebRTC Session Controller authentication schemes and the steps to configure them.
Before WebRTC Session Controller can process any signaling traffic, you must configure an authentication scheme.
WebRTC Session Controller provides out of the box support for these authentication schemes:
Guest authentication
This scheme allows anonymous guest access to WebRTC Session Controller.
HTTP authentication
This provider sends a HTTP GET request to a remote HTTP endpoint (for instance, a Representational State Transformation (REST) endpoint) using HTTP BASIC authentication headers or token-based authentication. A return code of 200 indicates that authentication was successful.
OAuth 2.0 authentication
This scheme lets you leverage OAuth 2.0 authentication support provided by companies such as Facebook or Google, and lets WebRTC Session Controller retrieve user information such as an email address or phone number, with the consent of that user.
The following sections describe the configuration steps for each of those authentication schemes.
To provision guest access for WebRTC Session Controller, you must configure settings in the WebLogic Administration Console and then define a new WebRTC Session Controller application in the WebRTC Session Controller console.
To configure the WebLogic Server guest access provider:
Start your Signaling Engine administration server if it is not already running. See Oracle Communications WebRTC Session Controller Installation Guide for more information.
Navigate to the WebLogic Server Administration Console and log in with your administrator user name and password:
http://hostname:port/console
where hostname is the name of your WebRTC Session Controller server and port is the Administration Console access port.
Note:
The default Administration Console port is 7001.In the Domain Structure pane, select Security Realms.
Select myrealm in the Realms table.
Select the Providers tab and then click New.
Enter a name in the Name text box, in the Type drop down list, select WscServletAuthenticator, and click OK.
Select the newly created authentication provider in the list of Authentication Providers, and select the Provider Specific tab.
Make a note of the Guest Uri Match Pattern. The default is /ws/webrtc/guest.
Navigate back to the myrealm Providers tab, and in the list of Authentication Providers, select DefaultAuthenticator.
Select the Common tab and choose a value for the Control Flag.
For information on Control Flag settings, see "Setting the JAAS Control Flag Option" in Administering Security for Oracle WebLogic Server.
Click Save.
Log out of the WebLogic administration interface and restart WebRTC Session Controller.
Continue to "Configuring the WebRTC Session Controller Guest Access Application".
For more details on WebRTC Session Controller application configuration options, see the discussion on creating applications in Oracle Communications WebRTC Session Controller Extension Developer's Guide.To configure the WebRTC Session Controller guest access application:
Navigate to the WebRTC Session Controller console and log in with your administrator user name and password:
http://hostname:port/wsc-console
where hostname is the name of your WebRTC Session Controller server and port is the Administration Console access port.
Note:
The default Signaling Engine console port is 7001.Select the Applications tab.
Click Edit.
Click Create.
Enter a name for the application in Create Application and select OK.
In the Request URI text box, enter the URI that you noted in "Configuring the WebLogic Server Guest Access Provider". The default value is /ws/webrtc/guest.
Enter guest for the Security Group.
Enter * for Allowed Domains, or customize as your deployment requires.
Select the + icon under Packages.
In the Packages window, select the packages you want and move them to Selected Packages.
Select OK.
Select Save.
To provision HTTP access for WebRTC Session Controller, you must configure settings in the WebLogic Administration Console and then define a new WebRTC Session Controller application in the WebRTC Session Controller console.
In addition you must have your own HTTP endpoints defined to handle authentication and identity assertion requests.
To configure the WebLogic Server HTTP access provider:
Start your Signaling Engine servers if they are not already running. See Oracle Communications WebRTC Session Controller Installation Guide for more information.
Navigate to the WebLogic Server Administration Console and log in with your administrator user name and password:
http://hostname:port/console
where hostname is the name of your WebRTC Session Controller server and port is the Administration Console access port.
Note:
The default Administration Console port is 7001.In the Domain Structure pane, select Security Realms.
Select myrealm in the Realms table.
Select the Providers tab and then click New.
Enter a name in the Name text box, in the Type drop down list, select WscRestAuthenticator, and click OK.
Select the newly created authentication provider in the list of Authentication Providers, select the Common tab and choose a value for the Control Flag.
For information on Control Flag settings, see "Setting the JAAS Control Flag Option" in Administering Security for Oracle WebLogic Server.
Select the Provider Specific tab.
Enter a Group Name to associate a group with authentication requests rather than individual user names. Make a note of this group name.
Enter a Token Name. The token name must match the name of the authentication token that is sent in the HTTP request parameter.
Enter an Authentication End Point Url. A REST endpoint URL that handles authentication.
To enable authentication over http, check Allow Http.
Enter an Identity Asserter End Point Url. A REST endpoint URL that handles matching the authentication token to a user.
If a user is found, a JSON string is returned by the REST endpoint with the user's credentials. Otherwise an HTTP 401 Forbidden error is returned.
Click Save.
Log out of the WebLogic administration interface and restart WebRTC Session Controller.
Continue to "Configuring the WebRTC Session Controller HTTP Access Application".
For more details on WebRTC Session Controller application configuration options, see the discussion on creating applications in Oracle Communications WebRTC Session Controller Extension Developer's Guide.
To configure the WebRTC Session Controller HTTP access application:
Navigate to the WebRTC Session Controller console and log in with your administrator user name and password:
http://hostname:port/wsc-console
where hostname is the name of your WebRTC Session Controller server and port is the Administration Console access port.
Note:
The default Signaling Engine console port is 7001.Select the Applications tab.
Click Edit.
Click Create.
In Create Application, enter a name for the application.
Select OK.
In the Request URI text box, enter the URI endpoint that you want WebRTC applications to use to access WebRTC Session Controller.
Enter the group name you defined in "Configuring the WebLogic Server HTTP Authentication Provider" for the Security Group.
Click the pencil icon under Allowed Domains.
In the Allowed Domains window, enter * to allow all domains, or customize as your deployment requires.
Select OK.
Select the + icon under Packages.
In the Packages window, select all of the packages and move them to Selected Packages.
Select OK.
Select Save.
Restart WebRTC Session Controller.
To provision OAuth access for WebRTC Session Controller, you must configure settings in the WebLogic Administration Console and then define a new WebRTC Session Controller application in the WebRTC Session Controller console.
In addition you must procure a developer's account from the provider from whom you want to leverage OAuth authentication services and obtain the following information:
The OAuth service provider's OAuth user information URL
An OAuth client ID supplied to you by the OAuth service provider
The service provider's OAuth server URL
Your OAuth client secret, defined when you create your account with your OAuth service provider
Following the general OAuth configuration steps, two specific OAuth configuration examples are provided:
To configure the WebLogic Server OAuth access provider:
Continue to.
Start your Signaling Engine servers if they are not already running. See Oracle Communications WebRTC Session Controller Installation Guide for more information.
Navigate to the WebLogic Server Administration Console and log in with your administrator user name and password:
http://hostname:port/console
where hostname is the name of your WebRTC Session Controller server and port is the Administration Console access port.
Note:
The default Administration Console port is 7001.In the Domain Structure pane, select Security Realms.
Select myrealm in the Realms table.
Select the Providers tab and then click New.
Enter a name in the Name text box, in the Type drop down list, select WscServletAuthenticator, and click OK.
The console creates the new provider and returns to the Authentication Providers table.
Note:
The WscServletAuthenticator must be deployed to enable OAuth security authentication, but it requires no further configuration.Click New.
Enter a name in the Name text box, in the Type drop down list, select WscOAuthIdentityAsserter, and click OK.
Select the newly created authentication provider in the list of Authentication Providers.
Assign an access token to the provider in Active Types and click Save.
If you are provisioning multiple OAuth authentication sources, for example, Facebook, Google, and Microsoft, you should select a different OAuth token for each in the Active Types list.
WARNING:
The user interface will let you select multiple OAuth tokens for a single provider. Only select a single token for each OAuth provider you provision.
Select the Provider Specific tab and enter the following information as described in Table 4-1.
Table 4-1 OAuth Provider Specific Attributes
| Attribute Name | Attribute Description |
|---|---|
|
Group Name |
Required. A group name used to associate a group with authentication requests. Specifying a group name allows both the user name and group name to be available in the authenticated subject. Make a note of this group name. |
|
OAuth Client ID |
Required. The OAuth client ID provided to you by your OAuth service provider. |
|
OAuth Server Url |
Required. The URI of your OAuth service provider's OAuth server which issues access tokens. |
|
OAuth User Info Url |
Required. The OAuth providers URI that provides user information. |
|
OAuth Redirect Url |
Optional. The URI to which the browser is re-directed after successful authentication by the OAuth provider. |
|
Fields As User Name |
Required. Determines which OAuth provider resources are used as principal names. Multiple entries are separated by commas. If the first entry returns nothing, then the second entry is used, continuing down the list. |
|
OAuth Client Secret |
Required. The OAuth client secret provided to you by your OAuth provider. |
|
Proxy Server |
Optional. The proxy URI used to connect to the OAuth server.. |
|
Proxy Port |
Optional. The proxy port used to connect to the OAuth server. |
Click Save.
Log out of the WebLogic administration interface and restart WebRTC Session Controller.
Continue to "Configuring the WebRTC Session Controller OAuth Access Application."
For more details on WebRTC Session Controller application configuration options, see the discussion on creating applications in Oracle Communications WebRTC Session Controller Extension Developer's Guide.
To configure the WebRTC Session Controller OAuth access application:
Navigate to the WebRTC Session Controller console and log in with your administrator user name and password:
http://hostname:port/wsc-console
where hostname is the name of your WebRTC Session Controller server and port is the Administration Console access port.
Note:
The default Signaling Engine console port is 7001.Select the Applications tab.
Click Edit.
Click Create.
Enter a name for the application in Create Application and select OK.
In the Description text box, enter a description for your application.
In the Request URI text box, enter the URI endpoint that you want WebRTC applications to use to access WebRTC Session Controller.
In the Security Group text box, enter the group name you defined in "Configuring the WebLogic Server OAuth Access Provider".
Click the pencil icon under Allowed Domains.
In the Allowed Domains window, enter * to allow all domains, or customize as your deployment requires.
Click OK.
Click the pencil icon under Packages.
In the Packages window, select all of the packages and move them to Selected Packages.
Click OK.
Click Save.
Restart WebRTC Session Controller.
This example outlines the steps to follow to configure OAuth authentication using Facebook as an OAuth authentication provider.
Note:
You must have a Facebook and be registered a Facebook or application developer before you can configure OAuth authentication as described in this example.To configure a Facebook authentication app:
Login to http://developers.facebook.com.
Click the Apps menu and then click Add a New App.
Choose a platform.
Enter a name for your app.
Click Create New Facebook App ID.
Choose a category from the Category drop down list and click Create App ID.
Click Skip Quick Start.
Click the Settings in the left panel and copy the App ID and the App Secret to a scratch file for future reference.
Note:
You must authenticate your Facebook account to display the App Secret.Add a Contact Email and click Save Changes.
Click Add Platform then click Website, enter the URL and port for your site, and click Save Changes.
Note:
Facebook does not accept IP addresses. You must use a domain name.Click Status & Review in the left panel, and in the Status tab set the switch adjacent the label Do you want to make this app and all its live features available to the general public? to YES. Click the Confirm button when prompted.
To configure a Facebook WebRTC Session Controller OAuth authentication provider:
Start your Signaling Engine servers if they are not already running. See Oracle Communications WebRTC Session Controller Installation Guide for more information.
Navigate to the WebLogic Server Administration Console and log in with your administrator user name and password:
http://hostname:port/console
where hostname is the name of your WebRTC Session Controller server and port is the Administration Console access port.
Note:
The default Administration Console port is 7001.In the Domain Structure pane, select Security Realms.
Select myrealm in the Realms table.
Select the Providers tab and then click New.
Enter a name in the Name text box, in the Type drop down list, select WscServletAuthenticator, and click OK.
The console creates the new provider and returns to the Authentication Providers table.
Note:
The WscServletAuthenticator must be deployed to enable OAuth security authentication, but it requires no further configuration.Click New.
Enter a name for the provider in the Name text box, in the Type drop down list, select WscOAuthIdentityAsserter, and click OK.
Select the newly created authentication provider in the list of Authentication Providers.
Assign an access token to the provider in Active Types and click Save.
WARNING:
The user interface will let you select multiple OAuth tokens for a single provider. Only select a single token for the Facebook OAuth provider. Note that each OAuth provider you provision must have a separate and distinct OAuth token.
Select the Provider Specific tab and enter the following information as described in Table 4-2.
Table 4-2 OAuth Provider Specific Attributes
| Attribute Name | Attribute Description |
|---|---|
|
Group Name |
This should be set to the value you entered in step 8. |
|
OAuth User Info Url |
Leave this set to the default, https://graph.facebook.com/me?. |
|
Proxy Port |
Set the Proxy Port to 80. |
|
OAuth Client ID |
Enter the App ID from your Facebook App configuration. |
|
OAuth Server Url |
Leave this set to the default, https://graph.facebook.com/oauth/access_token. |
|
OAuth Redirect Url |
Set this to the redirect URL you provided when creating your Facebook App. |
|
Fields As User Name |
Leave this set to the default. |
|
OAuth Client Secret |
Enter the App Secret from your Facebook App configuration. |
|
Proxy Server |
Enter the URI of your proxy server. |
Click Save.
Log out of the WebLogic administration interface and restart WebRTC Session Controller.
Continue to "Configuring the WebRTC Session Controller OAuth Access Application."
This example outlines the steps to follow to configure OAuth authentication using Google as an OAuth authentication provider.
Note:
You must have a Google Gmail account and be registered as a Google application developer before you can configure OAuth authentication as described in this example.To configure a Google authentication project:
Click the Create Project.
Enter a Project Name and a Project ID, and click Create.
Click APIs & auth in the left panel and then click Credentials.
In the right panel, click Create new Client ID and then click Configure consent screen.
Choose an email address and enter a Product Name. Fill in any other information you require and click Save.
In the Create Client ID dialog, choose Web application for the Application Type.
In Authorized JavaScript Origins, enter the URI and port for your WebRTC Session Controller application, and in Authorized Redirect URI enter the URI to use for authentication redirects.
Note:
Google does not accept IP addresses. You must use a domain name.Click Create Client ID.
Once the Client ID is created, copy the Client ID and the Client Secret to a scratch file for future reference
To configure a Google WebRTC Session Controller OAuth authentication provider:
Start your Signaling Engine servers if they are not already running. See Oracle Communications WebRTC Session Controller Installation Guide for more information.
Navigate to the WebLogic Server Administration Console and log in with your administrator user name and password:
http://hostname:port/console
where hostname is the name of your WebRTC Session Controller server and port is the Administration Console access port.
Note:
The default Administration Console port is 7001.In the Domain Structure pane, select Security Realms.
Select myrealm in the Realms table.
Select the Providers tab and then click New.
Enter a name in the Name text box, in the Type drop down list, select WscServletAuthenticator, and click OK.
The console creates the new provider and returns to the Authentication Providers table.
Note:
The WscServletAuthenticator must be deployed to enable OAuth security authentication, but it requires no further configuration.Click New.
Enter a name for the provider in the Name text box, in the Type drop down list, select WscOAuthIdentityAsserter, and click OK.
Select the newly created authentication provider in the list of Authentication Providers.
Assign an access token to the provider in Active Types and click Save.
WARNING:
The user interface will let you select multiple OAuth tokens for a single provider. Only select a single token for the Facebook OAuth provider. Note that each OAuth provider you provision must have a separate and distinct OAuth token.
Select the Provider Specific tab and enter the following information as described in Table 4-3.
Table 4-3 OAuth Provider Specific Attributes
| Attribute Name | Attribute Description |
|---|---|
|
Group Name |
This should be set to the value you entered in step 8. |
|
OAuth User Info Url |
Set this to https://www.googleapis.com/oauth2/v1/userinfo. |
|
Proxy Port |
Set this to 80. |
|
OAuth Client ID |
Enter the Client ID from your Google project configuration. |
|
OAuth Server Url |
Set this to https://accounts.google.com/o/oauth2/token. |
|
OAuth Redirect Url |
Set this to the redirect URL you provided when creating your Google project. |
|
Fields As User Name |
Leave this set to the default. |
|
OAuth Client Secret |
Enter the Client Secret from your Google project configuration. |
|
Proxy Server |
Enter the URI of your proxy server. |
Click Save.
Log out of the WebLogic administration interface and restart WebRTC Session Controller.
Continue to "Configuring the WebRTC Session Controller OAuth Access Application."
In certain cases, you may want to implement a two stage authentication workflow for your WebRTC Session Controller application. In a two stage authentication workflow, once a user has been authenticated by a standard authentication method (HTTP, OAuth or WebLogic in the case of WebRTC Session Controller), an additional separate authentication method is invoked. That separate authentication method usually takes the form of a one-time password which is delivered to the user either by email or short message (SMS). Once the one-time password is dispatched to the user, the user is redirected to a separate authentication web page where the one-time password is validated. After validation, the second stage authentication is usually skipped on subsequent logins.
Note:
WebRTC Session Controller does not provide facilities for one-time password generation and authentication. Such a system must be implemented by you according to your requirements.In order to support two stage authentication, WebRTC Session Controller provides a Groovy script library function, validateAuthenticatedUser.
The validateAuthenticatedUser function lets you evaluate a user's HTTP request details such as request parameters and cookies, and provide redirection to a web page if required based upon those details.
See "Editing validateAuthenticatedUser" for details on accessing and updating the validateAuthenticatedUser function.
Note:
While the validateAuthenticatedUser function is defined in the WebRTC Session Controller Script Library it must be implemented as per your system requirements. The default function logic is only for purposes of illustration.The validateAuthenticatedUser function has the following syntax:
void validateAuthenticatedUser(final HttpFilterContext httpFilterContext)
The HttpFilterContext class includes methods that return: parts of the request URL, the client's IP address, the authenticated subject, a Map of HTTP request parameters, and a Map of request cookies. It also has methods that redirect the client to a specified URL, log out of the current session, and so on. For a complete description of the HttpFilterContext class, see the Oracle Communications WebRTC Session Controller Configuration API Reference.
Example 4-1 illustrates a simple validateAuthenticatedUser implementation as well as the use of some HttpFilterContext methods.
Example 4-1 validateAuthenticatedUser
void validateAuthenticatedUser(final HttpFilterContext httpFilterContext) {
def loginCookie = httpFilterContext.cookies.WSC_LOGIN_COOKIE
def tempCookieValue = "temp_session_cookie";
if (tempCookieValue != loginCookie) {
httpFilterContext.redirect('/test/sample');
httpFilterContext.logOut('/test/newpage');
httpFilterContext.addCookie(loginCookie, tempCookieValue);
}
The function executes in the following manner:
The login cookie is retrieved from the httpFilterContext.cookies.WSC_LOGIN_COOKIE and stored in loginCookie.
An additional cookie is defined for the current session.
The cookie created for the current session is compared to the login cookie.
If the cookies match, no redirection occurs.
If the cookies do not match, the function sets the redirect and logout URLs and copies the session's cookie value to the login cookie.
Upon the user's second access attempt, the session cookie and the login cookie will match, and no redirection will occur.
That example uses custom cookies to track if this is the first login for a specific user. The cookie is reset when the browser restarts, which means that the user's next login will trigger a new redirect. To prevent continual redirects, you will need to flag a user as successfully authenticated in a persistent manner. For example, you can base the decision to redirect on an additional metadata comparison against the AUTHENTICATED_SUBJECT.
Note:
Such support requires additional custom integration with the security provider.To edit the validAuthenticatedUser function:
Navigate to the WebRTC Session Controller console and log in with your administrator user name and password:
http://hostname:port/wsc-console
where hostname is the name of your WebRTC Session Controller server and port is the Administration Console access port.
Note:
The default Signaling Engine console port is 7001.Select the Script Library tab.
Click Edit.
Edit the function validateAuthenticatedUser as required for your needs.
Click Validate Library to make sure you have not introduced any errors.
Click Save to save your changes to the Script Library.