Get Started with Asset Service
Get Started with Asset Service
Like other Predix platform services, authentication access to Asset service is controlled by the designated trusted issuer and is managed by the User Account and Authentication (UAA) web service. A UAA service instance must be already set up as the trusted issuer before getting started with this Asset service.
For more information about how authentication and authorization is enforced in Predix services, see Understanding Platform Services.
Asset Service Setup
This roadmap lists the high-level tasks for getting started with the Asset service.
Authentication for Asset service is controlled by the designated trusted issuer and is managed by the User Account and Authentication (UAA) web service. You must set up a UAA service instance as the trusted issuer before getting started with the Asset service. For information about authentication and authorization in Predix services, see About Security Services.
You will not perform all tasks if you have already set up UAA services, created a trusted issuer, and an OAuth2 client, as described in Setting Up Platform Services Using Cloud Foundry Commands.
Task Roadmap
# | Task | Information |
---|---|---|
1 | Create a text file to store values that you will need later. | See asset-service-set-started.html#task_8f95deec-3c92-4cb9-b121-746b0f3c7ec1. |
2 | 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. |
3 | Set up access to Predix platform Artifactory. | If you need access to Predix platform artifacts, you need to set up access for Artifactory. See t_defining_predix_platform_artifactory_access.html#task_9eb8a359-66c2-46d8-a74d-dd2c26fe85cd. |
4 | 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. |
5 | 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. |
6 | Create an instance of the Asset service. | See asset-service-set-started.html#task_485d337a-0c20-4349-a80c-b4447d267f99. |
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. 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. See uaas-managing-clients.html#task_k3h_k2c_1x. See asset-service-set-started.html#reference_91c61d6c-57e8-4bfe-a91b-d0f3565930c6. |
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 asset-service-set-started.html#task_a298649e-601b-4ed8-b4de-d331f42097c1. |
10 | Add asset model data to your application. | See asset-service-set-started.html#task_24953dd7-22e0-421c-8f7c-cb65f423c3e0 |
11 | Start using the Asset service. | See asset-service-set-started.html#concept_mjm_md1_xx. |
Creating a Parameters Text File
Create a text file to store values that you will need later.
Procedure
uaa_instance_issuerId:
uaa_instance_uri:
uaa_admin_account_name:
uaa_admin_client_secret:
predix-hello-world-app-<YourName>:
developer_username:
developer_password:
predix_asset_api_gateway_short_route_url:
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 Asset Service Instance
Create an Asset service instance to use to create, update, and store asset model data that defines asset properties and relationships between assets and other modeling elements.
Before You Begin
An instance of the UAA service has been configured as your trusted issuer. See Task Roadmap: Setting Platform Services.
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 and Scopes Required for Asset Service
To enable applications to access the Asset service, your JSON Web Token (JWT) must contain the following scope: predix-asset.zones.<service_instance_guid>.user
.
Binding an Application to an Asset Service Instance
You must bind your Asset instance to your application to provision connection details for your Asset service instance in the VCAP_SERVICES environment variable
About This Task
Cloud Foundry runtime uses the VCAP_SERVICES environment variable to communicate with a deployed application about its environment.
Procedure
Adding Asset Model Data to your Asset Service Instance
You can copy the Asset Model Sample Data to add a collection of assets to your Asset service instance.
About This Task
Client applications can access asset data using Asset service REST API endpoints. These endpoints provide a JSON interface where you can post the data that describes all of your assets. To use these APIs, your application makes HTTPS requests and parses the response. You can use any web-development language to access the APIs.
For more information about this API, see the API Documentation.
To add a collection of assets to your Asset service instance: