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 these 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 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".
In WebRTC Session Controller Administration Console, configure and manage the tenant application profile for each tenant through the Application Profiles tab.
See "Managing WebRTC Session Controller Application Profiles".
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:
Create an entry for the Security provider
Start your Signaling Engine servers if they are not already running. See 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.
Click OK.
Choose a value for the Control Flag
From the list of Authentication Providers, select the newly created authentication provider.
Select the Common tab.
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.
Enter the provider-specific configuration values
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.
In the Forward Header Prefix field, enter the prefix to prepend on header names when forwarded to the REST service.
In the Forward Parameter Names field, enter the HTTP parameters to extract from HTTP requests and send as query parameters with authenticate and identity assertion REST requests.
For multitenancy scenarios, enter the tenant key for this tenant. The default configuration entry is tenant_profile_key. It is included by default in HTTP requests.
In the Identity Asserter End Point Url field, enter 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.
In the Forward Header Names field, enter the HTTP headers to extract from HTTP request and send as headers with authenticate and identity assertion REST requests.
The extracted header name is prefixed with the value from the Forward Header Prefix.
Save your configuration and restart WebRTC Session Controller
Click Save.
Log out of the WebLogic administration interface.
Restart WebRTC Session Controller.
Note:
If authentication is successful, and if the response body returned by the remote HTTP endpoint is valid JSON formatted data, WebRTC Session Controller normalizes the JSON data as a Java Map and embeds this normalized data as credential information in the authenticated subject. That credential information is accessible in the groovy layer, enabling you to use it to build a credential map for the SIP Register request.Continue to "Configuring the WebRTC Session Controller HTTP Access Application".
In WebRTC Session Controller Administration Console, configure and manage the tenant application profile for each tenant through the Application Profiles tab.
See "Managing WebRTC Session Controller Application Profiles".
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:
Create an entry for the OAuth Security provider
Start your Signaling Engine servers if they are not already running. See 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.
Click OK.
Enter the Access Token for the Provider
From the list of Authentication Providers, select the newly created authentication provider.
From the set of Available tokens under Active Types, select an authentication token to assign as access token to the provider in Active Types and click Save.
From the set of Available tokens under Active Types, select the authentication token.
To move the selected token to the Chosen field, click the double arrow pointing to that field.
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.
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 authentication source from the Active Types list.)
Enter the provider-specific configuration values
Select the Provider Specific tab.
Enter the information specific to this provider, 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. |
|
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 Redirect Url |
Optional. The URI to which the browser is re-directed after successful authentication by the OAuth provider. |
|
Proxy Server |
Optional. The proxy URI used to connect to the OAuth server. |
|
OAuth Client Secret |
Required. The OAuth client secret provided to you by your OAuth provider. |
|
OAuth Client ID |
Required. The OAuth client ID provided to you by your OAuth service provider. |
|
Proxy Port |
Optional. The proxy port used to connect to the OAuth server. |
|
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. |
Save your configuration and restart WebRTC Session Controller
Click Save.
Log out of the WebLogic administration interface.
Restart WebRTC Session Controller.
Continue to "Configuring the WebRTC Session Controller OAuth Access Application".
In WebRTC Session Controller Administration Console, configure and manage the tenant application profile for each tenant through the Application Profiles tab.
See "Managing WebRTC Session Controller Application Profiles".
Before you proceed, please review the description about multitenancy in WebRTC Session Controller in the section, "About Multitenancy".
In general, your SaaS applications authenticate the users of a tenant according to their proprietary mechanisms. After a user is successfully authenticated, the SaaS application generates a token for the authenticated user. The user presents the token (using the client SDKs) to access WebRTC Session Controller resources. To validate the token, WebRTC Session Controller accesses a REST service.
WebRTC Session Controller does the following:
Basic Authentication HTTP request
When a Basic Authentication HTTP request arrives, WebRTC Session Controller extracts the user name, password, any optional query parameters and headers enabled for forwarding in Forward Header Names and Forward Parameter Names fields. (The tenant key is the value entered in the Forward Parameter Names field).
WscRestAuthenticator makes a REST request to the URL specified in the Authentication End Point Url field by using:
The enabled forward parameters as query parameters
The enabled forward headers as HTTP headers with the header name prefixed with the value from forward header prefix field
The user name and password as basic authentication credentials
HTTP request with a query parameter
When an HTTP request with a query parameter arrives with the name specified in the Token Name field, this parameter is inserted by a servlet filter in the provider as HTTP header under the name RestAccessAuthToken to have identity assertion invoked.
When an HTTP request arrives with an HTTP header named RestAccessAuthToken, WebRTC Session Controller extracts the user name, password, any optional query parameters and headers enabled for forwarding in Forward Header Names and Forward Parameter Names fields. (The tenant key is the value entered in the Forward Parameter Names field).
WscRestAuthenticatorl makes a REST request to the URL specified in the Identity Asserter End Point Url field by using:
The enabled forward headers as HTTP headers with the header name prefixed with the value from the Forward Header Prefix field.
The enabled forward parameters as query parameters together with a "token" parameter with the value from the RestAccessAuthToken header
When either authentication request or identity assertion REST request completes successfully, principals with the value from the Group Name field are added to the subject together with a public credential map object containing the credentials returned by the REST server as a JSON formatted response. For authentication requests, the user name is also added as a subject principal.
Example 4-1 shows a Basic authenticated HTTP request for user "wsc1" and with and without tenant profile key parameter included:
Example 4-1 Basic Authenticated HTTP Request
For a user "wsc1" and no tenant profile key parameter included:
GET /authenticate/basic HTTP/1.1\r\n Content-Type: application/json\r\n Accept: application/json\r\n Authorization: Basic wsc1:d2VsY29tZTE=\r\n Host: localhost:8190\r\n ...
For a user "wsc1token" with "tenant1" as the tenant profile key parameter:
GET /authenticate/basic?tenant_profile_key=tenant1 HTTP/1.1\r\n Content-Type: application/json\r\n Accept: application/json\r\n Authorization: Basic wsc1:d2VsY29tZTE=\r\n Host: localhost:8190\r\n ...
Example 4-2 shows an Identity asserted HTTP request for user "wsc1" and no tenant profile key parameter included:
Example 4-2 Identity Asserted HTTP Request
For user "wsc1" and no tenant profile key parameter included:
GET /authenticate/basic?token=wsc1token HTTP/1.1\r\n Content-Type: application/json\r\n Accept: application/json\r\n Host: localhost:8190\r\n ...
For user "wsc1token" with "tenant1" as the tenant profile key parameter:
GET /authenticate/token?token=wsc1token&tenant_profile_key=tenant1 HTTP/1.1\r\n Content-Type: application/json\r\n Accept: application/json\r\n Host: localhost:8190\r\n
If you employ a custom security provider, ensure that you provide the tenant key and the necessary logic to process the requests. You can also make use of ServletAuthenticationFilter to perform pre- and post-processing for authentication functions, including identity assertion.
For more information on ServletAuthenticationFilter, see the description about "Servlet Authentication Filters" in Fusion Middleware Developing Security Providers for Oracle WebLogic Server.
If you employ the WebLogic LDAP security provider, ensure that your implementation isolates the stores for each tenant. To do so, use the following workarounds:
Configure multiple authentication providers. Additionally configure the control flag as sufficient in the WebLogic Admin Server.
Create a separate domain for each tenant.
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 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 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-3 illustrates a simple validateAuthenticatedUser implementation as well as the use of some HttpFilterContext methods.
Example 4-3 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.