Introduction

The authentication module for OA4MP can be replaced by various means, such as using Tomcat's built in management, or even a complete standalone replacement. 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, since you establish a trust relation that logins on the proxy are exactly the logins on your system..

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. There is nothign special about this client, it is a standard OAuth or OIDC client.

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 should 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"
                        />

Configuring the client

The server configuration attribute cfgFile points to a standard OA4MP client configuration. This may be in its own configuration file or in the main server configuration, e.g.

<config> <service> ... server config </service> <client> .. client config </client> </config>

Using the Proxy

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, the default
  • [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 the scopes your client is to use with the proxy

Using the scopes in the client configuration

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. In that case, the proxy simply confirms that the user has a valid login on that system. A list that contains an asterisk ("*") means to request all scopes in the client's configuration file. If there is an asterisk anywhere on the list, all are requested.

Forwarding the scopes from the request.

It is also possible that the client should simply forward scopes from the user request. In that case, set the attribute forward_scopes_to_proxy to true. (Since the user may be requesting scopes for refresh and access tokens as well, this implies the proxy service is able to resolve these, so it is also performing authorization for the user.) If this flag is true, then the of scopes in the configuration you have will be ignored.

Note that forwarding has precedence, so setting this flag true will override sending scopes in proxy_request_scopes.