This document is intended for those managing and running AA in a SaaS as well as developers integrating with AA in the SaaS deployment.

Current SaaS Deployed Implementation ¶

In the OpenText managed SaaS environments some customers may be have only AA, some may have limited access to AA for example IG customers, or they might have bought the greater CyberSecurity product family and be allowed full access to AA and every other CyberSecurity product. The functionality that is permitted and billed for is dependent on which product definitions are associated with a tenant.

IG customers may upgrade to full AA license, or may be given a trial license to full AA+risk, after the trial license expires they would revert back to a limited license.

Advanced Authentication SaaS Concepts ¶

Products ¶

In essence a product is an integration with a system, systems may be part of the AA product not enabled, external processes, or a contract to deliver functionality. Examples of products are Password management, Identity Governance, Licenses for RIsk, License for Federation and Single Sign On, and trial versions of AA.

Tenants may be associated with more than one product, each association is made via a customer definition.

Product definitions have two identifiers, one is the database id used to identify the product within the AA system, this is dynamically assigned. The other identifier is the external_product_id, this identifier is how the product is defined in an external system. This could be a SKU, or salesforce product definition id, or Control Tower Asset Id, a contract identifier, or just a random string.

Products and Customers may be managed through the au-saas.py, manage_tenants.py scripts, or via rest API.

An AA product file is a json representation of the integration. See product files sample product files for examples of what can be contained in product files. The json defines UI representations oF a product, AA licenses which are to be granted, as well as onboarding actions.

Customers ¶

An AA Customer is an association between a Product and a Tenant, and the state of that association, and any metadata which is required for the product. Every SaaS tenant should have at least one customer record associating it with a product.

Customer definitions have two identifiers, one is the database id used to identify the customer within the AA system, this is dynamically assigned. The other identifier is the external_customer_id, this identifier is how the customer is defined in an external system. This could be something like a salesforce customer id. In addition the customer record contains the current state of the relationship (enabled/disabled), and metadata about the product being associated with the tenant. That metadata could be things like external service locations.

Customers and Products may be managed through the au-saas.py, manage_tenants.py scripts, or via rest API.

SaaS Specific AA Scripts ¶

Each of these scripts have cmd line help. To invoke scripts which must be executed from the aucore container:

• local development system:
  • Open a shell and cd into the “aucore/AuCore/app” directory
  • With the system running (i.e. make dev-up should already be executing in a different shell)

run "make dev-exec-shell"  # or "make saas-dev-exec-shell"  
run "au-saas-install development.ini"

• kubernetes based system:

kubectl exec -it -c aucore master-aaf-0 -- /bin/bash

Scripts:

• au-saas-install - Called once and only once during initial setup of a SaaS system, intended audience is development and Managed SasS Admins. Invoked from the aucore-container.

  au-saas-install production.ini

• au-saas - Used to manage products, customers, and their associated licenses. Invoked from the aucore container. See the au-saas help for additional details

  # show all tenants, products, and customers
      au-saas production.ini display
  
      # compare all tenants with their associated products and update licenses and onboarding actions
      # this should be run after adding/removing products to a tenant or after changing a product file
      au-saas production.ini reprocess 
  
      # Run this to rekey all service accounts
      au-saas production.ini reprocess-issue-new-tokens
  
      # Run this if tenant is associated with a product file containing a time limited trial license and we need to extend the trial 
      au-saas production.ini --product XYZ --tenant_name=SIX extendlicense
  
      # development system samples
      # adding a new product into the system
      au-saas development.ini add --product=SA-AB804 --topic=reserved --file=aa-trial.json
      # adding a product to a tenant
      au-saas development.ini add --product=SA-AB804 --tenantname=SIX --customer=CTAssetIDforSA-AB804-SIX
      # remove a customer (removes the product from the tenant)
      au-saas development.ini delete --customer=CTAssetIDforSA-AB810-ONE
      # after all operations are complete run reprocess to ensure that all tenants are properly updated
      au-saas development.ini reprocess
      # create a large number of tenants
      au-saas development.ini bloat
  

• onboard_tenant.py - used to call the rest apis to onboard tenants, or add additional products to tenants. Invoked from any system running python, requires TOP admin credentials. Available from the AA samples directory.

  # Add the product file to the system 
      python3 onboard_tenant.py --host 127.0.0.1 --user admin --password "1plethora*" -f sample-test-service.json -pid sts newproduct
      # Associate the product with an existing tenant 
      python3 onboard_tenant.py --host 127.0.0.1 --user admin --password "1plethora*" -pid sts -cid sts --json addproduct
      # Verify the product is associated to the tenant 
      python3 onboard_tenant.py --host 127.0.0.1 --user admin --password "1plethora*" -tn {tenant_name} --json display
      # The following command would create a new tenant and associate it with the sample test service product file 
      python3 onboard_tenant.py --host 127.0.0.1 --user admin --password "1plethora*" -tn ONBOARDTENANTSCRIPTTEST2 -td "description" -te admin@onboardtenantscripttest.frog.com -tp "1plethora*" -pid sts -cid sts --json newtenant

• bulk_operations.py - allows json files to be submitted to the the service for processing. Available from the AA samples directory.

• manage_token.py - create tokens used for SCIM and other API access. Invoked from any system running python, requires admin credentials. Available from the AA samples directory.

Product Files ¶

When a product file is associated with a tenant (via a customer record) the results of onboarding and other actions taken will be returned to the caller.

Top level items in a product file ¶

• force_on_tenant - optional (boolean) True means that this product is automatically associated with every tenant created. Useful for default licensing or global replacement variables (bulkids)

• description - required, json block containing

  • name - (string) natural language name of the product
  • nameid - (string) id for localization of the name
  • fulldesc - (string) an English description of the product
  • fulldescid - (string) id for localization of the description

• billing - optional, deprecated

• licenses - optional (json) containing AA specific license information consult with AA engineers on specifics.

• onboarding_actions - optional (json) block see Onboarding Actions in product files

• bulkids - optional (json) block of key value pairs which are global replacement variables for bulk operations using the rest api, and are available during onboarding operations as replacement variables.

Sample product definition files: ¶

• aa-base.json SA-AB807 - support for all authentication methods, the billing dimension is per user per month. Used when a customer buys AA.

{
  "licenses": [{"restricts": [{"type": "limited", "methods": {"*": {}}}]}],
  "billing": {"dimensions": ["user_month"]},
  "description": {"name": "AA Base", "nameid": "SA-AB807", "fulldesc": "Adaptive Authentication Base Active User Monthly Subscription SaaS", "fulldescid": "SA-AB807"},
    "onboarding_actions": 
    {
        "create_scim_repos": [
            {"name": "IAMSERVICES"}
        ]
    }
}

• ig-aa-addon.json Optional add-on product that must be added when customer purchases IG SaaS. No billing, only allows the methods allowed in aa-limited.

{
    "description": {name": "IG-AA", "nameid": "IG-AA-Integration", "fulldesc": "Identity Governance Integration with Advanced Authentication", "fulldescid": "IG-AA-Integration"},
    "onboarding_actions": 
    {
        "issue_token": true,
        "create_scim_repos": [
            {"name": "IGBOOTSTRAPS", "scim_repo_create_config": {"user_repository_alias": "IGBOOTSTRAPS"}},
            {"name": "IAMSERVICES"}
        ]
    }
}

• aa-limited.json SA-AB805 - an AA instance with support for limited authentication methods (email otp, emergency password, HOTP, ldap password, password, radius, SMS otp and TOTP).

{
    "licenses": [{"restricts": [{"type": "limited",    "methods": {"EMAIL_OTP:1": {}, "EMERG_PASSWORD:1": {}, "HOTP:1": {}, "LDAP_PASSWORD:1": {}, "PASSWORD:1": {}, "RADIUS:1": {}, "SMS_OTP:1": {}, "TOTP:1": {},     "SAML_SP:1": {}}}]}],
    "billing": {"dimensions": ["user_month"]},
    "description": {"name": "AA Limited", "nameid": "SA-AB805",    "fulldesc": "Adaptive Authentication Limited Active User Entitled Monthly Subscription SaaS", "fulldescid": "SA-AB805"},
    "onboarding_actions": 
    {
        "create_scim_repos": [
            {"name": "IAMSERVICES"}
        ]
    }
}

• aa-trial.json SA-AB804 - an AA instance with full AA support including risk. Limited to 50 users for one month.

{
  "licenses": [{"days": 31, "restricts": [{"type": "risk_service"}, {"type": "trial", "users": 50}]}],
  "billing": {"dimensions": ["user_month"]},
  "description": {"name": "AA Trial", "nameid": "SA-AB804", "fulldesc": "Adaptive Authentication Trial Active User 1-Month Subscription SaaS", "fulldescid": "SA-AB804"},
    "onboarding_actions": 
    {
        "create_scim_repos": [
            {"name": "IAMSERVICES"}
        ]
    }
}

• aa-risk.json SA-AB888 - a Risk based Adaptive AA instance with support for all authentication methods, the billing dimension is per user per month. Used when a customer buys Adaptive AA. Requires aa-client-usage and aa-data-usage be installed in tandem.

{
    "licenses": [{"restricts": [{"type": "limited",    "methods": {"EMAIL_OTP:1": {}, "EMERG_PASSWORD:1": {}, "HOTP:1": {}, "LDAP_PASSWORD:1": {}, "PASSWORD:1": {}, "RADIUS:1": {}, "SMS_OTP:1": {}, "TOTP:1": {},     "SAML_SP:1": {}}}]}],
    "billing": {"dimensions": ["user_month"]},
    "description": {"name": "AA Adaptive", "nameid": "SA-AB808", "fulldesc": "Adaptive Authentication Adaptive Active User Monthly Subscription SaaS", "fulldescid": "SA-AB808"}
}

Onboarding Actions in product files ¶

In the json product file there is a section for onboarding actions to be taken when the tenant is created. Testing the bulk section of the product file can be done using the bulk operations rest API

"onboarding_actions": {
        "issue_token": true,
        "create_scim_repos": [
            {
                "name": "SaaSAdmins",
                "scim_repo_create_config": {
                    "user_repository_alias": "admin"
                },
                "token_ttl": "1h",
                "bulk": {
                    "schemas": [
                        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
                    ],
                    "fullResponses": true,
                    "failOnErrors": 3,
                    "Operations": [
                        {
                            "method": "GET",
                            "bulkId": "get-app-id",
                            "path": "/rest/admin/bulk"
                        },
                        {
                            "method": "POST",
                            "path": "/Users",
                            "data": {
                                "schemas": [
                                    "urn:ietf:params:scim:schemas:core:2.0:User",
                                    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
                                     "urn:scim:schemas:extension:custom:1.0"
                                ],
                                "externalId": "aa-bulkId:get-app-id",
                                "userName": "aa",
                                "emails": [
                                    {
                                        "value": "aa@example.com",
                                        "type": "work",
                                        "primary": true
                                    }
                                ],
                                "roles": [
                                    {
                                        "display": "SERVICE_ACCOUNTS"
                                    },
                                    {
                                        "display": "TENANT_ADMINS"
                                    }
                                ],
                                "urn:scim:schemas:extension:custom:1.0": {
                                    "openid_scopes": {
                                        "openid": false,
                                        "mandatory": false,
                                        "require_owner_permission": false,
                                        "name": "aa:AdminUI",
                                        "title": "Admin UI Allowed"
                                    }
                                }
                            }
                        },
                        {
                            "method": "GET",
                            "path": "/Users?filter=externalId eq \"701984\"",
                            "bulkId": "get-aa-service-id"
                        },
                        {
                            "method": "PATCH",
                            "path": "/Users/bulkId:get-aa-service-id?attributes=password",
                            "data": {
                                "schemas": [
                                    "urn:ietf:params:scim:schemas:core:2.0:PatchOp"
                                ],
                                "Operations": [
                                    {
                                        "op": "replace",
                                        "path": "password",
                                        "value": ""
                                    }
                                ]
                            }
                        }
                    ]
                }
            }
        ],
        "bulk": {
            "fullResponses": true,
            "failOnErrors": 3,
            "Operations": [
                {
                    "method": "GET",
                    "bulkId": "get-email-chain",
                    "path": "/rest/admin/api/chains"
                },
                {
                    "method": "POST",
                    "bulkId": "create-email-chain",
                    "path": "/rest/admin/api/chains",
                    "data": {
                        "name": "simple name",
                        "is_enabled": true,
                        "methods": [
                            "EMAIL_OTP:1"
                        ],
                        "roles": [
                            {
                                "name": "ALL USERS",
                                "idx": 0
                            }
                        ],
                        "repos": [
                            {
                                "name": "LOCAL",
                                "idx": 0
                            }
                        ]
                    }
                }
            ]
        }

• Also see the bulk operations section of this document for further samples of potential bulk operations.

• Warning, product files may be run both during onboarding and if the COE runs the admin script au-saas with the reprocess option. If reprocessing product files any bulk operations should assume the objects may already exist and will get the 409 conflict error.

• issue_token results in a bearer token being issued which allows for public APIs to be called, the default validity period is 7 days, this can be changed by setting “token_ttl”: “1h”. Valid values for token_ttl are a number and a unit for example: 24days, 1hour, 60seconds see pytimeparse2 for additional examples. The issued bearer token has tenant admin privileges, best practices should be followed with securing the token.

• scim_repo_create_name results in a scim repo of the specified name to be created, the onboarding response will contain a bearer token valid for 1 year that allows all operations on the SCIM repo.

• scim_repo_create_config any configuration options valid on a SCIM repo. Repo aliases may be set using the attribute ‘user_repository_alias’.

• create_scim_repos - allows multiple scim repos to be created instead of just one, this is the preferred format, the ‘scim_repo_create_name’ will be phased out in the future. Each created repo will be issued a token for repo operations. The operations under the bulk tag are assumed to be SCIM bulk operations as documented in rfc 7644

• Creating a user with a blank password “” results in a generated password being assigned to the user and returned to the caller.

• Globally defined well known bulkids. AA knows and populates the following bulkids by default:

  • aa_tenant_name - well known bulkId contains the tenant name such as TOP
  • aa_tenant_base - in SaaS systems this will be the base domain to which the tenant name is prepended to get the per tenant hostname. This will not be populated in non-SaaS systems
  • aa_tenant_domain the url specific to the tenant for example: top.cyberresdev.com (lowercase) It will not always be bulkId:aa_tenant_name.bulkId:aa_tenant_base it may be the domain used in federating with external SAML IDPs.

• During onboarding operations bulkids are resolved in the following order 1) well known AA bulkids such as ‘aa_tenant_name’, ‘aa_tenant_base’, ‘aa_tenant_domain’ 2) from the bulkids associated with a specific customer config, 3) from templates on every product associated with the tenant 4) from templates on bulkids from the product file (global values this is the only product file that must be created per install)

• bulkid templates are any bulkid named with the suffix _template. During the building of the bulkid list for resolution only bulkids with _template will be used from customer, and product configs.

Changes to products already associated with a tenant ¶

There are two approaches to updating products already associated with a tenant:

1. In place upgrade of the product json. Requires access to the containers to run the au-saas script.

Steps: - Update the existing product json au-saas production.ini update --product {product id} --file {updated product json file}
- Reprocess all product definitions, from the console of the aucore container au-saas production.ini reprocess

2. Associate a new product with existing tenants. May be done via SaaS API or via a combination of au-saas and onboard-tenant. This method allows for incremental updates, and full rollback. Steps:
   • Create a new product with the new product.json

     python3 onboard_tenant.py --host 127.0.0.1 --user admin --password "1plethora*" -f sample-test-service.json -pid new_sts newproduct

   • List all tenants associated with the old product

• Add new product to all tenants who had the old product

  • Remove the old product association from all tenants

  • Remove the old product definition

    python3 onboard_tenant.py --host 127.0.0.1 --user admin --password "1plethora*" -f sample-test-service.json -pid sts newproduct

Infrastructure as Code ¶

In the onboarding_actions section a section labeled [bulk] may contain a set of rest calls to setup AA for the application may be included. See the sample above for possible uses. Alternatively scripts such as bulk_operations.py may call the AA bulk operations. Currently the bulk operations have been tested using the AA Public API as well as chains, events, policy, and methods from the AA Admin API. The structure of the bulk operations follows the same general rules as SCIM bulk operations.

Warning, product files may be run both during onboarding and if the COE runs the admin script ‘au-saas’ with the reprocess option. If reprocessing product files any bulk operations should assume the objects may already exist and will get the 409 conflict error. In the example below the bulk operations are structured such that proper result is achieved regardless of the prior state of the object. In this example the proper result is that the object exists and has had it’s password set.

{
    "fullRequests": false,
    "fullResponses": true,
    "failOnErrors": 1,
    "Operations": [
        {"method": "GET", "bulkId": "get-app-id", "path": "/rest/admin/bulk"},
        {"method": "POST", "path": "Users",
            "data": {
                "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
                "urn:scim:schemas:extension:aa:1.0"],
                "externalId": "aa-bulkId:get-app-id",
                "userName": "aa",
                "emails": [{"value": "aa-service@bulkId:aa_tenant_domain", "type": "work", "primary": True}],
                "roles": [{"display": "SERVICE_ACCOUNTS"}],
                "urn:scim:schemas:extension:aa:1.0": {
                    "openid_scopes": [ {"openid": False, "mandatory": False, "require_owner_permission": False, "name": "aa:AdminUI", "title": "Admin UI Allowed", "attributes": [
                            {"localName": "tenantname", "clientName": "tenantname"},
                            {"localName": "mobile", "clientName": "user_mobile_phone"},
                            {"localName": "userFirstName", "clientName": "user_first_name"},
                            {"localName": "userLastName", "clientName": "user_last_name"},
                            {"localName": "username", "clientName": "user_name"},
                            {"localName": "userRepository", "clientName": "user_repository_alias"},
                            {"localName": "mail", "clientName": "user_email"}] } ],
                    "oauth2_aud_base": "https://bulkId:aa_tenant_domain\n"https://bulkId:cb_tenant_domain"
                }
            }
        },
        {"method": "GET", "path": "Users?filter=emails[value] eq \"aa-service@bulkId:tenant_aa_domain\"]", "bulkId": "get-aa-service-id"},
        {"method": "PATCH", "path": "Users/bulkId:get-aa-service-id", "bulkId": "patch-aa-service-pwd",
                "data": {"schemas": ["urn:ietf:params:scim:schemas:core:2.0:PatchOp"], "Operations": [{"op": "replace", "path": "password", "value": ""}]
                                                                }
                                                      }
    ]
}

Instead of using explicit URIs in the example above it would be best practices to use bulkId:somevar and then add somevar to the metadata sent to the bulk operation, or somevar_template to metadata stored on the customer, or include somevar_template in the product definition.

A practical example. CBA and ILM both create service accounts and intend to communicate with each other, both require that incoming tokens have an audience set correctly, and both create their service account through their respective product files which are installation agnostic. So how can the ILM service account definition specify that the CBA should be one of it’s resources/audiences? If there is a well known convention for the location of services then the actual service account definitions can use the convention to list audiences that will be specified at a later time.

The conventions can be defined in one of two ways

1. In series of _templates stored in a single product file which is associated with all tenants by default. This product file would be landing zone dependent, and could be altered if any services shift from shared multitenancy to per-tenant names.

{
    "description": {"name": "IAM Service configuration", "nameid": "IAM-Service-Config"},
    "force_on_tenant": true,
    "bulkids": {
        "cba_domain_template": "cba.frog.com",
        "ilm_tenant_domain_template": "bulkId:aa_tenant_name.ilm.bulkId:aa_tenant_base",
        "pwm_domain_template": "password.bulkId:aa_tenant_base",
        "iga_tenant_domain_template": "bulkId:aa_tenant_name.iga.bulkId:aa_tenant_base"
    }
}

2. When the product file is registered the caller may inject the proposed template into the agnostic product prior to registration with AA. In the example below the CBA product file is injected with the landing zone specific rule for

cat aucore/products/cba.json | jq '. + {"bulkids": {"cba_domain_template": "cba.frog.com"}}'

Assuming the above template has been registered with AA using one of the methods above, then services may use any of the templates listed above by including the name of the bulkId (excluding the word template)

"oauth2_aud_base": "https://bulkId:cba_domain\nhttps://bulkId:ilm_tenant_domain\nhttps://bulkId:iga_tenant_domain_template"

If oauth2_aud_base includes a bulkId which cannot be resolved then AA removes that audience from the list before configuring OSP.

Per Tenant Hostname ¶

This is a simple assignment of each tenant to a subdomain under the primary domain where aa is running. For example, assuming that we own the domain name cyberresprod.com we could have top.cyberresprod.com represent the top tenant, each tenant added would be assigned a name (tenant_name).cyberresprod.com. Tenants would need to use that name to access both their admin pages and for regular client access such as enrollment.

Per Tenant Hostname Assumptions ¶

Assumes that a wildcard cert is in use, for the example above *.cyberresprod.com Assumes SRE has easy access to create DNS names for each tenant and would incorporate that in their onboarding flow. Allows tenant discovery to be based in the incoming hostname, thus eliminating the need for the user to know their tenant name. Also allows us to have one AA instance which has tenants with overlapping user or email names.

Per Tenant Hostname Testing / Deployment Instructions ¶

• load balancer in front of AA must be set with wildcard cert on the tenant_base.

• load balancer must accept all dns names of the form *.tenant_base.

• The dns system used by the installed aa must be able to resolve all tenant_name.tenant_base names.

• Under Policies/Public URL(load balancers) the default and the tenant_base must be set correctly.

• Fresh install

  • Verify that all auth urls and an issuers are tenant_name.base_tenant_domain
  • verify cb install and radius scripts get the correct domain name
  • verify that install flow returns the correct domain name

• Upgrade

  • Existing tenants should still have the old common webauth url as the issuer and public url
  • New tenants should get the new tenant_name.base_tenant_domain
  • Existing tenants will get the tenant_name.base_tenant_domain added to their logon domains by a background celery task, this task will also handle injecting tenant.base_name if the base name changes. Note the old tenant.base_name is not removed.
  • Existing tenants who don’t have a webauth url will need to set it properly. Changing the webauth url will require any federations be updated.
  • What needs to happen for IG to get the new domain name?

Advanced Authentication Hosted SaaS API doc ¶

The rest apis in this section are intended only for use when Advanced Authentication has been installed as a SaaS Product.

Authentication ¶

Acceptable authentication to the rest apis is either a login_session_id passed on each call or a bearer token passed in the http header as Authorization: Bearer {token}.

Generated by aglio on 29 Oct 2025