This topic tells you how admins or plan admins can manage Single Sign‑On for VMware Tanzu Application Service service plan configurations using the SSO Operator Dashboard or API using the User Account and Authentication Command Line Interface (UAAC).

Single Sign‑On manages configurations within the UAA and the Cloud Controller (CC) components of the VMware Tanzu Application Service for VMs. Each Single Sign‑On service plan ties together a CC plan and a UAA identity zone.

Beginning with Single Sign‑On v1.6, you can use the UAAC to manage UAA identity zones configured as part of Single Sign‑On service plans.

Configure a Token Policy

Single Sign‑On enables admins and plan admins to override the default expiry of access tokens (12 hours) and refresh tokens (30 days) by zone.

  • Access tokens carry information about users and clients to servers that manage resources. Servers use access tokens to detect whether the client is authorized or not. Access tokens typically have a short-lived expiration time.
  • Refresh tokens carry information necessary to retrieve a new access token after an existing access token expires. Refresh tokens typically have a longer expiration time than access tokens.

To configure the token policy:

  1. Log in to the SSO Operator Dashboard at https://p-identity.SYSTEM-DOMAIN using your UAA admin credentials. You can find these credentials in your TAS for VMs tile in Tanzu Operations Manager in Credentials.

  2. Select the name of the plan that you want to configure a token policy for, and click Configure from the dropdown.

  3. Enter the number of seconds for Access Token Expiration or select Use System Default.

  4. Enter the number of seconds for Refresh Token Expiration or select Use System Default.

  5. Click Save.

Create a UAA Identity Zone Admin Client

To use the UAAC with your Single Sign‑On for VMware Tanzu Application Service service plan, you need an identity zone admin client. To create the identity zone admin client, you must create a UAA admin client that corresponds to your Single Sign‑On service plan.

Create an admin client

To create a UAA admin client:

  1. Follow the procedure in Create an admin client.

  2. Record the App ID and App Secret. You need these for the procedure below.

Create a UAA identity zone admin client

To create a UAA identity zone admin client:

  1. Install the UAAC as follows:

    gem install cf-uaac

    For information about the UAAC, see the UAAC Github Repository.

  2. Use the UAAC to target your service plan:

    uaac target MY-AUTH-DOMAIN.login.example.com

    Where MY-AUTH-DOMAIN is the Auth Domain you entered when you created the Service Plan.

  3. Run the following command to authenticate and obtain an access token for the admin client for your service plan. UAAC stores the token in ~/.uaac.yml.

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

    Where:

    • MY-APP-ID is your admin app ID.
    • MY-APP-SECRET is your app secret.

    Use the App ID and App Secret provided when you created the admin client in the preceding procedure.

  4. Run this command to create an identity zone admin client. 

    uaac client add ZONE-ADMIN-CLIENT-ID --authorized_grant_types client_credentials --authorities uaa.admin

    Where ZONE-ADMIN-CLIENT-ID is an ID you want to use to identify this zone admin client.

    When prompted for a New client secret, provide a client secret for this identity zone admin client. Ensure that you use a secure value for your client secret.

    For example:

    $ uaac client add ExampleZoneAdminClientID --authorized\_grant\_types client\_credentials --authorities uaa.admin
New client secret:  *****
Verify new client secret:  *****

    Record the values you provide for ZONE-ADMIN-CLIENT-ID and New client secret.

    You can delete the original admin client created through the SSO Operator Dashboard after you create the identity zone client.

  5. Run this command to authenticate and obtain an access token for the identity zone admin client for your service plan.

    uaac token client get ZONE-ADMIN-CLIENT-ID

    Where ZONE-ADMIN-CLIENT-ID is zone admin client ID you provided earlier in the procedure.

    When prompted for a Client secret, use the client secret you provided earlier.

    For example:

    $ uaac token client get ExampleZoneAdminClientID
Client secret:  *****

  6. Use the following command to display your client context and verify that you have uaa.admin under the scope section.

    uaac context

    For example:

    $ uaac context
[1]*[ExampleZoneAdminClientID]
  client_id: ExampleZoneAdminClientID
    access_token: asdioqwuelk12312.e21e
    token_type: bearer
    expires_in: 43200
    scope: uaa.admin
    jti: 123908dkl1-23298

    You can now do operator level API configurations for the Single Sign‑On service plan. You do not have permissions for any other Single Sign‑On service plan.

Update UAA Identity Zone Configurations with the API

This section shows how to use the UAAC to update UAA identity zone configurations, using a PUT command.

Caution

This flow is for advanced users only. You must always run the PUT command with the latest data by doing a GET before a PUT command. You must also provide all configuration values, otherwise, data might be lost.

For general information about UAA API, see the Cloud Foundry documentation.

To make UAA identity zone API calls:

  1. Create an identity zone admin client by following the procedure in Create a UAA Identity Zone Admin Client above.

  2. Find the UAA identity zone ID:

    1. Log in to the SSO Operator Dashboard at https://p-identity.SYSTEM-DOMAIN using your User Account and Authentication (UAA) admin credentials. You can find these credentials in the TAS for VMs tile in Tanzu Operations Manager in Credentials.

    2. Click the name of the Single Sign‑On service plan that you want to configure on the SSO Operator Dashboard, and select Edit Plan from the dropdown.

    3. Record the identity zone ID for your plan from the SSO Operator Dashboard URL. The URL looks similar to the below:

      https://p-identity.SYSTEM-DOMAIN/dashboard/edit_plan/YOUR-IDENTITY-ZONE-ID

      Where YOUR-IDENTITY-ZONE-ID is your plan’s identity zone ID.

  3. Direct the output to a text file by running:

    uaac curl -k /identity-zones/YOUR-IDENTITY-ZONE-ID > JSON-BLOB.txt

    Where:

    • YOUR-IDENTITY-ZONE-ID is the UAA identity zone ID you obtained in step 2 part 3.
    • JSON-BLOB.txt is the name of your text file.

  4. In the JSON-BLOB.txt file, delete the header information and array wrapper, leaving just the JSON blob. Confirm that the id in this output matches YOUR-IDENTITY-ZONE-ID.

    Your remaining JSON blob looks similar to the truncated sample below:

    {
  "id": "d324e405-4976-49a4-a142-cf33e19d4715",
  "subdomain": "demo",
  "config": {
    "clientSecretPolicy": {
    "minLength": -1,
    "maxLength": -1,
    "requireUpperCaseCharacter": -1,
    "requireLowerCaseCharacter": -1,
    "requireDigit": -1,
    "requireSpecialCharacter": -1
    },
    ...
  },
  "name": "demo",
  "version": 2,
  "description": "{\"plan_display_name\":\"demo\",
  \"plan_description\":\"Demo Service Plan\"}",
  "created": 1510116389000,
  "last_modified": 1519859509000
}

  5. In your JSON-BLOB.txt file, update the configurations in the JSON blob as needed, and then save the file.

    Caution

    You must provide all config values, otherwise, data can be lost when doing an API update as a PUT command.

  6. Submit a UAAC curl request to apply your updated configurations to the identity zone, as shown below.

    Caution

    You must always run this command with the latest data by doing a GET before a PUT command.

    uaac curl -k /identity-zones/YOUR-IDENTITY-ZONE-ID -X PUT
\-H 'Content-Type: application/json' -d "$(cat file.txt)"

    Where YOUR-IDENTITY-ZONE-ID is the UAA identity zone ID you obtained in step 2 part 3.

    A truncated example command looks similar to the below:

    $ uaac curl -k identity-zones/YOUR-IDENTITY-ZONE-ID\
   -X PUT \
   -H 'Content-Type: application/json' \
   -d '{
        "subdomain": "demo",
        "config": {
          "clientSecretPolicy": {
            "minLength": 0,
            "maxLength": 255,
            "requireUpperCaseCharacter": 0,
            "requireLowerCaseCharacter": 0,
            "requireDigit": 0,
            "requireSpecialCharacter": 0
         },
         ...
       },
       "name": "demo",
       "version": 0,
       "description": "{\"plan\_display\_name\":\"demo\",
       \"plan\_description\":\"Demo Service Plan\"}",
       "created" : 1529690485998,
       "last_modified" : 1529690485998
     }

For a full list of UAA API update parameters, see the Identity Zones Update Documentation.

Set Default Identity Provider (IdP)

For VMware Tanzu Application Service for VMs (TAS for VMs) v2.4 or later, you can set a default IdP so that end users are automatically redirected to an appropriate enterprise IdP.

To set a default IdP:

  1. Follow steps 1–6 in Update UAA Identity Provider Configurations with the API above, and in step 5, add the following line to the config section in the JSON blob:

    "defaultIdentityProvider": "YOUR-IDP"

    Where YOUR-IDP is the IdP you want to set as the default.

For information about defaultIdentityProvider, see Creating an identity zone in the UAA documentation.

Deactivate Single Sign‑On Plans

For TAS for VMs v2.4 and later, you can deactivate Single Sign‑On plans that are no longer in use. You can re-enable deactivated plans later when they need to be used again.

To deactivate Single Sign‑On plans:

  1. Follow steps 1–6 in Update UAA Identity Provider Configurations with the API above, and in step 5, add the following line to the config section in the JSON blob:

    "active": false

For information about active, see Updating an Identity Zone in the UAA documentation.

(Optional) Modify Branding

You can modify the branding on your login page, such as your company name, logos, legal text, and legal links.

To modify branding on the login page:

  1. Follow steps 1–6 in Update UAA Identity Provider Configurations with the API above, and in step 5, add or modify the branding section in the JSON blob according to the Cloud Foundry documentation. An example branding section is shown below:

    All values are optional. You can also generate the base64 text of your PNG images using commands, such as base64 image.png. 

    "branding": {
  "companyName": "VMware",
  "productLogo": "(base64 of png image here, will show up as image on login page)",
  "squareLogo": "(base64 of png image here, will show up as browser icon)",
  "footerLegalText": "©2017 VMware, Inc. or its affiliates All Rights Reserved.",
  "footerLinks": {
    "Privacy Policy": "https://www.vmware.com/help/privacy.html",
    "Terms of Service": "https://www.vmware.com/content/dam/digitalmarketing/vmware/en/pdf/downloads/eula/vmware-cloud-services-universal-tos.pdf",
    "Up to three links, label here": "https://link-here"
  }
},

(Optional) Add Default Groups for Users

You can add additional default groups for all users. You do not need to manually assign groups or group mappings for these groups. Use default groups only for universal scopes that all users can have, such as for a global read-only resource.

To add default groups for users:

  1. Follow the steps 1–6 in Update UAA Identity Provider Configurations with the API above, and in step 5, update the default groups section in the JSON blob according to the Cloud Foundry documentation. An example default groups section is shown below:

    You can add more groups to the array list. Users automatically have these scopes though they are not explicitly assigned to users. 

    "userConfig": {
    "defaultGroups": [
      "openid",
      "password.write",
      "uaa.user",
      "approvals.me",
      "profile",
      "roles",
      "user_attributes",
      "uaa.offline_token",
      "new.group.everyone.should.have",
      "another.new.group.everyone.should.have"
    ]
},

Rotate JSON Web Token (JWT) Signing Keys

After you configure JWT signing keys within a service plan, you can no longer default to sharing the multi-tenant JWT signing key inherited from the default zone.

To rotate JWT signing keys:

  1. Generate a private key that can be used for signing. This is typically an asymmetric PEM-encoded private key that begins with —–BEGIN RSA PRIVATE KEY—–. The UAA might support other key types. For more information, see the Cloud Foundry documentation.

    Two example commands are below:

    $ ssh-keygen -t rsa -m PEM -b 2048 -f OUTPUT-FILE-NAME
    After running the above command, enter a blank password when prompted. 

    $ openssl genrsa -out OUTPUT-FILE-NAME 2048

    Generate your signing keys securely. Ask your security organization for acceptable key generation practices.

    Caution

    Do not use private keys that begin with -----BEGIN OPENSSH PRIVATE KEY-----.

  2. Take the value of the generated private key and make it a single line of text, replacing all new lines with \n. For example:

    -----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEA63iy3EpQG46eRzUKpI8sB/AQdbZwwrDkfPGg5Xt5xNM/wQrO
5l/yWp3lCElSqnKPJbCGu1DQThB47kGQjBoXL8TcrkxuCyuxaV7B5ryq3w+g3R1x
-----END RSA PRIVATE KEY-----

    Becomes:

    -----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEA63iSAMPLEzUKpI8sB/AQdbZwwrDkSAMPLEt5xNM/wQrO\n5l/yWp3lCElSqnKSAMPLE8TcrkxuCyuxaV7B5ryq3w+g3R1x\n-----END RSA PRIVATE KEY-----\n

  3. Follow the steps 1–6 in Update UAA Identity Provider Configurations with the API above, and in step 5, update the token policy section in JSON-BLOB.txt to add your new, generated private key as the value for signingKey. An example of this section is shown below:

    {
  "config": {
    "tokenPolicy": {
      "accessTokenValidity": -1,
      "refreshTokenValidity": -1,
      "jwtRevocable": false,
      "refreshTokenUnique": false,
      "refreshTokenFormat": "jwt",
      "activeKeyId": "first-signing-key",
      "keys" : {
        "first-signing-key" : {
          "signingKey" : "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEA63iSAMPLEzUKpI8sB/AQdbZwwrDkSAMPLEt5xNM/wQrO\n5l/yWp3lCElSqnKSAMPLE8TcrkxuCyuxaV7B5ryq3w+g3R1x\n-----END RSA PRIVATE KEY-----\n"
        }
      }
    }
  }
}

    For more information, see Updating an Identity Zone in the Cloud Foundry documentation.

  4. The first time you set a signing key for an identity zone, existing issued tokens are immediately invalidated for online validation. Restart apps that do offline validation so that new signing keys take effect.

check-circle-line exclamation-circle-line close-line
Scroll to top icon