Add a generic header application
The purpose of this tutorial is to step through the process of setting up a header application through the Access Gateway Admin Console.
- Access Gateway is installed and configured for use.
See Manage Access Gateway deployment.
- Access Gateway has been configured to use your Okta tenant as IDP.
See Configure your Okta tenant as an Identity Provider for more information about configuring your Okta tenant as an IDP.
- You have administrator rights on your Okta tenant and can assign applications to users and create groups.
- The external app version is supported. Supported header app versions include:
- Any that use HTTP Headers.
- Appropriate DNS entries for both the header application and the external exposed new URL exist.
Value Description https://application.headerapps.com Legacy application URL. https://gw-application.replaceinternal.com Protected application URL.
- Sign in to the Access Gateway Admin UI console.
Click the Applications tab.
Click +Add to add a new application.
Select the Header Based option from the application menu, and click Create.
The New Protected Application wizard will start and display the Essentials pane for the application being added.
In the Essentials pane, specify the following:
Field Value Label A name for the application. Public Domain A fully qualified host name, such as gw-header-app.<your domain> Protected Web Resource The URL of the protected resources.
Specifying a protected web resource of header.server.spgw tells Access Gateway to execute the header test suite. This is a special protected web resource.
Group Enter the group containing the users who should have access to the application. Description Optional. An appropriate description for your application.
- Expand the Certificates tab.
By default a wild card self signed certificate is created and assigned to the application when the application is initially created.
- Optional. Click Generate self-signed certificate
A self-signed certificate is created and automatically assigned to the application.
- Optional. Select an existing certificate from the list of provided certificates.
Use the Search field to narrow the set of certificates by common name.
Use the page forward (>)and backward(<) arrows to navigate through the list of available certificates.
- Click Next. The Attributes pane appears.
The Attributes pane provides a list of attributes that are passed into the application.
You can also add, edit, or remove any attribute using this page. See Application attributes for more information on the attribute options.
- Add any required attributes, and click Next. The Policies pane appears.
- Leave all policies unchanged and click Done. See About application policy for more information on application policies.
While optional, Okta recommends that all applications include certificates.
See About Access Gateway certificates for general information about certificate.
See Certificate management tasks for a general task flow for obtaining and assigning certificates.
You must define one or more groups representing the sections of your application being protected in your Okta tenant. See the Manage access control application policy guide for information on defining fine-grained access policy. You can also define additional attribute field values required by your application. However, they must be outside the values provided by default.
To define groups within your Okta tenant:
- Sign in to your Okta tenant as an administrator.
- In the Admin Console, go to Directory > Groups.
- Click Add Group.
- Click the name of the newly added group and use the various menu items to add members and manage group membership.
See Users, Groups, and Profiles for more information on user and group management.
With a tested Access Gateway application in place, the next step is to associate the application with a protected resource.
In this section, we will:
- Associate a protected application with an external URL.
- Associate one or more Okta tenant groups with an application.
- Define one or more policies to protect portions of an application.
Return to the Access Gateway Admin UI console
Select the Application table.
You can move directly to an application by clicking its name in the Topology tab.
In the row containing the header application, click Edit.
If required, expand the Essentials pane.
Replace the following values:
Field Value Example Public Domain External DNS entry https://gw-application.externally-visible.com Protected Resource Internal protected resource https://legacy.protected.com
In the Groups field, add groups associated with this application.
Set advanced fields as required.
|To add an attribute, click the plus icon.|
|To delete an attribute, select its row and click the delete icon|
|To modify an existing attribute, select its row and click Edit.|
For detailed information on the attribute options, see Application Attributes.
- Click the (+) icon
- From the Data Source drop-down box, select an appropriate data source.
- From the Field drop-down box, select a field name.
- From the Type drop-down box, select the appropriate target type as either Header or Cookie.
- In the Name field, enter the name for the header or cookie value expected by the legacy application.
For example, to map the IDP field username to the header field login, create an attribute resembling:
- Click Okay when the attribute is complete.
The root, represented by '/', is protected by Access Gateway by default. However, all users who can access the root can also access any subset of resources beneath the root. You can use a policy to protect subsets of the parent root URL.
To add a policy statement which protects an specific portion of an application,
- In the Policies tab, click the (+) icon.
- Select one of the following:
Protected - Creates a policy rule that protects a specific URI.
Unprotected - Creates a policy rule which marks a URL unprotected.
Adaptive - Creates an adaptive policy rule.
Protected Rule - Creates a Protected policy rule.
- Enter an appropriate Name for the rule.
- Enter the Resource Path to the URI being protected.
For example, a protected rule might protect the /secure URI.
- Depending on the rule type, enter additional details, such as Resource Matching Rule.
For example, to create a rule that only allows users with a valid username value to access the /secure/ URL, create a Protected Rule with Resource Matching Rule regular expression username=* as shown.
Repeat as required. Click Done when complete.
The following steps assign the application to a test account and then execute the application to verify basic functionality.
Assign the application
Sign in to your Okta tenant as administrator.
In the Admin Console, go to Applications > Applications.
Click the name of the newly added header application.
Select the Assignments tab.
Select .Assign > Assign To People.
Select an appropriate user and click Assign.
Usually, testing is initially done using the same user who is associated with administering Access Gateway.
Execute the Application
Return to the Access Gateway Admin UI console.
On the row representing the newly added header app, select Goto application > IDP Initiated.
- Verify that the results page displays all expected attribute values.
- Close the results page.
- See Access Gateway supported application and version information for details of supported application and version information.
- See Add a generic header application.
- See Add a sample policy application.
- See Troubleshoot applications.
- Add or review application essential settings. See About application essentials and Manage application essentials.
- Add application behaviors. See About application behaviors.
- Add fine grained policy to further protect resources. See About application policy and Manage access control application policy for an overview on user policy and for examples respectively.
- Extend existing policy using custom configuration. See Advanced Access Gateway policy.