Introduction

The authorization module for OA4MP can be replaced by various means, such as using Tomcat's built in management. However, this means that you will need to have separate logins that you manage for each user. Another option is using a proxy service. This is an OIDC service that allows for logins. Your OA4MP can simply forward all requested scopes to that service (including the device flow) and use the service, allowing your users to effectively log in there. In short, it allows some other service to do all your user management.

How does this do it?

You need to register a client with the proxy service (henceforth known as the proxy), then enable using proxies in your server configuration (see below). Since the service is a client of the proxy, you need to enable the callback servlet and register that as the callback.

Configuring the server

The Tomcat deployment descriptor (web.xml)

There is an included web.xml file, called proxy.xml that has a complete setup. Copy that over your web.xml file. The major point is that it enables the callback servlet (with endpoint ready) at 

/oauth2/ready

and when you are registering your client with the proxy, you need to set this callback to 

https://host:port/oauth2/ready

in a standard install. Key points are that https should be available, and that your server should be at host:port. The proxy must be able to contact your callback endpoint securely, so self-signed certs hould be avoided unless you have a specific agreement with the proxy.

The server configuration proper

You need to have using the proxy enabled within the authorizationServlet tag and set the configuration file as well as the name of the configuration for the client. Remember that this file is the configuration for a complete OAuth 2 client. If you need to, read up on the client configuration file syntax. A very typical entry in the server configuration file would be 

    <authorizationServlet useProxy="true"
                          cfgFile="/opt/oa4mp/etc/client.xml"
                          cfgName="cilogon-proxy"
                        />

Using the results

When your service contacts the proxy, a complete exchange is done including getting any claims from the proxy. This means that these are available for your service to harvest. The system will always set the subject to the subject returned by the proxy. You may configure a list of other claims from the proxy to be returned. This is done in the proxy_claims_list property of the client. The options there are

  • * = (an asterisk) pass along all claims
  • [claim0,claim1,...] = list of specific claims. Note that putting * in this list will simply return all claims.except audience, issuer, issued at, expiration because these must come from the current server, not the proxy (or any consumer of the id token must reject it.)

So if the proxy returns the following claims 

    {"sub":"user_123",
     "idp":"https:shibboleth.big_state.edu",
     "is_member_of":["admin","all-users","admin-phys"]
    }

Then at the least the server returns the "sub" claim. If you set the client's proxy_claims_list to do so, you may also return the idp or is_member_of claim. If you set the proxy_claims_list to be "*" then all relevant the claims will be passed along.

Configuring your clients

Each client may be configured to request specific scopes from the proxy. These are in the attribute proxy_request_scopes. An empty list means to request no scopes. A list that contains an asterisk ("*") means to request all configured scopes. If there is an asterisk anywhere on the list, all are requested. It is also possible that the client should simply forward scopes in the user request. In that case, set the attribute forward_scopes_to_proxy to true. If this flag is true, then any list of scopes you have will be ignored.