The Discovery Service

OA4MP (for OIDC) supports the .well-known endpoint, as per RFC 5785 OAuth 2 Discovery, and OIDC discovery. It should be noted that each instance of OA4MP will have its own location for this which corresponds to that instance. This allows for multiple services in a single domain.

You may also use the discovery service to get the public signing keys. This is at the certs endpoint.

By the specification

According to the specifications (RFC 8414, RFC 5785) a request to the service at the .well-known end point must return the information for the OAuth server. This means that

  • If Apache webserver is fronting Tomcat, you must use mod_rewrite to forward any requests to the OA4MP Discovery servlet
  • In a Tomcat only install, you should install the RFC8414 servlet that will automatically forward the requests.

It is also possible to just use the rewrite valve in Tomcat to forward requests, however, since it is possible to have multiple OA4MP instances each with its own Discovery service, the RFC8414 servlet is much more flexible.

A note on issuers.

OA4MP allows for multiple issuers with their own keys and hence discovery pages to be created. The normal way this works is that a virtual organization is created and

Example accessing the well-known page

In this case, Tomcat has been configured to return the well-known page for a single OA4MP install using the RFC8414 webapp. A request to https://services.bigstate.edu/.well-known/openid-configuration will be forwarded to the OA4MP instance and serviced there. See the next example for a typical response.

Example accessing the OA4MP Discovery service directly

If OA4MP is hosted at https://services.bigstate.edu/oauth2, then the discovery service is at https://services.bigstate.edu/oauth2/.well-known/openid-configuration and will return a JSON object such as 

    {
     "authorization_endpoint": "https://services.bigstate.edu/oauth2/authorize",
     "registration_endpoint": "https://services.bigstate.edu/oauth2/register",
     "token_endpoint": "https://services.bigstate.edu/oauth2/token",
     "userinfo_endpoint": "https://services.bigstate.edu/oauth2/userinfo",
     "issuer": "https://services.bigstate.edu/oauth2",
     "token_endpoint_auth_methods_supported": ["client_secret_post"],
     "subject_types_supported": ["public"],
     "scopes_supported":  [
      "email",
      "edu.uiuc.ncsa.myproxy.getcert",
      "openid",
      "profile",
      "org.cilogon.userinfo"
     ],
     "response_types_supported":  [
      "code",
      "token",
      "id_token"
     ],
     "claims_supported":  [
      "sub",
      "aud",
      "iss",
      "exp",
      "iat",
      "email"
     ],
     "id_token_signing_alg_values_supported":  [
      "RS256",
      "RS512"
     ],
     "jwks_uri": "https://services.bigstate.edu/oauth2/certs"
    }

Clients will parse this and use bits of the information (such as which signing algorithms are supported and the location of the public keys). There may be some variation, of course, depending on the server's exact configuration.

Getting the signing keys

This would live at jwks_uri address from the discovery service, so you can go to https://services.bigstate.edu/oauth2/certs from the above example and this will return a JSON WebKey object: 

 {"keys": [
   {
   "n": "4x7MbZyiKgD5xnEUOlPugxlUzLdNhbCXJqvrgRNj8w-O2hoHbnbJoA8rppco86LZ1W7WIIeOixw2YncKu5kISxq7lzMa_RNYOghkbeJzhs1PB_rUVkuZyySuLK9I2Q_2nfzlggVgn32JXiGR-u3ZqClGODJ8nh5m-H3eGR7-es2A3abQ4BydXbnAbFTTXMMk0C2w1eM5wgp15ZifdP6zfWkwsTpBYU80dRU1NpyZ2hryBtj6CS2sRKY9U09v-B0WlUL6m9RTDlxeQLwoz89XCe02zAftkTcAEQP56zs8SpUYQX_rVNtdI5KyMiOG8qbuYSt17GYynUB18zgc7sTzQ",
   "e": "AQAB",
   "alg": "RS512",
   "kid": "asdwer34df",
   "use": "sig",
   "kty": "RSA"
  },
   {
   "n": "JFsi9rKTZXkiuXBBX2xt4KQx6AgtjzwUkGHNWFEFIpTs2UiRhtTVLNDAU1ocP512uFPb6iQMe6sIdzxntF_bbstHWEtxLsJmqEgObcniI3jcSDtlnxSNuZUUCtNg1jvxxDSOx4yGtTJgQ8JIqhzrDErCG7rqi-gth2oMLtGHtJji9urMuUch42iRI-YoQ7FkFxGlHYZM23U00h0WKilXB5n-zXgoNZC_ALzhKG5dpZh8BsVC_yTrYAP1cCx8kmie8p7Z9V1U42yHiPxSNkIPuLlpXr4xmWLyD7jVm7ppQVQjWjxNlSBrAzjpYF7BMxWd0k8oJnou_1Pa9uK9z396BQ",
   "e": "AQAB",
   "alg": "RS256",
   "kid": "9k0HPG3moXENne",
   "use": "sig",
   "kty": "RSA"
  }
 ]}