Get Started With the UAA Service

UAA Security Service Setup

To begin using any secure Predix platform service, you must set up a UAA service instance as the trusted issuer.

Task Roadmap

#TaskDescription
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) Deploy a Predix Hello World Web application.t_Deploying_an_App_to_Cloud_Foundry.html#task_xwn_lvb_vx.
3Create the UAA service instance.See uaas-get-started.html#task_y1l_vms_2s.
4Create 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.

5Create Groups to set up the required permissions for the users.A group represents the privileges of a user.

See uaas-managing-users.html#task_vgj_vcy_1x.

6Create Users in the UAA instance.For UAA to authenticate the users, the users must first be created in UAA. You can either create users locally within UAA or federate to an external identity provider.

For creating users locally, see uaas-managing-users.html#task_lrr_n5w_fs.

To set up federated identity with UAA, see Managing Identity Providers.

7Bind your application to the service instance.See uaas-get-started.html#task_155dd0e5-ca06-45d3-833e-686a71f0ca98.

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": []
   }
  ],

Binding an Application to the UAA Instance

About This Task

You must bind your application to your UAA instance to provision its connection details in the VCAP_SERVICES environment variable. The Cloud Foundry runtime uses the VCAP_SERVICES environment variable to communicate with a deployed application about its environment.

You can retrieve the following UAA instance details from the VCAP_SERVICES environment variable:

  • A dashboard_url for your instance. You can use this URL to access the dashboard for managing this instance of UAA.

  • A subdomain that specifies a sub-domain you can use in addition to the domain created for UAA.

  • A uaa_instance_uri for your instance.

  • A uaa_instance_issuerId for your instance. The issuerID is required when you create an instance of another service that uses your UAA instance for authentication.

  • A uaa_instance_GUID is the zoneID for your instance.

Procedure

  1. Use the Cloud Foundry CLI to log into Cloud Foundry. 
    cf login -a <API_Endpoint>

    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 US-East

      https://api.system.asv-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. Bind the application to the service instance by entering the following command:
    cf bind-service <your_app_name> <uaa_instance_name>

    The <uaa_instance_name> instance is bound to your application, and the following message is returned:

    Binding service <uaa_instance_name> to app <your_app_name> in org predix-platform / space predix as userx@ge.com...
OK
TIP: Use 'cf restage' to ensure your env variable changes take effect
  3. Verify the binding by entering the following command:
    cf env <your_app_name>
    Messages that are similar to the following messages are returned:
    Getting env variables for app myApp in org predix-platform / space security as userx@ge.com...
OK
...
  ],
  "predix-uaa": [
        {
        "credentials":
        {
         "dashboardUrl": "https://uaa-dashboard.run.asv-pr.ice.predix.io/#/login/ff27c315-d027-4d1d-a30c-64f49b369ed9",
         "issuerId":
          "https://ff27c315-d027-4d1d-a30c-64f49b369ed9.predix-uaa.run.aws-usw02-pr.ice.predix.io/oauth/token",
         "subdomain": "ff27c315-d027-4d1d-a30c-64f49b369ed9",
         "uri": 
           "https://ff27c315-d027-4d1d-a30c-64f49b369ed9.predix-uaa.run.aws-usw02-pr.ice.predix.io",
          "zone": {
                    "http-header-name": "X-Identity-Zone-Id",
                    "http-header-value": "ff27c315-d027-4d1d-a30c-64f49b369ed9"
                   }
        },
        "label":
        "predix-uaa",
        "name":
        "my_uaa_instance",
        "plan":
        "free",
        "tags":
        []
        }
        ],

    In this sample, the following values are displayed:

    • dashboard_url = https://uaa-dashboard.run.asv-pr.ice.predix.io/#/login/ff27c315-d027-4d1d-a30c-64f49b369ed9
    • uaa_instance_issuerId = https://ff27c315-d027-4d1d-a30c-64f49b369ed9.predix-uaa.run.aws-usw02-pr.ice.predix.io/oauth/token
    • subdomain = 04187eb1-e0cf-4874-8218-9fb77a8b4ed9
    • uaa_instance_uri = https://ff27c315-d027-4d1d-a30c-64f49b369ed9.predix-uaa.run.aws-usw02-pr.ice.predix.io
    • uaa_instance_GUID = ff27c315-d027-4d1d-a30c-64f49b369ed9

Unbinding the UAA Instance From Your Application

Procedure

Unbind a service instance:
cf unbind-service <your_app_name> <uaa_instance_name>

The service instance is unbound from the application, and the following message is returned:

Unbinding app predix-service from service userX in org predix-platform / space predix as userx@ge.com...
OK

Deleting a UAA Instance

Procedure

Delete a service instance:
cf delete-service predix-uaa <uaa_instance_name>