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.
sm1252sp1
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 process to configure an OAuth scheme involves configuration tasks at the Policy Server and the Agent.
  • 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.
Configure OAuth authentication
Configure OAuth authentication
Review the OAuth Authentication Process
The following process explains how the OAuth authentication scheme works:
  1. A user requests a resource.
  2. The agent intercepts the request and contacts the Policy Server to see if the resource is protected.
  3. 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).
  4. The agent redirects the user to the FCC.
  5. The user selects an OAuth provider and submits credentials at the provider site.
  6. The FCC constructs the user identifier and passes it to the Policy Server.
  7. The Policy Server redirects the user to the OAuth provider by constructing an authentication request.
  8. The user authenticates with the OAuth provider using provider-specific credentials.
  9. The provider redirects the successful authentication response to the FCC.
  10. The agent passes the authentication response to the Policy Server.
  11. 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.
    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.
  12. The Policy Server returns the session details of the authenticated user to the FCC.
  13. 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
The Agent owner completes the registration task.
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 URL 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:
  1. Establish a Google Apps account.
  2. Navigate to https://code.google.com/apis/console and log in.
  3. 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
  4. Click Create clientID.
  5. 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)
  6. Click Update.
The Google registration process is complete.
Facebook
Follow these steps:
  1. Establish a Facebook account.
  2. Go to https://developers.facebook.com/apps.
  3. Choose the AppName and click Continue.
  4. Enter the captcha text that is displayed and click Continue.
  5. 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)orhttp
    (s)://agent_host
    /siteminderagent/forms/oauthcb.fcc?SMQUERYDATA=Sample(SecureURLs set to Yes) 
  6. Click Save changes.
  7. 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 at the Agent
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:
  1. Log in to the web agent host system.
  2. Open the web agent configuration file. The default file location depends on the web server type:
    IIS: 
    agent_home
    \bin\IIS
    agent_home s
    pecifies the agent installation path.
    Oracle iPlanet (iPlanet/SunOne): 
    web_server_home
    /https-hostname/config
    web_server_home s
    pecifies the web server installation path.
    Apache, IBM HTTP Server, and Oracle HTTP Server
    web_server_home
    /conf
    web_server_home s
    pecifies the web server installation path.
    Domino (Windows): 
    C:\lotus\domino
    Domino (UNIX):
     $HOME/notesdata 
  3. Uncomment line that loads the OAuth plug-in. 
    Example:
    #LoadPlugin="C:\Program Files\CA\webagent\bin\OAuthPlugin.dll"
  4. Save the file.
  5. Restart the web server.
Modify the OAuth Forms Credential Collector at the Agent
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:
  1. Log in to the web agent host system.
  2. Go to the location 
    agent_home
    \samples\forms
    agent_home
    specifies the web agent installation path.
  3. Open the oauth.fcc file with a text editor.
  4. Review the FCC. Determine whether to add or remove a provider.
  5. Locate the providers section in the FCC. Search on the text string
    var oauth_providers
    .
  6. 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' }
  7. 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.
    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' },
  8. 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' },*/
  9. Save the script after all modifications are complete.
  10. 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.
    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 that 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:
  1. Log in to the Policy Server host system.
  2. Go to the following location:
    siteminder_home
    \config\properties
    • siteminder_home
      Specifies the Policy Server installation path.
  3. Make a copy of the default provider configuration file as a backup.
  4. Open the oauthproviders.xml file.
  5. 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>
  6. 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.
      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 with application configuration details.
      Google example
      : https://accounts.google.com/o/oauth2/token
      Facebook example:
      https://graph.facebook.com/oauth/access_token
  7. 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
      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>
                  <!-- HOSTNAME : WebAgent/SPS host name -->
                 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 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."
  8. Save and close the file.
Disable FCCCompatMode at the Agent
Disable the FCCCompatMode setting in the cam-agent configuration.
Follow these steps:
  1. Log in to the Administrative UI.
  2. Click Infrastructure, Agent.
  3. Click Agent Configuration Objects.
  4. The Agent Configuration Objects page appears.
  5. Specify search criteria, and click Search.
    A list of Agent configuration objects that match the search criteria appears.
  6. Select the cam-agent and modify it.
  7. Click Modify.
  8. Set the FCCCompatMode setting to no.
  9. 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.
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:
  1. Click Infrastructure, Authentication, Authentication Schemes.
  2. Click Create Authentication Scheme.
  3. Select the new object option and click OK.
    The Create Authentication Scheme page appears.
  4. Enter a name and a protection level.
  5. Select the OAuth template from the Authentication Scheme Type list.
    The scheme-specific settings appear.
  6. Configure the remaining parameters and click Submit.
  7. (Optional) To configure the connection timeout and socket timeout values, perform the following steps:
    1. Navigate to <
      installation_home
      >/config/ and open the JVMOptions.txt file.
    2. Add the following parameters to the file:
      -Dauthscheme.oauth.connection_timeout=30000
      -Dauthscheme.oauth.socket_timeout=60000
    3. Modify the values, if required. 
    4. Save the changes.
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.