How to Configure an OAuth Authentication Scheme

Policy Server Guides › Policy Server Configuration Guide › Authentication Schemes › How to Configure an OAuth Authentication Scheme

How to Configure an OAuth Authentication Scheme

This scenario describes how a Policy Server administrator and an agent owner configure an OAuth authentication scheme.

The OAuth authentication scheme lets users submit credentials through an OAuth provider. The OAuth provider authenticates the user and sends an authentication response with claims about the user. The Policy Server verifies the authentication response, completes the authentication process, and authorizes access to the resource.

The goal of the scenario is for you to:

Identify how the OAuth authentication process works.
Configure the required agent-side components.
Configure the required Policy Server-side components.

The following figure shows the required tasks to configure an OAuth authentication scheme.

Flow diagram of OAuth configuration tasks

Complete the following steps for OAuth configuration:

OAuth Authentication Process

The following process explains how the OAuth authentication scheme works:

A user requests a resource.
The agent intercepts the request and contacts the Policy Server to see if the resource is protected.
The Policy Server determines that the resource is protected with an OAuth authentication scheme. The Policy Server requests that the agent redirect the user to the OAuth forms credential collector (FCC).
The agent redirects the user to the FCC.
The user selects an OAuth provider and submits credentials at the provider site.
The FCC constructs the user identifier and passes it to the Policy Server.
The Policy Server redirects the user to the OAuth provider by constructing an authentication request.
The user authenticates with the OAuth provider using provider-specific credentials.
The provider redirects the successful authentication response to the FCC.
The agent passes the authentication response to the Policy Server.
The Policy Server verifies the provider authentication response and uses it to determine the value of the first required claim. The Policy Server searches all user directories in the policy domain to locate a user with an attribute that matches the claim value. Upon a match, the Policy Server authenticates the user.
Note: The authentication scheme supports an anonymous mode of authentication. In anonymous mode, the Policy Server does not use the claim value to map to a user. The Policy Server searches all user directories in the policy domain for a user matching the anonymous user that you defined in the authentication scheme.
The Policy Server returns the session details of the authenticated user to the FCC.
The FCC creates the session cookie and passes it to the web browser. The user is redirected to the requested resource and the Policy Server maintains all authorization decisions.

Register an Application with an OAuth Provider

Prerequisite

Determine whether the SecureURLs parameter is set in your web agent configuration and its value, if it is set.

Part of the registration process is to specify an entry in the Redirect URIs setting (Google) or the Site URL setting (Facebook). The format of this entry depends on the value of the SecureURLs agent parameter. Check the value of the SecureURLs parameter from the Administrative UI. The parameter is in the Agent Configuration Object for the host agent.

If the SecureURLs parameter is set to Yes, enter the URL in the following format:
http(s)://agent_host/siteminderagent/forms/oauthcb.fcc?SMQUERYDATA=Sample
If the SecureURLs parameter is set to No, enter the URL in the following format:
http(s)://agent_host/siteminderagent/forms/oauthcb.fcc

Google

Follow these steps:

Establish a Google Apps account.
Navigate to https://code.google.com/apis/console and log in.
Select API Access and create an OAuth client ID. To create the client ID, enter the following information:

Home Page URL

http(s)://homepage.com

Example: http://www.forwardinc.com

Application type

Web application

Your site or hostname

http://agent_host

Example: http://myagent.ca.com
Click Create clientID.
Edit the setting of the Redirect URI to the following URI:

Redirect URls

http(s)://agent_host/siteminderagent/forms/oauthcb.fcc

(SecureURLs not set or set to No)

or

http(s)://agent_host/siteminderagent/forms/oauthcb.fcc?SMQUERYDATA=Sample

(SecureURLs set to Yes)
Click Update.

The Google registration process is complete.

Facebook

Follow these steps:

Establish a Facebook account.
Go to https://developers.facebook.com/apps.
Choose the AppName and click Continue.
Enter the captcha text that is displayed and click Continue.
In the Website with Facebook Login section, complete the following field:

Site URL

http(s)://agent_host/siteminderagent/forms/oauthcb.fcc

(SecureURLs not set or set to No)

or

http(s)://agent_host/siteminderagent/forms/oauthcb.fcc?SMQUERYDATA=Sample

(SecureURLs set to Yes)
Click Save changes.
Complete the following settings:
- Set Domain to ca.com
- Disable Sandbox mode
- Set the Canvas URL to https://apps.facebook.com/application_name/
- Set the Secure canvas URL to https://apps.facebook.com/application_name/

The registration process results in the generation of the client application URL, the client ID, and its associated secret. Registration also generates the OAuth authorization server endpoint URLs, from where the OAuth service obtains the authorization code and access token. Some of this information is required when setting up the files that the OAuth authentication scheme uses to operate properly.

Enable the OAuth Plug–in

The OAuth plug-in is referenced in the web agent configuration file (WebAgent.conf). The plug-in lets agents communicate with an OAuth provider and forwards the OAuth provider authentication response to the Policy Server.

Contact agent owners and instruct them to enable the required plug-in.

Follow these steps:

Log in to the web agent host system.
Open the web agent configuration file. The default file location depends on the web server type:
IIS
```
agent_home\bin\IIS
```
agent_home

Specifies the agent installation path.
Oracle iPlanet (iPlanet/SunOne)
```
web_server_home/https-hostname/config
```
web_server_home

Specifies the web server installation path.
Apache, IBM HTTP Server, and Oracle HTTP Server
```
web_server_home/conf
```
web_server_home

Specifies the web server installation path.
Domino (Windows)
```
C:\lotus\domino
```
Domino (UNIX)
```
$HOME/notesdata
```

Uncomment line that loads the OAuth plug–in.

Example:

#LoadPlugin="C:\Program Files\CA\webagent\bin\OAuthPlugin.dll"

Save the file.
Restart the web server.

Modify the OAuth Forms Credential Collector

A sample OAuth FCC is included with the web agent installation. The FCC lets users authenticate by entering an OAuth provider user name.

By default, the FCC presents numerous OAuth providers. Contact the agent owner and instruct them to modify the FCC so that the file includes only those providers that the protected application supports.

The following steps explain how to modify the FCC.

Follow these steps:

Log in to the web agent host system.
Go to the following location:
```
agent_home\samples\forms
```
agent_home

Specifies the web agent installation path.
Open the oauth.fcc file with a text editor.
Review the FCC. Determine whether to add or remove a provider.
Locate the providers section in the FCC. Search on the text string var oauth_providers.

Add the missing provider entry to the var oauth_providers section. Specify the name of the application next to the apps setting.

The following excerpt shows two examples of provider entries:

var oauth_providers = {
    google : {
        name : 'Google',
        image :'images/google.gif',
		apps : 'ForwardIncGoogleApp'
		
    },
    facebook : {
        name : 'Facebook',
        image :'images/facebook.gif',
		apps : 'ForwardIncFacebookApp'
    }

Locate the applications section in the FCC by searching on the text string var oauth_applications. Specify the following information for each application:
- Application name.
- Label, which is the text that the user sees after clicking the provider icon.
- Image. The image value is the location of the provider icon that the FCC displays.
The following excerpt shows two example application entries. One is named FowardIncGoogleApp and the other is named ForwardIncFacebookApp.

Important! These application names are only example values. Enter the real application names for your deployment. Also, the application names you enter in this FCC file must match the application names you enter in the oauthproviders.xml file.
```
};
var oauth_applications = {
	
ForwardIncGoogleApp : {
	name : 'ForwardIncGoogleApp',
	label : 'Login using google application',
	image : 'images/google.ico'
	}
ForwardIncFacebookApp : {
	name : 'ForwardIncFacebookApp',
	label : 'Login using facebook application',
	image : 'images/facebook.ico'
	},
```
Remove any unnecessary providers from the FCC by commenting out the provider entry. Enter the comment string /* in front of the provider name. Enter the closing comment string */ at the end of the entry. For example:
```
/* google : {
      name : 'ForwardIncGoogleApp',
      image :'images/google.gif',
     apps : 'ForwardIncGoogleApp'
},*/
```
Save the script after all modifications are complete.
Restart the web server.

Modify the OAuth Provider Configuration File

An OAuth provider configuration file (oauthproviders.xml) is installed with the Policy Server. The provider configuration file contains configuration details of each provider and the protected application. If the file does not include the correct settings, authentication fails.

Information about the file:

By default, the file includes sample settings for all of the providers that the OAuth FCC makes available. Review the sample settings and modify them as required.
Important! The values are samples only. We recommend that you verify all configuration settings with your OAuth provider before deploying the authentication scheme.
The provider configuration is separated from the registered applications configuration to reuse the provider configuration for multiple applications.
Providers configuration details must follow application configuration details. Each application uses one of the predefined provider configurations.
Each application must have a PROVIDERLINK to one provider with which it is registered.
If you add or modify provider settings in the FCC file, also add or modify configuration settings for the provider in this file.
The application names you enter in this file must match the application names you enter in the oauth.fcc file.
If you configure mulitple OAuth authentication schemes, each scheme can use its own provider configuration file.

Follow these steps:

Log in to the Policy Server host system.
Go to the following location:
```
siteminder_home\config\properties
```
siteminder_home

Specifies the Policy Server installation path.
Make a copy of the default provider configuration file as a backup.
Open the oauthproviders.xml file.
Review the file and determine if the necessary OAuth provider settings are available. To add a provider, complete the following steps:
1. Copy an existing OAuth provider node and all of its child nodes. All provider nodes are included within the following root node:
```
<OAuthProvider>
</OAuthProvider>
```
2. Add the new OAuth provider node and all of its child nodes under the following root node:
```
<TrustedOAuthProviders>
</TrustedOAuthProviders>
```
Configure the settings for each provider. Update values for the following settings:

OAuth providername

Identifies the OAuth provider for this node. Enter the name of the provider.

Note: Use lower-case when entering a provider name.

AuthorizationURL

Provides the authorization server end-point URL for this provider. This URL must generate an authorization token after successful authentication of a user.

Google example: https://accounts.google.com/o/oauth2/auth

Facebook example: https://www.facebook.com/dialog/oauth

AccessTokenURL

Provides an access token end-point URL. A user can query for an access token by exchanging authorization code along with application configuration details.

Google example: https://accounts.google.com/o/oauth2/token

Facebook example: https://graph.facebook.com/oauth/access_token
Configure the settings for each registered application. Application nodes and all child nodes exist under the root node:
```
<Application>
</Application>
```
Update values for the following settings:
Application appname

Identifies the configuration for the OAuth registered application and the user authentication configuration. The end user must provide this identifier in the FCC page to use the configuration for the OAuth authentication.

Examples: ForwardIncGoogleApp, ForwardIncFacebookApp

Important! These application names are only example values. Enter the real application names for your deployment. Also, the application names you enter in this file must match the application names you enter in the oauth.fcc file.

ApplicationURL
Specifies the registered application URL. Update the value of this setting with the same Redirect URIs (Google) or Site URL (Facebook) you entered when you registered the application. For example, if the Google Redirect URIs value is set to the following:

Redirect URIs: https://fedserver.bizpartnerinc.ca/siteminderagent/forms/oauthcb.fcc

The value for the ApplicationURL in this file is:

</OAuthProvider>

    <Application appname="ForwardIncGoogleApp">

        <ApplicationURL>

            

            https://fedserver.bizpartnerinc.ca/siteminderagent/forms/oauthcb.fcc

        </ApplicationURL>

The format of the URL depends on the value of the SecureURLs agent parameter. Check the value of the SecureURLs parameter from the Administrative UI. The parameter is in the Agent Configuration Object for the host agent.
- If the SecureURLs parameter is set to Yes, enter the URL in the following format:
  http(s)://agent_host/siteminderagent/forms/oauthcb.fcc?SMQUERYDATA=Sample
  
  Example: https://myagent.ca.com/siteminderagent/forms/oauthcb.fcc?SMQUERYDATA=Sample
- If the SecureURLs parameter is set to No, enter the URL in the following format:
  http(s)://agent_host/siteminderagent/forms/oauthcb.fcc
ClientID

Contains the identifier of the registered client application at the OAuth server. Update the value of this setting with the generated client ID. The authorization server provides this ID value when the application is successfully registered.

Secret

Indicates the secret associated with the ClientID. Update the value of this setting with the secret associated with the ClientID. The authorization server provides this value when the application is successfully registered.

PROVIDERLINK

Links the application with a provider. Specify the providername value of a defined provider. This application uses the provider configuration while performing OAuth authentication.

Examples: google, facebook

Scope

Specifies the required type of permission the application is requesting from the user. For example, if the scope value is https://www.googleapis.com/auth/userinfo.profile, the application can gain read-only access to basic user profile information.

This scope value is passed in the authorization token request. The client can use the code to access resource URLs, which are specified in the UserInfoURL attribute. Administrator can specify a single value or multiple space separated values for this attribute.

UserInfoURL

Designates a single URL or multiple space-separated URLs for which user information can be queried with the generated access token. The URL represents the resource the that client is trying access.

UserAttribute

Specifies a user attribute. Update this value with the user identifying claim from the OAuth user information. The value of this attribute is used to disambiguate the user. For example, the user attribute can be "email."
Save and close the file.

Disable FCCCompatMode at the Agent

Disable the FCCCompatMode setting in the cam-agent configuration.

Follow these steps:

Log in to the Administrative UI.
Click Infrastructure, Agent.
Click Agent Configuration Objects.
The Agent Configuration Objects page appears.
Specify search criteria, and click Search.
A list of Agent configuration objects that match the search criteria appears.
Select the cam-agent and modify it.
Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.
Click Modify.
Set the FCCCompatMode setting to no.
Save the change.

Configure the OAuth Authentication Scheme

Configure the OAuth authentication scheme object using the Administrative UI.

If your network includes multiple cookie domains and each cookie domain requires the authentication scheme, configure a separate authentication scheme object in each cookie domain.

Note: For operation on Solaris platforms, modify the java.security file in the directory jre_root/lib/security so that the sun.security.provider.Sun provider is registered as the first provider.

Follow these steps:

Click Infrastructure, Authentication, Authentication Schemes.
Click Create Authentication Scheme.
Select the new object option and click OK.
The Create Authentication Scheme page appears.
Enter a name and a protection level.
Select the OAuth template from the Authentication Scheme Type list.
The scheme-specific settings appear.
Configure the remaining parameters and click Submit.
Important! Restart the Policy Server if you change any of the proxy settings.

You have completed the required tasks to configure an OAuth authentication scheme. You can now use the authentication scheme in a policy or application component to protect resources.