Using the Authorization Servlet

OA4MP has an authorization module that is built in. This may be replaced by installations as needed. Part of the specification is that, if this is disabled, the username and information about the client making the delegation request must be shown. This is called client verification and is required by the OAuth protocol. You may have OA4MP do this or disable this as well, though it is encumbant on the installation to show this information. This results in 3 use cases which are discussed below in depth, after the table of attributes.

Attribute Required? Default Description
useProxy N false Valid values are "true" or "false". This flag determines whether or not to use a proxy for authorization.
See also cfgFile and cfgName
cfgFile N This is required if useProxy is true and ignored otherwise. This is the path to the client configuration file.
cfgName N This is required if useProxy is true and ignored otherwise. The name of the configuration within the cfgFile to use.
useHeader N false Valid values are "true" or "false". This flag determines whether or not to enable this facility. Default is to not use this.
requireHeader N false Valid values are "true" or "false". This flag forces the server to use the specified header. Note especially that if this is true and no such header is received then an exception is raised.
headerFieldName N N/A The name of the header field to use. Generally this is REMOTE_USER, but this must be specified. Other fields are permissible.
returnDNAsUsername N N/A Valid values are "true" or "false". This flag forces the server to return the DN (distinguished name) on the certificate as the username, as opposed to the usual name of the user. This has nothing to do with enabling the use of the header field.
convertDNToGlobusID N N/A Standard DN's (Distinguished names) are comma separated. Some versions of Globus, however, require that these be slash delimited. Enabling this option will convert commas to slashes using Globus's own utility for doing this. This means that you must follow the installation instruction for JGlobus to your Tomcat. Generally this option should rarely, if ever, be needed, so don't just enable it unless you are sure you know what it does and need it.

An Example of using a proxy

<config>
   <server name="my-config">
      <authorizationServlet useProxy="true"
           cfgFile="/opt/oa4mp/etc/clients.xml">
           cfgName="cilogon-proxy">
      <!-- rest of config -->
   <\server>
<\config>

In this case, there is a service configured (you have registered a client with it) and you need to have calls for authorization forwarded to it. All you need to do is ensure the configuration in the file is correct and that your Tomcat web.xml file is set right and you are good to go. See more at using prooxies

An Example of using remote user

<config>
   <server name="my-config">
      <authorizationServlet useHeader="true" headerFieldName="REMOTE_USER">
      <!-- rest of config -->
   <\server>
<\config>
In this case, use of authorization headers is enabled and a header named REMOTE_USER will be used. If it is missing though, no exception will be raised. By default, the header field will be shown to the user along with client information and the user will be prompted if s/he wishes to continue.

Use cases

There are three main use cases which should be discussed in more depth. The particulars of how to configure and authorization module are best dealt with elsewhere and a discussion can be found here.

Using the OA4MP authorization module

This is the default. In this case a logon will be shown to the user who will be prompted for the username and password. Since this page also contains the client information, the verification portion of the protocol is deemed satisfied. We highly recommend customizing the basic OA4MP page for a consistent look and feel in your site.

Using another authorization module, but using OA4MP's verification page.

In this case, the username and (possibly) password will be delivered in the header. We generally suggest that standard practice of using the REMOTE_USER header be used. Unless explicitly disabled, the verification page with the displayed username will be shown.

Options that may be configured here to

  • use the header
  • required the header
  • specify the header name

Specifying that the header should be used implies that the header may be present. Since the username may be created also via an extension to the system (see below for details) the lack oof a header field is not an error. However, requiring the header will cause an exception if the header is not found. The default is to assume that the header is the REMOTE_HEADER field, though any field name may be specified.

Completely replacing the authorization module.

In this case the server must have some way of performing the client verification. You will need to write a webapp that completely takes over the functions at the authorize endpoint. (found in the javadoc) should then be deployed elsewhere and invoked by your webapp when it has the username and password (if needed). Note that it is up to you to keep access to this servlet safe. We normally suggest that access be restricted to localhost only, so that only your webapp has access to the AuthorizationServlet. The AuthorizationServlet accepts the following call directly:

Parameter key Parameter values Comment
oauth_token String This is the token sent to the authorize endpoint as per the specification and identifies this user's delegation request uniquely.
AuthUserName String The username that will be sent unchanged to MyProxy
AuthPassword String (Optional) the password the user will require to log in to MyProxy.
lifetime int (Optional) The lifetime for the certificate. The client may request any value in the initial request, but server policies may override this here. If missing, the request sent by the client will be used and if there is none, any defaults will be used.

Customizing the username sent to MyProxy programatically . The UsernameTransformer

In this case, which e.g. occurs when using Shibboleth, you may create a completely customized handler that will allow you to create virtually any customized username for MyProxy you want from the request. You may also use it to set the username returned in the getCert response. This consists of a interface called UsernameTransformer which has two methods:

  • createMyProxyUsername(HttpServletRequest) -- returns the username for MyProxy
  • createReturnedUsername(HttpServletRequest, String) -- returns the username in the getCert response.
Generally you would implement this as a class and in the ServiceConfigLoader over ride the getUsernameTransformer

to return an instance of your transformer. This will be automatically invoked at the approprate time. If either of these methods return a null value, then they are simply ignored.