LATEST VERSION: 1.7 - RELEASE NOTES
Single Sign-On v1.7

Managing Clients with UAAC

This topic explains how plan administrators use the User Account and Authentication Command Line Interface (UAAC) to manage existing UAA Identity Zone clients.

About Managing Clients with UAAC

This section explains when and why you use the UAAC to update UAA Identity Zone clients.

All clients mentioned on this page are UAA Identity Zone clients. However, there are two kinds of UAA Identity Zone clients:

  • Non-Admin clients—When app developers configure their apps to use the Single Sign-On (SSO) service, each app corresponds to a non-admin client for an SSO service plan.
  • Admin clients—These can modify other clients and are created by completing the procedure below. See Create an Admin Client.

When Not to Use UAAC

Do not use the UAAC to do the following:

  • Create clients—Do not create clients through UAAC because additional metadata is required for their usage by SSO.

  • Make most types of updates—Most updates for UAA Identity Zone clients can be made through the SSO developer dashboard.

When to Use UAAC

Some updates cannot be done through the SSO developer dashboard and so must be made through the UAAC. You need to use the UAAC if you want to:

  • Add multiple grant types. The SSO developer dashboard only allows one grant type per client.

  • Set a configuration to a value that is not listed on the SSO developer dashboard.

Create an Admin Client

To use the UAAC to modify clients, you need an admin client that corresponds to your SSO service plan.

If you do not already have an admin client for your UAA Identity Zone, follow the steps below to create an admin client.

Note: You can use the same admin client for updating service plans and identity providers. For information, see Updating Service Plans with UAAC and Updating Identity Providers with UAAC.

  1. Target your Pivotal Cloud Foundry (PCF) deployment using cf.
  2. Target an org and space that your service plan is visible in.
  3. If you have not already created a service instance for your service plan, create one now. For how to create an instance, see Create a Service Instance. The service instance exposes the SSO developer dashboard.
  4. Log in to the SSO developer dashboard as an administrator. You can find the dashboard URL by using Apps Manager or cf service SERVICE-INSTANCE-NAME.
  5. Click New App.
  6. Enter an App Name.
  7. Under Select an Application Type, select Service-to-Service App.
  8. Click Select Scopes > Admin Permissions.

    Set the scopes as necessary for configuring the UAA resource.

    For… Add these scopes… For more information, see…
    updating UAA clients clients.admin Update Clients with UAAC below.
    managing SSO service plans clients.admin Updating Service Plans with UAAC.
    updating identity providers idps.read and idps.write Updating Identity Providers with UAAC.
  9. Record the App ID and App Secret.

Update Clients with UAAC

Use the UAAC to update a client to have multiple grant types or set a special value that is not available on the SSO developers dashboard.

The example shown here adds the client credentials grant type and the corresponding client credentials authorities to an existing web-app configured via SSO developers dashboard.

  1. Install the UAAC.

    $ gem install cf-uaac
    

  2. To target your service plan, run the following command:

    uaac target AUTH-DOMAIN
    

    Where AUTH-DOMAIN is the tenant-specific URL at which the service plan is accessible.

    For example:

    $ uaac target my-auth-domain.login.example.com  
  3. To authenticate and obtain an access token for the admin client for your service plan, run the following command:

    uaac token client get ADMIN-APP-ID -s ADMIN-APP-SECRET
    

    Where:

    • ADMIN-APP-ID is the App ID.
    • ADMIN-APP-SECRET is the App Secret.

    Use the App ID and App Secret that you created in Create a UAA Identity Zone Admin Client above. For example:

    $ uaac token client get MyAdminAppId -s MyAdminAppSecret 

    UAAC stores the token in ~/.uaac.yml.

  4. To display the client context, run the following command:

    uaac context
    

    For example:

    $ uaac context
    
    [1]*[admin]
        client\_id: MyAdminAppId
        access\_token: aBcdEfg0hIJKlm123.e
        token\_type: bearer
        expires\_in: 43200
        scope: clients.admin
        jti: 91b3-abcd1233
    
  5. Verify that you have the clients.admin permissions in the scope section.

  6. To obtain the existing configurations of the client, run the following command:

    uaac client get MY-WEB-APP-ID
    

    Where MY-WEB-APP-ID is your web app’s App ID. You can obtain this in the SSO developer dashboard.

    For example:

     $ uaac client get MyWebAppId

    scope: openid client_id: MyWebAppId resource_ids: none authorized_grant_types: authorization_code refresh_token redirect_uri: https://example.com access_token_validity: 43200 refresh_token_validity: 2592000 authorities: uaa.resource name: test-update allowedproviders: uaa google type: WEB space_guid: ebd0b512-d94c-49c3-87da-2766e3397a44 lastmodified: 1529517126000 created_by: e10c59d4-8fa4-4905-9ce5-d27e5163f455

  7. Confirm that in the output, client_id is the value of your web app ID.

  8. To update the client configuration, pass in flags with the following command:

    uaac client update MY-WEB-APP-ID --PROPERTY-1 VALUE-1,VALUE-2 --PROPERTY-N VALUE-N 
    

    Where:

    • PROPERTY-N’s are from the list returned in step 6 above, for example, redirect_uri.
    • VALUE-N’s are the configurations you want the client to have.

    For example:

     $ uaac client update MyWebAppId \
       --authorized_grant_types \
       authorization_code,refresh_token,client_credentials \
       --authorities todo.read,todo.write
    

    The example specifies grant types of authorization_code for the web app and respecifies the existing grant types. The example also replaces the uaa.resource authority with todo.read and todo.write. The client now has the ability to access todo.read and todo.write when acting on its own behalf.

  9. In the output from the command, verify that your client has the updates you expect.

    In this case, the additional grant types and todo.read and todo.write authorities.

     scope: openid
      client_id: MyWebAppId
      resource_ids: none
      authorized_grant_types: client_credentials authorization_code refresh_token
      redirect_uri: https://google.com
      access_token_validity: 43200
      refresh_token_validity: 2592000
      authorities: todo.read todo.write
      name: test-update
      allowedproviders: uaa google
      type: WEB
      space_guid: ebd0b512-d94c-49c3-87da-2766e3397a44
      required_user_groups:
      lastmodified: 1529518941000
      created_by: e10c59d4-8fa4-4905-9ce5-d27e5163f455
    

Create a pull request or raise an issue on the source for this page in GitHub