LATEST VERSION: 1.6 - RELEASE NOTES
Single Sign-On v1.6

Managing Service Plans with UAA API

This topic describes how Pivotal Cloud Foundry (PCF) administrators manage Single Sign-On (SSO) service plans.

The SSO service for PCF manages configurations within the User Account and Authentication (UAA) and the Cloud Controller (CC) components of the Pivotal Application Service (formerly Elastic Runtime). Each SSO service plan ties together a CC plan and a UAA identity zone.

Beginning with SSO v1.6, you can use the UAA API to manage UAA identity zones configured as part of SSO service plans.

Create a UAA Identity Zone Admin Client

To use the UAA identity zone APIs for your SSO service plan, you need a special identity zone admin client.

Prerequisites

  • Create an admin client as described in Create Admin Client, and give this client clients.admin permission.
  • Record the app ID and app secret provided when you create the above admin client, to use when creating the UAA identity zone admin client.

Create a UAA Identity Zone Admin Client

To create a UAA identity zone admin client, do the following:

  1. Install the UAA CLI (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 command below 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 with clients.admin permission.

  4. Run the following command to display your client context and verify that you have clients.admin under the scope section.

    uaac context 
    

    For example:

    $ uaac context
    [1]*[ExampleAppID]
      client_id: ExampleAppID
        access_token: aBcdEfg0hIJKlm123.e
        token_type: bearer
        expires_in: 43200
        scope: uaa.resource clients.admin
        jti: 91b3-abcd1233
    

  5. Run the following command to create an identity zone admin client.

    When prompted for a New client secret, provide a client secret for this identity zone admin client. Make sure to use a secure value for your client secret.

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

    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.

    For example:

    $ uaac client add ExampleZoneAdminClientID --authorized_grant_types client_credentials --authorities uaa.admin
    New client secret:  *****
    Verify new client secret:  *****
    

    You can delete the original admin client created via the SSO UI after you create the identity zone client.

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

    When prompted for a Client secret, use the client secret you provided in the previous step.

    uaac token client get ZONE-ADMIN-CLIENT-ID
    

    Where:

    • ZONE-ADMIN-CLIENT-ID is zone admin client ID you provided in the previous step.

    For example:

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

  7. 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 SSO service plan. You will not have permissions for any other SSO service plan.

Update UAA Identity Zone Configurations with the API

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

WARNING: 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 may be lost.

For general information about UAA API, see the CF UAA API documentation page.

To do UAA identity zone API calls:

  1. Log in to the identity zone admin client that you set up in Create a UAA Identity Zone Admin Client above.

  2. Use UAAC to retrieve the information for the identity zone you want to change.

    • If you know your identity zone ID, use the following command:

      uaac curl -k /identity-zones/YOUR-ZONE-ID > FILENAME.txt
      
    • If you do not know your identity zone ID, use the following command:

      uaac curl -k /identity-zones > FILENAME.txt
      

      In most cases, this returns one identity zone, but if there are several, you can identify your identity zone by the subdomain name or description in the array returned.

  3. In the array returned from the previous command, delete the header information and array wrapper, and leave the JSON blob. Your remaining JSON blob looks similar to the sample below. Your identity zone ID is at the top in the id line.

     {
    "id": "baf7814b-94ab-4011-a3df-6b34625167b8",
    "subdomain": "demo",
    "config": {
      "clientSecretPolicy": {
        "minLength": -1,
        "maxLength": -1,
        "requireUpperCaseCharacter": -1,
        "requireLowerCaseCharacter": -1,
        "requireDigit": -1,
        "requireSpecialCharacter": -1
      },
      "tokenPolicy": {
        "accessTokenValidity": -1,
        "refreshTokenValidity": -1,
        "jwtRevocable": false,
        "refreshTokenUnique": false,
        "refreshTokenFormat": "jwt",
        "activeKeyId": null
      },
      "samlConfig": {
        "assertionSigned": true,
        "requestSigned": true,
        "wantAssertionSigned": true,
        "wantAuthnRequestSigned": false,
        "assertionTimeToLiveSeconds": 600,
        "keys": {
        },
        "disableInResponseToCheck": false
      },
      "corsPolicy": {
        "xhrConfiguration": {
          "allowedOrigins": [
            ".*"
          ],
          "allowedOriginPatterns": [
    
          ],
          "allowedUris": [
            ".*"
          ],
          "allowedUriPatterns": [
    
          ],
          "allowedHeaders": [
            "Accept",
            "Authorization",
            "Content-Type"
          ],
          "allowedMethods": [
            "GET"
          ],
          "allowedCredentials": false,
          "maxAge": 1728000
        },
        "defaultConfiguration": {
          "allowedOrigins": [
            ".*"
          ],
          "allowedOriginPatterns": [
    
          ],
          "allowedUris": [
            ".*"
          ],
          "allowedUriPatterns": [
    
          ],
          "allowedHeaders": [
            "Accept",
            "Authorization",
            "Content-Type"
          ],
          "allowedMethods": [
            "GET"
          ],
          "allowedCredentials": false,
          "maxAge": 1728000
        }
      },
      "links": {
        "logout": {
          "redirectUrl": "/login",
          "redirectParameterName": "redirect",
          "disableRedirectParameter": false,
          "whitelist": null
        },
        "selfService": {
          "selfServiceLinksEnabled": true,
          "signup": null,
          "passwd": null
        }
      },
      "prompts": [
        {
          "name": "username",
          "type": "text",
          "text": "Email"
        },
        {
          "name": "password",
          "type": "password",
          "text": "Password"
        },
        {
          "name": "passcode",
          "type": "password",
          "text": "One Time Code (Get on at /passcode)"
        }
      ],
      "idpDiscoveryEnabled": false,
      "accountChooserEnabled": false,
      "userConfig": {
        "defaultGroups": [
          "openid",
          "password.write",
          "uaa.user",
          "approvals.me",
          "profile",
          "roles",
          "user_attributes",
          "uaa.offline_token"
        ]
      },
      "mfaConfig": {
        "enabled": false
      }
    },
    "name": "demo",
    "version": 2,
    "description": "{\"plan_display_name\":\"demo\",\"plan_description\":\"Demo Service Plan\"}",
    "created": 1510116389000,
    "last_modified": 1519859509000
    }
    
    
  4. Update the configurations in the JSON blob as needed.

    WARNING: You must provide all configuration values, otherwise, data may be lost when doing an API update as a PUT command.

  5. Submit a UAAC curl request to apply your updated configurations to the identity zone. Examples are shown below.

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

    uaac curl -k /identity-zones/YOUR-ZONE-ID -X PUT -H 'Content-Type: application/json' -d '{JSON HERE}'
    

    You can compact the JSON to avoid issues with line spacing when using a command line, or pass in the file. For example:

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

Modify Branding

You can optionally modify the branding of your login page by changing your company name, logos, legal text, and legal links.

Using the steps in Update UAA Identity Zone Configurations with the API above to retrieve the identity zone configurations for your SSO plan, add or modify the branding section according to the UAA API documentation.

An example branding section is shown below.

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

"branding": {
      "companyName": "Pivotal",
      "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 Pivotal Software, Inc. All Rights Reserved.",
      "footerLinks": {
        "Privacy Policy": "https://run.pivotal.io/policies/privacy-policy/",
        "Terms of Service": "https://run.pivotal.io/policies/terms-of-service",
        "Up to three links, label here": "https://link-here"
      }
    },

Add Default Groups for Users

Optionally, you can add additional default groups for all users. You do not need to do manual group assignment 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.

Using the steps in Update UAA Identity Zone Configurations with the API to retrieve and update the current identity zone configurations for your SSO plan, update the default groups section according to the UAA API documentation.

An example of the default groups section is shown below. You can add more groups in the array list. Users will 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

To rotate JWT signing keys, do the following:

  1. Generate a private key that can be used for signing. For example, run ssh-keygen -t rsa.

    Generate your signing keys in a secure manner. Refer to your security organization for acceptable key generation practices.

  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. Using the steps in Update UAA Identity Zone Configurations with the API above to retrieve and update the identity zone configurations for your SSO plan, update the token policy section to add your new generated private key as the value for signingKey.

    An example of this section is shown below.

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

    Note: The first time you set a signing key for an identity zone, existing issued tokens are immediately invalidated for online validation. You may need to restart applications that do offline validation for the new signing keys to take effect.

     "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 UAA API documentation.

Enable Multi-Factor Authentications (Beta)

WARNING: Multi-factor authentication is a beta feature for PCF v2.1. Do not use multi-factor authentication in a PCF production environment for PCF v2.1.

You can enable multi-factor authentication (MFA) via Google Authenticator, available on the Apple Store or Android Play, for all users logging in to your service plan.

  1. Log in to your identity zone admin client you have already based upon the steps here.

  2. Create an MFA provider based on the UAA API documentation using the command below. The issuer value appears on users’ mobile Google Authenticator, so customize this value based on your needs.

    uaac curl -k '/mfa-providers' -X POST \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
    "name" : "GoogleProvider",
    "config" : {
      "issuer" : "MFA Login for Company SSO Plan"
    },
    "type" : "google-authenticator"
    }'
    
  3. Using the steps in Update UAA Identity Zone Configurations with the API above to retrieve and update the current identity zone configurations for your SSO plan, update the mfaConfig section according to the UAA API documentation.

    An example of the section is below. Set the enable value to true and provide the MFA provider name.

    "mfaConfig" : {
      "enabled" : true,
      "providerName" : "GoogleProvider"
    }
    


    To disable MFA set enable to false.

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