The Command Line Test Client

New to version 3.3 of OA4MP for OIDC is a command line client. This allows you to register a client with a server and issue commands to the server to get access tokens, refresh tokens, user information and certs (assuming the server supports these). The only caveats are

  • You must register a client with the server. This must not have a functional callback.
  • You must manually cut and paste after authentication. This cannot be altered without changing the security model for OA4MP.

What it is

This command line utility allows you to issue commands against the server and view responses. Talking to a server requires some complex state generation and management. The client does all of this for you. The supported commands are

  • clear -- clear the current state and start over
  • exit -- end the session and shut down the client.
  • geturi -- this creates the URI (not trivial as it requires a lot of parameters) that you copy and paste in to your browser.
  • setgrant-- This is invoked on the callback uri from the server. It will grab the state information and manage it.
  • getat -- Get an access token. You may also get a refresh token at this time if the server supports this.
  • getuserinfo -- use the current access token to get the user's information
  • getcert -- get a certificate
  • savecert -- save the certificate to a file in PEM format
  • getrt -- get the next refresh token


You must register the a client with the server as per this. The trick that makes this work, however, is that the callback URL you supply must be invalid, i.e., the callback from the server must fail. This will allow you to get the OAuth transaction state.


The client is called either directly or through the oa2-client script. You need to specify the configuration file name and the name of the configuration.

    java -jar /opt/oa2/oa2-client.jar -cfg ~/config/clients.xml -name oa4mp2
    OA4MP Client OAuth 2 configuration loader, version 4.1 startup on Thu Aug 11 13:46:26 CDT 2016

The last line is the prompt. The startup message tell you that the loader found everything and there were no issues. You are now ready to start talking to an OA4MP OAuth 2 server.

Getting the correct URI

Issue the following geturi call:


The command causes a uri to be generated with the full state for the OIDC request (which is actually hard to make, hence the call). As with all calls, you can get a description of what it is and does by supplying the argument --help:

    client>geturi --help
    Usage: This will create the correct URL to pass to your browser.
           This URL should be pasted exactly into the location bar.
           You must then authenticate. After you authenticate, the
           service will attempt a call back to a client endpoint which will
           fail (this is the hook that lets us do this manually).
           Next Step: You should invoke setgrant with the callback uri from the server

You must cut and paste this into your browser. You will then complete the authorization there and then next step will fail. What has happened is that the server tries to do the callback to the supplied (bogus) URI and, of course, there is nothing at the endpoint. You take this callback from the browser's location bar and invoke the setgrant call


This call will update the internal state of the program. (This is managing a full client instance behind the scenes which takes quite some little work, but fortunately, you don't have to do any of that.) It prints out the grant that the server issued, mostly so you can see it. Now you are in a position to get an access token. You should issue the getat call

     access token =
    refresh token =
    RT expires in = 1000000000 ms.
       expires at Sat Sep 24 05:52:09 CDT 2016

This gets the access token from the server as well as any refresh token. It then prints out a small summary of these. (And it updates the internal state of the client, of course.) There are various things you can do at this point. since you have a valid access token. Nota Bene: an access token is valid for a short time -- server default is about 15 minutes. If you attempt to use the access token after that to get, say, a certificate, then you will get an error from the server. Notice though that the refresh token expires far into the future, in this case 1,000,000,000 ms or about 11.5 days. You may use the getrt call to get a new access token and refresh token:

     access token =
    refresh token =
    RT expires in = 1000000000 ms.
       expires at Sat Sep 24 23:05:51 CDT 2016

In any case, as long as you have a valid access token, you may get a certificate or user information. We will do examples of each of these in turn. First, the getuserinfo call.

    user info:
              sub = jgaynor

In this case the test server we are using is configured for the absolute minimum of information. It merely returns the username (i.e. the name used to authenticate). The getcert call will return a certificate and if the server returns the username (which is the same as the subject of the user info call) it will be displayed too:

    returned username=jgaynor
    -----END CERTIFICATE-----

You may cut and paste this or you can save it (PEM encoded) to a file using the savecert command:

     client>savecert /tmp/mycert.pem
     File "/tmp/mycert.pem" saved successfully.

It is useful to state that you may keep renewing the refresh token and getting certs. As long as you renew the refresh token before it expires, this may be done indefinitely. As long as you have a valid access token (such as right after getting a new refresh token) you may get a cert.

Last modified 11/20/19.
©2000-2013 Board of Trustees of the University of Illinois.