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

#TaskInformation
1Create a text file to store values that you will need later.See asset-service-set-started.html#task_8f95deec-3c92-4cb9-b121-746b0f3c7ec1.
2Configure 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.
3Set 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.

4Deploy 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.
5Create 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.

See uaas-get-started.html#task_y1l_vms_2s.

6Create an instance of the Asset service.See asset-service-set-started.html#task_485d337a-0c20-4349-a80c-b4447d267f99.
7Create 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.

8Update 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.

9Bind 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.

10Add asset model data to your application.See asset-service-set-started.html#task_24953dd7-22e0-421c-8f7c-cb65f423c3e0
11Start 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

Copy and paste the following parameters into a text file that you can use to record values as you create the Asset service instance. Once recorded, these values are used in subsequent steps.
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

  1. Sign into your Predix account at https://www.predix.io.
  2. Navigate to Catalog > Services, then click the User Account and Authentication tile.
  3. Click Subscribe on the required plan.
  4. Complete the fields on the New Service Instance page.
    FieldDescription
    OrgSelect your organization.
    SpaceSelect the space for your application.
    Service instance nameEnter a unique name for this UAA service instance.
    Service planSelect a plan.
    Admin client secretEnter a client secret (this is the admin password for this UAA instance). The client secret can be any alphanumeric string.
    Note: Record the client secret in a secure place for later use.
    Subdomain(Optional) Enter a subdomain you might need to use in addition to the domain created for UAA. You must not add special characters in the name of the subdomain. The value of sub-domain is case-insensitive.
  5. Click Create Service.

Results

Your UAA instance is created with the following specifications:

  • A client identifier (admin).
    Note: An admin 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

  1. Use the Cloud Foundry CLI to log into Cloud Foundry.
    cf login -a <API_Endpoint>
    Note: If you are a GE employee, you must use the cf login --sso command to log into Cloud Foundry. After you enter your SSO, you will receive a one-time passcode URL. Copy this URL and paste it in a browser to retrieve your one-time passcode. Use this code with the cf command to complete the CF login process.

    Depending on your Predix.io registration, the value of <API_Endpoint> is one of the following:

    • Predix US-West

      https://api.system.aws-usw02-pr.ice.predix.io

    • Predix Europe

      https://api.system.aws-eu-central-1-pr.ice.predix.io

    For example,

    cf login -a https://api.system.aws-usw02-pr.ice.predix.io
  2. List the services in the Cloud Foundry marketplace by entering the following command.
    cf marketplace

    The UAA service, predix-uaa, is listed as one of the available services.

  3. Create a UAA instance by entering the following command.
    cf create-service predix-uaa <plan> <my_uaa_instance> -c '{"adminClientSecret":"<my_secret>","subdomain":"<my_subdomain>"}'

    where:

    • cf stands for the CLI command, cloud foundry
    • cs stands for the CLI command create-service
    • <plan> is the plan associated with a service. For example, you can use the tiered plan for the predix-uaa service.
    • -c option is used to specify following additional parameters.
      • adminClientSecret specifies the client secret.
      • subdomain specifies a sub-domain you might need to use in addition to the domain created for UAA. This is an optional parameter. You must not add special characters in the name of the sub-domain. The value of sub-domain is case insensitive.
    Note: Cloud Foundry CLI syntax can differ between Windows and Linux operating systems. See the Cloud Foundry help for the appropriate syntax for your operating system. For example, to see help for the create service command, run cf cs.

Results

Your UAA instance is created with the following specification:

  • A client identifier (admin).

    Note: An admin 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

  1. Sign into your Predix account at https://www.predix.io.
  2. Navigate to Catalog > Services tab, and click the Asset Data Service tile.
  3. Click Subscribe on the required plan.
  4. On the New Service Instance page, enter:
    FieldDescription
    OrgSelect your org.
    SpaceSelect the space for your application.
    User Account & Authentication (UAA)Choose an existing UAA instance or create a new instance of UAA.

    See uaas-get-started.html#task_y1l_vms_2s.

    Service instance nameSpecify a unique name for your instance.
    Service planSelect a plan.
  5. Click Create Service.

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

  1. In the Predix.io Console view, select the Space where your services are located.
  2. In the Services Instances page, select the UAA instance to configure.
  3. Select the Configure Service Instance option.
  4. In the UAA Dashboard login page, specify your admin client secret and click Login.
  5. In UAA Dashboard, select the Client Management tab.
    The Client Management tab has two views, Clients and Services . The Services view displays the service instances that you have created for your services.
    Note: The service instances displayed in the Services view were created while using the UAA that you are trying to configure. Service instances that you created using other UAA instances are not displayed on this page.
  6. Click Create Client to open the Create Client form.
  7. Complete the Create Client form.
    FieldDescription
    Client IDSpecify a name for the OAuth2 client you are creating.
    Authorized Grant TypesChoose one or more of the following grant types:
    • authorization_code

      When you use the authorization code grant type, the client directs the resource owner to UAA, which in turn directs the resource owner back to the client with the authorization code.

    • client_credentials

      When you use the client credentials grant type, the OAuth2 endpoint in UAA accepts the client ID and client secret and provides Access Tokens.

    • password

      When you use the resource owner password credentials grant type, the OAuth2 endpoint in UAA accepts the username and password and provides Access Tokens.

    • refresh_token

      The refresh tokens are credentials used to obtain access tokens. You can choose this option to obtain refresh token from UAA. You can then use the refresh token to obtain a new access token from UAA when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope.

    • implicit

      When you use the implicit grant type, UAA directly issues an Access Token to the client without authenticating the client. This reduces the number of round trips required to obtain an access token.

    For more information on grant types, see RFC 6749.

    Client SecretSpecify the password. It is important that you keep a note of this password. If lost, this password cannot be retrieved.
    Confirm Client SecretReenter the client secret.
    Redirect URISpecify a redirect URI to redirect the client after login or logout (for example, http://example-app.com/callback). Use this URI when you start using UAA as the service provider for your external Identity provider. UAA uses the value of Redirect URI for /oauth/authorize and /logout endpoints.

    You must specify a Redirect URI value if you use the Authorization Code or Implicit authorization grant type. When you use the Authorization Code grant type, the Redirect URI is your application's endpoint or callback that expects user authorization code. When you use the Implicit grant type, the Redirect URI is the end point where UAA sends the bearer token.

    Unique Resource Identifier consists of:
    • Access Protocol, http or https
    • Domain or IP address
    • Access Port such as 80 or 443
    • Path

    If you have a specific URL for your application callback, you can use that to set the Redirect URI value for the related client. For example, https://your-app-domain.run.aws-usw02-pr.ice.predix.io/path1/path2/callback.

    You can specify multiple values for Redirect URI as a list of allowed destinations that UAA server can redirect the users. For example, https://yourappdomain1.run.aws-usw02-pr.ice.predix.io/path1/path2/callback, https://yourappdomain2.run.aws-usw02-pr.ice.predix.io/path1/path2/callback.

    If the subdomain of your application is dynamic, you can set the value of Redirect URI using wilcards. For example, https://*.your-app-domain.run.aws-usw02-pr.ice.predix.io/path1/path2/callback.

    Note: You must only use ‘*’ for a domain that is exclusive to your application (Such as your-app-domain in example above). This prevents the redirect to be routed to an application that you do not own. You cannot use * in the top domain and sub domain (such as predix.io in the example above).
    ScopesScopes are permissions associated with an OAuth Client to determine user access to a resource through an application. The user permissions are for authorization grant types authorization_code, password and implicit.

    By default, the admin client is assigned all required scopes. For a new client, an administrator can select the scopes to be added based on client requirements.

    For a list of available scopes, see Scopes Authorized by the UAA.

    To use an OAuth2 client for your Predix Platform service instance, you must update your OAuth2 client to add scopes that are specific to each service after adding the client to the service instance.

    AuthoritiesAuthorities are permissions associated with the OAuth Client when an application or API is acting on its own behalf to access a resource with its own credentials, without user involvement. The permissions are for the client_credentials authorization grant type.

    By default, the admin client is assigned all required authorities. For a new client, an administrator can select the authorities to be added based on client requirements.

    The list of authorities matches the list of scopes. For a list of available UAA scopes, see Scopes Authorized by the UAA.

    To use an OAuth2 client for your Predix Platform service instance, you must update your OAuth2 client to add authorities that are specific to each service after adding the client to the service instance.

    Note: An 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.
    Auto Approved ScopesSpecify scopes that can be approved automatically for the client without explicit approval from a resource owner.
    Allowed ProvidersSpecifies the names of the external identity providers, if any. This field is required if you are using external identity providers with UAA as a service provider.
    Access Token ValiditySpecifies the access-token expiration time in ms.
    Refresh Token ValiditySpecifies the refresh-token expiration time in ms.

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

  1. In the Console view, select the Space where your services are located.
  2. In the Services Instances page, select the UAA instance to configure.
  3. Select the Configure Service Instance option.
  4. In the UAA Dashboard login page, specify your admin client secret and click Login.
  5. In UAA Dashboard, select the Client Management tab.
    The Client Management tab has two views, Clients and Services. The Services view displays the service instances that you have created for your services.
    Note: The service instances displayed in the Services view are the instances that you created using the UAA that you are trying to configure. The service instances that you created using some other UAA instance are not displayed on this page.
  6. Select the Switch to Services View option.
  7. In the Services view, select the service that you need to update.
  8. Choose an existing client or choose the Create a new client option. If you chose to create a new client, follow the steps in uaas-managing-clients.html#task_79a81b74-552e-4f74-abfc-bd37e6adac87.
  9. Click Submit.
  10. Click on the Switch to Clients View option.
  11. In the Clients view, click the edit icon corresponding to the client added in the previous step.
  12. Complete the Edit Client form.
    FieldDescription
    Authorized Grant TypesChoose one or more of the following grant types:
    • authorization_code

      When you use the authorization code grant type, the client directs the resource owner to UAA, which in turn directs the resource owner back to the client with the authorization code.

    • client_credentials

      When you use the client credentials grant type, the OAuth2 endpoint in UAA accepts the client ID and client secret and provides Access Tokens.

    • password

      When you use the resource owner password credentials grant type, the OAuth2 endpoint in UAA accepts the username and password and provides Access Tokens.

    • refresh_token

      The refresh tokens are credentials used to obtain access tokens. You can choose this option to obtain refresh token from UAA. You can then use the refresh token to obtain a new access token from UAA when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope.

    • implicit

      When you use the implicit grant type, UAA directly issues an Access Token to the client without authenticating the client. This reduces the number of round trips required to obtain an access token.

    For more information on grant types, see RFC 6749.

    Redirect URISpecify a redirect URI to redirect the client after login (for example, http://example-app.com/welcome).

    This URI is used when you start using UAA as service provider for your external Identify provider.

    ScopesBy default, the client is assigned a few required scopes. For a new client, an administrator can select the scopes to be added based on the selected grant type.

    If you select the authorization_code, password and implicit grant type, you must update the scopes with service specific scopes.

    For a complete list of required scopes, see uaas-managing-clients.html#reference_ec1_t3d_bx.

    For a list of available UAA scopes, see Scopes Authorized by the UAA.

    AuthoritiesBy default, the client is assigned a few required authorities. For a new client, an administrator can select the authorities to be added based on the selected grant type.

    If you select the client_credentials grant type, you must update the authorities with service specific authorities.

    For a complete list of scopes to be added for each service, see uaas-managing-clients.html#reference_ec1_t3d_bx.

    For a list of available UAA authorities, see Scopes Authorized by the UAA.

    Auto Approved ScopesSpecify scopes that can be approved automatically for the client without explicit approval from the resource owner.
    Allowed ProvidersSpecify the names of the external identity providers, if any. This field is required if you are using external identity providers with UAA as a service provider.
    Access Token ValiditySpecifies the access token expiration time in ms.
    Refresh Token ValiditySpecifies the refresh token expiration time in ms.

What To Do Next

You can complete the following additional tasks in UAA Dashboard:

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

  1. Bind your application to the new Asset service instance.
    cf bind-service <your_app_name> <asset_instance_name>
    The <asset_instance_name> instance is bound to your application, and the following message is returned:
    Binding service <asset_instance_name> to app <your_app_name> in org cf_org_name / space cf_space_name as cf_username...
    OK
    TIP: Use 'cf restage' to ensure your env variable changes take effect
    
  2. Verify the binding:
    cf env <your_app_name>
    Messages that are similar to the following messages are returned:
    Getting env variables for app your_app_name in org cf_org_name / space cf_space_name as cf_user_name...
    OK
    {
     "VCAP_SERVICES": {
      "predix-asset-dev": [
       {
        "credentials": {
         "instanceId": "69c2bd61-4526-4379-9533-a2721fe83ba8",
         "uri": "http://predix-asset-rc.grc-apps.svc.ice.ge.com",
         "zone": {
          "http-header-name": "Predix-Zone-Id",
          "http-header-value": "69c2bd61-4526-4379-9533-a2721fe83ba8",
          "oauth-scope": "predix-asset.zones.69c2bd61-4526-4379-9533-a2721fe83ba8.user"
         }
        },
        "label": "predix-asset",
        "name": "testAsset",
        "plan": "<your_plan_name>",
        "tags": []
       }
      ]
     }
    }
    
    

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:

Procedure

  1. Copy the sample files in asset-service-asset-model.html#reference_99274c09-7d07-40fe-95a7-3219cd905ca1.
  2. Retrieve Asset instance details from the VCAP_SERVICES environment variable:
    • Asset instance uri
    • The ID required for making any REST calls, instanceId.
  3. In a REST client:
    1. Choose the POST method.
    2. Enter the URI of your Asset service instance, from the VCAP_SERVICES environment variable.
    3. Add the following HTTP headers:
      • Content-Type

        Enter the value.application/json.

      • Authorization

        Enter the token you receive from UAA in the form of Bearer <token from trusted issuer>. See uaas-get-started.html#task_155dd0e5-ca06-45d3-833e-686a71f0ca98.

      • Predix-Zone-Id

        Enter the ID required for making any REST calls, using the value from instanceId from the VCAP_SERVICES environment variable.

    4. Enter well-formed JSON in the Body of your request.
      To use sample data, copy the JSON objects from asset-service-asset-model.html#reference_99274c09-7d07-40fe-95a7-3219cd905ca1.
      
      [
         {
            "uri": "/locomotives/1",
            "type": "Diesel-electric",
            "model": "ES44AC",
            "serial_no": "001",
            "emission_tier": "0+",
            "fleet": "/fleets/up-1",
            "manufacturer": "/manufacturers/GE",
            "engine": "/engines/v12-1",
            "installedOn": "01/12/2005",
            "dateIso": "2005-12-01T13:15:31Z",
            "hqLatLng": {
                "lat": 33.914605,
                "lng": -117.253374
            }
         },
         }
            "uri": "/locomotives/84",
            "type": "Diesel-electric",
            "model": "3GS21B",
            "serial_no": "0084",
            "emission_tier": "0+",
            "fleet": "/fleets/cn-4",
            "manufacturer": "/manufacturers/national-railway-equipment",
            "engine": "/engines/QSK19-26",
            "hqLatLng": {
                "lat": 49.296307,
                "lng": -118.827314
            }
          }
      
          ]
                
  4. Use the Asset service API endpoints to run the asset-service-sample-api.html#reference_8c1e0944-babc-4f8a-bba0-8492e8439fa5.