org.forgerock.openig.uma

Class UmaSharingService

java.lang.Object

org.forgerock.openig.uma.UmaSharingService

public class UmaSharingService
extends Object

An UmaSharingService provides core UMA features to OpenIG when acting as an UMA Resource Server.

It is linked to a single UMA Authorization Server and needs to be pre-registered as an OAuth 2.0 client on that AS.

It is also the place where protected application knowledge is described: each item of the resources array describe a resource set (that can be composed of multiple endpoints) that share the same set of scopes.

Each resource contains a pattern used to define which one of them to use when a Share is created. A resource also contains a list of actions that defines the set of scopes to require when a requesting party request comes in.

      {
         "name": "UmaService",
         "type": "UmaService",
         "config": {
           "protectionApiHandler": "HttpsClient",
           "authorizationServerUri": "https://openam.example.com:8443/openam",
           "clientId": "uma",
           "clientSecret": "welcome",
           "resources": [
             {
               "pattern": "/guillaume/.*",
               "actions" : [
                 {
                   "scopes"    : [ "http://api.example.com/operations#read" ],
                   "condition" : "${request.method == 'GET'}"
                 },
                 {
                   "scopes"    : [ "http://api.example.com/operations#delete" ],
                   "condition" : "${request.method == 'DELETE'}"
                 }
               ]
             }
           ]
         }
       }
     
 

Along with the UmaService, a REST endpoint is deployed in OpenIG's API namespace: /openig/api/system/objects/../objects/[name-of-the-uma-service-object]/share. The dotted segment depends on your deployment (like which RouterHandler hosts the route that in turns contains this object).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UmaSharingService.Heaplet Creates and initializes an UMA service in a heap environment.

Constructor Summary

Constructors

Constructor and Description
UmaSharingService(org.forgerock.http.Handler protectionApiHandler, List<org.forgerock.openig.uma.ShareTemplate> templates, URI authorizationServer, String clientId, String clientSecret) Constructs an UmaSharingService bound to the given authorizationServer and dedicated to protect resource sets described by the given templates.

Method Summary

Modifier and Type	Method and Description
org.forgerock.util.promise.Promise<org.forgerock.openig.uma.Share,UmaException>	createShare(org.forgerock.services.context.Context context, String resourcePath, String pat) Creates a Share that will be used to protect the given resourcePath.
org.forgerock.openig.uma.Share	findShare(org.forgerock.http.protocol.Request request) Find a Share.
URI	getAuthorizationServer() Returns the UMA authorization server base Uri.
String	getClientId() Returns the client identifier used to identify this RS as an OAuth 2.0 client.
String	getClientSecret() Returns the client secret.
URI	getIntrospectionEndpoint() Returns the OAuth 2.0 Introspection endpoint Uri.
org.forgerock.openig.uma.Share	getShare(String id) Returns the Share with the given id.
URI	getTicketEndpoint() Returns the UMA Permission Request endpoint Uri.
Set<org.forgerock.openig.uma.Share>	listShares() Returns a copy of the list of currently managed shares.
org.forgerock.openig.uma.Share	removeShare(String shareId) Removes the previously created Share from the registered shares.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UmaSharingService

public UmaSharingService(org.forgerock.http.Handler protectionApiHandler,
                         List<org.forgerock.openig.uma.ShareTemplate> templates,
                         URI authorizationServer,
                         String clientId,
                         String clientSecret)
                  throws URISyntaxException

Constructs an UmaSharingService bound to the given authorizationServer and dedicated to protect resource sets described by the given templates.

Parameters:

protectionApiHandler - used to call the resource set endpoint

templates - list of resource descriptions

authorizationServer - Bound UMA Authorization Server

clientId - OAuth 2.0 Client identifier

clientSecret - OAuth 2.0 Client secret

Throws:

URISyntaxException - when the authorization server URI cannot be "normalized" (trailing '/' append if required)

Method Detail

createShare

public org.forgerock.util.promise.Promise<org.forgerock.openig.uma.Share,UmaException> createShare(org.forgerock.services.context.Context context,
                                                                                                   String resourcePath,
                                                                                                   String pat)

Creates a Share that will be used to protect the given resourcePath.

Parameters:

context - Context chain used to keep a relationship between requests (tracking)

resourcePath - resource to be protected

pat - Protection Api Token (PAT)

Returns:

the created Share asynchronously

See Also:

Resource Set Registration

findShare

public org.forgerock.openig.uma.Share findShare(org.forgerock.http.protocol.Request request)
                                         throws UmaException

Find a Share.

Parameters:

request - the incoming requesting party request

Returns:

a Share to be used to protect the resource access

Throws:

UmaException - when no Share can handle the request.

removeShare

public org.forgerock.openig.uma.Share removeShare(String shareId)

Removes the previously created Share from the registered shares. In effect, the resources is no more shared/protected

Parameters:

shareId - share identifier

Returns:

the removed Share instance if found, null otherwise.

listShares

public Set<org.forgerock.openig.uma.Share> listShares()

Returns a copy of the list of currently managed shares.

Returns:

a copy of the list of currently managed shares.

getAuthorizationServer

public URI getAuthorizationServer()

Returns the UMA authorization server base Uri.

Returns:

the UMA authorization server base Uri.

getTicketEndpoint

public URI getTicketEndpoint()

Returns the UMA Permission Request endpoint Uri.

Returns:

the UMA Permission Request endpoint Uri.

getIntrospectionEndpoint

public URI getIntrospectionEndpoint()

Returns the OAuth 2.0 Introspection endpoint Uri.

Returns:

the OAuth 2.0 Introspection endpoint Uri.

getShare

public org.forgerock.openig.uma.Share getShare(String id)

Returns the Share with the given id.

Parameters:

id - Share identifier

Returns:

the Share with the given id (or null if none was found).

getClientId

public String getClientId()

Returns the client identifier used to identify this RS as an OAuth 2.0 client.

Returns:

the client identifier used to identify this RS as an OAuth 2.0 client.

getClientSecret

public String getClientSecret()

Returns the client secret.

Returns:

the client secret.