Using the Authentication Configuration

Authentication in OA4MP may be accomplished in several ways. This configuration element will tell the system which method you are using. Note that the OAuth specification places authentication at the /authorize endpoint, which does not help clarity. For purposes of this blurb, these should be considered synonyms, but OA4MP itself has stark differences between them. T

  1. Replace authorization completely In this case, you may write anything you like independent of OA4MP. CILogon, for instance, has its authorization layer written in PHP. You then notify OA4MP when you are done.
  2. Use Tomcat and have it manage users. This can work for very small systems.
  3. Use a proxy, i.e., another OAuth server's authorization.

The configuration has the elements for all three cases.

Attribute Required? Default Description
authorizationURI N -- (Replace authorization case). This is the address of whatever application does the authorization. This must be specified so that it can be put into the well-known endpoint for discovery by other services. It is required in the replacement case, but otherwise will be generated as per standard location.
use N default Which paradigm of authentication you are using. Options are
  • default - extending the Java classes in OA4MP for direct user support
  • proxy - use a proxy
  • header - use an HTTP header to identify the user
  • external - Use and external authentication server and notify OA4MP with it DI Service
  • dedicated - Use OA4MP as a dedicated token issuer
useProxy N false (Deprecated) If "true" this is the same as setting the use attrbute to "proxy".
See also cfgFile and cfgName
cfgFile N (Proxy case) This is required if useProxy is true and ignored otherwise. This is the path to the client configuration file.
cfgName N (Proxy case) This is required if useProxy is true and ignored otherwise. The name of the configuration within the cfgFile to use.
localDFConsent N false (Proxy case) As per the OIDC specification, showing a consent screen is optional. When proxying, this will request that the proxy redirect the user back to the local service to use the consent screen there. Otherwise, the assumption is that the consent the user gave on the proxy is sufficient. Also, note that the request parameters used are OA4MP only, so if you are using another system for proxying, the request will be ignored by that proxy.
useHeader N false (Deprecated) Use an HTTp header. Same as setting the use attribute to "header".
requireHeader N false (Header case) 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 REMOTE_USER (Header case) The name of the header field to use. Generally this is REMOTE_USER. Other fields are permissible.
returnDNAsUsername N N/A (Deprecated) 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 (Deprecated) 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.

Example of each

A Proxy Example

<config>
   <server name="my-config">
      <authorizationServlet use="proxy"
           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 proxies

Header case, with the REMOTE_USER Header

<config>
   <server name="my-config">
      <authorizationServlet use="header"
          headerFieldName="REMOTE_USER"/>
      <!-- rest of config -->
   <\server>
<\config>

In this case, use of authentication 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. Be sure to enable the correct machinery in the web.xml file. The one supplied with the standard distribution is annotated.

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.

Replacing the authorization module with a Java extension of OA4MP

Acomplete example of a an extensioin. Either no configuration or if you want to make it explicit. 
<config>
   <server name="my-config">
      <authorizationServlet use="default"/>
      <!-- rest of config -->
   <\server>
<\config>

This tells the system that the entire authorization is handled at the endpoint in the OAuth specification and the well-known file generated by OA4MP will point to that. See below for the particulars of how to integrate it with OA4MP.

Using your own Authentication Server (AS)

In this case, you have an external AS which handles all authentication and you need to simply notify OA4MP of its state. 

<config>
   <server name="my-config">
      <authorizationServlet use="external"
          authorizationURI="https://your.AS.address"/>
      <!-- rest of config -->
   <\server>
<\config>

In this case, the well-known file points to the authorizationURI value and all clients will therefore make requests to that. Your AS should be able to do all the authentication needed. OA4MP must be configured to run its DIService so your system can send it notifications.

Additionally, make sure that if you set the device endpoiont for the device flow (so user's are directed to your AS to authenticate for the device flow) by configuring the verficationURI in the deviceFlowServlet configuration. The device_authorization endpoint (where user's start the device flow) must be managed by OA4MP, since that sets up all the state needed for the flow, although you can hide it and simply call it on behalf of users.

Using OA4MP as a Dedicated Issuer

In this case, you have a DTI (Dedicated Token Issuer) service that generates token requests which OA4MP will service, but there is need for the DIService. All that is needed is the endpoint for your service to be specified in the configuration so it will be correctly set in the well-known page:

<config>
   <server name="my-config">
      <authorizationServlet use="dedicated"
          authorizationURI="https://your.DTI.address"/>
      <!-- rest of config -->
   <\server>
<\config>

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.

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
authorizationGrant String This is the token sent to the authorize endpoint as per the specification and identifies this user's delegation request uniquely.
authorizationState String This is the (optional) state parameter the user sent in the initial request. It is echoed back.
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.