Integrating Access Control Service With Your Application

Access Control Services Spring Security Extensions

Predix platform provides Spring Security Extensions that can be used for integrating with spring security, to implement fine-grained access control of application resources, using the Access Control Service (ACS).

Note:

If you do not use Java using spring framework, you can use the ACS REST APIs directly.

Securing Resources With ACS Using Spring Security Extensions

About This Task

To enforce authentication and authorization, you can restrict access to the RESTful endpoints exposed with Spring MVC.

Procedure

Include the isAcsAuthorized() expression in the access attribute on http element for resources that need to be protected with ACS.

For example,

Set use-expressions attribute to true.
Configure the ACS Expression handler <expression-handler ref="acsExpressionHandler"/>.
Use isAcsAuthorized() expression to add authorization with ACS. If your ACS instance has more than one policy set configured, you must provide an ordered list of the policy set names to be used for evaluation. You can specify the policy set names as method parameters. If there is just one policy set, this parameter is optional.

<http pattern="/**"
     request-matcher="ant" xmlns="http://www.springframework.org/schema/security"
 disable-url-rewriting="true"
 use-expressions="true"
 entry-point-ref="preAuthenticationEntryPoint" >
 <expression-handler ref="acsExpressionHandler" />
 
 <!-- /greeting not authorized with ACS -->
 <intercept-url pattern="/greeting" 
    access="isFullyAuthenticated()"/>

 <!-- /sites/** authorized with ACS based on 'policy-set-2' -->
 <intercept-url pattern="/sites/**"
    access="isAcsAuthorized( 'policy-set-2') and isFullyAuthenticated()" />

 <!-- /resources/** authorized with ACS based on provided ordered list of available policy sets -->
 <intercept-url pattern="/resources/**"
    access="isAcsAuthorized('policy-set-1', 'policy-set-2') and isFullyAuthenticated()" />
 <anonymous enabled="false" />
 <custom-filter ref="oauth2ClientFilter" before="PRE_AUTH_FILTER" />
 <custom-filter ref="oauth2ServiceFilter" position="PRE_AUTH_FILTER" />
</http>

Getting Started With the Spring Security Extensions

About This Task

Add the ACS spring security extensions dependency and import the spring configuration bean.

Procedure

Set up access to Predix platform Artifactory.

Add the acs-spring-security-extensions library dependency to your application POM file.

<dependency>
    <groupId>com.ge.predix</groupId>
    <artifactId>acs-spring-security-extensions</artifactId>
    <version>5.1.0</version>
</dependency>

Add the following import in your application configuration beans xml file:
```
<import resource="classpath:acs-spring-config.xml" />
```

Configuring ACS Details

ACS spring security extensions require ACS instance details to delegate resource authorization to ACS.

You can use the ACS spring security extensions in one of the following two ways:

Use the default implementation, com.ge.predix.acs.spring.security.config.AcsClientConfigurationProvider. The default implementation relies on the UAA and ACS services information to be available in your application property file.
Override the default implementation by creating your own implementation of the com.ge.predix.acs.spring.security.config.AcsClientConfigurationProvider interface. You can use this option if your application requires multiple OAuth2 clients accessing ACS.

Configure Java Properties to Use Default Implementation

Update your application properties file (application.properties) to include the UAA and ACS service instance details.

Update your application properties file for the following values:

Variable	Description
`acsServiceInstanceName`	Specify the name of your ACS instance. If you specify the name of the ACS instance, the ACS spring security extension uses your application's VCAP_SERVICES environment variable to retrieve the values for `acsZone` and `acsPolicyEvaluationTokenScope`. If the details are specified both in VCAP_SRVICES and in the properties file, the values in VCAP_SERVICES take precedence. `acsZone` Specifies the name of the ACS instance zone. It is the `http-header-name` value generated in the VCAP_SERVICES environment variable. For example, `Predix-Zone-Id`. `acsPolicyEvaluationTokenScope` Specifies the ACS zone scope. It is the `oauth-scope` value generated in the VCAP_SERVICES environment variable. For example, `predix-acs.zones.9378e3db-e683-46a2-97c2-ccd11d75869d.user`.
`accessTokenEndpointUrl`	Specify the UAA instance issuer identifier. For example, `https://ff27c315-d027-4d1d-a30c-64f49b369ed9.predix-uaa.run.aws-usw02-pr.ice.predix.io/oauth/token`.
`clientId`	Specify the client identifier for your UAA instance.
`clientSecret`	Specify the client secret for your UAA instance.

For example, the following properties file shows the updated values:

accessTokenEndpointUrl=https://ff27c315-d027-4d1d-a30c-64f49b369ed9.predix-uaa.run.aws-usw02-pr.ice.predix.io/oauth/token 

clientId=<client_id>
clientSecret=<client_secret> 

# The following properties are used by acs-spring-security-extensions to invoke ACS for policy evaluation.
# acsServiceInstanceName takes precedence over acsUri, when that instance is available in the application's
# VCAP_SERVICES 
#Specify ACS endpoint (http://host:port) to use when cloud foundry VCAP services are not available.
acsUri=${ACS_URL} 

#Specify ACS instance name to bind. This is used by acs-spring-security-extension.
acsServiceInstanceName= 

acsZone=9378e3db-e683-46a2-97c2-ccd11d75869d 

acsPolicyEvaluationTokenScope=predix-acs.zones.9378e3db-e683-46a2-97c2-ccd11d75869d.user

Configure Custom Provider

If you need to override the default implementation, you can create your own implementation as follows:

Implement the com.ge.predix.acs.spring.security.config.AcsClientConfigurationProvider interface.
Annotate the implementation with @Primary and @Component. This ensures that your implementation is used while calling ACS.

Providing Additional Subject Attributes for Policy Evaluation

By default, ACS uses the subject attributes that you specify for policy evaluation. Some applications require to specify additional subject attributes during runtime. ACS spring security extensions provide a way for your application to provide additional subject attributes that you can use for the policy evaluation of the current request.

To provide additional attributes:

Implement the com.ge.predix.acs.spring.security.extensions.policy.evaluation.AcsPolicyEvaluationRequestCustomizer interface.
Annotate the implementation with @Primary and @Component to ensure it is used when calling ACS.