How can I move a SAML Proxy identity zone between UAA instances?

Products

• VMware Tanzu Application Service

Issue/Introduction

A SAML Proxy Identity Zone in UAA acts as a logical tenant that proxies authentication requests to an external SAML Identity Provider (IdP) for single sign-on (SSO). Moving such a zone between UAA instances involves replicating its configuration, including SAML settings, from one UAA instance to another. Below, I’ll provide a clear, step-by-step guide to achieve this, based on Cloud Foundry UAA documentation and standard SAML practices, while addressing the provided web results where relevant.

Prerequisites

• Administrative Access: You need admin credentials for both the source and target UAA instances.
• UAA CLI (uaac): Ensure the UAA Command Line Interface is installed (gem install cf-uaac) for interacting with UAA.
• SAML Metadata: Obtain the SAML IdP metadata XML file and any associated certificates from the source zone’s configuration.
• Target UAA Instance: The target UAA instance must be running and accessible, with the same or compatible UAA version as the source.
• Network Access: Ensure the target UAA can communicate with the external SAML IdP (e.g., via HTTPS, no firewall blocks).

Resolution

Log in to the Source UAA Instance:

• Use uaac to target the source UAA instance:
  

  uaac target <source-uaa-url>
  uaac token client get <admin-client-id> -s <admin-client-secret>

  
  

  Replace <source-uaa-url>, <admin-client-id> , and <admin-client-secret> with the source UAA’s endpoint and admin credentials.

• Verify login:
  

  uaac context

Export the Identity Zone Configuration:

• Retrieve the list of identity zones to identify the SAML Proxy Identity Zone:

  uaac curl /identity-zones

  Note the id or subdomain of the zone you want to move (e.g., zone-id or myzone.example.com).

• Export the specific zone's configuration:

  uaac curl/identity-zones/<zone-id> > zone-config.json

  This JSON file includes the zone's SAML configuration (e.g., samlConfig , idpMetadata , entityID , etc.).

• Extract the SAML IdP metadata XML and certificates:
  • Check the samlConfig section in zone-config.json for idpMetadata (the SML IdP's metadata XML) or metadataURL .
  • If certificates are used (e.g., for signing/encryption), note the activeKeyId , privateKey , and certificate fields.

Prepare the SAML IdP Metadata:

• If the idpMetadata field contains the XML directly, save it to a file (e.g., idp-metadata.xml).
• If a metadataURL is specified, download the metadata:

  curl <metadataURL> -o idp-metadata.xml

  Verify the metadata includes the IdP's entityID , SingleSignOnService URL, and signing certificate. Ensure the target UAA can access this URL or use the statis XML file.

   

Set Up the Target UAA Instance:

• Target the new UAA instance:

  uaac target <target-uaa-url>
  uaac token client get <admin-client-id> -s <admin-client-secret>

• Verify the target UAA is running and compatible with the source UAA's version (e.g., both use UAA 4.x). 

 

Create the Identity Zone in the Target UAA:

• Modify the zone-config.json file:
  • Update the subdomain if it needs to change (e.g., to match a new domain like newzone.example.com).
  • Ensure the idpMetadata or metadataURL points to the correct SAML IdP.
  • Update entityID if the Service Provider (SP) entity ID must reflect the target UAA’s domain (e.g., https://newzone.example.com/saml).
  • Adjust activeKeyId, privateKey, and certificate if the target UAA requires different signing/encryption keys. Generate new keys if needed:

    openssl genrsa -out privatekey.pem 2048
    openssl req -new -x509 -key privatekey.pem -out certificate.pem -days 365

  • Remove the id field, as the target UAA will assign a new one.
• Create the new identity zone:

  uaac curl -X POST /identity-zones -H "content-Type: applicaiton/json" -d @zone-config.json

  This creates the zone with the SAML Proxy configuration.

 

Configure the SAML IdP for the Target UAA:

• The SAML IdP needs to trust the target UAA as a Service Provider (SP).
• Export the SP metadata from the target UAA:

  uaac curl /saml/metadata -o sp-metadata.xml

  Or access it via the browser at http://<target-uaa-url>/saml/metadata .

• Update the SAML IdP (e.g., Okta, Microsoft Entra ID, ADFS) with the new SP metadata:
  
  • Add a new SAML application or update the existing one with the target UAA’s entityID, AssertionConsumerService URL (e.g., https://<target-uaa-subdomain>/saml/SSO), and certificate.
  • Example for Microsoft Entra ID:
    • In the Entra ID portal, create a new enterprise application or edit the existing one.
    • Upload sp-metadata.xml or manually set the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL).
    • Assign users or groups to the application

• Ensure the IdP sends the correct NameID format (e.g., urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress) and any required attributes (e.g., email, group).

 

Migrate Users and Groups (Optional):

• If the zone includes user accounts or groups, export them from the source UAA:

  uaac user > user.json
  uaac groups > groups.json

• Import users and groups to the target UAA:
  • For each user, create a new account:

    uaac user add <username> -p <password> --email <email>

  • For groups, recreate them and assign users:

    uaac group add <group-name>
    uaac member add <group-name> <username>

• If using Just-In-Time (JIT) provisioning, the SAML IdP can create users dynamically on first login, provided enableJITProvisioning is enabled in the zone’s samlConfig.

 

Test the SAML Configuration:

• Log in to the target UAA’s identity zone:

  uaac target <target-uaa-url>/<zone-subdomain>
  uaac token sso get <client-id> -s <client-secret>

• Alternatively, access a protected resource (e.g., https://<target-uaa-subdomain>/info) in a browser to trigger the SAML SSO flow.
• Verify redirection to the SAML IdP, successful authentication, and return to the target UAA.
• Check logs for errors:

   

  uaac curl /var/log/uaa.log

• Use browser tools like the Firefox SAML Tracer add-on to inspect SAML requests/responses.
   

 

Update DNS and Clients:

• If the zone’s subdomain changed (e.g., from myzone.example.com to newzone.example.com), update DNS records to point to the target UAA’s IP or load balancer.
• Update client applications to use the new UAA endpoint and zone subdomain.
• Test client access to ensure seamless SSO.

 

Decommission the Source Zone (Optional):

• Once the target zone is verified, disable or delete the source zone:

  uaac curl -X DELETE /identity-zones/<zone-id>

   

 

Additional Information

Additional Notes

• SAML Proxy Identity Zone: In UAA, the SAML Proxy Identity Zone delegates authentication to an external SAML IdP. Ensure the IdP’s metadata and trust relationship are correctly configured in the target UAA. The samlConfig section includes settings like assertionConsumerService, signingKey, and wantAssertionSigned.
   
• Certificates and Security: If the SAML IdP requires signed requests, ensure the target UAA’s signing certificate is uploaded to the IdP. Use SHA-256 for modern security requirements.
• Downtime Planning: Test the target zone before updating DNS or client configurations to avoid downtime.
• Version Compatibility: Ensure the source and target UAA instances run compatible versions, as schema changes (e.g., UAA 3.x to 4.x) may affect JSON compatibility.
• Automation: For large-scale migrations, use the UAA API or scripts to automate user/group migration and configuration updates.
• Error Handling: Common issues include mismatched entityID, incorrect NameID formats, or expired certificates. Check UAA logs and SAML responses for errors like AADSTS75006 or NameIdentifierPolicy issues.