Scopes

Scope of this document: for client and server, OAuth 2/OIDC only.

OAuth 2 supports custom scopes for servers. The top-level tag is the scopes tag and that in turn contains scope tags. These scope tags contain a single scope and support a single attribute:

Name Required Default Description
enabled N true Enable or disable this scope.

The basic supported scopes in OA4MP are

  • openid - this is required in every request. If omitted, the server must reject the request
  • email - returns the user's email address, if available.
  • profile - returns information about the user's profile
  • org.cilogon.userinfo - This returns all enabled inforation about the user from the service and allows access to the user information endpoint.
  • edu.uiuc.ncsa.myproxy.getcert - the server returns a certificate from the getCert endpoint. If the client omits this, then attempts to get a certificate will be rejected. However, requests to the user info endpoint will still be processed.

The default behavior is that all basic scopes are used. Any other scopes that are specified are added to the list. On the client, this means that these will be requested. On the server, this means that if requested, they will be processed. Specifying a scope on the client that is unknown to a server will make the request fail.

Sometimes, it is necessary to disable a scope. For instance, a specialized instance that only issues certificates against a refresh token should never return any user information. This is the purpose of the enabled flag. Here would be how to effect that.

<service name="default" address="https://myservice.org:8443/oauth">
   <scopes>
       <scope enabled="false">profile</scope>
       <scope enabled="false">email</scope>
   </scopes>
    <!-- other stuff.. -->
</service>
Attempts by a client to request the profile scope would be rejected. Since the getcert scope is not specified, it is enabled (you could also simply specify explicitly) so this server will return certificates but only the sub claim (since that is required by the openid scope, which is manadatory for OA4MP since it is OIDC compliant.)

A Server Example

<service name="default" address="https://myservice.org:8443/oauth">
   <scopes>
       <scope>custom.scope</scope>
   </scopes>
    <!-- other stuff.. -->
</service>

This informs the server that the scope with tag "custom.scope" should be passed through to whatever custom handler has been specified. If this were not configured, the server would reject any request with this scope.

A Client Example

<config>
   <client name="my-cfg">
    <scopes>
        <scope>custom.scope</scope>
    </scopes>
        <!-- other stuff.. -->
</config>
The client will include the custom scope in requests to the server. If this is omitted, then the scope is not added and whatever claims that are associated with this scope will not be made.

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