CA API Gateway 9.1

9.4 9.1

Gateway Migration Example

This topic provides a start-to-finish example of how to migrate a gateway OAuth Toolkit using the Gateway Migration Utility (GMU).
gateway83
This topic provides a start-to-finish example of how to migrate a
CA API Gateway
 OAuth Toolkit using the Gateway Migration Utility (GMU).
(1) This sample workflow illustrates how multiple entity types (policies, folders, services, encapsulated assertions, jdbc connections, and so on) are involved in the migration. This workflow is an example only, it is insufficient to use without modifications for your implementation. (2) GMU migrates only the OAuth configuration. You must migrate the database separately.
Set Up
Migration Scenario
 
Bob_Alice
Bob_Alice
  1. Bob needs Alice to test OTK policies.
  2. Bob changes the OTK policies for Alice to retest.
 
Security Requirements
 
security_architect1
security_architect1
  • Gateway connection
    : Mutual authentication
  • Password used by GMU:
     Must be encoded
Gateway Set Up
 
source_target_small
source_target_small
Source
Gateway (source host)
  • Licensed with the REST Management service published
  • OAuth Toolkit is installed
Target Gateway (target host)
  • Licensed with the REST Management service published
  • OAuth-specific custom and modular assertions are installed
  • OAuth Toolkit not installed
Bryan's Tasks
 
Admin_Bryan2
Admin_Bryan2
Prerequisites
:
Bryan has configured GMU and the source and target Gateway using instructions in,
Configure GMU and Gateways for Migration
In these scenarios, Bryan will:
  1. Migrate a default OTK into a Gateway without OTK installed.
  2. Migrate a modified OTK to a Gateway with an existing default OTK.
  3. Modify a default OTK in a Gateway without OTK installed using template modifications.
Migrate a Default OTK Into a Gateway Without OTK Installed
Step 1: Create folder for bundle
Although optional, Bryan creates a folder named, 
bundles,
 for all of the migration-related files. This practice is recommended for organizing all XML files for migration.
Step 2: Encode passwords for certificate file
The Security Architect requires that Bryan encodes the password for the pkcs12 file. Bryan uses the 
encodePassword
 command to generate encoded passwords for the source and target Gateways. 
source Gateway
$ ./GatewayMigrationUtility.sh encodePassword --password password1
 Running...
 B8HPvx3xsW8.GlPDkJPcmscJTtqM2wTOsA
target Gateway
$ ./GatewayMigrationUtility.sh encodePassword --password password2
 Running...
 B6IPve3xsW4.GlLDkJPcmsomTtnM2wJOsB
Step 3: Create common argument files 
Bryan follows the best practice and creates common argument files for the target and source Gateways: 
  • sourceSSGcommon.properties
  • targetSSGcommon.properties
Bryan includes the pkcs12 file to use for mutual authentication.
sourceSSGcommon.properties
 
file
host=source host
clientCert=sourceGateway.p12
password=B8HPvx3xsW8.GlPDkJPcmscJTtqM2wTOsA
targetSSGcommon.properties file
host=target host
clientCert=targetGateway.p12
password=B6IPve3xsW4.GlLDkJPcmsomTtnM2wJOsB
Step 4: Create encryption passphrase
Bryan runs the 
encodePassword
 command to create an encryption passphrase, and saves it to the file, 
encrypt.txt
. 
$ touch encrypt.txt
$ chmod 0700 encrypt.txt
$ ./GatewayMigrationUtility.sh encodePassword --password foo --hideProgress > encrypt.txt
encrypt.txt file 
ASjQMQtW__s.SezfPjyonoXK5H6Iyd1kGg
Step 5: Export OTK from source Gateway
Bryan runs the 
migrateOut
 command to export a full bundle with the default OTK. Bryan encrypts secrets in the bundle by specifying the 
encrypt.txt
 file. 
$ ./GatewayMigrationUtility.sh migrateOut --argFile sourceSSGcommon.properties --all --encryptionPassphrase @file:encrypt.txt --dest bundles/OTK-all.xml
Running........................
Done
Step 6: Test import to target Gateway
Bryan tests the import and specifies a file for test results: 
OTK-all-results.xml
. Bryan reviews the file, and verifies that the migration is successful. 
$ ./GatewayMigrationUtility.sh migrateIn --argFile targetSSGcommon.properties --bundle bundles/OTK-all.xml --results bundles/OTK-all-results.xml --encryptionPassphrase @file:encrypt.txt --test
Running............................................
MigrateIn results saved in: bundles/OTK-all-results.xml
Test?migrate in successful
Step 7: Import bundle to target Gateway
$ ./GatewayMigrationUtility.sh migrateIn --argFile targetSSGcommon.properties --bundle bundles/OTK-all.xml --results bundles/OTK-all-results.xml --encryptionPassphrase @file:encrypt.txt
Running.................................................................................
MigrateIn results saved in: bundles/OTK-all-results.xml
Migrate in successful
Step 8: Verify OTK policies on target Gateway 
Bryan opens Policy Manager and checks verifies the OTK policies.
Migrate a Modified OTK to a Gateway With an Existing Default OTK
Bob changes the OTK policies for Alice to retest. The policies are in the folder:
 /OAuth-3.0/Policy Fragments/configuration
. 
Step 1: Export bundle with modifications
Bryan exports the new bundle with modifications from the source Gateway.
$ ./GatewayMigrationUtility.sh migrateOut --argFile sourceSSGcommon.properties --all --encryptionPassphrase @file:encrypt.txt --dest bundles/OTK-all-modified.xml
Running.....................
Done
Step 2: Create an override mapping file to update all policies in the bundle file
Bryan runs the 
manageMappings
 command with the 
Update
 argument to change the policies on the target Gateway
$ ./GatewayMigrationUtility.sh manageMappings --bundle bundles/OTK-all-modified.xml --outputFile bundles/OTK-all-modified-override-mappings.xml --type policy --action Update
Running.............
Updated mappings value:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<l7:Mapping xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management" action="NewOrUpdate" srcId="674b52d75faa1429c2bb8fdb7c8d2bb1" srcUri="https://127.0.0.1:8443/restman/1.0/policies/674b52d75faa1429c2bb8fdb7c8d2bb1" type="POLICY">
    <l7:Properties>
       <l7:Property key="FailOnNew">
            <l7:BooleanValue>true</l7:BooleanValue>
        </l7:Property>
    </l7:Properties>
</l7:Mapping>
Updated mappings value:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<l7:Mapping xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management" action="NewOrUpdate" srcId="674b52d75faa1429c2bb8fdb7c8d2d56" srcUri="https://127.0.0.1:8443/restman/1.0/policies/674b52d75faa1429c2bb8fdb7c8d2d56" type="POLICY">
   <l7:Properties>
       <l7:Property key="FailOnNew">
           <l7:BooleanValue>true</l7:BooleanValue>
       </l7:Property>
   </l7:Properties>
</l7:Mapping>
...
Step 3: Test import to target Gateway
Bryan tests the migration and verifies that the migration is successful. 
$ ./GatewayMigrationUtility.sh migrateIn --argFile targetSSGcommon.properties --bundle bundles/OTK-all-modified.xml --map bundles/OTK-all-modified-override-mappings.xml --encryptionPassphrase @file:encrypt.txt --results bundles/OTK-all-modified-results.xml --test
Running.............................
MigrateIn results saved in: bundles/OTK-all-modified-results.xml
Test?migrate in successful
Step 4: Import modified bundle to target Gateway
Byran is confident of the test migration and commits the migration. 
$ ./GatewayMigrationUtility.sh migrateIn --argFile targetSSGcommon.properties --bundle bundles/OTK-all-modified.xml --map bundles/OTK-all-modified-override-mappings.xml --encryptionPassphrase @file:encrypt.txt --results bundles/OTK-all-modified-results.xml
Running..........................
MigrateIn results saved in: bundles/OTK-all-modified-results.xml
Migrate in successful
Modify a Default OTK in a Gateway Without OTK Installed Using Template Modifications
Bryan wants to reuse the single bundle to migrate into a different Gateway, but a few changes must be made to accommodate the target Gateway.
Step 1: Copy the bundle
Bryan makes a copy of the bundle.
$ cp bundles/OTK-all.xml bundles/OTK-all-templatized.xml
Step 2: Templatize the bundle
Bryan uses the 
template
 command to modify the bundle and create a properties file of key=value pairs from the bundle.
$ ./GatewayMigrationUtility.sh template --bundle bundles/OTK-all-templatized.xml --template bundles/OTK-all-templatized.properties
Running.........
Template completed
Step 3: Back up the template.properties file
As a best practice, Bryan ensures that the original template file is backed up. 
$ cp bundles/OTK-all-templatized.properties OTK-all-templatized.properties.bak
Step 4: Change JDBC URL to point to a different database
Bryan wants to change the JDBC URL to point to a different database. He opens the template properties file in a text editor and searches for the value of jdbcUrl, which ends with:
 localhost/otk
. Using the correct GMU and Linux escaping characters, Bryan changes the database from "otk" to "gmu_otk" (
localhost/gmu_otk
).
$ sed -i 's/localhost\/otk/localhost\/gmu_otk/' bundles/OTK-all-templatized.properties
Step 5: Change a context variable value that is unique in the template 
In the template properties file, Bryan wants to replace the values for the 
cookieKey 
context
 
variable in the bundle. He searches and finds that the
 cookieKey
 value (
SV9IQVZFX1RPX0JFX0NIQU5HRUQ\=)
 is unique in the template file. Bryan enters the following command to change the value to: 
Q0hBTkdFRF9CWV9HTVU\=
.
$ sed -i 's/SV9IQVZFX1RPX0JFX0NIQU5HRUQ\\=/Q0hBTkdFRF9CWV9HTVU\\=/' bundles/OTK-all-templatized.properties?
Step 6: Change a context variable value that is not unique in the template
In the template properties file, Bryan wants to change the value of the 
session.lifetime.s
 context variable. Bryan searches and finds that the 
session.lifetime.s
 context variable value is used in many places. Because the value is not unique, Bryan must search again by the
 whole key name
.
 
To change the 
session.lifetime.s
 context variable for this policy to 
MTAw 
(100 base64 encoded), Bryan needs a more complex command. 
$ sed -i 's/template.policy.oauth\\ manager\\ config.Resources.ResourceSet.xml.All.5.SetVariable.Base64Expression.stringValue=NjAw/template.policy.oauth\\ manager\\ config.Resources.ResourceSet.xml.All.5.SetVariable.Base64Expression.stringValue=MTAw/' bundles/OTK-all-templatized.properties
Step 7: Review differences between template.properties and backup file
Bryan reviews the differences between the original backup file and the template file to see the changes.
$ diff -b bundles/OTK-all-templatized.properties bundles/OTK-all-templatized.properties.bak
3191c3191
< template.jdbc_connection.Oauth.Extension.JdbcUrl=jdbc\:mysql\://localhost/gmu_otk
---
> template.jdbc_connection.Oauth.Extension.JdbcUrl=jdbc\:mysql\://localhost/otk
12516c12516
< template.policy.oauth\ manager\ config.Resources.ResourceSet.xml.All.4.SetVariable.Base64Expression.stringValue=Q0hBTkdFRF9CWV9HTVU\=
---
> template.policy.oauth\ manager\ config.Resources.ResourceSet.xml.All.4.SetVariable.Base64Expression.stringValue=SV9IQVZFX1RPX0JFX0NIQU5HRUQ\=
12522c12522
< template.policy.oauth\ manager\ config.Resources.ResourceSet.xml.All.5.SetVariable.Base64Expression.stringValue=MTAw
---
> template.policy.oauth\ manager\ config.Resources.ResourceSet.xml.All.5.SetVariable.Base64Expression.stringValue=NjAw
Step 8: Test import to target Gateway
Bryan tests the migration to a new target Gateway.
$ ./GatewayMigrationUtility.sh migrateIn --argFile targetSSGcommon.properties --bundle bundles/OTK-all-templatized.xml --template bundles/OTK-all-templatized.properties -encryptionPassphrase @file:encrypt.txt --results bundles/OTK-all-templatized-results.xml --test
Running....................................................
MigrateIn results saved in: bundles/OTK-all-templatized-results.xml
Test?migrate in successful
Step 9: Import in to target Gateway
Bryan is confident of the migration and commits the bundle to the new target Gateway.
$ ./GatewayMigrationUtility.sh migrateIn --argFile targetSSGcommon.properties --bundle bundles/OTK-all-templatized.xml --template bundles/OTK-all-templatized.properties --encryptionPassphrase @file:encrypt.txt --results bundles/OTK-all-templatized-results.xml
Running......................................................
MigrateIn results saved in: bundles/OTK-all-templatized-results.xml
Migrate in successful
Step 10: Verify context variable changes on the target Gateway
Bryan logs in to Policy Manager, views the /OAuth-3.0/Policy Fragments/configuration/oauth manager/oauth manager config policy, and verifies the modifications to the context variables, 
cookieKey
 and 
session.lifetime.s
.
Step 11: Update the bundle for other Gateways
Bryan can now copy the 
bundles/OTK-all-templatized.properties.bak
 file and repeat steps 4-9 to accommodate changes for other target Gateways.

Content feedback and comments