LDSTechForumProjects

SSO Simulator CD-OESv1 REST interface

Description

As outlined in the SSO Environment Overview a REST service is available for answering Fine Grained Permission (FGP) questions for applications. In addition, it can answer whether a token or tokens represent valid sessions and it can indicate the name of the cookie used to store the token in the browser. This page is the specification of that interface and the reference implementation was created in the simulator followed soon after by the implementation in the SSO environment. In either environment, running behind the simulator or within the SSO environment the injected header, policy-service-url, conveys to applications the location of this REST interface and ClientLib leverages this value to provide its functionality.

It is important to note that each REST instance is bound to policies for which it can answer fine grained permissions(FGPs). This means that if an application is hit more than others and leverages FGPs, as a scalability and performance improvement option a REST service cluster specific to that application can be started and bound to the policies for just that application and removed from the more general REST service instance. Then we can set the injected policy-service-url header to point to that cluster for requests specific to that application. This offloads REST traffic from the instances managing policies for other applications, removes the sheer number of policies that must be evaluated in each instance, and scales the processing power where it needs to be.

History

When the simulator was originally created in mid 2009 the SSO system in use by the next generation group was openSSO. At the start of 2010 work was begun on the Enterprise version which was based upon Oracle Access Manager and Oracle Entitlements Server. Therefore, in version 4.12 a REST interface was added implementing the characteristics needed by applications for the new solution. This version is specified by a rest-version of CD-OESv1 on the <config> element (see SSO Simulator Configuration Files). For the curious, the name for this REST service is an acronym and stands for "Church Developed Oracle Entitlements Server version 1". This REST interface is exposed in the simulator at the location in Listing 1. The value of the policy-service-url should be set to this value minus the last path element "/1" since versions of ClientLib are crafted for specific version of this interface and will add that portion.

Listing 1: CD-OESv1 REST Endpoint Base and policy-service-url Header Value

http://<simulator-host:console-port>/rest/oes/1

Specification of APIs

All Rest API paths in the tables below must be prefixed with the value in Listing 1 to access that API directly. Applications intending to run in the new SSO environment must update to the suitable version of ClientLib that can converse with this REST API endpoint.


/getCookieName

Related Item Description
Clientlib IPolicyClient interface: doesn’t expose
PDPAccessPoint Interface: String getCookieName()
Rest API Request Path: /getCookieName
Request Method: GET
Request Query Parameters: none
Request body: none
Response type: text/plain
Response Body: <cookiename> unencrypted.
Server Action Return the response with the value determined via Spring injection unless there is a mechanism in the OAM API that returns this value. Current value is “ObSSOCookie”.

/areTokensValid

Related Item Description
Clientlib IPolicyClient interface: doesn’t expose
PDPAccessPoint Interface: Old method is replaced with Map<String, Boolean> areTokensValid(String token)
Rest API Request Path: /areTokensValid
Request Method: POST
Request Query Parameters: none
Request body: The body conforms to form submission encoding application/x-www-form-urlencoded as specified in HTML 4.01 Specification, section 17.13.4. Namely, that name/value pairs url encoded, separated by an equal sign, and delimited from other name/value pairs by an ampersand.
The following parameters are used. For token.cnt the ‘N’ represents a number and is indicative of the number of tokens being submitted.
token.cnt=N
token.1=<token>
...
token.N=<token>
Response type: text/plain
Response Body: order is not guaranteed but you will receive an answer for each token passed in.
token.1 = [‘true’ | ‘false’]CRLF
...
token.N = [‘true’ | ‘false’]CRLF
Server Action Simulator: see if each token’s session has expired and respond accordingly.

REST Server: for each token: AuthNService.assertIdentity(<cookie-name>, <token>) and respond accordingly.

/arePermitted

Related Item Description
Clientlib IPolicyClient interface:
Existing interface:
public boolean isPermitted(String action, String resource);
New Methods:
public boolean isPermitted(String action, String resource, Map<String, String> ctx);
public void arePermitted(List<ResourceAction> bulkQuery); // ResourceAction objects are updated with answer
where ResourceAction class contains getters and setters for:
String action;
String resource;
Map<String, String> ctx;
boolean permitted; // defaults to false, holds answer upon returning from call.
PDPAccessPoint Interface: Existing method is replaced and IPolicyClient instances will channel all requests through the new method.
void arePermitted(String token, List<ResourceAction>) // ResourceAction objects are updated with answer.
Rest API Request Path: /arePermitted
Request Method: POST
Request Query Parameters: none
Request body: The body conforms to form submission encoding application/x-www-form-urlencoded as specified in HTML 4.01 Specification, section 17.13.4. Namely, that name/value pairs url encoded, separated by an equal sign, and delimited from other name/value pairs by an ampersand.
The following parameters are used. For res.cnt the ‘N’ represents a number and is indicative of the number of resources being submitted. For ctx.N.cnt the ‘M’ represents a number indicating the number of context key value pairs for the Nth resource if any. The ctx.N.cnt value should not be included if there are no context parameters submitted for a resource.
token=<token-value>
res.cnt=N
res.1=<1st resource in list> This value is a URN in one of two forms. Resource URNs have form "/x/y/z" and Link URNs have form "/LINK/x/y/z". The former protects resources within an application. The latter protects an anchor tag with an href to a well known link that is intended to be linked to by multiple applications. An application will be the only application that knows about its resource URNs. Link URNs on the other hand can be known by many applications. Internal to policy management this keeps policies for resources within an application in one location and policies surrounding links between applications in another. The pattern of x/y/z should be related to the canonical URL context of the application to alleviate naming collisions but this is not strictly mandated.
act.1=<action for res.1>
ctx.1.cnt=M
ctx.1.1.key=<1st key>
ctx.1.1.val=<1st value
ctx.1.2.key=<2nd key>
ctx.1.2.val=<2nd value
...
ctx.1.M.key=<Mth key>
ctx.1.M.val=<Mth value
res.2=<2nd resource>
act.2=<action for res.2>
...
res.N=<Nth resource> See comments for res.1 above.
act.N=<action for Nth resource>
...
Response type: text/plain
Response Body: order is not guaranteed but an answer is returned for all resources that have both a resource and an action specified. If the action is not specified that resource will not be evaluated nor included in the response.
res.1=[‘true’ | ‘false’]CRLF
res.2=[‘true’ | ‘false’]CRLF
...
res.N=[‘true’ | ‘false’]CRLF
Server Action Simulator: Build the response according to configured policies. If the token represents an expired or invalid session then the response for all resources must be false.
Rest Server: If server is configured to run in test mode then token must be username followed by “|” followed by password and the authentication service’s authenticate method will be used to obtain an Identity. Otherwise, the token must be a valid obssocookie value and the authentication service’s assertIdentity method will be used to obtain an Identity. In either case, if an identity can not be obtained then the response for all resources must be false.
Once an identity is obtained the the authorization service’s isAccessAllowed is called for each resource passing its action and context values if any and the response for that resource constructed accordingly.

/encode

Related Item Description
Definition Converts the passed-in URL to the form used within the OES policy management user interface. Not used by applications themselves.
Clientlib IPolicyClient interface: doesn’t expose
PDPAccessPoint Interface: doesn't expose
Rest API Request Path: /encode
Request Method: GET
Request Query Parameters: res
Request body: none
res=<absolute URL to be encoded for use within the admin UI>
Response type: text/plain
Response Body: the absolute URL with restricted characters replaced according to the needs of the OES admin UI.
Server Action Simulator: converts the URL accordingly.

REST Server: converts the URL accordingly.

This page was last modified on 8 March 2011, at 12:47.

Note: Content found in this wiki may not always reflect official Church information. See Terms of Use.