Replacing the authorization servlet

It is also possible to replace the authorization servlet in any version of OA4MP with a customized version. You may then, for instance, use LDAP or Shibboleth for authentication. The protocols require that your module occupy the authorize endpoint. The assumptions then are that

  • Your module will handle the authentication.
  • After a successful authentication, your module will make a callout to another, private endpoint.
  • This private endpoint is tasked to set up all the state and check that the request is valid. Skipping a call to this module means there will be no state for this request and all subsequent attempts to use the service will be rejected.
  • This private endpoint is either protected at the network level (access via Apache) or with a security constraint in Tomcat (Tomcat only servers).
  • Your call to this will follow a mini-protocol, then process the response. Each version of OA4MP has its own details on this.

Having Tomcat handle security.

If you have a Tomcat only service, then you must protect this endpoint. A typical security security constraint is the following, which should be added to the deployment descriptor (web.xml file)

    <security-constraint>
           <web-resource-collection>
               <web-resource-name>Lockdown_initiate_endpoint</web-resource-name>
               <url-pattern>/authorized</url-pattern>
               <http-method>GET</http-method>
               <http-method>POST</http-method>
               <http-method>PUT</http-method>
               <http-method>DELETE</http-method>
           </web-resource-collection>
           <auth-constraint/>
       </security-constraint>

which will prevent all access to the authorized endpoint except from Tomcat itself. If you access the service from Apache, you will have to limit access to this endpoint at the server level to calls from localhost only. The authorized servlet comes with this security constraint enabled by default since it is better to have the authentication fail if there is any question about the setup.

Accessing the Authorized Servlet for OA4MP under OAuth 1.0a

The initial setup

Since OA4MP is no longer authorizing the login (e.g. Shibboleth is), you need to deploy the correct servlet in your web.xml file, to wit AuthorizedServlet. So a typical entry would look like
<servlet>
       <servlet-name>authorized</servlet-name>
       <servlet-class>edu.uiuc.ncsa.myproxy.oa4mp.server.servlet.AuthorizedServlet</servlet-class>
       <load-on-startup>0</load-on-startup>
   </servlet>
   <servlet-mapping>
       <servlet-name>authorized</servlet-name>
       <url-pattern>/authorized</url-pattern>
   </servlet-mapping>
NOTE that the endpoint is authorized for here. See below for more details on accessing this. In effect, to be spec. compliant, a mini-API is implemented for this which will now be explained.

The mini-protocol

The specification requires that the call to your module has the oauth_token present, which you must pass on to the authorized servlet -- this the internal identifier linking the user to their request. A common method of deployment, e.g for Shibboleth, is to use Apache with ProxyPass for Tomcat and only allow localhost access to Tomcat. Your module can then call Tomcat. The expected request to the server consists of 4 parameters:

  • username the username that the user authenticates with
  • password the password used
  • lifetime the certificate lifetime (in milliseconds)
  • oauth_token the token generated in the initial request by the server
A typical example invocation would be
localhost://oa4mp.bigstate.edu:8080/authorized?oauth_token=sj38GHTYf24354&username=bob&password=somepassword&lifetime=100000000
Assuming that your oa4mp instance is deployed at oa4mp.bigstate.edu. It is assumed that all parameters will be url escaped. The response contains two items
  • status a code, "ok" indicating success
  • redirect_uri which is the redirect generated by OA4MP. This should be used to redirect the user's browser and is, if you recall, generated from information only OA4MP has in the client's initial request.
For instance the body of the response contains the following two lines to parse:
status=ok
redirect_uri=https%3A%2F%2Fportal.example.edu%2Foauth%2Fready%3Foauth_token%3Dhdk48Djdsa%26oauth_verifier%3Dhfdp7dh39dks9884
If there is an error, then the first line will not have a status of "ok" and an error should be issued by your module. (Don't forget to check the OA4MP logs to find why it failed!)

Accessing the Authorized Servlet for OA4MP under OAuth 2.0

Initial setup

The servlet used in this case is named OA2AuthorizedServlet. So a typical entry would look like

  <servlet>
      <servlet-name>authorized</servlet-name>
      <servlet-class>edu.uiuc.ncsa.myproxy.oa4mp.oauth2.servlet.OA2AuthorizedServlet</servlet-class>
  </servlet>
  <servlet-mapping>
      <servlet-name>authorized</servlet-name>
      <url-pattern>/authorized</url-pattern>
  </servlet-mapping>

Note that the name of this servlet may be altered without changing the protocol. Some installation prefer to call it /init since authorize and authorized are very similar.

The mini-protocol

The very first step in the OAuth 2.0 protocol is that the user goes to the authorize endpoint which will then simply call the end authorized endpoint by passing along verbatim the original request your authorization module received. For instance, if your server got the following request

https://your.server.edu/oauth2/authorize?state=s0jByyFvSNeoDUZ1GbyRy&nonce=ABC75344A&...

You do the authorization and once completed successfully, you call the authorized servlet:

https://localhost/oauth2/authorized?state=s0jByyFvSNeoDUZ1GbyRy&nonce=ABC75344A&...

All state and error checking will be done for you. You will simply receive the standard response (with HTML status code of 200, since 302 is reserved for error conditions -- see below for more) in JSON of the token and the state (if that was passed in the initial request) -- simply pass this response back to the client in the standard OIDC redirect. For instance

    {"code":"urn:oauth2:aMQ53UmEtb5cM6WF/ps7wOmYQoJTTKAW9","state":"s0jByyFvSNeoDUZ1GbyRy"}

Errors

The authorized servlet supports all of the same error codes as the standard OAuth 2.0/OIDC specification. This means that there will be an HTML status code of 302 (a redirect) to the callback url that the client supplied (in the request and at registration). This may again be passed along directly to the client which is required to process it. For example, if the above request were invalid and had consequently, failed then if the base url of the error is https://your.client.org/cb your authorize module would get the following redirect, as per the OA4MP/OIDC spec:

    Location: https://your.client.org/cb?
      error=invalid_request
      &error_description=
        the%20request%20is%20not%20valid%20or%20malformed
      &state=s0jByyFvSNeoDUZ1GbyRy

Last modified 10/25/18.
©2000-2013 Board of Trustees of the University of Illinois.