Get Started with Access Control Services
Access Control Services Setup
Authentication for the Access Control services(ACS) is controlled by the designated trusted issuer and is managed by the User Account and Authentication (UAA) security service. You must set up a UAA service instance as the trusted issuer before getting started with the ACS services.
For information about authentication and authorization in Predix services, see uaas-overview.html#concept_gg1_t5r_zr.
Task Roadmap
# | Task | Information |
---|---|---|
1 | (Optional) Configure your proxy settings if necessary. | Depending on your location and network configuration, you may need to configure your proxy settings to access remote resources. See t_defining_proxy_connections_to_remote_resources.html#task_97cc6304-e168-459d-9952-a45708ff8361. |
2 | (Optional) Set up access to Predix platform Artifactory. | If you need access to Predix platform artifacts, you need to set up access for Artifactory. Predix provides ACS spring security extensions for integrating with spring security. The libraries are stored in Artifactory. See t_defining_predix_platform_artifactory_access.html#task_9eb8a359-66c2-46d8-a74d-dd2c26fe85cd. |
3 | Deploy your application to Cloud Foundry. | For an example of deploying a Predix Hello World Web application to cloud foundry, see t_Deploying_an_App_to_Cloud_Foundry.html#task_xwn_lvb_vx. |
4 | Create an instance of the trusted issuer. | Create an instance of User Account and Authentication (UAA) service. UAA is the authorization server that each platform service uses for authentication. For more information, see uaas-get-started.html#task_y1l_vms_2s. |
5 | Create an instance of the ACS service. | For more information, see acs-getting-started.html#task_j4d_3bw_fs. |
6 | (Optional) Update an ACS instance that you created. | For more information, see acs-getting-started.html#task_ibc_sgt_dbb. |
7 | Create OAuth2 clients to setup access to your service authenticated using UAA. | When you create a UAA instance, an admin client is automatically created for you to access UAA for additional configuration. You can create a new client for your service instance with specific scopes. If an Oauth2 client already exists, you can update the client to add your service instance. For more information, see uaas-managing-clients.html#task_79a81b74-552e-4f74-abfc-bd37e6adac87. |
8 | Update the Oath2 client to add service specific scopes or authorities. | To enable your application to access a platform service, your JSON Web Token (JWT) must contain the scopes required for a platform service. For more information see uaas-managing-clients.html#task_k3h_k2c_1x. For ACS specific scopes, see acs-getting-started.html#reference_xkh_mkd_bx. |
9 | Bind your application to the service instance. | To establish communication between your application and the platform service, you must bind the application to the service. See acs-getting-started.html#task_a2375607-175a-40bc-b53b-2133c16473ad. |
10 | Start using the Access Control services. | See Using Access Control Services. |
Creating a UAA Service Instance
You can create multiple instances of the UAA service in your space.
About This Task
As a best practice, first delete any older unused instances before creating a new one.
Procedure
Results
Your UAA instance is created with the following specifications:
- A client identifier (
admin
).Note: Anadmin
client is required for bootstrap purposes. You can create additional clients to use with your application. - A client secret (that you specified while creating the service).
To retrieve additional details of your instance, you can bind an application to your instance.
Using the Command Line to Create a UAA Service Instance
Optional procedure for using the command line instead of the graphical user interface to create a UAA service instance.
About This Task
You can create up to 10 instances of UAA service in your space. If you need additional instances, you must delete an older unused instance and create a new one.
Procedure
Results
Your UAA instance is created with the following specification:
-
A client identifier (
admin
).Note: Anadmin
client is created for bootstrap purposes. You can create additional clients to use with your application. -
A client secret (that you specified while creating the service).
To retrieve additional details of your instance, you can bind an application to your instance.
Example
Create a predix-uaa service instance with client secret as admin and sub-domain as ge-digital:
cf cs predix-uaa tiered test-1 -c '{"adminClientSecret":"admin","subdomain":"ge-digital"}'
This is how it appears in VCAP SERVICES when using the cf env <app_name>
command:
"VCAP_SERVICES": {
"predix-uaa": [
{
"credentials": {
"dashboardUrl": "https://uaa-dashboard.run.asv-pr.ice.predix.io/#/login/04187eb1-e0cf-4874-8218-9fb77a8b4ed9",
"issuerId": "https://04187eb1-e0cf-4874-8218-9fb77a8b4ed9.predix-uaa.run.asv-pr.ice.predix.io/oauth/token",
"subdomain": "04187eb1-e0cf-4874-8218-9fb77a8b4ed9",
"uri": "https://04187eb1-e0cf-4874-8218-9fb77a8b4ed9.predix-uaa.run.asv-pr.ice.predix.io",
"zone": {
"http-header-name": "X-Identity-Zone-Id",
"http-header-value": "04187eb1-e0cf-4874-8218-9fb77a8b4ed9"
}
},
"label": "predix-uaa",
"name": "testuaa",
"plan": "Tiered",
"provider": null,
"syslog_drain_url": null,
"tags": [],
"volume_mounts": []
}
],
Creating an ACS Instance
You can create an instance of access control service for setting up fine-grained access permissions for users. You can create a maximum of 200 instances of ACS in your space.
Before You Begin
An instance of the UAA service has been configured as your trusted issuer. See Task Roadmap: Setting Platform Services.
Procedure
Using Command Line to Create an ACS Instance
Procedure
Updating an ACS Instance
Before You Begin
You need the name of the ACS instance <my_acs_instance>
that you created (see acs-getting-started.html#task_j4d_3bw_fs).
create service
command, run cf cs
.Procedure
Creating an OAuth2 Client
You can create OAuth2 clients with specific permissions for your application to work with Predix Platform services. Often this is the first step after creating an instance of a service.
About This Task
When you create an instance of UAA, the UAA Dashboard is available for configuring that instance of UAA. You can use the Client Management tab in the UAA Dashboard to create the OAuth2 clients.
If you are prefer using the UAA command-line interface (UAAC) instead of UAA Dashboard to create an OAuth2 client, see uaas-managing-clients.html#task_sp2_zvk_rdb
Procedure
What To Do Next
uaas-managing-clients.html#task_k3h_k2c_1x for your service specific information.
Updating the OAuth2 Client for Services
To use an OAuth2 client for secure access to your Predix Platform service instance from your application, you must update your OAuth2 client to add additional authorities or scopes that are specific to each service.
About This Task
To enable your application to access a platform service, your JSON Web Token (JWT) must contain the scopes required for a platform service. For example, some of the scope required for Access Control service are acs.policies.read acs.policies.write
.
The OAuth2 client uses an authorization grant to request an access token. Based on the type of authorization grant that you have used, you must update your OAuth2 client to generate the required JWT. For more information on how the OAuth2 client is created, see Creating OAuth2 client.
If you use the UAA Dashboard to create additional clients, the client is created for the default client_credentials
grant type. Some required authorities and scopes are automatically added to the client. You must add additional authorities or scopes that are specific to each service.
In addition, the admin client is not assigned the default authority to change the user password. To change the user password, you must add the uaa.admin
authority to your admin client.
Use the following procedure to update the OAuth2 client.
Procedure
What To Do Next
You can complete the following additional tasks in UAA Dashboard:
- If you are using authorization grant type as Authorization Code, Implicit, or Resource Owner Password, you can manage users in UAA.
- You can create password policies for user passwords.
- You can set up external identity provider or use UAA as an identity provider. See Managing Identity Providers.
If you have completed your OAuth2 client setup, you can bind your application to your service instance.
Authorities or Scopes Required for ACS Services
List of scopes and authorities specific to ACS service that you must add to your OAuth2 client.
When you create a new OAuth2 client, the client is assigned default scopes and authorities. You must add additional authorities or scopes that are specific to each service.
- acs.policies.read
- acs.policies.write
- acs.attributes.read
- acs.attributes.write
- predix-acs.zones.<acs_instance_guid>.user
This value is added by default if you use UAA Dashboard. It is also generated in the VCAP_SERVICES environment variable as
oauth-scope
when you bind your application to your ACS service instance.
Binding an Application to the ACS Instance
About This Task
You must bind your application to your ACS instance to provision its connection details in the VCAP_SERVICES environment variable. Cloud Foundry runtime uses VCAP_SERVICES environment variable to communicate with a deployed application about its environment.
You can retrieve the following ACS instance details from the VCAP_SERVICES environment variable:
-
A
acs_instance_uri
for your instance. -
HTTP header information to access your ACS instance. It includes:
http-header-name
asPredix-Zone-Id
http-header-value
-
An
oauth-scope
for your instance. The scope is required in the end-user token to access a specific ACS instance.