Dynamic Client Registration

The dynamic client registration specification is supported in OA4MP as of version 4.2. This means that a trusted administrative client can dynamically create regular clients for use with an OA4MP system. If you have not done so already, you should read the section on administrative clients .

Note: When we refer to a client we mean an OAuth 2 client and otherwise any other will be qualified such as "admin client".

How's it work?

If you are not an administrator and just need a client, you should go to ../oauth2/register. Your request will then be seen by the site adminstrator(s) and once approved, you will be notified. The facilities described in this document allow for a trusted (after vetting, of course) site manager who must manage several OAuth clients to do so without having to resort to the usual vetting process.

How to become an admin

You must register an administrative client as per here.

Implemented specifications here.

The two specifications that are behind this are RFC 7591 and RFC 7592. The flow is that you register an administrative client. This is initially not approved and any operation you try will fail with a message to that effect. We get an notification and once the admin client is approved, it may be used. All calls then create regular (not admin!) clients for use with OA4MP.

The RFCs specify a REST-ful API for clients, so that

  • POST creates a new client
  • GET lists what the server knows about this client
  • PUT will update the client
  • DELETE will remove the client and all of its information from the server

Note: OA4MP does have one nice little extension for querying clients. If you do a GET with no client id, then a list of all client ids and their names will be returned.

The toolkit

Included with the latest release on GitHub are a suite of associated command line scripts in oidc-cm-scripts.tar aka the toolkit which contains a complete but minimal functional toolkit. There are basic scripts for each method as well as several examples for using each.

To dynamically register a client you need to make a call to the supported service endpoint, typically ../oauth2/oidc-cm with the appropriate HTTP method and payload. The specification should not be repeated here but the toolkit has a tutorial and many examples. There is also a very detailed readme.txt in the toolkit.

Parameters specific to OA4MP

OA4MP allows you to specify several client properties that it uses which are not in the specification. These are

  • at_lifetime = the lifetime in seconds that an access token may have
  • cfg = a configuration (JSON) for managing ID, access and refresh tokens and for running QDL scripts.
  • rt_lifetime = the lifetime in seconds that a refresh token may have
  • strict_scopes = a boolean that when true (default) will reject any scopes not explicitly set. When false, any scope may be sent. This is typically set to false for clients that return JWTs as access tokens.

Note that all of these are subject to server policies. You may request an outlandish refresh token lifetime, e.g., but if serverpolicy restricts it, then the server will make the final determination. See the table below for the specifics.

Notes on Legal Requests

What values can be sent and are accepted?

Valid values
Parameter Required? Values Comments
name Y The human readable name for this client, to be displayed on the consent screen. Note that the RFC's do not require this, but OA4MP does.
callback_uri Y A JSON array of callback uris. You must have at least one callback uri. Note that the OAuth spec. requires that this be checked as a string against requests to the server that include it. No checking is done to resolve the address, so it is a bad idea to, e.g. have a raw IP address. By the same token, you can include parameters and such, but if they vary at all in the requests, then the request will be rejected. If you need to have some form of state management for each request, you should send the state parameter in the initial request. This is guaranteed to be returned to you unchanged as a parameter in the callback.
grant_type N Either a JSON array of blank delimited list which may contain
authorization_code (default),
refresh_token
urn:ietf:params:grant_type:token_exchange (for token exchange)
If omitted, the assumption is authorization_code. If the refresh token lifetime (rt_lifetime) is specified, then refresh_token is added to the list of accepted grants.
response_type N code (default), id_token. Response types the client may support. If a requested response_type is not on this list, it should be rejected. Note that the initial request always must have the type "code." The others are used at other points and sent along in those requests, e.g. getting a refresh token requires you send "refresh_token" to the token endpoint.
contacts N A list or string This should contain the valid email for a person to contact in case there is an issue with the client. You should assume that if you are going to be contacted at this address it will only be because of some dire issue. Supplying a generic institutional email is useless. The spec. allows for multiples but we only support a single (at this writing) so only the first will be used if a list is sent.
scope N Either a JSON array or blank delimited list of scopes If you wish to use OIDC, you must at least supply a scope of openid. All supported scopes are
openid
email
profile
org.cilogon.userinfo
edu.uiuc.ncsa.myproxy.getcert
Note that the getcert scope requires you be able to get X509 certs via a MyProxy server, so only specify that if you really need it.
Public clients: Only openid scope is allowed and attempts to change the scopes will result in an error. It is not possible to change a public client to a confidential client. You must register a new client instead (This is due to our policies regarding creation of client secrets.).
at_lifetime N A integer (in seconds) (OA4MP specific!!)This sets the access token lifetime for all subsequent access tokens. Note that is must be less than or equal to the server's default. You should only set this if you have a specific need for it an knowledge of what values will work.
cfg N A JSON object (OA4MP specific!!)This is a configuration that includes scripting for gettign and processing additional claims. Generally you do not need one of these unless you have a very, very specific requirement. If you send attributes that do not fall within the spec., they will be put in this object for you. Generally if you do not know you need it and know what it does, you can safely ignore it.
Public clients:This parameter is not supported and will result in the rejection of any request.
rt_lifetime N A integer (in seconds) (OA4MP specific!!) If you request a grant_type of refresh_token, this specifies the maximum lifetime, in seconds, that it will be valid. Normally this is set for a very long time, as in weeks if not months. If this is omitted or set to 0 (zero) then no refresh tokens will be created.
strict_scopes N true (OA4MP specific!!) If set to true (default) only scopes explicitly set at registration will be allowed. If false then any unrecognized scopes in the initial request will cause the request to be rejected. If set to true you may send anything as a scope and allowed scopes will be processed, unknown scopes will be passed along for later processing and if not used, simply ignored. In the case that the access tokens is a JWT (such as SciTokens or WLCG tokens) set this false since the access token scopes would be passed in.